xHarbour Reference Documentation > Function Reference

NextKey()

Returns the next pending key or mouse event.

Syntax

NextKey( [<nEventMask>] ) --> nNextInkeyCode

Arguments

<nEventMask>

A numeric value specifying the type of events NextKey() should retrieve. #define constants from INKEY.CH must be used for <nEventMask>. They are listed below:

Constants for <nEventMask>

Constant	Value	Events returned by NextKey()
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, NextKey() returns only keyboard events.

Return

The function returns a numeric value identifying the next keyboard or mouse event that can be retrieved by the Inkey() function.

Description

The NextKey() function returns the next keyboard or mouse event that is pending in the internal input buffers to be retrieved by the Inkey() function. NextKey() does not remove events from the input buffers and does not update the LastKey() value. This way, the input buffers can be polled without actually removing an event.

If only a subset of the Inkey codes is required, NextKey() can be passed a parameter <nEventMask> that filters Inkey codes. Only Inkey codes matching <nEventMask> are returned from NextKey().

Note:  the file INKEY.CH contains numerous symbolic #define constants that identify different key strokes or mouse input. It is recommended to use #define constants for prosessing Inkey codes, rather than using their numeric values.

Info

See also:	Inkey(), KEYBOARD, LastKey(), SET EVENTMASK, SET TYPEAHEAD
Category:	Keyboard functions , Mouse functions
Source:	rtl\inkey.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// In the example, two characters are stuffed into the keyboard buffer
// and the results of Inkey(), LastKey() and NextKey() are shown

   #include "Inkey.ch"

   PROCEDURE Main
      KEYBOARD "19"

      ? Chr( NextKey() )               // result: 1
      ? Chr( LastKey() )               // result: Chr(0)

      ? Chr( Inkey()   )               // result: 1
      ? Chr( LastKey() )               // result: 1

      ? Chr( NextKey() )               // result: 9
      ? Chr( LastKey() )               // result: 1

      ? Chr( Inkey()   )               // result: 9
      ? Chr( LastKey() )               // result: 9
      ? Chr( NextKey() )               // result: Chr(0)
    RETURN