The KEYCODE() and KEYCODEV() functions read a single keystroke from the keyboard.
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
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.
K = KEYCODEV()
CASE K = KV$LEFT ;* Cursor left key
DISPLAY 'Seen cursor left key'
DISPLAY 'Seen cursor right key'
DISPLAY 'Mouse clicked at ' : @MCOL : ',' : @MROW
The KV$xxx tokens are defined in the KEYIN.H include record in the SYSCOM file.