CrystalSpace

Public API Reference

Public Member Functions | Static Public Member Functions | Friends
csInputDefinition Class Reference

This class holds a description of a physical source of input events, such as a keyboard key, mouse or joystick button, or a mouse or joystick axis. More...

#include <csutil/inputdef.h>

List of all members.

Public Member Functions

int Compare (csInputDefinition const &) const
 Returns a number indicating the relation of the two definitions.
uint32 ComputeHash () const
 Generate a hash value from the object.
 csInputDefinition (iEventNameRegistry *name_reg, uint32 honorModifiers=0, bool useCookedCode=false)
 Default constructor.
 csInputDefinition (const csInputDefinition &other)
 Copy constructor.
 csInputDefinition (iEventNameRegistry *name_reg, iEvent *event, uint32 honorModifiers=0, bool useCookedCode=false)
 Construct an input description from an iEvent (usually a button).
 csInputDefinition (iEventNameRegistry *name_reg, iEvent *event, uint8 axis)
 Construct an input description from an iEvent (usually an axis).
 csInputDefinition (iEventNameRegistry *name_reg, const char *string, uint32 honorModifiers=0, bool useCookedCode=false)
 Construct an input description from a string.
const uint GetDeviceNumber () const
 Returns the (basis-0) device number of the description.
bool GetKeyCode (utf32_char &code, bool &isCooked) const
 Gives the key code of the description, assuming it is a keyboard type.
const csKeyModifiersGetModifiers () const
 Returns the keyboard modifiers of the description.
csEventID GetName () const
 Returns the event name of the description (a csev... constant).
int GetNumber () const
 Returns the numeric value of the description.
bool IsValid () const
 Returns a boolean indicating whether the object contains a valid input.
bool SetKeyCode (utf32_char code)
 Sets the key code of the description, assuming it is a keyboard type.
void SetModifiers (const csKeyModifiers &mods)
 Sets the keyboard modifiers of the description.
void SetName (csEventID n)
 Set the event type of the description (a csev... constant).
void SetNumber (int n)
 Sets the numeric value of the description.
csString ToString (bool distinguishModifiers=true) const
 Gets the string representation of the description.

Static Public Member Functions

static csString GetKeyString (iEventNameRegistry *reg, utf32_char code, const csKeyModifiers *mods, bool distinguishModifiers=true)
 Helper function to return a string (eg "Ctrl+A") from values describing a keyboard event.
static csString GetOtherString (iEventNameRegistry *reg, csEventID type, uint device, int num, const csKeyModifiers *mods, bool distinguishModifiers=true)
 Helper function to return a string (eg "MouseX", "Alt+Mouse1") from values describing a non-keyboard event.
