Responding to Keyboard Events

OBJECTS

  typedef void (*KeyFunc)(Control *c, unsigned long key);

FUNCTIONS

  void  on_control_key_down  (Control *c, KeyFunc key_down);
  void  on_control_key_action(Control *c, KeyFunc key_action);

CONSTANTS

  enum {
    BELL  = 0x07,           /* ASCII bell character */
    BKSP  = 0x08,           /* ASCII backspace */
    VTAB  = 0x0B,           /* ASCII vertical tab */
    FF    = 0x0C,           /* ASCII form-feed */
    ESC   = 0x1B            /* ASCII escape character */
  };

  enum {
    INS   = 0x2041,         /* Insert key */
    DEL   = 0x2326,         /* Delete key */
    HOME  = 0x21B8,         /* Home key */
    END   = 0x2198,         /* End key */
    PGUP  = 0x21DE,         /* Page Up key */
    PGDN  = 0x21DF,         /* Page Down key */
    ENTER = 0x2324          /* Numerical keypad Enter key */
  };

  enum {
    LEFT  = 0x2190,         /* Left arrow key */
    UP    = 0x2191,         /* Up arrow key */
    RIGHT = 0x2192,         /* Right arrow key */
    DOWN  = 0x2193          /* Down arrow key */
  };

  enum {
    F1    = 0x276C,         /* Function keys */
    F2    = 0x276D,
    F3    = 0x276E,
    F4    = 0x276F,
    F5    = 0x2770,
    F6    = 0x2771,
    F7    = 0x2772,
    F8    = 0x2773,
    F9    = 0x2774,
    F10   = 0x2775
  };

  enum {
    CONTROL = 0x20000000L,  /* Modifier bit-fields */
    SHIFT   = 0x10000000L
  };

NOTES

Keyboard events can be caught using the on_control_key_down and on_control_key_action functions. The first function sets the call-back used to handle normal Unicode keys, including the return and escape keys. Keys which do not produce Unicode values are sent to the second function's call-back, such as when the user presses an arrow key or a function key.

Keyboard call-backs can be associated with controls. Typically you should not use these functions with pre-defined controls such as buttons, fields etc, only with custom-designed controls, since the pre-defined controls already make use of their own keyboard call-backs.

The call-back specified by the on_control_key_down 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).
• Any Unicode value which the keyboard may generate.

To see other keyboard events, the on_control_key_action 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.
• Keys modified by holding down the CONTROL key, or the other keys in this list modified by CONTROL and/or SHIFT being held down.

These keys should not be handled by same call-back as ordinary key_down events, since a Unicode keyboard may be able to generate the same value explicitly, and then confusion would exist about whether the user pressed an arrow key, or generated a Unicode value which happens to map to the same number.