xHarbour Reference Documentation > Function Reference

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