CrystalSpace

Public API Reference

Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

Event handling


Classes

class  csBaseEventHandler
 Base implementation of a generic event handler. More...
struct  csCommandEventData
 Structure that collects the data a command event carries. More...
struct  csJoystickEventData
 Structure that collects the data a joystick event carries. More...
struct  csKeyEventData
 Structure that collects the data a keyboard event carries. More...
struct  csMouseEventData
 Structure that collects the data a mouse event carries. More...
struct  iEvent
 This interface describes any system event. More...
struct  iEventAttributeIterator
 Event attribute iterator. More...
struct  iEventAttributeIterator
 Event attribute iterator. More...
struct  iEventCord
 The iEventCord is an interface provided by an event queue to any event handlers wanting to receive some subclasses of events ASAP in a specified priority, bypassing the queue itself. More...
struct  iEventCord
 The iEventCord is an interface provided by an event queue to any event handlers wanting to receive some subclasses of events ASAP in a specified priority, bypassing the queue itself. More...
struct  iEventHandler
 This interface describes an entity that can receive events. More...
struct  iEventHandler
 This interface describes an entity that can receive events. More...
struct  iEventOutlet
 The iEventOutlet is the interface to an object that is provided by an event queue to every event plug when it registers itself. More...
struct  iEventOutlet
 The iEventOutlet is the interface to an object that is provided by an event queue to every event plug when it registers itself. More...
struct  iEventPlug
 Event plug interface, also referred as "event source". More...
struct  iEventPlug
 Event plug interface, also referred as "event source". More...
struct  iEventQueue
 This interface represents a general event queue. More...
struct  iEventQueue
 This interface represents a general event queue. More...
struct  iJoystickDriver
 Generic Joystick driver. More...
struct  iJoystickDriver
 Generic Joystick driver. More...
struct  iKeyboardDriver
 Generic Keyboard Driver. More...
struct  iKeyboardDriver
 Generic Keyboard Driver. More...
struct  iKeyComposer
 Keyboard input handler. More...
struct  iKeyComposer
 Keyboard input handler. More...
struct  iMouseDriver
 Generic Mouse Driver. More...
struct  iMouseDriver
 Generic Mouse Driver. More...

Defines

#define _CSBASEEVENT_MAXARRAYINDEX   csevFrameStart
#define CS_MAX_JOYSTICK_AXES   8
 Maximal number of joystick axes supported.
#define CS_MAX_JOYSTICK_BUTTONS   10
 Maximal number of joystick buttons supported.
#define CS_MAX_JOYSTICK_COUNT   16
 Maximal number of joysticks supported.
#define CS_MAX_MOUSE_AXES   8
 Maximal number of mouse axes supported.
#define CS_MAX_MOUSE_BUTTONS   10
 Maximal number of mouse buttons supported.
#define CS_MAX_MOUSE_COUNT   4
 Maximal number of mice supported.

Typedefs

typedef enum _csEventType csEventType
 System Events.
typedef enum _csKeyEventType csKeyEventType
 Keyboard event type.

Enumerations

enum  _csEventType {
  csevNothing = 0, csevKeyboard, csevMouseMove, csevMouseDown,
  csevMouseUp, csevMouseClick, csevMouseDoubleClick, csevJoystickMove,
  csevJoystickDown, csevJoystickUp, csevCommand, csevBroadcast,
  csevMouseEnter, csevMouseExit, csevLostFocus, csevGainFocus,
  csevGroupOff, csevFrameStart
}
 System Events. More...
enum  _csKeyEventType { csKeyEventTypeUp = 0, csKeyEventTypeDown }
 Keyboard event type. More...
enum  csEventAttributeType {
  csEventAttrUnknown, csEventAttrInt, csEventAttrUInt, csEventAttrFloat,
  csEventAttrDatabuffer, csEventAttrEvent, csEventAttriBase
}
 Various attribute data types supported by the event system (iEvent). More...
enum  csEventError {
  csEventErrNone, csEventErrLossy, csEventErrNotFound, csEventErrMismatchInt,
  csEventErrMismatchUInt, csEventErrMismatchFloat, csEventErrMismatchBuffer, csEventErrMismatchEvent,
  csEventErrMismatchIBase, csEventErrUhOhUnknown
}
 Error codes for event attribute retrieval. More...
