Functions and Directives

Function Inkey() Foundation

Reads the next character in the keyboard buffer and removes it from the buffer.

Syntax
Inkey( [<nSeconds>] ) --> nInkeyCode
Parameters
<nSeconds>
<nSeconds> is a numeric expression specifying the maximum number of seconds to wait for a keypress. The smallest time unit handled by Inkey() is one thousandth of a second. When the value is zero, the function waits indefinitely for a key press. When <nSeconds> is not specified, the next character is read from the keyboard buffer and no wait occurs.
Return

The return value of Inkey() is an integer in the range of -47 to 422. This value identifies the key taken from the keyboard buffer. When the keyboard buffer has no value (no key has been pressed), Inkey() returns zero.

Description

The function Inkey() is a compatibility function which checks the keyboard buffer but is limited in scope. The function AppEvent() should be used instead of Inkey() in the Xbase++ system. AppEvent() processes mouse events as well as keyboard events.

Inkey() removes the next key code (value of the next key pressed) from the keyboard buffer and returns it. This value is stored internally and can be rechecked with the function LastKey() (last key pressed). When no values are in the keyboard buffer and the argument <nSeconds>contains a value, Inkey() waits a maximum of <nSeconds> seconds for a new keypress. When the value for <nSeconds> equals 0, Inkey() waits until a key is pressed.

The functions Inkey(), LastKey() and NextKey() all retrieve keyboard input. Inkey() reads the next keypress and removes it from the keyboard buffer. NextKey() reads the next keypress without removing it from the keyboard buffer. LastKey() returns the last keypress removed from the keyboard buffer.

Symbolic constants are defined in the header file "Inkey.ch" for all key codes which are returned from Inkey()

The operation system supports multithreading. Contrary to the DOS system, other processes can continue running when the expression Inkey(0) occurs in a program. For example, while Inkey(0) is waiting a TBrowse object may continue to stabilize or a report may continue printing. Because of this, the following control structure, which is not a problem under DOS, should not be used in Xbase++:

DO WHILE (nKey := Inkey()) <> K_ESC 
   DO CASE 
   CASE nKey == K_RETURN 
      // Program code 
   ENDCASE 
   // Program code 
ENDDO 

A DO WHILE loop like this, where the keyboard is continuously polled, makes use of substantial system resources and impedes other processes because they cannot take advantage of the time when no key is being pressed. Instead of a loop like the one shown above, the following structure is preferable in Xbase++.

nKey := 0 
DO WHILE nKey <> K_ESC 
   nKey := Inkey(0) 
   DO CASE 
   CASE nKey == K_RETURN 
      // Program code 
   ENDCASE 
   // Program code 
ENDDO 

Inkey() is a compatibility function used with the Get system and functions such as AChoice(). Such functions require a console window and hence can only be used in text and hybrid mode applications.

Examples
Inkey()
// In the example the key code of a pressed key is 
// output to the screen. 

#include "Inkey.ch" 

PROCEDURE Main 
   LOCAL nKey := 0 

   DO WHILE nKey <> K_ESC 
      ? "Press key: " 
      nKey := Inkey(0) 

      ? "The value of the key is:", LTrim( Str(nKey) ) 

   ENDDO 

RETURN 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.