Info Catalog elisp: Controlling Active Maps elisp: Keymaps elisp: Functions for Key Lookup

elisp: Key Lookup

 
 21.10 Key Lookup
 ================
 
 “Key lookup” is the process of finding the binding of a key sequence
 from a given keymap.  The execution or use of the binding is not part of
 key lookup.
 
    Key lookup uses just the event type 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 a mouse event with just its types (a
 symbol) instead of the entire event (a list).  Input Events.
 Such a key sequence is insufficient for ‘command-execute’ to run, 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 found by
 looking up an event type in a keymap.  (This doesn’t include the item
 string and other extra elements in a keymap element for a menu item,
 because ‘lookup-key’ and other key lookup functions don’t include them
 in the returned value.)  While any Lisp object may be stored in a keymap
 as a keymap entry, not all make sense for key lookup.  Here is a table
 of the meaningful types 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, and has no default binding, that is equivalent to a binding of
      ‘nil’ for that event type.
 
 COMMAND
      The events used so far in the lookup form a complete key, and
      COMMAND is its binding.  What Is a Function.
 
 ARRAY
      The array (either a string or a vector) is a keyboard macro.  The
      events used so far in the lookup form a complete key, and the array
      is its binding.  See Keyboard Macros, for more information.
 
 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.
 
 LIST
      The meaning of a list depends on what it contains:
 
         • 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 function, and is treated
           as such (see above).  In order to execute properly as a key
           binding, this function must be a command—it must have an
           ‘interactive’ specification.  Defining Commands.
 
 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 that is a keymap,
      a command, or a keyboard macro.
 
      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 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’
      (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 that leads to one of them, or ‘nil’.
 

Info Catalog elisp: Controlling Active Maps elisp: Keymaps elisp: Functions for Key Lookup