If you want to get a single printable character, you can use
key; to check whether a character is available for key,
you can use key?.
key ( – char ) core “key”
Receive (but do not display) one character, char.
key-ior ( – char|ior ) gforth-1.0 “key-ior”
Receive (but do not display) one character, char, in case of an error or interrupt, return the negative ior instead.
key? ( – flag ) facility “key-question”
Determine whether a character is available. If a character is
available, flag is true; the next call to key will
yield the character. Once key? returns true, subsequent
calls to key? before calling key or ekey will
also return true.
xkey? ( – flag ) xchar “x-key-query”
If you want to process a mix of printable and non-printable
characters, you can do that with ekey and friends. Ekey
produces a keyboard event that you have to convert into a character
with ekey>char or into a key identifier with ekey>fkey.
Typical code for using EKEY looks like this:
ekey ekey>xchar if ( xc )
... \ do something with the character
else ekey>fkey if ( key-id )
case
k-up of ... endof
k-f1 of ... endof
k-left k-shift-mask or k-ctrl-mask or of ... endof
...
endcase
else ( keyboard-event )
drop \ just ignore an unknown keyboard event type
then then
ekey ( – u ) facility-ext “e-key”
Receive a keyboard event u (encoding implementation-defined).
ekey>xchar ( u – u false | xc true ) xchar-ext “e-key-to-x-char”
Convert keyboard event u into xchar xc if
possible.
ekey>char ( u – u false | c true ) facility-ext “e-key-to-char”
Convert keyboard event u into character c if
possible. Note that non-ASCII characters produce false
from both ekey>char and ekey>fkey. Instead of
ekey>char, use ekey>xchar if available.
ekey>fkey ( u1 – u2 f ) facility-ext “e-key-to-f-key”
If u1 is a keyboard event in the special key set, convert keyboard event u1 into key id u2 and return true; otherwise return u1 and false.
ekey? ( – flag ) facility-ext “e-key-question”
True if a keyboard event is available.
The key identifiers for cursor keys are:
k-left ( – u ) facility-ext “k-left”
k-right ( – u ) facility-ext “k-right”
k-up ( – u ) facility-ext “k-up”
k-down ( – u ) facility-ext “k-down”
k-home ( – u ) facility-ext “k-home”
aka Pos1
k-end ( – u ) facility-ext “k-end”
k-prior ( – u ) facility-ext “k-prior”
aka PgUp
k-next ( – u ) facility-ext “k-next”
aka PgDn
k-insert ( – u ) facility-ext “k-insert”
k-delete ( – u ) facility-ext “k-delete”
the DEL key on my xterm, not backspace
The key identifiers for function keys (aka keypad keys) are:
k-f1 ( – u ) facility-ext “k-f-1”
k-f2 ( – u ) facility-ext “k-f-2”
k-f3 ( – u ) facility-ext “k-f-3”
k-f4 ( – u ) facility-ext “k-f-4”
k-f5 ( – u ) facility-ext “k-f-5”
k-f6 ( – u ) facility-ext “k-f-6”
k-f7 ( – u ) facility-ext “k-f-7”
k-f8 ( – u ) facility-ext “k-f-8”
k-f9 ( – u ) facility-ext “k-f-9”
k-f10 ( – u ) facility-ext “k-f-10”
k-f11 ( – u ) facility-ext “k-f-11”
k-f12 ( – u ) facility-ext “k-f-12”
Note that k-f11 and k-f12 are not as widely available.
You can combine these key identifiers with masks for various shift keys:
k-shift-mask ( – u ) facility-ext “k-shift-mask”
k-ctrl-mask ( – u ) facility-ext “k-ctrl-mask”
k-alt-mask ( – u ) facility-ext “k-alt-mask”
There are a number of keys that have ASCII values, and therefore are unlikely to be reported as special keys, but the combination of these keys with shift keys may be reported as a special key:
k-enter ( – u ) gforth-1.0 “k-enter”
k-backspace ( – u ) gforth-1.0 “k-backspace”
k-tab ( – u ) gforth-1.0 “k-tab”
Moreover, there the following key codes for keys and other events:
k-winch ( – u ) gforth-1.0 “k-winch”
A key code that may be generated when the user changes the window size.
k-pause ( – u ) gforth-1.0 “k-pause”
k-mute ( – u ) gforth-1.0 “k-mute”
k-volup ( – u ) gforth-1.0 “k-volup”
k-voldown ( – u ) gforth-1.0 “k-voldown”
k-sel ( – u ) gforth-1.0 “k-sel”
keycode for Android selections
k-eof ( – u ) gforth-1.0 “k-eof”
Note that, even if a Forth system has ekey>fkey and the key
identifier words, the keys are not necessarily available or it may not
necessarily be able to report all the keys and all the possible
combinations with shift masks. Therefore, write your programs in such
a way that they are still useful even if the keys and key combinations
cannot be pressed or are not recognized.
Examples: Older keyboards often do not have an F11 and F12 key. If you run Gforth in an xterm, the xterm catches a number of combinations (e.g., Shift-Up), and never passes it to Gforth. Finally, Gforth currently does not recognize and report combinations with multiple shift keys (so the shift-ctrl-left case in the example above would never be entered).
Gforth recognizes various keys available on ANSI terminals (in MS-DOS you need the ANSI.SYS driver to get that behaviour); it works by recognizing the escape sequences that ANSI terminals send when such a key is pressed. If you have a terminal that sends other escape sequences, you will not get useful results on Gforth. Other Forth systems may work in a different way.
Gforth also provides a few words for outputting names of function keys:
fkey. ( u – ) gforth-1.0 “fkey-dot”
Print a string representation for the function key u. U must be a function key (possibly with modifier masks), otherwise there may be an exception.
simple-fkey-string ( u1 – c-addr u ) gforth-1.0 “simple-fkey-string”
c-addr u is the string name of the function key u1. Only works for simple function keys without modifier masks. Any u1 that does not correspond to a simple function key currently produces an exception.