bx-lib : the Basic X11 Library tuned for C beginners  1.0
Functions
Actively reading the current state of the keyboard
Input Control (how to deal with mouse and keyboard)

Functions

bx_key bx_read_key (void)
int bx_keyname_pressed (bx_key key, char keyname[])
int bx_keycode_pressed (bx_key key, unsigned char keycode)
unsigned char bx_keyname_to_keycode (char keyname[])
char * bx_keycode_to_keyname (unsigned char keycode)
char * bx_keynames (bx_key key)
int bx_key_number (bx_key key)
void bx_set_autorepeat (int activate)
int bx_get_autorepeat (void)

Detailed Description

Function Documentation

bx_key bx_read_key ( void  )

Takes an instantaneous snapshot of the current state of the whole keyboard, that is, the state pressed/released of all its keys.

Returns
the snapshot of the keyboard
Remarks
int bx_keyname_pressed ( bx_key  key,
char  keyname[] 
)

Checks if a key known by its keyname is pressed in a given keyboard snapshot.

Parameters
keya snapshot of the keyboard returned by bx_read_key().
keynamethe name of a given key of the keyboard.
Returns
whether the key is pressed (= 1) or released (= 0).
Remarks
  • see also bx_keynames() for a list of the names of all pressed keys.
  • if keys named "Shift" and "x" are pressed, then they are both reported as such individually, but keep in mind there is no such key named as "X" for example.
  • You use bx_keyname_pressed() instead of bx_keycode_pressed() when you want to know if the key named "a" is pressed whatever the keyboard mapping (AZERTY, QWERTY, etc...), that is, whatever the keycode is attributed for the key named "a".
int bx_keycode_pressed ( bx_key  key,
unsigned char  keycode 
)

Checks if a key known by its keycode is pressed in a given keyboard snapshot. The keycode is a number given to key depending on its physical location on the keyboard.

Parameters
keya snapshot of the keyboard returned by bx_read_key().
keycodea keycode describing the physical location of a key.
Returns
whether the key is pressed (= 1) or released (= 0).
Remarks
  • see also bx_keynames() for a list of the names of all pressed keys.
  • if keys named "Shift" and "x" are pressed, then they are both reported as such individually, but keep in mind there is no such key named as "X" for example.
    • You use bx_keycode_pressed() instead of bx_keyname_pressed() when you want to know if this key located in the region of the top-left corner of the keyboard is pressed, whatever keyname is mapped onto it (such as a "a" on AZERTY mappings, or a "q" for QWERTY mappings, etc...).
  • For example, on AZERTY mappings, key named "Q", "S", "D", and "Z" are physically located in a way that make them easy to use them as arrows (left, down, right and up) in a game. This is not the case on QWERTY mappings, so for such a use, you may want to use bx_keycode_pressed() instead of bx_keyname_pressed().
unsigned char bx_keyname_to_keycode ( char  keyname[])

Given a key named keyname, returns its keycode, that its physical location on the keyboard with respect to the installed key mapping (AZERTY, QWERTY, ...)

Parameters
keynamea name describing a key
Returns
the keycode of this key, or 0 if no such key exists.
char* bx_keycode_to_keyname ( unsigned char  keycode)

Given a physical location on the keyboard described by keycode, returns its keyname, that is, the attribution of this key with respect the installed key mapping (AZERTY, QWERTY, ...)

Parameters
keycodea keycode describing the physical location of a key.
Returns
the keyname of this key, or NULL if no such key exists.
Remarks
  • you do not own the returned string, so you must not write over it, and you must not call free() on it.
char* bx_keynames ( bx_key  key)

Returns a string listing the names of all keys that are pressed in the given snapshot.

Parameters
keya snapshot of the keyboard returned by bx_read_key().
Returns
a string listing the keynames, separated by spaces.
Remarks
  • you do not own the returned string, so you must not write over it, and you must not call free() on it.
  • also, the same string is shared for all the calls to this function, so you have to strcpy() the results if you want to keep track of calls older than the last one.
int bx_key_number ( bx_key  key)

Gets the number of key that are pressed in a given keyboard snapshot.

Parameters
keya snapshot of the keyboard returned by bx_read_key().
Returns
the number of keys that are pressed in the snapshot.
void bx_set_autorepeat ( int  activate)

Sets the autorepeat mode of the keyboard on or off. When on, if a key is kept physically pressed after a certain amount of time, the system cyclically reports "fake" couples of release/press states. In bx-lib, autorepeat is off by default, thaty is, bx-lib ignores the "fake" states reported by X11.

Parameters
activatesets autorepeat mode on (non zero) or off (zero).
Returns
nothing
Remarks
  • bx-lib never asks X11 to stop to emit "fake" reports. It only ignores them when it wants to. If bx-lib did such a thing, it would only be possible at a global level, that is, other X11 applications would also be deprived of the "fake" reports", a thing we certainly do not want (pressing continously the space-bar in a text editor unrelated to the program would be without the desired effect for example).
  • Conversely, bx-lib never force X11 to emit "fake" reports, it just does not ignore them when it wants to. So, if another application asks X11 to stop to emit "fake" reports, or if the user does the same with the unix command "xset r off", a call to bx_set_autorepeat (1) has no visible effect because we bx-lib just stops to ignore "fake" reports that never happen.
int bx_get_autorepeat ( void  )

Checks whether autorepeat mode for the keyboard is on or off.

Returns
autorepeat on (= 1), or autorepeat off (= 0).