Class Definition File | Disptch.idl |
Class C++ Binding | Disptch.xh |
Class Hierarchy |
SOMObject
ODObject
ODBaseDispatcher
ODDispatcher
|
Description | An object of the ODDispatcher class is responsible for distributing events to part editors. When a document is opened, the session object creates a single dispatcher object. All parts of the document share the dispatcher object; you can obtain a reference to it by calling the session object's GetDispatcher method. The dispatcher maintains a dispatch module dictionary, indexed by event type. The dictionary contains at least one internal dispatch module to handle standard events (such as, mouse clicks, keystrokes, and menu commands) of a particular platform. You can extend the OpenDoc dispatching system by installing additional dispatch modules to dispatch new types of events or messages to your part editor. For more information, see the class description of ODDispatchModule. Part editors do not receive events directly from the operating system; rather, OpenDoc notifies the appropriate part editor when an event occurs. To do so, the document shell's event loop calls the dispatcher's Dispatch method to dispatch events to part editors. The dispatcher handles the events it recognizes using dispatch module objects to dispatch specific events to individual parts. The dispatcher locates the dispatch module for the specified event in its dispatch module dictionary and calls the dispatch module's Dispatch method. The Dispatch method, in turn, calls the part editor's HandleEvent method to give the part the opportunity to handle the specified event. If your part contains embedded frames, OpenDoc can also send your part editor special mouse events that occur within and on the borders of your part's embedded frames' facets. The dispatcher leaves all other events, as well as events dispatched to parts but not handled by them, to the document shell to handle. Events not handled by the document shell are ignored. For more information on event handling in OpenDoc, see the chapter on user events in the OpenDoc Programming Guide. OpenDoc allows you to monitor the event stream without interfering with it. By registering a dispatch module as a monitor for a specified event type, OpenDoc notifies the dispatch module when an event of that type occurs. You might use a monitor in a debugging environment to monitor events and display a log of the events in a window. In general, you should install monitors and not patch the dispatch module. Patching occurs when the creator of the new dispatch modules saves the existing dispatch module and then installs its own replacement dispatch module that calls the original. |
Methods | The methods defined by the ODDispatcher class include: |
Overridden Methods | There are no methods overridden by the ODDispatcher class. |
This method adds the specified dispatch module for the specified event type to the dispatch module dictionary.
Signature
void AddDispatchModule (ODEventType eventType,
ODDispatchModule *dispatchModule)
|
Parameters
Returns
None.
Remarks
Your part editor calls this method to install a custom dispatch module. This method is not called by part editors under normal circumstances.
Exception Handling
| kODErrIllegalNullDispatchModuleInput | The dispatchModule parameter is null. |
Related Methods
This method adds the specified dispatch module, which is a monitor for the specified event type, to the dispatch module dictionary.
Signature
void AddMonitor (ODEventType eventType,
ODDispatchModule *dispatchModule)
|
Parameters
Returns
None.
Remarks
This method is not called by part editors under normal circumstances; however, your part editor calls this method to install a custom dispatch module as a monitor for the specified event type.
Exception Handling
| kODErrIllegalNullDispatchModuleInput | The dispatchModule parameter is null. |
Related Methods
This method is called by the document shell and container applications to dispatch the specified event to the appropriate part.
Signature
ODBoolean Dispatch (ODEventData *eventData) |
Parameters
Returns
| kODTrue | The event was handled by a part. |
| kODFalse | The event is not associated with an existing dispatch module or the event was not handled. |
Remarks
The document shell and container applications call this method when an event occurs. This method looks up the dispatch module for the specified event in the dispatch module dictionary and then calls the dispatch module's Dispatch method. This method can also be called by parts that handle events in dialog boxes.
Related Methods
This method is called by the document shell to set a Boolean value in the dispatcher that specifies that the document shell should terminate.
Signature
void Exit () |
Parameters
None.
Returns
None.
Remarks
This method is not called by most parts.
Related Methods
This method returns a reference to the dispatch module for the specified event type.
Signature
ODDispatchModule *GetDispatchModule (ODEventType eventType) |
Parameters
Returns
Remarks
This method might be called to patch a dispatch module. Patching occurs when the creator of the new dispatch module saves the existing dispatch module and then installs its own replacement dispatch module that calls the original. Your part editor calls this method to save the existing dispatch module so it can delegate to that dispatch module when necessary; this method is not called by parts.
Related Methods
This method redispatches the specified event to the appropriate part.
Signature
ODBoolean Redispatch (ODEventData *eventData,
ODEventInfo *eventInfo)
|
Parameters
Returns
| kODTrue | The event was handled by a part. |
| kODFalse | The event is not associated with an existing part or the event was not handled. |
Remarks
OpenDoc calls this method when it translates an event. For example, when the standard dispatch module transforms a mouse-down event in the menu bar to a menu event, the dispatch module redispatches the event so that monitors and patches can intercept the new event.
Related Methods
This method removes the dispatch module for the specified event type from the dispatch module dictionary.
Signature
void RemoveDispatchModule (ODEventType eventType) |
Parameters
Returns
None.
Remarks
This method is not called by part editors under normal circumstances; however, your part editor may call this method to remove a custom dispatch module.
Related Methods
This method removes the specified dispatch module, which is a monitor for the specified event type, from the dispatch module dictionary.
Signature
void RemoveMonitor (ODEventType eventType,
ODDispatchModule *dispatchModule)
|
Parameters
Returns
None.
Remarks
This method is not called by part editors under normal circumstances; however, your part editor may call this method to remove a custom dispatch module as a monitor for the specified event type.
Related Methods
This method is called by the document shell or container application to indicate whether the document shell should terminate.
Signature
ODBoolean ShouldExit () |
Parameters
None.
Returns
| kODTrue | The document shell should terminate. |
| kODFalse | The document shell should not terminate. |
Remarks
The document shell and container applications call this method to see whether the dispatcher recommends that their main event loop be terminated.
Related Methods