CrystalSpace

Public API Reference

iEventOutlet Struct Reference
[Event handling]

The iEventOutlet is the interface to an object that is provided by an event queue to every event plug when it registers itself. More...

#include <iutil/event.h>

Inheritance diagram for iEventOutlet:

List of all members.

Public Member Functions

virtual void Broadcast (csEventID iName, intptr_t iInfo=0)=0
 Put a broadcast event into event queue.
virtual csPtr< iEventCreateEvent ()=0
 Create a event object on behalf of the event queue.
virtual void ImmediateBroadcast (csEventID iName, intptr_t iInfo)=0
 This is a special routine which is called for example when the application is going to be suspended (suspended means "frozen", that is, application is forced to not run for some time).
virtual void Joystick (uint iNumber, int iButton, bool iDown, const int32 *axes, uint numAxes)=0
 Put a joystick event into event queue.
virtual void Key (utf32_char codeRaw, utf32_char codeCooked, bool iDown, bool autorep=false)=0
 Put a keyboard event into event queue.
virtual void Mouse (int iButton, bool iDown, int x, int y)=0
 Put a mouse event into event queue.
virtual void Post (iEvent *)=0
 Put a previously created event into system event queue.

Detailed Description

The iEventOutlet is the interface to an object that is provided by an event queue to every event plug when it registers itself.

Any event plug will interact with event outlet to put events into system queue and so on.

The event queue is responsible for detecting potentially conflicting situations when several event plugs may generate a event from same original event (e.g. a key press will cause several keydown events coming from several event source plugins). In this case the event sources are queried for how strong their "wish" to generate certain types of events is, and the one with the strongest "wish" wins. Then the respective outlet is set up such that any unwanted events coming from 'disqualified' event plugs are discarded.

Definition at line 439 of file event.h.


Member Function Documentation

virtual void iEventOutlet::Broadcast ( csEventID  iName,
intptr_t  iInfo = 0 
) [pure virtual]

Put a broadcast event into event queue.

This is a generalized way to put any broadcast event into the system event queue. Command code may be used to tell user application that application's focused state has changed (e.g. csevFocusGained), that a graphics context has been resized (e.g. csevCanvasResize), that it has been closed (e.g. csevCanvasClose), to finish the application immediately (e.g. csevQuit) and so on.

virtual csPtr<iEvent> iEventOutlet::CreateEvent (  )  [pure virtual]

Create a event object on behalf of the event queue.

A general function for generating virtually any type of event. Since all events for a particular event queue should be created from the same heap, you should generate first a event object (through CreateEvent method) then you fill it whatever you like and finally you insert it into the event queue with the Post() method.

virtual void iEventOutlet::ImmediateBroadcast ( csEventID  iName,
intptr_t  iInfo 
) [pure virtual]

This is a special routine which is called for example when the application is going to be suspended (suspended means "frozen", that is, application is forced to not run for some time).

This happens for example when user switches away from a full-screen application on any OS with MGL canvas driver, or when it presses <Pause> with the OS/2 DIVE driver, or in any other drivers that supports forced pausing of applications.

This generates a `normal' broadcast event with given command code; the crucial difference is that the event is being delivered to all clients *immediately*. The reason is that the application is frozen right after returning from this routine thus it will get the next chance to process any events only after it will be resumed (which is kind of too late to process this kind of events).

virtual void iEventOutlet::Joystick ( uint  iNumber,
int  iButton,
bool  iDown,
const int32 axes,
uint  numAxes 
) [pure virtual]

Put a joystick event into event queue.

iNumber is joystick number (from 0 to CS_MAX_JOYSTICK_COUNT-1).

If iButton == 0, this is a joystick move event and iDown is ignored. numAxes can be from 1 to CS_MAX_JOYSTICK_AXES. Otherwise an joystick up/down event is generated. iButton can be from 1 to CS_MAX_JOYSTICK_BUTTONS (or 0 for a joystick move event).

virtual void iEventOutlet::Key ( utf32_char  codeRaw,
utf32_char  codeCooked,
bool  iDown,
bool  autorep = false 
) [pure virtual]

Put a keyboard event into event queue.

Note that codeRaw is the key code, either the alphanumeric symbol that is emmited by the given key when no shift keys/modes are active (e.g. 'a', 'b', '.', '/' and so on) or one of CSKEY_XXX values (with value above 255) and the codeCooked parameter is the translated key, after applying all modeshift keys.

If you pass 0 as codeCooked, a synthesized value is created based upon codeRaw using an simple internal translation table that takes care of Control/Shift/Alt for English characters. However, in general, it is best if the entity posting the event can provide both codes.

virtual void iEventOutlet::Mouse ( int  iButton,
bool  iDown,
int  x,
int  y 
) [pure virtual]

Put a mouse event into event queue.

If iButton == 0, this is a mouse motion event, and iDown argument is ignored. Otherwise an mousedown or mouseup event is generated at respective location. iButton can be in the range from 1 to CS_MAX_MOUSE_BUTTONS (or 0 for mouse move event).

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

Put a previously created event into system event queue.

Remarks:
The event you pass to this method should be heap-allocated rather than stack-allocated since the event will be queued for later dispatch and because receivers of the event may claim their own references to it. The typical way to create a heap-allocated event is with iEventQueue::CreateEvent(), iEventOutlet::CreateEvent(), or via the C++ 'new' operator. The CreateEvent() methods have the benefit that they pool "dead" events and re-issue them to you when needed, thus they are quite efficient.

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

Generated for Crystal Space 1.4.1 by doxygen 1.7.1