KEYMAPS AND KEYMAP LISTS
Key maps and key-map lists let you manipulate a set of key definitions as
a unit rather than individually. For example, key maps make it easier to
implement a command that defines all the keys on the keypad.
A key map is a set of key definitions. DECTPU supplies a default key map
called TPU$KEY_MAP. To create a key map other than the default, use the
CREATE_KEY_MAP built-in. To add key definitions to a key map, use the
DEFINE_KEY built-in. To see a list of all key maps that have been defined
by a program, use the SHOW(KEY_MAPS) built-in.
Key maps may be stored in one or more key-map lists. A key-map list is a
structure containing the following:
o Key maps ordered in the sequence you specify
o Additional information specifying how DECTPU should respond to the
user's keystrokes
DECTPU supplies a default key map list called TPU$KEY_MAP_LIST. To create
a list other than the default, use the CREATE_KEY_MAP_LIST built-in.
Key-map lists are stored in section files.
To use a key map, you must first put it in a key-map list, even if you
only want to use one key map in your program. To add a key map to a list,
use the ADD_KEY_MAP built-in. You can add the same key map to more than
one list. You may want to do so if you want different buffers to handle
keystrokes in different ways. For example, suppose you had an application
in which you wanted one buffer that would display all self-inserting
characters and another buffer that would disable all self-inserting keys.
Suppose, too, that you wanted the user's key definitions to work in both
buffers. In such a case, you would add the key map containing the user's
key definitions to the key-map lists associated with both buffers.
When adding key maps to a key-map list, you must specify whether the map
is added to the beginning or the end of the list. When you add a map to
the beginning of the list, the keys defined in the map override the key
definitions in all other maps in the list. If you add the map to the end,
its key definitions take effect only for keys that are not defined in the
other key maps. To obtain the first, last, next, or previous key map in a
key map list, use the GET_INFO(KEY_MAP...) built-in.
A key-map list controls what happens in a buffer when the user presses a
key. To have an effect, a key-map list must be bound to a buffer. A
buffer can only have one key-map list bound to it at a time. However, a
given key-map list can be bound to more than one buffer at a time. Every
buffer must have a key-map list bound to it, but not every key map has to
be bound to a buffer. There may be points in your program where a given
key-map list is not bound to any buffer.
By default, each newly-created buffer is bound to the default key map
list, TPU$KEY_MAP_LIST. To change the key-map list to which a buffer is
bound, use the SET(KEY_MAP_LIST...) built-in. A buffer remains bound to a
key-map list regardless of whether the buffer is displayed on the screen.
To see a list of all key-map lists that have been defined by a program,
use the SHOW(KEY_MAP_LISTS) built-in. To obtain the current, first, last,
next, or previous key map list in the section file, use the
GET_INFO(KEY_MAP_LIST...) built-in.
When the user presses a key, DECTPU uses the information stored in the
key-map list bound to the current buffer to determine what to do. The
order in which DECTPU uses the information is as follows:
1. DECTPU determines whether the key pressed is the "shift" key (or
GOLD key). If so, no action is taken until another key is pressed.
2. If the key is not the "shift" key, DECTPU checks the key maps to
see if the key is defined. DECTPU looks through the key maps in
order and uses the first definition of a given key that it
encounters.
3. If the key is defined, DECTPU checks whether a pre-key execution
procedure has been stored in the key-map list by use of the SET
(PRE_KEY_PROCEDURE...) built-in. If so, DECTPU executes the
procedure. Next, DECTPU executes the code bound to the key. After
executing that code, DECTPU checks whether a post-key execution
procedure has been stored in the key-map list. If so, the post-key
execution procedure is executed.
4. If the key is not defined, DECTPU checks whether the key pressed is
the key for a printable character. If so, the program checks
whether the SET (SELF_INSERT...) built-in is set to ON or OFF. If
SELF_INSERT is set to ON, DECTPU displays the character on the
screen. If SELF_INSERT is set to OFF, DECTPU takes whatever action
is specified by the SET (UNDEFINED_KEY...) built-in.
5. If the key is not for a printable character and is not defined,
DECTPU takes whatever action is specified by the SET
(UNDEFINED_KEY...) built-in.
To remove a key map from a key-map list, use the REMOVE_KEY_MAP built-in.
A key map is not destroyed even if it is removed from all key-map lists.
Likewise, a key-map list is not destroyed even if all key maps have been
removed from it.
If you are extending or layering on top of EVE, note the following about
EVE usage of key maps and key-map lists:
o In EVE, the name of a key map is not the same as the variable that
contains the key map. For example, the EVE variable
EVE$X_USER_KEYS contains the key map named EVE$USER_KEYS, which
stores the user's key definitions.
o EVE stores all its key maps in the default key-map list,
TPU$KEY_MAP_LIST. However, the default key map, TPU$KEY_MAP, is
removed from the default key-map list by the standard EVE section
file.
o The order of key maps in the EVE key map list depends on the
terminal type, as follows:
VT200 Key Map Order VT100 Key Map Order
------------------- ------------------
EVE$X_USER_KEYS EVE$X_USER_KEYS
EVE$X_MOUSE_KEYS EVE$X_VT100_KEYS
EVE$X_VT200_KEYS EVE$X_STANDARD_KEYS
EVE$X_STANDARD_KEYS
Related Topics
ADD_KEY_MAP CREATE_KEY_MAP CREATE_KEY_MAP_LIST
DEFINE_KEY GET_INFO REMOVE_KEY_MAP
SET(KEY_MAP_LIST) SET(PRE_KEY_PROCEDURE) SET(POST_KEY_PROCEDURE)
SET(SELF_INSERT) SET(UNDEFINED_KEY) SHOW