Overview
--------

   Use this functions to get keyboard input
   and to get the actual mouse position and pressed mouse buttons.




The functions
-------------


CLEAR_KEYS:
   Macro to set the key field empty.
   Before getting keyboard input, all keys, which shall be watched,
   must be set into the key field.

   Example:
     CLEAR_KEYS;




void ADD_KEYS(key,type):
   Macro to add a key into the key field.

   Arguments:
    - key: is a symbolic keyname
    - type: is SHORT_KEY
            or LONG_KEY
            (see Macro IS_KEYS() for explanation)

   Example:
     ADD_KEYS(KEY_A,SHORT_KEY);  // add key "A" as a short key
     ADD_KEYS(KEY_B,LONG_KEY);  // add key "B" as a long key

   Symbolic keynames:
   ------------------
      keyname        key on keyboard
      =======        ===============
      KEY_0          0
      KEY_1          1
      KEY_2          2
      KEY_3          3
      KEY_4          4
      KEY_5          5
      KEY_6          6
      KEY_7          7
      KEY_8          8
      KEY_9          9
      KEY_A          A
      KEY_B          B
      KEY_C          C
      KEY_D          D
      KEY_E          E
      KEY_F          F
      KEY_G          G
      KEY_H          H
      KEY_I          I
      KEY_J          J
      KEY_K          K
      KEY_L          L
      KEY_M          M
      KEY_N          N
      KEY_O          O
      KEY_P          P
      KEY_Q          Q
      KEY_R          R
      KEY_S          S
      KEY_T          T
      KEY_U          U
      KEY_V          V
      KEY_W          W
      KEY_X          X
      KEY_Y          Y
      KEY_Z          Z
      KEY_KP_0       Keypad 0
      KEY_KP_1       Keypad 1
      KEY_KP_2       Keypad 2
      KEY_KP_3       Keypad 3
      KEY_KP_4       Keypad 4
      KEY_KP_5       Keypad 5
      KEY_KP_6       Keypad 6
      KEY_KP_7       Keypad 7
      KEY_KP_8       Keypad 8
      KEY_KP_9       Keypad 9
      KEY_ESC        Escape
      KEY_TAB        Tabulator
      KEY_RSHIFT     Right Shift
      KEY_LSHIFT     Left Shift
      KEY_RCTRL      Right Control
      KEY_LCTRL      Left Control
      KEY_RALT       Right Alt
      KEY_LALT       Left Alt
      KEY_SPACE      Space
      KEY_ENTER      Return
      KEY_BSP        Backspace
      KEY_RCURS      Right Cursor
      KEY_LCURS      Left Cursor
      KEY_UCURS      Up Cursor
      KEY_DCURS      Down Cursor
      KEY_F1         F1
      KEY_F2         F2
      KEY_F3         F3
      KEY_F4         F4
      KEY_F5         F5
      KEY_F6         F6
      KEY_F7         F7
      KEY_F8         F8
      KEY_F9         F9
      KEY_F10        F10
      KEY_F11        F11
      KEY_F12        F12




void SAVE_KEYS(keyfield):
   Macro to save a key field, e.g. for temporaryly defining new keys

   Arguments:
    - keyfield: pointer to an integer (not yet allocated)

   Example:
     int * keyf;
     SAVE_KEYS(keyf);  /* allocate keyf and save actual defined keys */
     CLEAR_KEYS;
     /* now you can define new keys and call later RESTORE_KEYS() */




void RESTORE_KEYS(keyfield):
   Macro to restore a saved key field (with SAVE_KEYS())
   (all pressed keys are set to be released)

   Arguments:
    - keyfield: pointer to an integer (saved key field)

   Example:
     int * keyf;
     SAVE_KEYS(keyf);  /* allocate keyf and save actual defined keys */
     CLEAR_KEYS;
     /* now you can define new keys etc. */
     [ ... ]
     RESTORE_KEYS(keyf);  /* set old key field back and free keyf */




int IS_KEYS(key):
   Macro to check whether a key is pressed or not.
   You must have called get_keys() before.

   Arguments:
    - key: is a symbolic keyname,
           it must have been set into the key field with ADD_KEYS()

   Return value: 0=key is not pressed (or is released)
                 1=key is pressed

   Note: There is a difference whether a key is defined in the key field
         as a short key or a long key.

         A key defined with SHORT_KEY will only be returned as "pressed"
         if it was just pressed down, but not if it is keeped pressed.
         The key must at first be released and pressed again to get it
         returned as "pressed" again.

         A key defined with LONG_KEY will always be returned as "pressed"
         when it is (keeped) pressed, and as "not pressed" when it is
         released or not pressed.

   Example:
     get_keys();
     if (IS_KEYS(KEY_B)==1) { ... }  // key "B" or "b" is pressed
     if (IS_KEYS(KEY_F9)==0) { ... }  // key "F9" is not pressed




int MOUSE_FOUND:
   Macro to test whether a mouse was found or not.

   Return value: 0=no mouse was found
                 1=mouse was found

   Example:
     if (MOUSE_FOUND==0) { ... }  // no mouse found




int MOUSE_X
int MOUSE_Y:
   Macros to get the position of the mouse pointer at x,y.
   You must have called get_keys() before.

   Return value: coordinate x of mouse pointer (MOUSE_X)
                 coordinate y of mouse pointer (MOUSE_Y)

   Note: You have to draw your mouse pointer yourself at position x,y.
         If your mouse pointer has left your window, the coordinates
         are both set to -1.

   Example:
     int x,y;
     get_keys();
     x=MOUSE_X;
     y=MOUSE_Y;




int IS_MOUSELEFT
int IS_MOUSERIGHT
int IS_MOUSEMIDDLE:
   Macros to check whether a mouse button is pressed or not.
   Mouse buttons are always like keys defined with SHORT_KEY (see IS_KEYS()).
   You must have called get_keys() before.

   Return value: 0=mouse button is not pressed
                 1=mouse button is pressed

   Example:
     get_keys();
     if (IS_MOUSELEFT==1) { ... }  // left mouse button was pressed




int mouse_speed(int arg1):
   sets the mouse pointer speed, if possible.

   Arguments:
    - arg1: 1 to 3 (1=slow, 2=normal, 3=fast)

   Return value: 0=mouse speed cannot be set
                 1-3: previous mouse speed

   Example:
     int prev_mspeed;
     prev_mspeed=mouse_speed(2);
     if (prev_mspeed==0) {
       /* not an error, but mouse speed cannot be changed */
     }




void get_keys():
   update function to get pressed/not pressed keys and mouse events.
   Call this function before checking with macros IS_KEYS() and IS_MOUSE*.
   Only keys set into the key field with ADD_KEYS() are updated.

   Note: If using X window and switching to another mode (e.g. 640x480)
         with fullscreen, moving the mouse will move your screen away, but
         calling get_keys() corrects this and puts your screen back.
         Therefore it is a good idea to call get_keys() regularly even if
         you don't need it for a longer time.

   Example:
     get_keys();




void clearstate():
   clear all pending key, mouse button, mouse motion events.
   Call this function before get_keys() if you want to discard previous
   inputs.

   Example:
     clearstate();