Forth 2012: EKEYFKEY

( x -- u flag )

If the keyboard event x corresponds to a keypress in the implementation-defined special key set, return that key's id u and true. Otherwise return x and false.

Note:

The keyboard may lack some of the keys, or the capability to report them. Programs should be written such that they also work (although less conveniently or with less functionality) if these key numbers cannot be produced.

See:

Rationale:

EKEY produces an abstract cell type for a keyboard event (e.g., a keyboard scan code). EKEY>FKEY checks if such an event corresponds to a special (non-graphic) key press, and if so, returns a code for the special key press. The encoding of special keys (returned by EKEY>FKEY) may be different from the encoding of these keys as keyboard events (input to EKEY>FKEY).

Typical Use:

... EKEY EKEY>FKEY IF
   CASE
     K-UP OF ... ENDOF
     K-F1 OF ... ENDOF
     K-LEFT K-SHIFT-MASK OR K-CTRL-MASK OR OF ... ENDOF
     ...
   ENDCASE
ELSE
   ...
THEN

The codes for the special keys are system-dependent, but this standard provides words for getting the key codes for a number of keys:


Word	Key	Word	Key

K-F1	F1	K-LEFT	cursor left
K-F2	F2	K-RIGHT	cursor right
K-F3	F3	K-UP	cursor up
K-F4	F4	K-DOWN	cursor down
K-F5	F5	K-HOME	home or Pos1
K-F6	F6	K-END	End
K-F7	F7	K-PRIOR	PgUp or Prior
K-F8	F8	K-NEXT	PgDn or Next
K-F9	F9	K-INSERT	Insert
K-F10	F10	K-DELETE	Delete
K-F11	F11
K-F12	F12

In addition, you can get codes for shifted variants of these keys by ORing with K-SHIFT-MASK, K-CTRL-MASK and/or K-ALT-MASK, e.g. K-CTRL-MASK K-ALT-MASK OR K-DELETE OR. The masks for the shift keys are:


Word	Key

K-SHIFT-MASK	Shift
K-CTRL-MASK	Ctrl
K-ALT-MASK	Alt

Note that not all of these keys are available on all systems, and not all combinations of keys and shift keys are available. Therefore programs should be written such that they continue to work (although less conveniently or with less functionality) if these key combinations cannot be produced.

Implementation:

The implementation is closely tied to the implementation of EKEY and therefore unportable.

Testing:

: TFKEY" ( "ccc<quote>" -- u flag )
CR ." Please press " POSTPONE ." EKEY EKEY>FKEY ;

T{ TFKEY" <left>" -> K-LEFT  <TRUE> }T
T{ TFKEY" <right>" -> K-RIGHT <TRUE> }T
T{ TFKEY" <up>"    -> K-UP    <TRUE> }T
T{ TFKEY" <down>" -> K-DOWN  <TRUE> }T
T{ TFKEY" <home>" -> K-HOME  <TRUE> }T
T{ TFKEY" <end>"   -> K-END   <TRUE> }T
T{ TFKEY" <prior>" -> K-PRIOR <TRUE> }T
T{ TFKEY" <next>" -> K-NEXT  <TRUE> }T

T{ TFKEY" <F1>" -> K-F1  <TRUE> }T
T{ TFKEY" <F2>" -> K-F2  <TRUE> }T
T{ TFKEY" <F3>" -> K-F3  <TRUE> }T
T{ TFKEY" <F4>" -> K-F4  <TRUE> }T
T{ TFKEY" <F5>" -> K-F5  <TRUE> }T
T{ TFKEY" <F6>" -> K-F6  <TRUE> }T
T{ TFKEY" <F7>" -> K-F7  <TRUE> }T
T{ TFKEY" <F8>" -> K-F8  <TRUE> }T
T{ TFKEY" <F9>" -> K-F9  <TRUE> }T
T{ TFKEY" <F10>" -> K-F10 <TRUE> }T
T{ TFKEY" <F11>" -> K-F11 <TRUE> }T
T{ TFKEY" <F11>" -> K-F12 <TRUE> }T

T{ TFKEY" <shift-left>" -> K-LEFT K-SHIFT-MASK OR <TRUE> }T
T{ TFKEY" <ctrl-left>" -> K-LEFT K-CTRL-MASK OR <TRUE> }T
T{ TFKEY" <alt-left>" -> K-LEFT K-ALT-MASK OR <TRUE> }T

T{ TFKEY" <a>" SWAP EKEY>CHAR -> <FALSE> CHAR a <TRUE> }T