enum  csKeyComposeResult { csComposeNoChar = -1, csComposeNormalChar, csComposeComposedChar, csComposeUncomposeable }
 Results for attempts to process a character key. More...
enum  csMouseButton {
  csmbLeft = 1, csmbRight = 2, csmbMiddle = 3, csmbWheelUp = 4,
  csmbWheelDown = 5, csmbExtra1 = 6, csmbExtra2 = 7
}
 Constants for mouse buttons. More...

Keyboard events

Keyboard events are emitted when the user does something with the keyboard - presses down a key ("key down" events), holds it down (more "key down" events in a specific interval - "auto-repeat") and releases it ("key up").

Every keyboard event has a bunch of data associated with it. First, there is a code to identify the key: the 'raw' code. It uniquely identifies the key, and every key has a distinct code, independent from any pressed modifiers: For example, pressing the "A" key will always result in the raw code 'a', holding shift or any other modifier down won't change it. However, the 'cooked' code contains such additional information: If Shift+A is pressed, the cooked code will be 'A', while the raw code is still 'a'. Other keys are also normalized; for example keypad keys: pressing "9" will result in either CSKEY_PGUP or '9', depending on the NumLock state. So, the same key can result in different 'cooked' codes, and the same 'cooked' code can be caused by different keys.

Other data contained in a keyboard event is:

Keyboard event data is stored as properties of iEvent, accessible thorugh iEvent->Find() and iEvent->Add().
Property NameType Description
keyEventTypecsKeyEventType (stored as uint8) Event type (up vs down)
keyCodeRawuint32Raw key code
keyCodeCookeduint32Cooked key code
keyModifierscsKeyModifiersModifiers at time of the key press
keyAutoRepeatboolAutorepeat flag
keyCharTypecsKeyCharType (stored as uint8) Character type

A way to retrieve an keyboard event's data without requiring a plethora of iEvent->Find() invocations provides the csKeyEventHelper class.

Also see iKeyComposer for informations about composing accented etc. characters from dead and normal keys.

Overall structure of the basic event flow in Crystal Space

   ......................
   .User application    .
   . +----------------+ .
 +-->+ Event consumer | .
 | . +----------------+ .
 | ......................
 |
 | .....................................
 | .System driver plugin               .
 | .                          +------+ .   +-----+
 | .                       +<-|event +-<<--+event|
 | .   +---------------+   |  |outlet| .   |plug |
 +-----+  event queue  +<--+  +------+ .   +-----+
 | .   +---------------+   |  +------+ .   +-----+
 | .                       +<-|event +-<<--+event|
 | .   +---------------+   |  |outlet| .   |plug |
 +-----+ event cord    +<--|  +------+ .   +-----+
   .   +---------------+   |  +------+ .   +-----+
   .                       +<-|event +-<<--+event|
   .                          |outlet| .   |plug |
   .                          +------+ .   +-----+
   .                            ....   .     ...
   .....................................
 
The events are generated by 'event plugs' which are plugged into 'event outlets'. The event outlets are reponsible for filtering the possibly duplicate messages that are coming from different event plugs (for example two different plugs may both intercept the keyboard and generate duplicate keydown events).

Events are put into the event queue, from where they are sent to applications and plugins. Event cords bypass the queue for specific command event categories and deliver events immediately in a prioritizied chain to specific plugins which request the categories.


Define Documentation

#define CS_MAX_JOYSTICK_AXES   8
 

Maximal number of joystick axes supported.

Definition at line 47 of file event.h.

#define CS_MAX_JOYSTICK_BUTTONS   10
 

Maximal number of joystick buttons supported.

Definition at line 45 of file event.h.

Referenced by csJoystickDriver::GetLastButton().

#define CS_MAX_JOYSTICK_COUNT   16
 

Maximal number of joysticks supported.

Definition at line 43 of file event.h.

Referenced by csJoystickDriver::GetLastButton().

#define CS_MAX_MOUSE_AXES   8
 

Maximal number of mouse axes supported.

Definition at line 39 of file event.h.

#define CS_MAX_MOUSE_BUTTONS   10
 

Maximal number of mouse buttons supported.

Definition at line 41 of file event.h.

Referenced by csMouseDriver::GetLastButton().

#define CS_MAX_MOUSE_COUNT   4
 

