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.chMeaning
INKEY_MOVEMouse motion events are allowed
INKEY_LDOWNThe mouse left click down event is allowed
INKEY_LUPThe mouse left click up event is allowed
INKEY_RDOWNThe mouse right click down event is allowed
INKEY_RUPThe mouse right click up event is allowed
INKEY_KEYBOARDAll keyboard events are allowed
INKEY_ALLAll mouse and keyboard events are allowed

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 -39 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.

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