The HTML version of this RfD is <http://www.forth200x.org/ekeys.html>

Change History

2006-05-28
Added K-INSERT, K-DELETE, K-F* and K-*-MASK. Added Sections
Programming Advice and Shift Keys. Reported comments by various
people.


Problem

How do I write a portable Forth program that reacts to key presses of
cursor keys (and possibly other keys not represented by ASCII), e.g., an
editor?


Proposal

The following words produce the same values that EKEY produces when the
user presses the corresponding key.

K-LEFT ( -- u ) facility ext
The "cursor left" key

K-RIGHT ( -- u ) facility ext
The "cursor right" key

K-UP ( -- u ) facility ext
The "cursor up" key

K-DOWN ( -- u ) facility ext
The "cursor down" key

K-HOME ( -- u ) facility ext
The "home" or "Pos1" key

K-END ( -- u ) facility ext
The "End" key

K-PRIOR ( -- u ) facility ext
The "PgUp" or "Prior" key

K-NEXT ( -- u ) facility ext
The "PgDn" or "Next" key

K-INSERT ( -- u ) facility ext
The "Insert" key

K-DELETE ( -- u ) facility ext
The "Delete" key

K-F1 ( -- u ) facility ext
The "F1" key

K-F2 ( -- u ) facility ext
The "F2" key

K-F3 ( -- u ) facility ext
The "F3" key

K-F4 ( -- u ) facility ext
The "F4" key

K-F5 ( -- u ) facility ext
The "F5" key

K-F6 ( -- u ) facility ext
The "F6" key

K-F7 ( -- u ) facility ext
The "F7" key

K-F8 ( -- u ) facility ext
The "F8" key

K-F9 ( -- u ) facility ext
The "F9" key

K-F10 ( -- u ) facility ext
The "F10" key

K-F11 ( -- u ) facility ext
The "F11" key

K-F12 ( -- u ) facility ext
The "F12" key

The following words procude a mask, that you can OR with the key values
above to produce a value that EKEY may produce when the user presses the
corresponding key combination.

K-SHIFT-MASK ( -- u ) facility ext
Mask for the shift key

K-CTRL-MASK ( -- u ) facility ext
Mask for the ctrl key

K-ALT-MASK ( -- u ) facility ext
Mask for the alt key


Typical Use

... ekey case
k-up of ... endof
k-f1 of ... endof
k-left k-shift or k-ctrl or of ... endof
...
endcase


Remarks

Programming advice

Note that, even if a Forth system supports these words, many environments
do not have or do not report all these keys and key combinations, so it
is a good idea to write your program such that it is still useful even if
these keys and key combinations cannot be pressed or are not recognized.

Shift keys

Note that, as defined, the shift key masks defined above are only useful
for recognizing shifted cursor and function keys, because these are the
only keys that EKEY return values are defined for. E.g., we cannot
program Forth to recognize recognize ALT-T, because no EKEY return value
for T has been defined.

Other Keys

Gforth and PFE have words K1...K10 for the function/keypad keys; they
also contain S-K1...S-K10 for shifted function/keypad keys, but they
don't work as widely. Moreover, Gforth (but not PFE) also has K-INSERT
K-DELETE K11 K12 S-K11 S-K12. Should any of these words be added to this
proposal? After the first RfD, several people were in favour of adding
such words and nobody spoke out against, so I added the words after
K-NEXT. If you don't like such words in general, or would like them, but
differently, please speak up now.


Experience

These words have been implemented for several years in PFE and
Gforth. Several editors have been published in ANS Forth that would
have profited from these words. Also, the original version of the
MiniSpreadsheet <http://wiki.forthfreak.net/index.cgi?MiniSpreadsheet>
hardcoded the values for the keys for one platform; I then fixed it to
use the cursor-key words proposed above.


Implementation and Tests

The implementation is closely tied to the implementation of EKEY, and
therefore unportable, so I don't provide a reference
implementation. However, you can look at the Gforth implementation
<http://b2.complang.tuwien.ac.at/cgi-bin/cvsweb/~checkout~/gforth/ekey.fs?rev=HE\
AD;content-type=text%2Fplain;cvsroot=gforth>
of EKEY and many of these words (based on ANSI terminal escape
sequences).

Tests <http://www.complang.tuwien.ac.at/forth/ansforth/tests/ekeys.fs>


Comments

Alex McDonald writes:

Win32Forth provides;

k_home k_up k_pgup k_left k_right k_end k_down k_pgdn k_insert
k_delete k_scroll

plus k_1 through k_12 for function keys.

+k_control +k_alt +k_shift provide a mask when these keys are depressed
with any of the above.

Marcel Hendrix writes <13073534183561@...> that iForth
implements this functionality, but with different key names.

Charles Melice and Alex McDonald would prefer K-F1 etc. for function
keys, and masks for shifted keys etc.

Charles Melice would also like to see some events defined for mouse
events (<44734824$0$20278$ba620e4c@...> ff.). There was some
discussion on how that should be done; however, it will not be done in
this proposal.

Robert Epprecht uses these words and would like to have them available in
different Forth implementations. Also, he would like to see the words for
the function keys.

- anton