CrystalSpace

Public API Reference

iEventQueue Struct Reference
[Event handling]

This interface represents a general event queue. More...

#include <iutil/eventq.h>

Inheritance diagram for iEventQueue:

List of all members.

Public Member Functions

virtual void Clear ()=0
 Clear event queue.
virtual csPtr< iEventCreateBroadcastEvent (const csEventID &name)=0
 Create an event with the broadcast flag set.
virtual csPtr< iEventCreateEvent (const csEventID &name)=0
 Create an event, from the pool if there are any free events available.
virtual csPtr< iEventOutletCreateEventOutlet (iEventPlug *)=0
 Register an event plug and return a new outlet.
virtual void Dispatch (iEvent &)=0
 Dispatch a single event from the queue.
virtual csPtr< iEventGet ()=0
 Get next event from queue; returns a null reference if no events are present.
virtual iEventCordGetEventCord (const csEventID &name)=0
 Get the event cord for a given category and subcategory.
virtual iEventOutletGetEventOutlet ()=0
 Get a public event outlet for posting just an event.
virtual bool IsEmpty ()=0
 Query if queue is empty.
virtual void Post (iEvent *)=0
 Place an event into queue.
virtual void Process ()=0
 Process the event queue.
virtual csHandlerID RegisterListener (iEventHandler *)=0
 Register a listener with the event scheduling subsystem.
virtual csHandlerID RegisterListener (iEventHandler *, const csEventID &ename)=0
 Convenient shorthand for RegisterListener() followed by Subscribe().
virtual csHandlerID RegisterListener (iEventHandler *, const csEventID ename[])=0
 Convenient shorthand for RegisterListener() followed by Subscribe().
virtual void RemoveAllListeners ()=0
 Unregister all listeners.
virtual void RemoveListener (iEventHandler *)=0
 Unregister a listener and drop all of its subscriptions.
virtual bool Subscribe (iEventHandler *, const csEventID ename[])=0
 Subscribe an event listener to a given list of event subtrees.
virtual bool Subscribe (iEventHandler *, const csEventID &ename)=0
 Subscribe an event listener to a given event subtree.
virtual void Unsubscribe (iEventHandler *, const csEventID &)=0
 Unsubscribe an event listener from a particular set of event subtrees.
virtual void Unsubscribe (iEventHandler *, const csEventID[])=0
 Unsubscribe an event listener from a particular event subtree.

Detailed Description

This interface represents a general event queue.

Events may be posted to the queue by various sources. Listeners (implementing iEventHandler) can register to receive notification when various events are processed. Typically, one instance of this object is available from the shared-object registry (iObjectRegistry).

Main creators of instances implementing this interface:

Main ways to get pointers to this interface:

Definition at line 56 of file eventq.h.


Member Function Documentation

virtual void iEventQueue::Clear (  )  [pure virtual]

Clear event queue.

virtual csPtr<iEvent> iEventQueue::CreateBroadcastEvent ( const csEventID name  )  [pure virtual]

Create an event with the broadcast flag set.

Draw from the pool if any are available, else create a new event in the pool and use it.

virtual csPtr<iEvent> iEventQueue::CreateEvent ( const csEventID name  )  [pure virtual]

Create an event, from the pool if there are any free events available.

Else create a new event in the pool and use it.

virtual csPtr<iEventOutlet> iEventQueue::CreateEventOutlet ( iEventPlug  )  [pure virtual]

Register an event plug and return a new outlet.

Any module which generates events should consider using this interface for posting those events to the queue. The module should implement the iEventPlug interface and register that interface with this method. In return, an iEventOutlet object will be created which can be used to actually post events to the queue. It is the caller's responsibility to send a DecRef() message to the returned event outlet when it is no longer needed.

virtual void iEventQueue::Dispatch ( iEvent  )  [pure virtual]

Dispatch a single event from the queue.

This is normally called by Process() once for each event in the queue. Events are dispatched to the appropriate listeners (implementors of iEventHandler) which have been registered via RegisterListener().

virtual csPtr<iEvent> iEventQueue::Get (  )  [pure virtual]

Get next event from queue; returns a null reference if no events are present.

