BINDKEY()

BINDKEY()

Top  Previous  Next

 

The BINDKEY() function sets, removes, queries, saves or restores key bindings.

 

 

Format

 

BINDKEY(key.string, action)

 

where

 

key.stringThe character sequence for the key to be bound, unbound or queried.

 

actionidentifies the action to be performed:
>= 0Bind key to this code (0 to 65535)
-1Remove binding for key.string.
-2Query binding for key.string.
-3Save bindings.
-4Restore bindings from key.string.
-5Disables lone Esc key handling in KEYCODE().
-6Re-enables lone Esc key handling in KEYCODE().

 

 

The BINDKEY() function used with an action value in the range 0 to 65535 (0xFFFF) binds the key sequence in key.string to the given action value. This is the underlying mechanism of the KEYEDIT, KEYEXIT and KEYTRAP statements used to set up keys for special handling by INPUT@ and INPUTFIELD. If successful, the function returns True and the STATUS() function would return zero. If an error occurs, the function returns False and the STATUS() function can be used to find the cause of the error:

1        Invalid key.string

2        Invalid action

3        Key.string conflicts with an existing binding

 

Action values for many keys are defined in the KEYIN.H include record in the SYSCOM file. It is recommended that when binding special keys such as the function keys and cursor keys, the action values defined with the KV$ prefix should be used in preference to those with the K$ prefix. If this is done, the KEYCODE() function will return the corresponding 8-bit character  associated with this key but the KEYCODEV() function will return the Unicode BMP Private Use Area value. If the K$ prefix values are used, both functions return the 8-bit value which may cause programs to fail on ECS mode systems.

 

An action value of -1 removes any defined binding for key.string. Used in this mode, the function always returns True even if there was no binding for this key.string.

 

An action value of -2 returns the action number bound to the given key.string. If there is no binding, the function returns -1.

 

An action value of -3 returns a string that contains all defined key bindings. The value of key.string is ignored. Programs should make no assumption about the format of this string as it may change between releases of QM.

 

An action value of -4 restores the bindings define in a key.string that was returned by a previous call to BINDKEY() with an action of -3. This action also restores the state of lone Esc key handling to its setting at the time when the key bindings were saved.

 

Actions -5 and -6 control whether the KEYCODE() function returns char(27) on detection of an incoming Escape character that is not closely followed by further characters. When this mode is enabled (which is the default), the Esc is returned by KEYCODE() if no further characters are received within 200mS. When disabled, the Esc is always treated as the start of a control sequence and KEYCODE() will wait for further characters. These two action codes return True if lone Esc key handling was previously enabled, or False if it was previously disabled.

 

 

Because retrieval of a key binding returns -1 if the key is not bound, it is easy to save and restore a single key binding:

OLD.BINDING = BINDKEY(KEY.STRING, -2)

IF BINDKEY(KEY.STRING, NEW.ACTION) THEN ...

 

To restore the original binding, unbinding the key if there was no previous binding:

X = BINDKEY(KEY.STRING, OLD.BINDING)

 

 

To save and subsequently restore all bindings:

SAVED.KEYS = BINDKEY('', -3)

...rebind some keys and do some processing...

X = BINDKEY(SAVED.KEYS, -4)

 

Note that key bindings set using BINDKEY() are lost on return to the command processor. This ensures that private bindings do not interfere with programs run later in the process. Persistent bindings can be set by modifying the terminfo database.

 

 

See also:

INPUT@, INPUTFIELD, KEYCODE(), KEYCODEV(), KEYEDIT, KEYEXIT, KEYTRAP