Programming Reference: ODDispatchModule

# Programming Reference

## ODDispatchModule

Class Definition File | DispMod.idl
Class C++ Binding | DispMod.xh

Class Hierarchy

    SOMObject
       ODObject
          ODDispatchModule

Description

An object of the ODDispatchModule class is used to distribute one or more event types.

Part editors do not receive events directly from the operating system; rather, OpenDoc receives events, interprets them, and dispatches them, using the dispatcher, to the appropriate part editor. The dispatcher uses dispatch module objects to dispatch specific events to individual parts. The dispatcher uses at least one internal dispatch module to handle standard events (such as, mouse clicks, keystrokes, and menu commands) of a particular platform. Typically, you do not need to subclass ODDispatchModule or even access the internal dispatch module directly; however, you can extend the OpenDoc dispatching system by installing additional dispatch modules.

The ODDispatchModule class is an abstract superclass that you can subclass to create a dispatch module. You can define dispatch modules to dispatch new types of events or messages, such as the custom events generated by a data glove or pen, to your part editor. Each dispatch module is responsible for determining the frame or part to which it dispatches an event.

You can create a dispatch module object from within a shell plug-in or from within your part's methods that are called during startup.

Your part editor can also install a dispatch module as a monitor, using the dispatcher's AddMonitor method. In this case, you can 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. There can be one or more monitors for each event type.

For more information related to the dispatcher, see the class description of ODDispatcher. For more information on event handling in OpenDoc, see the chapter on user events in the OpenDoc Programming Guide.

Overriding Inherited Methods

The following methods are inherited and available for use by your subclass of ODDispatchModule.

- somInit
- somUninit

Methods

The methods defined by the ODDispatchModule class include:

- Dispatch
- InitDispatchModule

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

### Dispatch

This method should dispatch the specified event to the appropriate part.

Signature

    ODBoolean Dispatch (ODEventData *event,
                        ODEventInfo *eventInfo)

Parameters

event (ODEventData *) - in/out

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

eventInfo (ODEventInfo *) - in/out

  A platform-specific structure that contains additional event information. On return, the relevant fields of the 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 after it has located this dispatch module in its dispatch module dictionary. This method in turn calls the part's HandleEvent method to give the part the opportunity to handle the specified event.

Override Policy

If you subclass ODDispatchModule, you must override this method. Your override method must not call its inherited method; that is, your override method must implement this method's functionality completely.

Related Methods

- ODDispatcher::Dispatch
- ODPart::HandleEvent

### InitDispatchModule

This method initializes the dispatch module object.

Signature

    void InitDispatchModule (ODSession *session)

Parameters

session (ODSession *) - input

  A reference to the current session object.

Returns

None.

Remarks

This method is not called directly to initialize this dispatch module object, but it is called by a subclass-specific initialization method. By convention, every subclass of ODDispatchModule should have a separate initialization method (for example, the InitMyDispatchModule method) that is called when an instance of that subclass is created. The override method may have additional parameters beyond those of the InitDispatchModule method. The InitMyDispatchModule method should call the inherited InitDispatchModule method at the beginning of its implementation.

If you subclass ODDispatchModule, your subclass-specific initialization method, rather than its somInit method, should handle any initialization code that can potentially file. For example, your initialization method may attempt to allocate memory for your dispatch module.

Override Policy

If you subclass ODDispatchModule, you should not override this method.

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