4.4.3 Subscription

The event scheduling system is invoked by calling the csEventQueue::RegisterListener() or csEventQueue::Subscribe() methods (or, if you are inheriting from `csBaseEventHandler', csBaseEventHandler::RegisterQueue()). For each of these, the arguments of interest are the `csEventID' and csEventID[] parameters. (Note that the RegisterListener() form with no `csEventID' argument does not subscribe the listener to anything, and must be followed by a call to Subscribe() if you ever want the handler to receive any events.) For each `csEventID' (arrays are terminated by `CS_EVENTLIST_END'), these functions will subscribe the event handler to that event name as well as all of its children. Note, however, that it will only retrieve from the event handler the ordering lists (the Prec() and Succ() methods) for the event name to which it is explicitly subscribed; if you wish to have one set of ordering constraints for both `crystalspace.input.keyboard' and `crystalspace.input.mouse' but a different set for `crystalspace.input.joystick', you should not simply subscribe to `crystalspace.input' and have the Prec() and Succ() functions return different values for each of `.keyboard', `.mouse', and `.joystick'; rather, you should subscribe to each of those three event names individually. This restriction helps us avoid the introduction of hard-to-detect circular ordering rules.

Also note that you should use the Subscribe() and Unsubscribe() methods to add and remove events from the set of events a handler wishes to receive. You should only Unsubscribe() from the particular events to which you have Subscribe()d; the behavior is undefined otherwise (e.g., if you subscribe to `crystalspace.input' and subsequently unsubscribe from `crystalspace.input.joystick').

This document was generated using texi2html 1.76.