5.19.7 Single-key input

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?– 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.

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.

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 X:ekeys “k-left”

k-right– u X:ekeys “k-right”

k-up– u X:ekeys “k-up”

k-down– u X:ekeys “k-down”

k-home– u X:ekeys “k-home”

aka Pos1

k-end– u X:ekeys “k-end”

k-prior– u X:ekeys “k-prior”

aka PgUp

k-next– u X:ekeys “k-next”

aka PgDn

k-insert– u X:ekeys “k-insert”

k-delete– u X:ekeys “k-delete”

The key identifiers for function keys (aka keypad keys) are:

k-f1– u X:ekeys “k-f1”

k-f2– u X:ekeys “k-f2”

k-f3– u X:ekeys “k-f3”

k-f4– u X:ekeys “k-f4”

k-f5– u X:ekeys “k-f5”

k-f6– u X:ekeys “k-f6”

k-f7– u X:ekeys “k-f7”

k-f8– u X:ekeys “k-f8”

k-f9– u X:ekeys “k-f9”

k-f10– u X:ekeys “k-f10”

k-f11– u X:ekeys “k-f11”

k-f12– u X:ekeys “k-f12”

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 X:ekeys “k-shift-mask”

k-ctrl-mask– u X:ekeys “k-ctrl-mask”

k-alt-mask– u X:ekeys “k-alt-mask”

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 “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-stringu1 – c-addr u gforth “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.