Click above to get retro games delivered to your door ever month!

KEY_PRESS()                                                         C_EXAM03
   Waits for an event to occur.

   Syntax
         nEvent = KEY_PRESS()

   Arguments
         None

   Returns
         +--------------------------+
         | KEY PRESS EVENTS         |
         ---------------------------|
         | nEvent |Event Description|
         ---------+-----------------|
         |    0   |No event occurred|
         |    2   |Keyboard event   |
         |    4   |Mouse event      |
         |    8   |Region event     |
         |   16   |Timer event      |
         |   32   |Menu event       |
         |   64   |Hot object event |
         |  128   |Grid event       |
         |  256   |Double click     |
         |  512   |Macro event      |
         +--------------------------+

   Description
         KEY_PRESS() waits in a loop until an event occurs. The event that
         causes KEY_PRESS() to release is returned from this function as
         nEvent. Information abaout the current status of the event queue is
         recorded and can be returned by a number of KP_.. functions.

         FLUSH_EVQ() clears the event queue so any events that have
         accumulated will be cleared.

         At the same time, the KEY_PRESS() queue is updated with the current
         mouse status. The queue holds a variety of mouse related information
         that can be returned with the following functions:

         KP_ABS_X()   Absolute horizontal mouse position.

         KP_ABS_Y()   Absolute vertical mouse position.

         KP_SCALE_X() World scale horizontal mouse position.

         KP_SCALE_Y() World scale vertical mouse position.

         KP_MSTATE(nFlag)

         KP_MSTATE() returns the mouse's shift status flags. Each bit has
         a special value indicating the mouse status. To find the flag
         state, you must determine the status of the flag's corresponding
         bit by calling KP_MSTATE() with the flag number that you want
         checked. A return of 0 would indicate the status is FALSE, while a
         1 would be TRUE.
            +---------------------------------------------+
            | MOUSE STATE EVENT FLAGS                     |
            ----------------------------------------------|
            |nFlag|Bit Value| Flag description            |
            ------+---------+-----------------------------|
            |  1  |    1    |Mouse cursor position changed|
            |  2  |    2    |Left button pressed          |
            |  3  |    4    |Left button released         |
            |  4  |    8    |Right button pressed         |
            |  5  |   16    |Right button released        |
            |  6  |   32    |Middle button pressed        |
            |  7  |   64    |Middle button released       |
            +---------------------------------------------+

         nValue=KP_BUTTON()

         KP_BUTTON() returns the mouse buttons that were pressed and in what
         combination. If the event is a mouse event, then KP_BUTTON()
         returns the state of the mouse buttons at the time of the event.
         This will return 0 for non-mouse events. The bits represent the
         buttons of the mouse: Bit 0 is the left mouse button, Bit 1 is the
         right mouse button, and Bit 2 is the middle mouse button. The
         following is the possible return values from the function:

            +-------------------------------+
            | MOUSE BUTTON RETURN VALUES    |
            --------------------------------|
            | Value | Flag description      |
            --------+-----------------------|
            |   0   | No buttons pressed    |
            |   1   | Left button           |
            |   2   | Right button          |
            |   3   | Left & right button   |
            |   4   | Middle button         |
            |   5   | Middle & left button  |
            |   6   | Middle & right button |
            |   7   | All three buttons     |
            +-------------------------------+

         KP_SCAN()   Returns the keyboard scan code.

         KP_ASCII()

         KP_ASCII() returns the ASCII value of the key pressed. Each keystroke
         is uniquely identified by a pair of one-byte values - its scan and
         ASCII codes. IBM added the scan code so that each key on the keyboard
         would have a unique value. KP_SCAN() and KP_ASCII() uniquely identify
         an input event. For a keyboard event, these are the standard IBM
         values for a key stroke.

         For a region event, KP_SCAN() is set to 214, indicating that a
         region border has been crossed. KP_ASCII() returns the region that
         has been exited. The MS_REGION() function will return the region
         that has been entered.

         For all other events, both of these values are set to 0 and the
         event is recorded in the mouse event and mouse buttons structures.

         KP_FLAGS(nFlag)

         Set only for keystokes, this area holds the keyboard's shift status
         flags. Each bit has a special value indicating keyboard status. To
         find the flag state, you must determine the status of the flag's
         corresponding bit. A return of 0 would indicate the status is
         FALSE, while a return of 1 would be TRUE.
            +--------------------------------------+
            | KEY STROKE STATUS FLAGS              |
            ---------------------------------------|
            | Flag  | Flag description             |
            --------+------------------------------|
            |  1    | Right shift key is depressed |
            |  2    | Left shift key is depressed  |
            |  3    | Ctrl shift key is depressed  |
            |  4    | Alt shift key is depressed   |
            |  5    | Scroll Lock state is active  |
            |  6    | Num Lock state is active     |
            |  7    | Caps Lock state is active    |
            |  8    | Insert state is active       |
            +--------------------------------------+

         KP_MENU()    Returns the last menu set selected.

         KP_ITEM_NO()

         For menu events, KP_ITEM_NO() returns the menu button number
         selected. For hot object events, KP_ITEM_NO() returns the number of
         objects found.

         KP_TIME()

         KP_TIME() returns the low word of the IBM clock time. There are 18.2
         clock ticks per second. The time is set when the event is placed into
         the queue.