static bool ParseKey (iEventNameRegistry *reg, const char *iStr, utf32_char *oKeyCode, utf32_char *oCookedCode, csKeyModifiers *oModifiers)
 Helper function to parse a string (eg.
static bool ParseOther (iEventNameRegistry *reg, const char *iStr, csEventID *oType, uint *oDevice, int *oNumeric, csKeyModifiers *oModifiers)
 Helper function to parse a string (eg "MouseX", "Alt+Mouse1") into values describing a non-keyboard event.

Friends

class csInputBinder

Detailed Description

This class holds a description of a physical source of input events, such as a keyboard key, mouse or joystick button, or a mouse or joystick axis.

Input string syntax
The general syntax for an input description string is:
[ Modifiers ] [ DeviceNumber ] DeviceAspect
Devices, device aspect
Input devices supported by CrystalSpace are joysticks (or more generally, game controllers), mice and the keyboard. In principle, multiple mice and joysticks are supported, hence the optional DeviceNumber to distinguish between devices. If omitted, the first device (number 0) is assumed. The device number is ignored for keyboard input.
The "device aspect" identifies what can actually produce input. For the keyboard, these are the keys. For mice and joysticks, these are buttons and axes.
Modifiers
Modifiers are combinations of certain keys that need to be pressed down together with the actual "input aspect".
The modifier string consists of one or more modifier names, listed below. After each name, a '+' or '-' must follow.
Modifier nameKey
LCtrlLeft "Control"
RCtrlRight "Control"
CtrlAny "Control"
LAltLeft "Alt"
RAltRight "Alt"
AltAny "Alt"
LShiftLeft "Shift"
RShiftRight "Shift"
ShiftAny "Shift"
NumNum Lock
ScrollScroll Lock
CapsCaps Lock
The difference between "left" resp. "right" and "any" modifiers is that, for "left" or "right", only exactly that modifier key is matched. For "any", either of the left or right modifier matches.
Examples with modifiers: Shift+A, LAlt+MouseButtonLeft.
Keyboard keys
A keyboard key can be classified as a "normal" or "special" key.
Normal keys are basically those that result in a character to be entered, such as 'A', '1', '.' etc. The input string is a UTF-8 encoded string, and non-ASCII characters are accepted as keys as well (e.g. 'Ä' which could be found on a German keyboard). Case does not matter, 'A' and 'a' is the same.
Since '+' and '-' could be confused with the characters used for modifier specification these two "normal" keys can also be specified with the strings "Plus" and "Minus".
Special keys are the other keys. They include keys such as the cursor keys, num pad keys, etc.
Available special key strings (in some cases, multiple strings are accepted for the same key):
  • Esc
  • Enter
  • Return
  • Tab
  • Back, BackSpace
  • Space
  • Up (cursor key)
  • Down (cursor key)
  • Left (cursor key)
  • Right (cursor key)
  • PgUp, PageUp
  • PgDn, PageDown
  • Home
  • End
  • Ins, Insert
  • Del, Delete
  • F1
  • F2
  • F3
  • F4
  • F5
  • F6
  • F7
  • F8
  • F9
  • F10
  • F11
  • F12
  • Print, PrntScrn
  • Pause
  • PadPlus
  • PadMinus
  • PadMult
  • PadDiv
  • Pad0
  • Pad1
  • Pad2
  • Pad3
  • Pad4
  • Pad5 (Numlock on), Center (Numlock off)
  • Pad6
  • Pad7
  • Pad8
  • Pad9
  • PadDecimal
  • PadEnter
  • Shift
  • LShift
  • RShift
  • Ctrl
  • LCtrl
  • RCtrl
  • Alt
  • LAlt
  • RAlt
  • Num
  • Caps
  • Scroll
Note 1: The modifier keys can also be used for "regular" input keys.
Note 2: In cooked mode, "Pad*" keys will not be recognised - the CrystalSpace input system converts them to the characters they represent (numbers etc.) resp. their associated "navigation" key (cursor keys etc.). For Pad5, the "cooked" key is Center.
Mouse input
Mice have buttons and axes.
The two mice axes are identified with MouseX and MouseY.
Buttons are identified by Mouse or MouseButton followed by either a name or a number.
Button nameNumber
MouseButtonLeft0
MouseButtonRight1
MouseButtonMiddle2
MouseWheelUp3
MouseWheelDown4
MouseButtonExtra15
MouseButtonExtra26
MouseHWheelLeft7
MouseHWheelRight8
Buttons beyond that can be accessed by number: MouseButton9, MouseButton10, and so on.
Joystick input
Joysticks have buttons and axes.
The joystick axes are identified by JoystickAxis followed by a number, such as JoystickAxis0 for the first axis.
Buttons are identified by Joystick or JoystickButton followed by the button number, such as JoystickButton3 for the fourth button.
Distinguishing devices
Especially in the case of joysticks multiple devices can usually be found attached to a computer. To distinguish between these prefix the device number to the input string, but after the modifiers.
Note that the numbering is totally arbitrary. Device 0 is probably some user-selected, "primary" input device. However, in general, you should allow some degree of user configurability when supporting multiple input devices is desired.
E.g. the fourth axis of the third joystick is 2JoystickAxis3, and its first button is 2JoystickButton0. Combined with modifiers you would get strings such as Ctrl+2JoystickButton0.

Definition at line 232 of file inputdef.h.


Constructor & Destructor Documentation

csInputDefinition::csInputDefinition ( iEventNameRegistry name_reg,
uint32  honorModifiers = 0,
bool  useCookedCode = false 
)

Default constructor.

Parameters:
name_regA pointer to the event name registry.
honorModifiersA bitmask of modifier keys that will be recognised.
useCookedCodeIf true, will use the cooked key code instead of raw.

Copy constructor.

csInputDefinition::csInputDefinition ( iEventNameRegistry name_reg,
iEvent event,
uint32  honorModifiers = 0,
bool  useCookedCode = false 
)

Construct an input description from an iEvent (usually a button).

Parameters:
name_regA pointer to the event name registry.
eventThe event to analyse for input data.
honorModifiersA bitmask of modifier keys that will be recognised.
useCookedCodeIf true, will use the cooked key code instead of raw.
csInputDefinition::csInputDefinition ( iEventNameRegistry name_reg,
iEvent event,
uint8  axis 
)

Construct an input description from an iEvent (usually an axis).

Parameters:
name_regA pointer to the event name registry.
eventThe event to analyse for input data.
axisEvents include all axes, so choose: 0 = x, 1 = y.
csInputDefinition::csInputDefinition ( iEventNameRegistry name_reg,
const char *  string,
uint32  honorModifiers = 0,
bool  useCookedCode = false 
)

Construct an input description from a string.

Parameters:
name_regA pointer to the event name registry.
stringThe string to parse, e.g. "mousebutton1", "shift+a".
honorModifiersA bitmask of modifier keys that will be recognised.
useCookedCodeIf true, will use the cooked key code instead of raw. More precisely, the syntax for string is (in EBNF):

Member Function Documentation

Returns a number indicating the relation of the two definitions.

Generate a hash value from the object.

const uint csInputDefinition::GetDeviceNumber ( ) const [inline]

Returns the (basis-0) device number of the description.

Definition at line 357 of file inputdef.h.

bool csInputDefinition::GetKeyCode ( utf32_char code,
bool &  isCooked 
) const [inline]

Gives the key code of the description, assuming it is a keyboard type.

Parameters:
codeWill be set to the key code.
isCookedWill be set to true if the code is cooked, false if raw.
Returns:
False if the description is not a keyboard type.

Definition at line 328 of file inputdef.h.

static csString csInputDefinition::GetKeyString ( iEventNameRegistry reg,
utf32_char  code,
const csKeyModifiers mods,
bool  distinguishModifiers = true 
) [static]

Helper function to return a string (eg "Ctrl+A") from values describing a keyboard event.

Parameters:
regA pointer to the event name registry.
codeThe key code, treated as a raw code although raw vs. cooked doesn't matter here.
modsThe keyboard modifiers. Will be ignored if 0.
distinguishModifiersWhether to output distinguished modifiers (eg. "LCtrl" as opposed to just "Ctrl").
Returns:
The description string.

Returns the keyboard modifiers of the description.

Definition at line 354 of file inputdef.h.

Returns the event name of the description (a csev... constant).

Definition at line 317 of file inputdef.h.

int csInputDefinition::GetNumber ( ) const [inline]

Returns the numeric value of the description.

Returns:
If non-keyboard button event, the button number. If axis event, the axis number (0 = x, 1 = y).

Definition at line 344 of file inputdef.h.

static csString csInputDefinition::GetOtherString ( iEventNameRegistry reg,
csEventID  type,
uint  device,
int  num,
const csKeyModifiers mods,
bool  distinguishModifiers = true 
) [static]

Helper function to return a string (eg "MouseX", "Alt+Mouse1") from values describing a non-keyboard event.

Parameters:
regA pointer to the event name registry.
typeThe event type of the description (a csev... identifier).
deviceFor mouse and joystick events, the device number, basis 0 (first mouse is 0, second joystick is 1, etc).
numFor button events, the button number. For axis events, the axis number (0 = x, 1 = y).
modsThe keyboard modifiers. Will be ignored if 0.
distinguishModifiersWhether to output distinguished modifiers (eg. "LCtrl" as opposed to just "Ctrl").
Returns:
The description string.

Returns a boolean indicating whether the object contains a valid input.

static bool csInputDefinition::ParseKey ( iEventNameRegistry reg,
const char *  iStr,
utf32_char oKeyCode,
utf32_char oCookedCode,
csKeyModifiers oModifiers 
) [static]

Helper function to parse a string (eg.

"Ctrl+A") into values describing a keyboard event, returning both raw and cooked key codes.

Parameters:
regA pointer to the event name registry.
iStrThe string to parse.
oKeyCodeWill be set to the raw code of the parsed description.
oCookedCodeWill be set to the cooked code of the description.
oModifiersThe modifiers of the description.
Returns:
Whether the string could be successfully parsed.
Remarks:
Any of the output parameters may be null, in which case they are ignored.
static bool csInputDefinition::ParseOther ( iEventNameRegistry reg,
const char *  iStr,
csEventID oType,
uint oDevice,
int *  oNumeric,
csKeyModifiers oModifiers 
) [static]

Helper function to parse a string (eg "MouseX", "Alt+Mouse1") into values describing a non-keyboard event.

Parameters:
regA pointer to the event name registry.
iStrThe string to parse.
oTypeWill be set to the event name of the description (a csev... identifier).
oDeviceFor mouse and joystick events, will be set to the device number, basis 0 (e.g., the third joystick device is "2").
oNumericFor button events, will be set to the button number. For axis events, will be set to the axis number (0 = x, 1 = y).
oModifiersWill be populated with the modifiers of the description.
Returns:
Whether the string could be successfully parsed.
Remarks:
Any of the output parameters may be null, in which case they are ignored.
bool csInputDefinition::SetKeyCode ( utf32_char  code) [inline]

Sets the key code of the description, assuming it is a keyboard type.

Definition at line 334 of file inputdef.h.

void csInputDefinition::SetModifiers ( const csKeyModifiers mods) [inline]

Sets the keyboard modifiers of the description.

Definition at line 360 of file inputdef.h.

void csInputDefinition::SetName ( csEventID  n) [inline]

Set the event type of the description (a csev... constant).

Definition at line 320 of file inputdef.h.

void csInputDefinition::SetNumber ( int  n) [inline]

Sets the numeric value of the description.

Parameters:
nIf non-keyboard button event, the button number. If axis event, the axis number (0 = x, 1 = y).

Definition at line 351 of file inputdef.h.

csString csInputDefinition::ToString ( bool  distinguishModifiers = true) const

Gets the string representation of the description.

Parameters:
distinguishModifiersIf false, left and right modifiers will be output as plain-old modifiers (e.g. "LAlt" and "RAlt" become just "Alt").
Returns:
The string representation of the description (e.g. "mousebutton1", "shift+a").

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

Generated for Crystal Space 2.0 by doxygen 1.7.6.1