# 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

See Also

- inkey.ch