## 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.