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."
      DO WHILE Inkey( 0.1 ) != K_ESC
      ENDDO

Tests

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

Compliance

INKEY() is compliant with the CA-Cl*pper 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 CA-Cl*pper, this also blocks SET KEY events).

Files

Library is rtl

Seealso

inkey.ch