GNU Info

(elisp)Key Sequence Input

---

Next: Reading One Event Up: Reading Input

---

Enter node , (file) or (file)node

Key Sequence Input
------------------

   The command loop reads input a key sequence at a time, by calling
`read-key-sequence'.  Lisp programs can also call this function; for
example, `describe-key' uses it to read the key to describe.

 - Function: read-key-sequence prompt
     This function reads a key sequence and returns it as a string or
     vector.  It keeps reading events until it has accumulated a
     complete key sequence; that is, enough to specify a non-prefix
     command using the currently active keymaps.

     If the events are all characters and all can fit in a string, then
     `read-key-sequence' returns a string (Note: Strings of Events).
     Otherwise, it returns a vector, since a vector can hold all kinds
     of events--characters, symbols, and lists.  The elements of the
     string or vector are the events in the key sequence.

     The argument PROMPT is either a string to be displayed in the echo
     area as a prompt, or `nil', meaning not to display a prompt.

     In the example below, the prompt `?' is displayed in the echo area,
     and the user types `C-x C-f'.

          (read-key-sequence "?")
          
          ---------- Echo Area ----------
          ?C-x C-f
          ---------- Echo Area ----------
          
               => "^X^F"

     The function `read-key-sequence' suppresses quitting: `C-g' typed
     while reading with this function works like any other character,
     and does not set `quit-flag'.  Note: Quitting.

 - Function: read-key-sequence-vector prompt
     This is like `read-key-sequence' except that it always returns the
     key sequence as a vector, never as a string.  Note: Strings of
     Events.

   If an input character is an upper-case letter and has no key binding,
but its lower-case equivalent has one, then `read-key-sequence'
converts the character to lower case.  Note that `lookup-key' does not
perform case conversion in this way.

   The function `read-key-sequence' also transforms some mouse events.
It converts unbound drag events into click events, and discards unbound
button-down events entirely.  It also reshuffles focus events and
miscellaneous window events so that they never appear in a key sequence
with any other events.

   When mouse events occur in special parts of a window, such as a mode
line or a scroll bar, the event type shows nothing special--it is the
same symbol that would normally represent that combination of mouse
button and modifier keys.  The information about the window part is kept
elsewhere in the event--in the coordinates.  But `read-key-sequence'
translates this information into imaginary "prefix keys", all of which
are symbols: `header-line', `horizontal-scroll-bar', `menu-bar',
`mode-line', `vertical-line', and `vertical-scroll-bar'.  You can define
meanings for mouse clicks in special window parts by defining key
sequences using these imaginary prefix keys.

   For example, if you call `read-key-sequence' and then click the
mouse on the window's mode line, you get two events, like this:

     (read-key-sequence "Click on the mode line: ")
          => [mode-line
              (mouse-1
               (#<window 6 on NEWS> mode-line
                (40 . 63) 5959987))]

 - Variable: num-input-keys
     This variable's value is the number of key sequences processed so
     far in this Emacs session.  This includes key sequences read from
     the terminal and key sequences read from keyboard macros being
     executed.

 - Variable: num-nonmacro-input-events
     This variable holds the total number of input events received so
     far from the terminal--not counting those generated by keyboard
     macros.