Maximal number of mice supported.

Definition at line 37 of file event.h.

Referenced by csMouseDriver::GetLastButton().


Typedef Documentation

typedef enum _csEventType csEventType
 

System Events.

typedef enum _csKeyEventType csKeyEventType
 

Keyboard event type.


Enumeration Type Documentation

enum _csEventType
 

System Events.

Enumerator:
csevNothing  Nothing happened.
csevKeyboard  A keyboard event (key down/up).

See also:
csKeyEventHelper

csKeyEventType

csevMouseMove  Mouse has been moved.
csevMouseDown  A mouse button has been pressed.
csevMouseUp  A mouse button has been released.
csevMouseClick  A mouse button has been clicked.
csevMouseDoubleClick  A mouse button has been clicked twice.
csevJoystickMove  A joystick axis has been moved.
csevJoystickDown  A joystick button has been pressed.
csevJoystickUp  A joystick button has been released.
csevCommand  Somebody(-thing) sent a command.

See also:
csCommandEventData
csevBroadcast  Somebody(-thing) sent a broadcast command.
csevMouseEnter  The mouse has entered a component.
csevMouseExit  The mouse has exited a component.
csevLostFocus  The component has lost keyboard focus.
csevGainFocus  The component has gained keyboard focus.
csevGroupOff  A component in a group has been selected, everyone else should go to their off state.
csevFrameStart  The frame is about to draw.

Definition at line 40 of file evdefs.h.

enum _csKeyEventType
 

Keyboard event type.

Enumerator:
csKeyEventTypeUp  A 'key down' event.
csKeyEventTypeDown  A 'key up' event.

Definition at line 89 of file evdefs.h.

enum csEventAttributeType
 

Various attribute data types supported by the event system (iEvent).

Enumerator:
csEventAttrUnknown  The attribute type is unknown.

This shouldn't occur.

csEventAttrInt  A signed integer is contained.
csEventAttrUInt  An unsigned integer is contained.
csEventAttrFloat  A floating point number is contained.
csEventAttrDatabuffer  A string or raw data buffer is contained.
csEventAttrEvent  An iEvent is contained.
csEventAttriBase  An iBase interface is contained.

Definition at line 265 of file event.h.

enum csEventError
 

Error codes for event attribute retrieval.

Enumerator:
csEventErrNone  No error.
csEventErrLossy  The attribute value could be converted to the requested type, however, data was lost during the conversion.
csEventErrNotFound  The requested attribute was not found.
csEventErrMismatchInt  The contained value can not be converted to the requested type.

The error code indicates the actual contained type.

csEventErrMismatchUInt  The contained value can not be converted to the requested type.

The error code indicates the actual contained type.

csEventErrMismatchFloat  The contained value can not be converted to the requested type.

The error code indicates the actual contained type.

csEventErrMismatchBuffer  The contained value can not be converted to the requested type.

The error code indicates the actual contained type.

csEventErrMismatchEvent  The contained value can not be converted to the requested type.

The error code indicates the actual contained type.

csEventErrMismatchIBase  The contained value can not be converted to the requested type.

The error code indicates the actual contained type.

csEventErrUhOhUnknown  Unknown error.

Something doesn't work like it should.

Definition at line 235 of file event.h.

enum csKeyComposeResult
 

Results for attempts to process a character key.

Enumerator:
csComposeNoChar  No character could be retrieved. Possibly the key was dead.
csComposeNormalChar  A single, normal chararacter is retrieved.
csComposeComposedChar  A single, composed chararacter is retrieved.
csComposeUncomposeable  A key couldn't be combined with a previously pressed dead key, and both characters are returned individually.

Definition at line 43 of file csinput.h.

enum csMouseButton
 

Constants for mouse buttons.

Note: the possibly occuring values are not limited to those below, e.g. maybe some day 6-button mice are available...

Enumerator:
csmbLeft  Left button.
csmbRight  Right button.
csmbMiddle  Middle button.
csmbWheelUp  Wheel was scrolled up.
csmbWheelDown  Wheel was scrolled up.
csmbExtra1  Thumb button 1 (e.g. on 5-button mice).
csmbExtra2  Thumb button 2 (e.g. on 5-button mice).

Definition at line 150 of file event.h.


Generated for Crystal Space by doxygen 1.4.4