INKEY usage, little help

[Luigi Ferraris]

Hi friends, 

I have read several documents, but I don't quite understand the behavior using next syntax:
iKey := INKEY( NIL, INKEY_KEYBOARD )
Any hints appreciated.
Best regards
Luigi

[marcos...@gmail.com]

xHarbour Language Reference Guide version 1.1.

Inkey()

Retrieves a character from the keyboard buffer or a mouse event.

Syntax
Inkey( [<nWaitSeconds>] [,<nEventMask>] ) --> nInkeyCode

Arguments
<nWaitSeconds>
A numeric value specifying the number of seconds to wait for a key stroke or a mouse event
until Inkey() returns. The value 0 instructs Inkey() to wait forever until a key is pressed or a
mouse event occurs. When <nWaitSeconds> is omitted, the function returns immediately, even
if no key stroke or mouse event is pending.

<nEventMask>
A numeric value specifying the type of events Inkey() should recognize.
#define constants from INKEY.CH must be used for <nEventMask>.

They are listed below:
Constants for <nEventMask>
Constant Value Events returned by Inkey()

INKEY_MOVE           1 Mouse pointer moved
INKEY_LDOWN        2 Left mouse button pressed
INKEY_LUP               4 Left mouse button released
INKEY_RDOWN        8 Right mouse button pressed
INKEY_RUP             16 Right mouse button released
INKEY_MMIDDLE  32 Middle mouse button pressed
INKEY_MWHEEL   64 Mouse wheel turned
INKEY_KEYBOARD 128 Key pressed
INKEY_ALL               255 All events are returned

IF <nEventMask> is omitted, the current SET EVENTMASK setting is used. If this is not
issued, Inkey() returns only keyboard events.

Return
The function returns a numeric value identifying the keyboard or mouse event that occured last. If no
key stroke or mouse event is pending and <nWaitSeconds> is not set to zero, Inkey() returns zero.

Description
The Inkey() function is used to retrieve key strokes from the keyboard buffer or monitor mouse events,
if <nEventMask> is set accordingly. Inkey() removes the key or mouse event from the internal buffer
and stores it so that it can be queried later using LastKey(). The similar function NextKey() reads a key
or mouse event without removing it from the internal buffer.

Inkey() can be used to interrupt program execution for a period of <nWaitSeconds> time while no
keyboard or mouse events are pending. The return value of Inkey() is usually processed in a DO CASE
or SWITCH control structure that results in an appropriate action for a key or mouse event. The
INKEY.CH file contains numerous symbolic #define constants used to identify single key strokes or
mouse events. It is recommended to use these constants in program code rather than the numeric value
of a keyboard or mouse event.

Note that SetKey() code blocks are not evaluated by Inkey().

Info
See also: Chr(), HB_KeyPut(), Lastkey(), Nextkey(), MCol(), MRow(), SET KEY, Set()
Category: Keyboard functions, Mouse functions
Header: Inkey.ch
Source: rtl\inkey.c
LIB: xhb.lib
DLL: xhbdll.dll

Example
// The example changes the event mask for Inkey() to ALL events
// and displays the mouse cursor position.
#include "Inkey.ch"
PROCEDURE Main
LOCAL nEvent

CLS
? "Waiting for events (press ESC to quit)"
SET EVENTMASK TO INKEY_ALL

DO WHILE Lastkey() <> K_ESC
nEvent := Inkey(0)
@ 0, 0 CLEAR TO 1, MaxCol()
IF nEvent >= K_MINMOUSE
// display current mouse cursor position
@ 0,1 SAY "Mouse Row:"
?? MRow()
@ 1,1 SAY "Mouse Col:"
?? MCol()
ELSE
@ 0,1 SAY "Key Code:"
?? nEvent
ENDIF
ENDDO

RETURN