(lispref.info)Key Lookup


Next: Functions for Key Lookup Prev: Active Keymaps Up: Keymaps

Key Lookup
==========

   "Key lookup" is the process of finding the binding of a key sequence
from a given keymap.  Actual execution of the binding is not part of
key lookup.

   Key lookup uses just the event types of each event in the key
sequence; the rest of the event is ignored.  In fact, a key sequence
used for key lookup may designate mouse events with just their types
(symbols) instead of with entire mouse events (lists).  Note: Input
Events.  Such a pseudo-key-sequence is insufficient for
`command-execute', but it is sufficient for looking up or rebinding a
key.

   When the key sequence consists of multiple events, key lookup
processes the events sequentially: the binding of the first event is
found, and must be a keymap; then the second event's binding is found in
that keymap, and so on until all the events in the key sequence are used
up.  (The binding thus found for the last event may or may not be a
keymap.)  Thus, the process of key lookup is defined in terms of a
simpler process for looking up a single event in a keymap.  How that is
done depends on the type of object associated with the event in that
keymap.

   Let's use the term "keymap entry" to describe the value directly
associated with an event type in a keymap.  While any Lisp object may be
stored as a keymap entry, not all make sense for key lookup.  Here is a
list of the meaningful kinds of keymap entries:

`nil'
     `nil' means that the events used so far in the lookup form an
     undefined key.  When a keymap fails to mention an event type at
     all, that is equivalent to an entry of `nil' for that type.

KEYMAP
     The events used so far in the lookup form a prefix key.  The next
     event of the key sequence is looked up in KEYMAP.

COMMAND
     The events used so far in the lookup form a complete key, and
     COMMAND is its binding.

STRING
VECTOR
     The events used so far in the lookup form a complete key, whose
     binding is a keyboard macro.  See Note: Keyboard Macros, for more
     information.

LIST
     The meaning of a list depends on the types of the elements of the
     list.

        * If the CAR of LIST is the symbol `keymap', then the list is a
          keymap, and is treated as a keymap (see above).

        * If the CAR of LIST is `lambda', then the list is a lambda
          expression.  This is presumed to be a command, and is treated
          as such (see above).

        * If the CAR of LIST is a keymap and the CDR is an event type,
          then this is an "indirect entry":

               (OTHERMAP . OTHERTYPE)

          When key lookup encounters an indirect entry, it looks up
          instead the binding of OTHERTYPE in OTHERMAP and uses that.

          This feature permits you to define one key as an alias for
          another key.  For example, an entry whose CAR is the keymap
          called `esc-map' and whose CDR is 32 (the code for space)
          means, "Use the global binding of `Meta-SPC', whatever that
          may be."

SYMBOL
     The function definition of SYMBOL is used in place of SYMBOL.  If
     that too is a symbol, then this process is repeated, any number of
     times.  Ultimately this should lead to an object which is a
     keymap, a command or a keyboard macro.  A list is allowed if it is
     a keymap or a command, but indirect entries are not understood
     when found via symbols.

     Note that keymaps and keyboard macros (strings and vectors) are not
     valid functions, so a symbol with a keymap, string or vector as its
     function definition is also invalid as a function.  It is, however,
     valid as a key binding.  If the definition is a keyboard macro,
     then the symbol is also valid as an argument to `command-execute'
     (Note: Interactive Call.).

     The symbol `undefined' is worth special mention: it means to treat
     the key as undefined.  Strictly speaking, the key is defined, and
     its binding is the command `undefined'; but that command does the
     same thing that is done automatically for an undefined key: it
     rings the bell (by calling `ding') but does not signal an error.

     `undefined' is used in local keymaps to override a global key
     binding and make the key "undefined" locally.  A local binding of
     `nil' would fail to do this because it would not override the
     global binding.

ANYTHING ELSE
     If any other type of object is found, the events used so far in the
     lookup form a complete key, and the object is its binding, but the
     binding is not executable as a command.

   In short, a keymap entry may be a keymap, a command, a keyboard
macro, a symbol which leads to one of them, or an indirection or `nil'.
Here is an example of a sparse keymap with two characters bound to
commands and one bound to another keymap.  This map is the normal value
of `emacs-lisp-mode-map'.  Note that 9 is the code for TAB, 127 for
DEL, 27 for ESC, 17 for `C-q' and 24 for `C-x'.

     (keymap (9 . lisp-indent-line)
             (127 . backward-delete-char-untabify)
             (27 keymap (17 . indent-sexp) (24 . eval-defun)))


automatically generated by info2www