4.4.2 Scheduling

The event system provides a generic mechanism for representing the order in which handlers of particular events should be invoked, regardless of the order in which they are initialized or in which their respective plugins are loaded.

The event scheduler takes advantage of properties exposed by the iEventHandler interface to do exactly this. For each event name to which an event handler subscribes, it may also specify essentially arbitrary happens-before and happens-after relationships with other event handlers, both abstractly (I want to handle all input events before any instance of the `crystalspace.aws' handler) and specifically (I want to handle the mouse event only after the `crystalspace.cel' event handler).

The specific functions which all iEventHandler implementations must provide are:

• const char *GenericName(): Returns a simple text name common to all instances of this event handler.
• csHandlerID GenericID(): A `csHandlerID' is a lightweight way to manage generic handler names. Under almost all circumstances, the implementation of this method simply is implemented as:

  return csHandlerRegistry::GetID(this->GenericName());

• const csHandlerID[] GenericPrec(csEventID): Returns an array (terminated by `CS_EVENTLIST_END') of `csHandlerID's of generic event handlers which, for the event name identified by the argument, should always handle events with that name before instances of the current handler.
• const csHandlerID[] GenericSucc(csEventID): Returns an array (terminated by `CS_EVENTLIST_END') of `csHandlerID's of generic event handlers which, for the event name identified by the argument, should always handle events with that name after instances of the current handler.
• const csHandlerID[] InstancePrec(csEventID): Returns an array (terminated by `CS_EVENTLIST_END') of `csHandlerID's of both generic event handlers and event handler instances which, for the event name identified by the argument, should always handle events with that name before this particular instance of the event handler.
• const csHandlerID[] InstanceSucc(csEventID): Returns an array (terminated by `CS_EVENTLIST_END') of `csHandlerID's of both generic event handlers and event handler instances which, for the event name identified by the argument, should always handle event with that name after this particular instance of the event handler.

In many simple cases, you will want to use default implementations of these functions provided by the CS_EVENTHANDLER_NAMES() and `CS_EVENTHANDLER_NIL_CONSTRAINTS' macros, like so:

struct myEventHandler : public iEventHandler
{
  virtual bool HandleEvent (iEvent &Event)
  {
    foo();
    bar();
    return baz();
  }
  CS_EVENTHANDLER_NAMES("crystalspace.module.name")
  CS_EVENTHANDLER_NIL_CONSTRAINTS
}

As a convention, most `csEventHandler's will implement a static method, `const char *StaticHandlerName()', which can be retrieved and converted without instantiating the handler. This name string can then be converted into a `csHandlerID' by invoking:

csHandlerRegistry::GetID(myHandlerClass::StaticHandlerName())

The `csHandlerID' of an instance of an event handler class can be retrieved by passing a pointer to that class to csHandlerRegistry::GetID(). For example:

csHandlerRegistry::GetID(new myHandlerClass())

This document was generated using texi2html 1.76.