Programming Reference: ODDispatcher

# Programming Reference

## ODDispatcher

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:

- AddDispatchModule
- AddMonitor
- Dispatch
- Exit
- GetDispatchModule
- Redispatch
- RemoveDispatchModule
- RemoveMonitor
- ShouldExit

Overridden Methods | There are no methods overridden by the ODDispatcher class.

### AddDispatchModule

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

eventType (ODEventType) - input

  A platform-specific event code that specifies the type of event to be handled by the new dispatch module. On OS/2, this is a PM message identifier. On Windows, this is a Windows message identifier. On AIX, this is an X11 event type.

dispatchModule (ODDispatchModule *) - input

  A reference to a dispatch module to be added.

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

- ODDispatcher::GetDispatchModule
- ODDispatcher::RemoveDispatchModule

### AddMonitor

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

eventType (ODEventType) - input

  A platform-specific event code that specifies the type of event to be handled by the new dispatch module. On OS/2, this is a PM message identifier. On Windows, this is a Windows message identifier. On AIX, this is an X11 event type.

dispatchModule (ODDispatchModule *) - input

  A reference to the dispatch module to be added.

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

- ODDispatcher::RemoveMonitor

### Dispatch

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

eventData (ODEventData *) - in/out

  A platform-specific structure representing an event. On return, the fields of this structure may have been modified.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the event was handled by a part.

  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

- ODDispatchModule::Dispatch
- ODPart::HandleEvent

### Exit

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

- ODDispatcher::ShouldExit

### GetDispatchModule

This method returns a reference to the dispatch module for the specified event type.

Signature

    ODDispatchModule *GetDispatchModule (ODEventType eventType)

Parameters

eventType (ODEventType) - input

  A platform-specific event code that specifies the type of event to be handled by the requested dispatch module. On OS/2, this is a PM message identifier. On Windows, this is a Windows message identifier. On AIX, this is an X11 event type.

Returns

rv (ODDispatchModule *) - returns

  A reference to the dispatch module for the specified event type or kODNULL if the event type is not associated with an existing dispatch module.

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

- ODDispatcher::AddDispatchModule
- ODDispatcher::RemoveDispatchModule

### Redispatch

This method redispatches the specified event to the appropriate part.

Signature

    ODBoolean Redispatch (ODEventData *eventData,
                          ODEventInfo *eventInfo)

Parameters

eventData (ODEventData *) - in/out

  A platform-specific structure representing an event. On return, the fields of this structure may have been modified.

eventInfo (ODEventInfo *) - in/out

  A platform-specific structure that contains additional event information. On return, the fields of this structure are filled in if the event was handled.

Returns

rv (ODBoolean) - returns

  A flag indicating whether the event was handled by a part.

  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

- ODDispatcher::Dispatch
- ODDispatchModule::Dispatch

### RemoveDispatchModule

This method removes the dispatch module for the specified event type from the dispatch module dictionary.

Signature

    void RemoveDispatchModule (ODEventType eventType)

Parameters

eventType (ODEventType) - input

  A platform-specific event code that specifies the type of event to be handled by the new dispatch module. On OS/2, this is a PM message identifier. On Windows, this is a Windows message identifier. On AIX, this is an X11 event type.

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

- ODDispatcher::AddDispatchModule
- ODDispatcher::GetDispatchModule

### RemoveMonitor

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

eventType (ODEventType) - input

  A platform-specific event code that specifies the type of event to be removed from the new dispatch module. On OS/2, this is a PM message identifier. On Windows, this is a Windows message identifier. On AIX, this is an X11 event type.

dispatchModule (ODDispatchModule *) - input

  A reference to the dispatch module to be removed.

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

- ODDispatcher::AddMonitor

### ShouldExit

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

rv (ODBoolean) - returns

  A flag indicating whether the document shell should terminate.

  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

- ODDispatcher::Exit

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]