- All Superinterfaces:
- iBase, iPointer
- All Known Implementing Classes:
- public interface iEventQueue
- extends iBase
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
- Java wrapper - Quentin Anciaux, c++ version -
public void changeListenerTrigger(iEventHandler handler,
- Change a listener's trigger. See RegisterListener(); for a discussion of
the trigger. Implemented in csEventQueue.
public void clear()
- Clear event queue. Implemented in csEventQueue.
public iEvent createEvent(byte type)
- Create an event, from the pool if there are any free events available.
Else create a new event in the pool and use it. Implemented in
public iEventOutlet createEventOutlet(iEventPlug plug)
- 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. Implemented in
public void dispatch(iEvent event)
- 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();. Implemented in csEventQueue.
public iEvent get()
- 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.
Implemented in csEventQueue.
public iEventCord getEventCord(int Category,
- 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. Implemented in
public iEventOutlet getEventOutlet()
- 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. Implemented
public boolean isEmpty()
- Query if queue is empty. Implemented in csEventQueue.
public void post(iEvent event)
- 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. Implemented in csEventQueue.
public void process()
- 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. Implemented in csEventQueue.
public void registerListener(iEventHandler handler,
- Register a listener for specific events. If the listener is already
registered, then this method merely changes the listener's `trigger'. The
`trigger' argument is a combination of the CSMASK_XXX event triggers
defined in iutil/evdefs.h. Multiple triggers may be specified by combining
them with the bitwise "or" operator (`|');. The CSMASK_Nothing event
trigger is special. If registered with this trigger, the listener will be
called in just before Process(); iterates over the event queue, and then
it will be called with 3 different csevBroadcast events after has been
dispatched the last event. In this case, the listener will be sent an
csevBroadcast event with the Event.Command.Code equal to cscmdPreProcess
before events dispatching, and after events dispatching the listener will
receive three csevBroadcast events, in 3 successive phases, following this
ordering: the first broadcasted event has the Event.Command.Code equal to
cscmdProcess, then the second broadcasted event has a value of
cscmdPostProcess and finally the last event broadcasted has the
cscmdFinalProcess value . Implemented in csEventQueue.
public void removeAllListeners()
- 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. Implemented in csEventQueue.
public void removeListener(iEventHandler handler)
- Unregister a listener. It is important to call RemoveListener(); before
deleting your event handler! Implemented in csEventQueue.