KEYEDIT statement

Syntax

KEYEDIT (function, key) [ , (function, key) ] ...

Description

Use the KEYEDIT statement to assign specific keyboard keys to the editing functions of the INPUT statement @ statement, and to the !EDIT.INPUT and !GET.KEY subroutines. KEYEDIT supports the following editing functions:

• Left arrow (<-)
• Enter (Return)
• Back space
• Right arrow (->)
• Insert character
• Delete character
• Insert mode on
• Insert mode off
• Clear field
• Erase to end-of-line
• Insert mode toggle

In addition to the supported editing functions, two codes exist to designate the Esc and function keys.

function is an expression that evaluates to a numeric code assigned to a particular editing function.

Code

Function

1

Function key

2

Left arrow (<-)

3

Return key

4

Back space

5

Esc key

6

Right arrow (->)

7

Insert character

8

Delete character

9

Insert mode ON

10

Insert mode OFF

11

Clear from current position to end-of-line

12

Erase entire line

13

Insert mode toggle

key is an expression evaluating to a decimal value that designates the keyboard key to assign to the editing function. There are three key types, described in the following table:

If either function or key evaluates to the null value or an empty string, the KEYEDIT statement fails, the program terminates, and a run-time error message is produced.

To define key, you must know the ASCII value generated by the keyboard on the terminal being used. Once you know the ASCII code sequence generated by a particular keyboard key, you can use one of the following three methods for deriving the numeric key value.

Defining Control Keys

A control key is one whose ASCII value falls within the range of 1 through 31. Generally keys of this type consist of pressing a keyboard key while holding down the Ctrl key. The key value is the ASCII code value, that is, Ctrl-A is 1, Ctrl-M is 13, and so on

Defining Escape Keys

An escape key is one which consists of pressing the Esc key followed by a single ASCII value. The Esc key can be defined by issuing a KEYEDIT statement using a function value of 5 and the ASCII value of the escape character for the key parameter, for example, KEYEDIT (5,27).

The key value for an escape key is derived by adding the ASCII value of the character following the Esc key and 32. The constant 32 is added to ensure that the final key value falls within the range of 32 to 159, that is, Esc-a is 33 (1+32), Esc-z is 122 (90+32), Esc-p is 144 (112+32), and so on.

Defining Function Keys

A function key is similar to an escape key but consists of a function key followed by one or more ASCII values. The function key can be defined by issuing a KEYEDIT statement using a function value of 1 and the ASCII value of the function character for the key parameter, for example, KEYEDIT(1,1).

Deriving the key value for a function key depends on the number of characters in the sequence the keyboard key generates. Because the KEYEDIT statement recognizes function keys that generate character sequences up to five characters long, the following method can be used to derive the key value.

Assume that keyboard key F7 generates the following character sequence:

Ctrl-A ] 6 ~ <Return>

This character sequence is to be assigned to the Clear Field functionality of the INPUT @ statement. It can be broken into five separate characters, identified as follows:

First you define the function key value. Do this by issuing the KEYEDIT statement with a function value of 1 and with a key value defined as the ASCII value of the preamble character, that is, KEYEDIT (1, 1).

Once you define the function key, the following formula is applied to the remaining characters in the sequence:

ASCII value * ( 2(8*(character position - 1))

Using the example above:

The results of each calculation are then added together. Finally, the constant 160 is added to insure that the final key parameter value falls within the range of 160 through 2,139,062,303. For our example above, this would yield 176,043,613 + 160, or 176,043,773. To complete this example and assign this key to the Clear Field functionality, use the following KEYEDIT statement:

KEYEDIT (11, 176043773)

Historically, key values falling in the range of 160 through 287 included an implied Return, as there was no method for supporting multiple character sequences. With the support of multiple character sequences, you must now include the Return in the calculation for proper key recognition, with one exception. For legacy key values that fall within the range of 160 through 287, a Return is automatically appended to the end of the character sequence, yielding an internal key parameter of greater value.

A function key generates the character sequence:

Ctrl-A B <Return>

Before supporting multiple character sequences, this function key would have been defined as:

KEYEDIT (1, 1), (11, 225)

(1,1) defined the preamble of the function key, and (11, 225) defined the Clear-to-end-of-line key. The 225 value was derived by adding 160 to B (ASCII 65). The <Return> (ASCII 10) was implied. This can be shown by using the SYSTEM(1050) function to return the internal trap table contents:

The value 2785 is derived as follows:

(65 * 1) + (10 * 256) + 160 = 65 + 2560 + 160 = 2785.

Defining Unsupported Keys

You can use the KEYEDIT statement to designate keys that are recognized as unsupported by the !EDIT.INPUT subroutine. When the !EDIT.INPUT subroutine encounters an unsupported key, it sounds the terminal bell.

An unsupported key can be any of the three key types:

• Control key
• Escape key
• Function key

Define an unsupported key by assigning any negative decimal value for the function parameter.

The key parameter is derived as described earlier.

See the !EDIT.INPUT or !GET.KEY subroutine for more information.

Retrieving Defined Keys

The SYSTEM function(1050) function returns a dynamic array of defined KEYEDIT, KEYEXIT statement and KEYTRAP statement keys. Field marks (ASCII 254) delimit the elements of the dynamic array. Each field in the dynamic array has the following structure:

key.type V function.parameter V key.parameter

key.type is one of the following values:

Value

Description

1

A KEYEDIT value

2

A KEYTRAP value

3

A KEYEXIT value

4

The INPUTNULL value

5

An unsupported value

function.parameter and key.parameter are the values passed as parameters to the associated statement, except for the INPUTNULL value.

Example

The following example illustrates the use of the KEYEDIT statement and the SYSTEM(1050) function:

KEYEDIT (1,1), (2,21), (3,13), (4,8), (6,6), 
(12,176043773)
KEYTRAP (1,2)
keys.dfn=SYSTEM(1050)
PRINT "#","Type","Value","Key"
XX=DCOUNT(keys.dfn,@FM)
FOR I=1 TO XX
print I-1,keys.dfn<I,1>,keys.dfn<I,2>,keys.dfn<I,3>
NEXT I

The program output is:

#         Type      Value     Key
0         1         3         10
1         1         3         13
2         1         4         8
3         1         1         1
4         1         2         21
5         1         6         6
6         1         12        176043773
7         2         1         2