KEYCODE()

KEYCODE(), KEYCODEV()

Top  Previous  Next

 

The KEYCODE() and KEYCODEV() functions read a single keystroke from the keyboard.

 

 

Format

 

KEYCODE({timeout})

KEYCODEV({timeout})

 

 

The KEYCODE() function pauses program execution until a key is pressed. The character associated with that key is returned as the value of the function. The character is not echoed to the display.

 

The KEYCODEV() function is similar but returns the code point value of the key rather than the character corresponding to the key.

 

KEYCODE() and KEYCODEV() do not take data from the DATA queue.

 

The optional timeout parameter specifies a period in seconds after which the function will return if no input is received. In this case the returned value is a null string and the STATUS() function will return ER$TIMEOUT.

 

A null string is also returned when taking input from a pipe if the piped data stream is exhausted. In this case the STATUS() function will return ER$EOF. The value returned by the STATUS() function is not significant unless KEYCODE() has returned a null string.

 

The KEYCODE() function differs from KEYIN() in that it uses the terminfo database to identify certain special keys and returns the character representing the internal representation of that key as defined in the KEYIN.H include record in the SYSCOM file. The special keys recognised by this function are:

Function keys F1 to F12

Left, right, up and down cursor keys

Page up and Page down keys

Home and End

Insert and Delete

Back-tab

Mouse

 

Use of the Escape key will return char(27) if no further characters are received within 200mS. This mechanism can be disabled using the BINDKEY() function.

 

The KEYCODEV() function has a similar relationship with KEYINV(), returning the code point value. For the special keys recognised by the key bindings, the returned value will correspond to positions in the Unicode BMP Private Use Area that QM assigns to the keys. The function is valid on non-ECS systems but the returned values are usually not able to be stored as single characters.

 

Click here for a table of the values returned by these functions. These are also defined in the KEYIN.H include record in the SYSCOM file.

 

 

Handling Mouse Clicks

 

The mouse code is returned when the mouse control prefix sequence defined in the terminfo database is detected. The way in which mouse clicks are handled varies considerably between different terminal emulators. When using terminal types supported by standard QM terminfo definitions the KEYCODE() and KEYCODEV() functions additionally process the qualifying data sent by the terminal device, saving the button number in @MBUTTON and the screen coordinates at which the mouse was clicked in @MCOL and @MROW.

 

Mouse click detection is disabled by default. It can be enabled or disabled by use of the QMBasic MOUSE statement. See the MOUSE statement for more information.

 

 

Example

 

K = KEYCODEV()

BEGIN CASE

  CASE K = KV$LEFT   ;* Cursor left key

     DISPLAY 'Seen cursor left key'
  CASE K = KV$RIGHT  ;* Cursor right key

     DISPLAY 'Seen cursor right key'
  CASE K = KV$MOUSE  ;* Mouse click

     DISPLAY 'Mouse clicked at ' : @MCOL : ',' : @MROW
  ...etc...
END CASE

 

The KV$xxx tokens are defined in the KEYIN.H include record in the SYSCOM file.

 

 

See also:

Terminfo database, BINDKEY(), MOUSE, TERMINFO()