There is rarely any need to manually retrieve events from the queue. Instead, normal event processing via Process() takes care of this responsibility. iEventQueue gives up ownership of the returned iEvent.

virtual iEventCord* iEventQueue::GetEventCord ( const csEventID name  )  [pure virtual]

Get the event cord for a given category and subcategory.

This allows events to be delivered immediately, bypassing the normal event queue, to a chain of plugins that register with the implementation of iEventCord returned by this function. The category and subcategory are matched against the category and subcategory of each actual iEvent.

virtual iEventOutlet* iEventQueue::GetEventOutlet (  )  [pure virtual]

Get a public event outlet for posting just an event.

In general most modules should create their own private outlet via CreateEventOutlet() and register as a normal event plug. However, there are cases when you just need to post one event from time to time; in these cases it is easier to post it without the bulk of creating a new iEventPlug interface. In these cases, you can post the event by obtaining the shared event outlet from GetEventOutlet(), and use it to post an event instead.

virtual bool iEventQueue::IsEmpty (  )  [pure virtual]

Query if queue is empty.

virtual void iEventQueue::Post ( iEvent  )  [pure virtual]

Place an event into queue.

In general, clients should post events to the queue via an iEventOutlet rather than directly via Post(), however there may be certain circumanstances where posting directly to the queue is preferred.

Remarks:
Post() takes ownership of the event. That means that you MUST NOT DecRef() the event after passing it to Post(). Instead, if you want to keep it, IncRef() it.
virtual void iEventQueue::Process (  )  [pure virtual]

Process the event queue.

Calls Dispatch() once for each event in the queue in order to actually dispatch the event. Typically, this method is invoked by the host application on a periodic basis (often from the host's own event loop) in order to give Crystal Space modules a chance to run and respond to events.

virtual csHandlerID iEventQueue::RegisterListener ( iEventHandler  )  [pure virtual]

Register a listener with the event scheduling subsystem.

The handler will name itself via the iEventHandler::GetGenericID() method.

virtual csHandlerID iEventQueue::RegisterListener ( iEventHandler ,
const csEventID ename 
) [pure virtual]

Convenient shorthand for RegisterListener() followed by Subscribe().

virtual csHandlerID iEventQueue::RegisterListener ( iEventHandler ,
const csEventID  ename[] 
) [pure virtual]

Convenient shorthand for RegisterListener() followed by Subscribe().

virtual void iEventQueue::RemoveAllListeners (  )  [pure virtual]

Unregister all listeners.

Remarks:
This function is used to clear all listeners from the event queue stack. You should only call this function at the end of your program after the event queue processing has terminated.
If you make use of csInitializer::DestroyApplication(), this is done for you by that call.
virtual void iEventQueue::RemoveListener ( iEventHandler  )  [pure virtual]

Unregister a listener and drop all of its subscriptions.

It is important to call RemoveListener() before deleting your event handler!

virtual bool iEventQueue::Subscribe ( iEventHandler ,
const csEventID  ename[] 
) [pure virtual]

Subscribe an event listener to a given list of event subtrees.

The list shold be terminated with the CS_EVENTLIST_END token.

virtual bool iEventQueue::Subscribe ( iEventHandler ,
const csEventID ename 
) [pure virtual]

Subscribe an event listener to a given event subtree.

For example, subscribers to "crystalspace.input.keyboard" will receive "crystalspace.input.keyboard.up" and "crystalspace.input.keyboard.down" events. csEventIDs should be retrieved from csEventNameRegistry::GetID().

virtual void iEventQueue::Unsubscribe ( iEventHandler ,
const csEventID  
) [pure virtual]

Unsubscribe an event listener from a particular set of event subtrees.

This should only be called on event names which were used as arguments to Subscribe or RegisterListener; otherwise, the results are undefined. It is important to call RemoveListener() before deleting your event handler!

virtual void iEventQueue::Unsubscribe ( iEventHandler ,
const   csEventID[] 
) [pure virtual]

Unsubscribe an event listener from a particular event subtree.

This should only be called on an event name which was used as an argument to Subscribe or to RegisterListener; otherwise, the results are undefined.


The documentation for this struct was generated from the following file:

Generated for Crystal Space 1.4.1 by doxygen 1.7.1