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...
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 csKeyModifiers & | GetModifiers () 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 |
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 name | Key |
LCtrl | Left "Control" |
RCtrl | Right "Control" |
Ctrl | Any "Control" |
LAlt | Left "Alt" |
RAlt | Right "Alt" |
Alt | Any "Alt" |
LShift | Left "Shift" |
RShift | Right "Shift" |
Shift | Any "Shift" |
Num | Num Lock |
Scroll | Scroll Lock |
Caps | Caps 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 name | Number |
MouseButtonLeft | 0 |
MouseButtonRight | 1 |
MouseButtonMiddle | 2 |
MouseWheelUp | 3 |
MouseWheelDown | 4 |
MouseButtonExtra1 | 5 |
MouseButtonExtra2 | 6 |
MouseHWheelLeft | 7 |
MouseHWheelRight | 8 |
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.