/sys$common/syshlp/TPUHELP.HLB  —  KEYMAPS_AND_KEYMAP_LISTS
  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.  TPU 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 TPU should respond to the
         user's keystrokes

  TPU 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, TPU uses the information stored in the
  key-map list bound to the current buffer to determine what to do.  The
  order in which TPU uses the information is as follows:

     1.  TPU 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, TPU checks the key maps to
         see if the key is defined.  TPU 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, TPU 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, TPU executes the
         procedure.  Next, TPU executes the code bound to the key.  After
         executing that code, TPU 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, TPU 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, TPU displays the character on the
         screen.  If SELF_INSERT is set to OFF, TPU 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,
         TPU 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
Close Help