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

INKEY()

Extracts the next key code from the Harbour keyboard buffer.
---------------------------------------------------------------------------------

 Syntax

        INKEY( [<nTimeout>] [,<nEvents>] ) --> nKey  

 Arguments

        <nTimeout>   is an optional timeout value in seconds, with a 
                  granularity of 1/10th of a second. If omitted, INKEY()
                  returns immediately. If set  to 0, INKEY() waits until an
                  input event occurs. If set to any other  value, INKEY()
                  will return either when an input event occurs or when
                  the timeout period has elapsed. If only this parameter is
                  specified  and it is not numeric, it will be treated as
                  if it were 0. But if both  parameters are specified and
                  this parameter is not numeric, it will be  treated as if
                  it were not present.

        <nEvents>   is an optional mask of input events that are to be 
                  enabled. If omitted, defaults to
                  hb_set.HB_SET_EVENTMASK. Valid input masks are  in
                  inkey.ch and are explained below. It is recommended that
                  the mask  names be used rather than their numeric values,
                  in case the numeric  values change in future releases of
                  Harbour. To allow more than one  type of input event,
                  simply add the various mask names together.

+-----------------------------------------------------------------------+
| inkey.ch       | Meaning                                              |
|----------------+------------------------------------------------------|
| INKEY_MOVE     | Mouse motion events are allowed                      |
| INKEY_LDOWN    | The mouse left click down event is allowed           |
| INKEY_LUP      | The mouse left click up event is allowed             |
| INKEY_RDOWN    | The mouse right click down event is allowed          |
| INKEY_RUP      | The mouse right click up event is allowed            |
| INKEY_KEYBOARD | All keyboard events are allowed                      |
| INKEY_ALL      | All mouse and keyboard events are allowed            |
|                | HB_INKEY_EXTENDED  Extended keyboard codes are used. |
+-----------------------------------------------------------------------+
       If  the parameter is not numeric, it will be treated as if it were 
                  set to hb_set.HB_SET_EVENTMASK.

 Returns

       0  in case of timeout with no input event, otherwise returns a value 
                  in the range -47 to 386 for keyboard events or the range
                  1001 to 1007  for mouse events. Mouse events and
                  non-printable keyboard events are  represented by the
                  K_<event> values listed in inkey.ch. Keyboard  event
                  return codes in the range 32 through 127 are equivalent
                  to the  printable ASCII character set. Keyboard event
                  return codes in the  range 128 through 255 are assumed to
                  be printable, but results may  vary based on hardware and
                  nationality. If HB_INKEY_EXTENDED mode is  used, then the
                  return value for keyboard events ranges from 1 through
                  767 and 1077 through 1491, although not all codes are
                  used.

       Extended  key codes consist of the PC keyboard scan code and one or 
                  more offset values. If no keyboard modifier was used,
                  then  HB_INKEY_NONE is added. The Alt key adds
                  HB_INKEY_ALT, the Ctrl  key adds HB_INKEY_CTRL, the Shift
                  key adds HB_INKEY_SHIFT, and  enhanced keys (KeyPad+/ and
                  CursorPad keys) add HB_INKEY_ENHANCED.  For example, F1
                  is scan code 59, so if you just press F1, you get  key
                  code 315, but Alt+F1 gives 443, Ctrl+F1 gives 571, and
                  Shift+  F1 gives 699. And NumPad+/ gives 1077, 1205,
                  1333, and 1461. At  this time, the only value that can
                  combine with other values is  HB_INKEY_ENHANCED (i.e.,
                  there are no Alt+Ctl combinations, etc.)

       Note:  The extended key code set is larger than the normal key code 
                  set. As a result, if you switch between the normal and
                  extended  modes, you need to be aware that some codes get
                  translated into a  zero in normal mode (because there is
                  no corresponding code in  normal mode) and that these
                  codes get removed from the keyboard  input buffer in
                  normal mode and you won't be able to go back and  fetch
                  them later in extended mode.

 Description

      INKEY() can be used to detect input events, such as keypress, mouse
      movement, or mouse key clicks (up and/or down).

 Examples

      // Wait for the user to press the Esc key
      ? "Please press the ESC key."
      WHILE INKEY( 0.1 ) != K_ESC
      END
  

 Tests

      KEYBOARD "AB"; ? INKEY(), INKEY() ==>   65   66
  

Status

      Started

 Compliance

      INKEY() is compliant with the Clipper 5.3 INKEY() function with one
      exception: The Harbour INKEY() function will raise an argument
      error  if the first parameter is less than or equal to 0 and the
      second  parameter (or the default mask) is not valid, because
      otherwise INKEY  would never return, because it was, in effect,
      asked to wait forever  for no events (Note: In Clipper, this also
      blocks SET KEY events).

 Files

      Library is rtl