Responding to Keyboard Events

OBJECTS

  typedef void (*keyfn)(control c, int key);

FUNCTIONS

  void setkeydown(control c, keyfn fn);		/* handle ASCII keys */
  void setkeyaction(control c, keyfn fn);	/* handle other keys */

  int  getkeystate();				/* keystate bit-field */

CONSTANTS

  #define BKSP    0x08      /* backspace key */
  #define ESC     0x1B      /* escape key */

  #define INS     0x2041    /* insert key */
  #define DEL     0x2326    /* delete key */
  #define HOME    0x21B8    /* home key */
  #define END     0x2198    /* end key */
  #define PGUP    0x21DE    /* page up key */
  #define PGDN    0x21DF    /* page down key */
  #define ENTER   0x2324    /* enter key on numeric keypad */

  #define LEFT    0x2190    /* left arrow key */
  #define UP      0x2191    /* up arrow key */
  #define RIGHT   0x2192    /* right arrow key */
  #define DOWN    0x2193    /* down arrow key */

  #define F1      0x276C    /* function key F1 */
  #define F2      0x276D    /* function key F2 */
  #define F3      0x276E    /* function key F3 */
  #define F4      0x276F    /* function key F4 */
  #define F5      0x2770    /* function key F5 */
  #define F6      0x2771    /* function key F6 */
  #define F7      0x2772    /* function key F7 */
  #define F8      0x2773    /* function key F8 */
  #define F9      0x2774    /* function key F9 */
  #define F10     0x2775    /* function key F10 */

  #define AltKey    0x0001  /* alt key mask */
  #define CmdKey    0x0001  /* Mac command key mask */
  #define CtrlKey   0x0002  /* ctrl key mask */
  #define OptionKey 0x0002  /* Mac option key mask */
  #define ShiftKey  0x0004  /* shift key mask */

NOTES

Keyboard events can be caught using the setkeydown and setkeyaction functions. The setkeydown function sets the call-back used to handle normal ASCII keys, including the return and escape keys. Other non-ASCII key values are sent to the setkeyaction call-back, such as when the user presses an arrow key or a function key.

Keyboard call-backs can be associated with controls or windows. Typically you should not use these functions with pre-defined controls such as buttons, fields etc, only with your own controls.

The call-back specified by the setkeydown function may be passed any of the following keys:

• Any normal ASCII key value which can generated by the keyboard.
• The value ESC is defined as the Escape key.
• The value BKSP is defined as the Backspace key.
• A newline character '\n' is sent when the main keyboard Enter or Return key is pressed (but not the numeric keypad Enter key).

To see other keyboard events, the setkeyaction function associates a call-back with a control or window. That call-back can see the following key values:

• INS, DEL, HOME, END, PGUP, PGDN which correspond to the keys Insert, Delete, Home, End, Page Up and Page Down.
• ENTER which is the Enter key on a numeric keypad. Note that this value is different from the normal ASCII return key, 0x0A or '\n' (newline).
• LEFT, UP, RIGHT, DOWN which are the arrow keys.
• F1, F2, F3, F4, F5, F6, F7, F8, F9, F10 which correspond to the Function keys on a keyboard. Note that there is currently no provision for Function keys higher than F10.

These values have been chosen from the Unicode font specification used for multi-byte fonts. The values are representative of various symbols associated with the above keys.

The getkeystate function can be used within any call-back to reveal the current state of the shift, control and alt keys. It returns a bit-field which is the bitwise-or of the following constants:

• AltKey which means a PC's Alt key is held down.
• CmdKey is the same field, and is just the Macintosh name for the Alt key.
• CtrlKey means the Control or Ctrl key held down.
• OptionKey is the same field, on the Macintosh.
• ShiftKey means the Shift is held down.

Hence, by using the bitwise-and operator & with the above constants, it is possible to discover which keys were held down when the getkeystate function was called.