You can extend OpenDoc's event-dispatching architecture to include new kinds of events by creating your own dispatch module.
The class ODDispatchModule is an abstract superclass. OpenDoc uses instances of a subclass of ODDispatchModule to dispatch certain types of events (such as keystroke events) to part editors. For normal program execution, you do not need to subclass ODDispatchModule or even access the existing dispatch module objects directly. Your interaction with OpenDoc regarding event dispatching is mainly through the dispatcher.
You can, however, provide for dispatching of new types of events or messages to your part editor by subclassing ODDispatchModule. For example, you could create a dispatch module that handled events from an exotic input device such as a 3D glove for a virtual reality game.
Patching the dispatcher It is possible to use custom dispatch modules to patch the functioning of the dispatcher in relation to all event types, although that is in general not recommended. In most cases there is no need for such drastic alteration of OpenDoc functionality.
At run-time the dispatcher maintains a dictionary of installed dispatch modules, keyed by event type. When the dispatcher's Dispatch method is called, it looks up the dispatch module for the supplied event type and calls the Dispatch method of that module.
When the standard OpenDoc dispatch module transforms an event of one type (such as a mouse-down event in the menu bar) into an event of another type (such as an OpenDoc menu event), it passes the event back to the dispatcher for redispatching, by calling the dispatcher's Redispatch method. This redispatching allows your custom dispatch module to patch out or monitor the standard dispatch module for just those transformed events.
If you subclass ODDispatchModule, you need to implement a SOM constructor (somInit), a SOM destructor (somUninit), and an initialization method. Your initialization method should call (but not override) the InitDispatchModule method of ODDispatchModule.
Your dispatch module is responsible for performing the actual dispatching of events. The dispatcher calls your module's override of the Dispatch method, passing it the event information.
You install the dispatch module by calling the AddDispatchModule method of the dispatcher; you remove a dispatch module by calling the RemoveDispatchModule method of the dispatcher. The installation might occur during the initialization of your part (or shell plug-in, if you create one).
Your dispatch module should be installed just before your part will be handling events of the specified type, and removed right after your part is finished handling events of that type. If you are unable to add your dispatch module because another dispatch module already exists, you can still handle your events by doing the following:
You can also use a dispatch module as a monitor. In this case, the dispatch module is notified of events of its kinds but does not have to dispatch them. You might use a monitor in debugging, for example, to capture all events and display a log of them in a window.
You install a monitor with the dispatcher's AddMonitor method. For a given event, the dispatcher calls the Dispatch method for all installed monitors (of that event type) before calling the Dispatch method of the regular dispatch module for that event type. The dispatcher ignores the Boolean function result of the Dispatch method of all monitors; thus, unlike with normal use of a dispatch module, you can have more than one monitor for a single event type.