Next: , Previous: Terminal output, Up: Other I/O


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.

Typical code for using EKEY looks like this:

     ekey ekey>char if ( c )
       ... \ 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>char       u – u false | c true         facility-ext       “e-key-to-char”

Convert keyboard event u into character c if possible.

ekey>fkey       u1 – u2 f         X:ekeys       “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-string       u1 – 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.