iEventHandler Struct Reference
[Event handling]
This interface describes an entity that can receive events.
More...
#include <iutil/eventh.h>
Inheritance diagram for iEventHandler:
Public Member Functions | |
| virtual csHandlerID | GenericID (csRef< iEventHandlerRegistry > &) const =0 |
| This function returns a csHandlerID corresponding with GenericName, i.e., it should always return csHandlerRegistry::GetGenericID (this->GenericName()). | |
| virtual const char * | GenericName () const =0 |
| This function returns a string which "names" this event handler generically (i.e., it identifies all instances of this event handler as a group). | |
| virtual const csHandlerID * | GenericPrec (csRef< iEventHandlerRegistry > &, csRef< iEventNameRegistry > &, csEventID) const =0 |
| This function takes a csEventID as an argument and returns an array of csHandlerIDs identifying those event handlers which must, for the given event, only be called before this one (if they have been instantiated). | |
| virtual const csHandlerID * | GenericSucc (csRef< iEventHandlerRegistry > &, csRef< iEventNameRegistry > &, csEventID) const =0 |
| This function takes a csEventID as an argument and returns an array of csHandlerIDs identifying those event handlers which must, for the given event, only be called after this one (if the have been instantiated). | |
| virtual bool | HandleEvent (iEvent &)=0 |
| This is the basic event handling function. | |
| virtual const csHandlerID * | InstancePrec (csRef< iEventHandlerRegistry > &, csRef< iEventNameRegistry > &, csEventID) const =0 |
| This function takes a csEventID as an argument and returns an array of csHandlerIDs identifying those event handlers which must, for the given event, only be called before this one. | |
| virtual const csHandlerID * | InstanceSucc (csRef< iEventHandlerRegistry > &, csRef< iEventNameRegistry > &, csEventID) const =0 |
| This function takes a csEventID as an argument and returns an array of csHandlerIDs identifying those event handlers which must, for the given event, only be called after this one. | |
Detailed Description
This interface describes an entity that can receive events.
Definition at line 39 of file eventh.h.
Member Function Documentation
| virtual csHandlerID iEventHandler::GenericID | ( | csRef< iEventHandlerRegistry > & | ) | const [pure virtual] |
This function returns a csHandlerID corresponding with GenericName, i.e., it should always return csHandlerRegistry::GetGenericID (this->GenericName()).
Normally, it will actually wrap a static method StaticID() which can be used to reference a class of event handlers abstractly without it having been instantiated. Usually, you will want to use the CS_EVENTHANDLER_NAMES macro instead of defining this yourself.
| virtual const char* iEventHandler::GenericName | ( | ) | const [pure virtual] |
This function returns a string which "names" this event handler generically (i.e., it identifies all instances of this event handler as a group).
For example, the core application logic would be "application", a window system plugin would be "crystalspace.windowsystem", etc. This is used, in combination with the GenericPrec, GenericSucc, InstancePrec, and InstanceSucc functions, by the subscription scheduler to establish the order in which event handlers are to be called.
Too bad C++ doesn't allow virtual static functions, because this would be one. To make up for this, it is conventional to also define a static method StaticHandlerName() which can be used to reference a class of event handlers abstractly without it having been instantiated, e.g., csBaseEventHandler::StaticHandlerName().
The csEventHandlerRegistry also uses this method to construct a unique instance name for each iEventHandler.
Usually, you will want to use the CS_EVENTHANDLER_NAMES macro instead of defining this yourself.
- See also:
- csHandlerRegistry::GetID
csHandlerRegistry::ReleaseID
| virtual const csHandlerID* iEventHandler::GenericPrec | ( | csRef< iEventHandlerRegistry > & | , | |
| csRef< iEventNameRegistry > & | , | |||
| csEventID | ||||
| ) | const [pure virtual] |
This function takes a csEventID as an argument and returns an array of csHandlerIDs identifying those event handlers which must, for the given event, only be called before this one (if they have been instantiated).
Should only return generic identifiers, not instance identifiers; in other words, every member of the array should be the result of a call to csHandlerRegistry::GetGenericID("name"), where "name" may be some class's static GenericName() function or a literal string.
This should also be a "virtual static" function, but C++ doesn't have them.
Implemented in FrameSignpost_Logic3D, FrameSignpost_3D2D, FrameSignpost_2DConsole, FrameSignpost_ConsoleDebug, and FrameSignpost_DebugFrame.
| virtual const csHandlerID* iEventHandler::GenericSucc | ( | csRef< iEventHandlerRegistry > & | , | |
| csRef< iEventNameRegistry > & | , | |||
| csEventID | ||||
| ) | const [pure virtual] |
This function takes a csEventID as an argument and returns an array of csHandlerIDs identifying those event handlers which must, for the given event, only be called after this one (if the have been instantiated).
Should only return generic identifiers, not instance identifiers; in other words, every member of the array should be the result of a call to csHandlerRegistry::GetGenericID("name"), where "name" may be some class's static GenericString() function or a literal string.
This should also be a "virtual static" function, but C++ doesn't have them.
Implemented in FrameSignpost_Logic3D, FrameSignpost_3D2D, FrameSignpost_2DConsole, FrameSignpost_ConsoleDebug, and FrameSignpost_DebugFrame.
| virtual bool iEventHandler::HandleEvent | ( | iEvent & | ) | [pure virtual] |
This is the basic event handling function.
To receive events, a component must implement iEventHandler and register with an event queue using iEventQueue::RegisterListener() and iEventQueue::Subscribe(). The event handler should return true if the event was handled. Returning true prevents the event from being passed along to other event handlers (unless the event's Broadcast flag has been set, in which case it is sent to all subscribers regardless of the return value). If the event was not handled, then false should be returned, in which case other event handlers are given a shot at the event. Do not return true unless you really handled the event and want event dispatch to stop at your handler.
Implemented in csGraphics2D, csInputBinder, FrameBegin3DDraw, FramePrinter, csEventQueue::iTypedFrameEventDispatcher, csKeyboardDriver, csJoystickDriver, and iFrameEventSignpost.
| virtual const csHandlerID* iEventHandler::InstancePrec | ( | csRef< iEventHandlerRegistry > & | , | |
| csRef< iEventNameRegistry > & | , | |||
| csEventID | ||||
| ) | const [pure virtual] |
This function takes a csEventID as an argument and returns an array of csHandlerIDs identifying those event handlers which must, for the given event, only be called before this one.
May include both generic and instance identifiers, i.e., the results of both csHandlerRegistry::GetGenericID() and csHandlerRegistry::GetID() calls.
If the instance constraints are the same as the generic ones, use ths CS_EVENTHANDLER_DEFAULT_INSTANCE_CONSTRAINTS macro instead of defining this for yourself.
| virtual const csHandlerID* iEventHandler::InstanceSucc | ( | csRef< iEventHandlerRegistry > & | , | |
| csRef< iEventNameRegistry > & | , | |||
| csEventID | ||||
| ) | const [pure virtual] |
This function takes a csEventID as an argument and returns an array of csHandlerIDs identifying those event handlers which must, for the given event, only be called after this one.
May include both generic and instance identifiers, i.e., the results of both csHandlerRegistry::GetGenericID() and csHandlerRegistry::GetID() calls.
If the instance constraints are the same as the generic ones, use ths CS_EVENTHANDLER_DEFAULT_INSTANCE_CONSTRAINTS macro instead of defining this for yourself.
The documentation for this struct was generated from the following file:
- iutil/eventh.h
Generated for Crystal Space by doxygen 1.4.7