   This version is newer than the second printed edition of the GNU
Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.

   Published by the Free Software Foundation 675 Massachusetts Avenue
Cambridge, MA 02139 USA

   Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.

Code Characters for `interactive'
---------------------------------

   The code character descriptions below contain a number of key words,
defined here as follows:

Completion
     Provide completion.  TAB, SPC, and RET perform name completion
     because the argument is read using `completing-read' (see
     Completion.).  `?' displays a list of possible completions.

Existing
     Require the name of an existing object.  An invalid name is not
     accepted; the commands to exit the minibuffer do not exit if the
     current input is not valid.

Default
     A default value of some sort is used if the user enters no text in
     the minibuffer.  The default depends on the code character.

No I/O
     This code letter computes an argument without reading any input.
     Therefore, it does not use a prompt string, and any prompt string
     you supply is ignored.

Prompt
     A prompt immediately follows the code character.  The prompt ends
     either with the end of the string or with a newline.

Special
     This code character is meaningful only at the beginning of the
     interactive string, and it does not look for a prompt or a newline.
     It is a single, isolated character.

   Here are the code character descriptions for use with `interactive':

`*'
     Signal an error if the current buffer is read-only.  Special.

`@'
     Select the window mentioned in the first mouse event in the key
     sequence that invoked this command.  Special.

`_'
     Do not cause the region to be deactivated when this command
     completes.  Special.

`a'
     A function name (i.e., a symbol which is `fboundp').  Existing,
     Completion, Prompt.

`b'
     The name of an existing buffer.  By default, uses the name of the
     current buffer (see Buffers.).  Existing, Completion, Default,
     Prompt.

`B'
     A buffer name.  The buffer need not exist.  By default, uses the
     name of a recently used buffer other than the current buffer.
     Completion, Prompt.

`c'
     A character.  The cursor does not move into the echo area.  Prompt.

`C'
     A command name (i.e., a symbol satisfying `commandp').  Existing,
     Completion, Prompt.

`d'
     The position of point as a number (see Point.).  No I/O.

`D'
     A directory name.  The default is the current default directory of
     the current buffer, `default-directory' (see System Environment.).
     Existing, Completion, Default, Prompt.

`e'
     The last mouse event in the key sequence that invoked the command.
     No I/O.

`f'
     A file name of an existing file (see File Names.).  The default
     directory is `default-directory'.  Existing, Completion, Default,
     Prompt.

`F'
     A file name.  The file need not exist.  Completion, Default,
     Prompt.

`k'
     A key sequence (see Keymap Terminology.).  This keeps reading
     events until a command (or undefined command) is found in the
     current key maps.  The key sequence argument is represented as a
     vector of events.  The cursor does not move into the echo area.
     Prompt.

     This kind of input is used by commands such as `describe-key' and
     `global-set-key'.

`m'
     The position of the mark as a number.  No I/O.

`n'
     A number read with the minibuffer.  If the input is not a number,
     the user is asked to try again.  The prefix argument, if any, is
     not used.  Prompt.

`N'
     The raw prefix argument.  If the prefix argument is `nil', then a
     number is read as with `n'.  Requires a number.  Prompt.

`p'
     The numeric prefix argument.  (Note that this `p' is lower case.)
     No I/O.

`P'
     The raw prefix argument.  (Note that this `P' is upper case.)
     See Prefix Command Arguments.  No I/O.

`r'
     Point and the mark, as two numeric arguments, smallest first.
     This is the only code letter that specifies two successive
     arguments rather than one.  No I/O.

`s'
     Arbitrary text, read in the minibuffer and returned as a string
     (see Text from Minibuffer.).  Terminate the input with either
     LFD or RET.  (`C-q' may be used to include either of these
     characters in the input.)  Prompt.

`S'
     An interned symbol whose name is read in the minibuffer.  Any
     whitespace character terminates the input.  (Use `C-q' to include
     whitespace in the string.)  Other characters that normally
     terminate a symbol (e.g., parentheses and brackets) do not do so
     here.  Prompt.

`v'
     A variable declared to be a user option (i.e., satisfying the
     predicate `user-variable-p').  See High-Level Completion.
     Existing, Completion, Prompt.

`x'
     A Lisp object specified in printed representation, terminated with
     a LFD or RET.  The object is not evaluated.  See Object from Minibuffer.
     Prompt.

`X'
     A Lisp form is read as with `x', but then evaluated so that its
     value becomes the argument for the command.  Prompt.

Examples of Using `interactive'
-------------------------------

   Here are some examples of `interactive':

     (defun foo1 ()              ; `foo1' takes no arguments,
         (interactive)           ;   just moves forward two words.
         (forward-word 2))
          => foo1

     (defun foo2 (n)             ; `foo2' takes one argument,
         (interactive "p")       ;   which is the numeric prefix.
         (forward-word (* 2 n)))
          => foo2

     (defun foo3 (n)             ; `foo3' takes one argument,
         (interactive "nCount:") ;   which is read with the Minibuffer.
         (forward-word (* 2 n)))
          => foo3

     (defun three-b (b1 b2 b3)
       "Select three existing buffers.
     Put them into three windows, selecting the last one."
         (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
         (delete-other-windows)
         (split-window (selected-window) 8)
         (switch-to-buffer b1)
         (other-window 1)
         (split-window (selected-window) 8)
         (switch-to-buffer b2)
         (other-window 1)
         (switch-to-buffer b3))
          => three-b
     (three-b "*scratch*" "declarations.texi" "*mail*")
          => nil

Interactive Call
================

   After the command loop has translated a key sequence into a
definition, it invokes that definition using the function
`command-execute'.  If the definition is a function that is a command,
`command-execute' calls `call-interactively', which reads the arguments
and calls the command.  You can also call these functions yourself.

 - Function: commandp OBJECT
     Returns `t' if OBJECT is suitable for calling interactively; that
     is, if OBJECT is a command.  Otherwise, returns `nil'.

     The interactively callable objects include strings and vectors
     (treated as keyboard macros), lambda expressions that contain a
     top-level call to `interactive', byte-code function objects,
     autoload objects that are declared as interactive (non-`nil'
     fourth argument to `autoload'), and some of the primitive
     functions.

     A symbol is `commandp' if its function definition is `commandp'.

     Keys and keymaps are not commands.  Rather, they are used to look
     up commands (see Keymaps.).

     See `documentation' in Accessing Documentation, for a
     realistic example of using `commandp'.

 - Function: call-interactively COMMAND &optional RECORD-FLAG
     This function calls the interactively callable function COMMAND,
     reading arguments according to its interactive calling
     specifications.  An error is signaled if COMMAND cannot be called
     interactively (i.e., it is not a command).  Note that keyboard
     macros (strings and vectors) are not accepted, even though they
     are considered commands.

     If RECORD-FLAG is the symbol `lambda', the interactive calling
     arguments for `command' are read and returned as a list, but the
     function is not called on them.

     If RECORD-FLAG is `t', then this command and its arguments are
     unconditionally added to the list `command-history'.  Otherwise,
     the command is added only if it uses the minibuffer to read an
     argument.  See Command History.

 - Function: command-execute COMMAND &optional RECORD-FLAG
     This function executes COMMAND as an editing command.  The
     argument COMMAND must satisfy the `commandp' predicate; i.e., it
     must be an interactively callable function or a string.

     A string or vector as COMMAND is executed with
     `execute-kbd-macro'.  A function is passed to
     `call-interactively', along with the optional RECORD-FLAG.

     A symbol is handled by using its function definition in its place.
     A symbol with an `autoload' definition counts as a command if it
     was declared to stand for an interactively callable function.
     Such a definition is handled by loading the specified library and
     then rechecking the definition of the symbol.

 - Command: execute-extended-command PREFIX-ARGUMENT
     This function reads a command name from the minibuffer using
     `completing-read' (see Completion.).  Then it uses
     `command-execute' to call the specified command.  Whatever that
     command returns becomes the value of `execute-extended-command'.

     If the command asks for a prefix argument, the value
     PREFIX-ARGUMENT is supplied.  If `execute-extended-command' is
     called interactively, the current raw prefix argument is used for
     PREFIX-ARGUMENT, and thus passed on to whatever command is run.

     `execute-extended-command' is the normal definition of `M-x', so
     it uses the string `M-x ' as a prompt.  (It would be better to
     take the prompt from the events used to invoke
     `execute-extended-command', but that is painful to implement.)  A
     description of the value of the prefix argument, if any, also
     becomes part of the prompt.

          (execute-extended-command 1)
          ---------- Buffer: Minibuffer ----------
          M-x forward-word RET
          ---------- Buffer: Minibuffer ----------
               => t

 - Function: interactive-p
     This function returns `t' if the containing function (the one that
     called `interactive-p') was called interactively, with the function
     `call-interactively'.  (It makes no difference whether
     `call-interactively' was called from Lisp or directly from the
     editor command loop.)  Note that if the containing function was
     called by Lisp evaluation (or with `apply' or `funcall'), then it
     was not called interactively.

     The usual application of `interactive-p' is for deciding whether to
     print an informative message.  As a special exception,
     `interactive-p' returns `nil' whenever a keyboard macro is being
     run.  This is to suppress the informative messages and speed
     execution of the macro.

     For example:

          (defun foo ()
            (interactive)
            (and (interactive-p)
                 (message "foo")))
               => foo

          (defun bar ()
            (interactive)
            (setq foobar (list (foo) (interactive-p))))
               => bar

          ;; Type `M-x foo'.
               -| foo

          ;; Type `M-x bar'.
          ;; This does not print anything.

          foobar
               => (nil t)

Information from the Command Loop
=================================

   The editor command loop sets several Lisp variables to keep status
records for itself and for commands that are run.

 - Variable: last-command
     This variable records the name of the previous command executed by
     the command loop (the one before the current command).  Normally
     the value is a symbol with a function definition, but this is not
     guaranteed.

     The value is set by copying the value of `this-command' when a
     command returns to the command loop, except when the command
     specifies a prefix argument for the following command.

 - Variable: this-command
     This variable records the name of the command now being executed by
     the editor command loop.  Like `last-command', it is normally a
     symbol with a function definition.

     This variable is set by the command loop just before the command
     is run, and its value is copied into `last-command' when the
     command finishes (unless the command specifies a prefix argument
     for the following command).

     Some commands change the value of this variable during their
     execution, simply as a flag for whatever command runs next.  In
     particular, the functions that kill text set `this-command' to
     `kill-region' so that any kill commands immediately following will
     know to append the killed text to the previous kill.

 - Function: this-command-keys
     This function returns a vector containing the key and mouse events
     that invoked the present command, plus any previous commands that
     generated the prefix argument for this command. (Note: this is not
     the same as in FSF Emacs 19, which can return a string.)  See
     Input Events.

     This function copies the vector and the events; it is safe to keep
     and modify them.

          (this-command-keys)
          ;; Now type `C-u C-x C-e'.
               => [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]

 - Variable: last-command-event
     This variable is set to the last input event that was read by the
     command loop as part of a command.  The principal use of this
     variable is in `self-insert-command', which uses it to decide which
     character to insert.

     This variable is off limits: you may not set its value or modify
     the event that is its value, as it is destructively modified by
     `read-key-sequence'.  If you want to keep a pointer to this value,
     you must use `copy-event'.

     Note that this variable is an alias for `last-command-char' in FSF
     Emacs 19.

          last-command-event
          ;; Now type `C-u C-x C-e'.
               => #<keypress-event control-E>

 - Variable: last-command-char
     If the value of `last-command-event' is a keyboard event, then this
     is the nearest ASCII equivalent to it.  This the the value that
     `self-insert-command' will put in the buffer.  Remember that there
     is *not* a 1:1 mapping between keyboard events and ASCII
     characters: the set of keyboard events is much larger, so writing
     code that examines this variable to determine what key has been
     typed is bad practice, unless you are certain that it will be one
     of a small set of characters.

     This function exists for compatibility with Emacs version 18.

          last-command-char
          ;; Now type `C-u C-x C-e'.
               => 5

     The value is 5 because that is the ASCII code for `C-e'.

 - Variable: current-mouse-event
     This variable holds the mouse-button event which invoked this
     command, or `nil'.  This is what `(interactive "e")' returns.

 - Variable: echo-keystrokes
     This variable determines how much time should elapse before command
     characters echo.  Its value must be an integer, which specifies the
     number of seconds to wait before echoing.  If the user types a
     prefix key (say `C-x') and then delays this many seconds before
     continuing, the key `C-x' is echoed in the echo area.  Any
     subsequent characters in the same command will be echoed as well.

     If the value is zero, then command input is not echoed.

Input Events
============

   The Emacs command loop reads a sequence of "input events" that
represent keyboard or mouse activity.  Unlike in Emacs 18 and in FSF
Emacs 19, events are a primitive Lisp type that must be manipulated
using their own accessor and settor primitives.  This section describes
the representation and meaning of input events in detail.

   A key sequence that starts with a mouse event is read using the
keymaps of the buffer in the window that the mouse was in, not the
current buffer.  This does not imply that clicking in a window selects
that window or its buffer--that is entirely under the control of the
command binding of the key sequence.

   For information about how exactly the Emacs command loop works,
see Reading Input.

 - Function: eventp OBJECT
     This function returns non-`nil' if EVENT is an input event.

Event Types
-----------

   Events represent keyboard or mouse activity or status changes of
various sorts, such as process input being available or a timeout being
triggered.  The different event types are as follows:

key_press_event
     A key was pressed.  Note that modifier keys such as "control",
     "shift", and "alt" do not generate events; instead, they are
     tracked internally by Emacs, and non-modifier key presses generate
     events that specify both the key pressed and the modifiers that
     were held down at the time.

button_press_event
button_release_event
     A button was pressed or released.  Along with the button that was
     pressed or released, button events specify the modifier keys that
     were held down at the time and the position of the pointer at the
     time.

pointer_motion_event
     The pointer was moved.  Along with the position of the pointer,
     these events also specify the modifier keys that were held down at
     the time.

menu_event
     A menu item was selected.

process_event
     Input is available on a process.

timeout_event
     A timeout has triggered.

magic_event
     Some window-system-specific action (such as a screen being resized
     or a portion of a screen needing to be redrawn) has occurred.  The
     contents of this event are not accessible at the E-Lisp level, but
     `dispatch-event' knows what to do with an event of this type.

eval_event
     This is a special kind of event specifying that a particular
     function needs to be called when this event is dispatched.  An
     event of this type is sometimes placed in the event queue when a
     magic event is processed.  This kind of event should generally
     just be passed off to `dispatch-event'.  See Dispatching an Event.

Contents of the Different Types of Events
-----------------------------------------

   Every event, no matter what type it is, contains a timestamp (which
is typically an offset in milliseconds from when the X server was
started) indicating when the event occurred.  In addition, many events
contain a "channel", which specifies which screen the event occurred on,
and/or a value indicating which modifier keys (shift, control, etc.)
were held down at the time of the event.

   The contents of each event are as follows:

key_press_event
    channel
    timestamp
    key
          Which key was pressed.  This is an integer (in the printing
          ASCII range: >32 and <127) or a symbol such as `left' or
          `right'.  Note that many physical keys are actually treated
          as two separate keys, depending on whether the shift key is
          pressed; for example, the "a" key is treated as either "a" or
          "A" depending on the state of the shift key, and the "1" key
          is similarly treated as either "1" or "!" on most keyboards.
          In such cases, the shift key does not show up in the modifier
          list.  For other keys, such as `backspace', the shift key
          shows up as a regular modifier.

    modifiers
          Which modifier keys were pressed.  As mentioned above, the
          shift key is not treated as a modifier for many keys and will
          not show up in this list in such cases.

button_press_event
button_release_event
    channel
    timestamp
    button
          What button went down or up.  Buttons are numbered starting
          at 1.

    modifiers
          Which modifier keys were pressed.  The special business
          mentioned above for the shift key does *not* apply to mouse
          events.

    x
    y
          The position of the pointer (in pixels) at the time of the
          event.

pointer_motion_event
    channel
    timestamp
    x
    y
          The position of the pointer (in pixels) after it moved.

    modifiers
          Which modifier keys were pressed.  The special business
          mentioned above for the shift key does *not* apply to mouse
          events.

menu_event
    timestamp
    function
          The E-Lisp function to call for this event.  This is normally
          either `eval' or `call-interactively'.

    object
          The object to pass to the function.  This is normally the
          callback that was specified in the menu description.

process_event
    timestamp
    process
          The Emacs "process" object in question.

timeout_event
    timestamp
    function
          The E-Lisp function to call for this timeout.  It is called
          with one argument, the event.

    object
          Some Lisp object associated with this timeout, to make it
          easier to tell them apart.  The function and object for this
          event were specified when the timeout was set.

magic_event
    timestamp
     (The rest of the information in this event is not user-accessible.)

eval_event
    timestamp
    function
          An E-Lisp function to call when this event is dispatched.

    object
          The object to pass to the function.  The function and object
          are set when the event is created.

Event Predicates
----------------

   The following predicates return whether an object is an event of a
particular type.

 - Function: button-event-p OBJECT OBJECT
     This is true if OBJECT is a button-press or button-release event.

 - Function: button-press-event-p OBJECT
     This is true if OBJECT is a mouse-button-press event.

 - Function: button-release-event-p OBJECT
     This is true if OBJECT is a mouse-button-release event.

 - Function: eval-event-p OBJECT
     This is true if OBJECT is an eval or menu event.

 - Function: key-press-event-p OBJECT
     This is true if OBJECT is a key-press event.

 - Function: menu-event-p OBJECT
     This is true if OBJECT is a menu event.

 - Function: motion-event-p OBJECT
     This is true if OBJECT is a mouse-motion event.

 - Function: process-event-p OBJECT
     This is true if OBJECT is a process event.

 - Function: timeout-event-p OBJECT
     This is true if OBJECT is a timeout event.

Accessing the Contents of Events
--------------------------------

   The following functions allow access to the contents of events.

 - Function: event-timestamp EVENT
     This function returns the timestamp of the given event object.

 - Function: event-screen EVENT
     This function returns the "channel" or screen that the given mouse
     motion, button press, or button release event occurred in.  This
     will be `nil' for non-mouse events. (Note that, although a
     keyboard event has a screen associated with it, it is not
     currently user-accessible.)

 - Function: event-x-pixel EVENT
     This function returns the X position in pixels of the given
     mouse-motion, button-press, or button-release event.

 - Function: event-y-pixel EVENT
     This function returns the Y position in pixels of the given
     mouse-motion, button-press, or button-release event.

 - Function: event-key EVENT
     This function returns the KeySym of the given key-press event.
     This will be the ASCII code of a printing character, or a symbol.

 - Function: event-button EVENT
     This function returns the button-number of the given
     mouse-button-press event.

 - Function: event-modifiers EVENT
     This function returns a list of symbols, the names of the modifier
     keys which were down when the given mouse or keyboard event was
     produced.

 - Function: event-modifier-bits EVENT
     This function returns a number representing the modifier keys
     which were down when the given mouse or keyboard event was
     produced.

 - Function: event-function EVENT
     This function returns the callback function of the given timeout,
     menu, or eval event.

 - Function: event-object EVENT
     This function returns the callback function argument of the given
     timeout, menu, or eval event.

 - Function: event-process EVENT
     This function returns the process of the given process event.

   The following functions return information about the position that a
mouse event occurred at, in an alternative form that may be more useful
than the raw (x,y) pixel value.

 - Function: event-glyph EVENT
     If the given mouse-motion, button-press, or button-release event
     happened on top of a glyph, this returns it; else `nil'.

 - Function: event-point EVENT
     This function returns the character position of the given
     mouse-motion, button-press, or button-release event.  If the event
     did not occur over a window, or did not occur over text, then this
     returns `nil'.  Otherwise, it returns an index into the buffer
     visible in the event's window.

 - Function: event-window EVENT
     Given a mouse-motion, button-press, or button-release event,
     compute and return the window on which that event occurred.  This
     may be `nil' if the event did not occur in an Emacs window (in the
     border or modeline).

 - Function: event-x EVENT
     This function returns the X position of the given mouse-motion,
     button-press, or button-release event in characters.

 - Function: event-y EVENT
     This function returns the Y position of the given mouse-motion,
     button-press, or button-release event in characters.

Working With Events
-------------------

   Emacs provides primitives for creating, copying, and destroying event
objects.  Many functions that return events take an event object as an
argument and fill in the fields of this event; or they make accept
either an event object or `nil', creating the event object first in the
latter case.

 - Function: allocate-event
     This function returns an empty event structure.  WARNING: The event
     object returned may be a reused one; see the function
     `deallocate-event'.

 - Function: copy-event EVENT1 &optional EVENT2
     This function makes a copy of the given event object.  If a second
     argument is given, the first event is copied into the second and
     the second is returned.  If the second argument is not supplied
     (or is `nil') then a new event will be made as with
     `allocate-event'.

 - Function: deallocate-event EVENT
     This function allows the given event structure to be reused.  You
     MUST NOT use this event object after calling this function with
     it.  You will lose.  It is not necessary to call this function, as
     event objects are garbage-collected like all other objects;
     however, it may be more efficient to explicitly deallocate events
     when you are sure that that is safe.

Converting Events
-----------------

   Emacs provides some auxiliary functions for converting between events
and other ways of representing keys.  These are useful when working with
ASCII strings and with keymaps.

 - Function: character-to-event CH &optional EVENT
     This function converts a numeric ASCII value to an event structure,
     replete with modifier bits.  CH is the character to convert, and
     EVENT is the event object to fill in.  This function contains
     knowledge about what the codes "mean" - for example, the number 9
     is converted to the character Tab, not the distinct character
     Control-I.

     If `event' is not `nil', it is modified; otherwise, a new event
     object is created.  In both cases, the event is returned.

     Beware that `character-to-event' and `event-to-character' are not
     strictly inverse functions, since events contain much more
     information than the ASCII character set can encode.

 - Function: event-to-character EVENT &optional ALLOW-EXTRA-MODIFIERS
          ALLOW-META ALLOW-NON-ASCII
     This function returns the closest ASCII approximation to EVENT.
     If the event isn't a keypress, this returns `nil'.

     If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its
     translation; it will ignore modifier keys other than control and
     meta, and will ignore the shift modifier on those characters which
     have no shifted ASCII equivalent (Control-Shift-A for example,
     will be mapped to the same ASCII code as Control-A).

     If ALLOW-META is non-`nil', then the Meta modifier will be
     represented by turning on the high bit of the byte returned;
     otherwise, `nil' will be returned for events containing the Meta
     modifier.

     If ALLOW-NON-ASCII is non-`nil', then characters which are present
     in the prevailing character set (see variable `character-set-property')
     will be returned as their code
     in that character set, instead of the return value being
     restricted to ASCII.

     Note that specifying both ALLOW-META and ALLOW-NON-ASCII is
     ambiguous, as both use the high bit; M-x and oslash will be
     indistinguishable.

 - Function: events-to-keys EVENTS &optional NO-MICE
     Given a vector of event objects, this function returns a vector of
     key descriptors, or a string (if they all fit in the ASCII range).
     Optional arg NO-MICE means that button events are not allowed.

Reading Input
=============

   The editor command loop reads keyboard input using the function
`next-event' and constructs key sequences out of the events using
`dispatch-event'.  Lisp programs can also use the function
`read-key-sequence', which reads input a key sequence at a time.  See
also `momentary-string-display' in Temporary Displays, and
`sit-for' in Waiting.  See Terminal Input, for functions
and variables for controlling terminal input modes and debugging
terminal input.

   For higher-level input facilities, see Minibuffers.

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

   Lisp programs can read input a key sequence at a time by calling
`read-key-sequence'; for example, `describe-key' uses it to read the
key to describe.

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

     The vector and the event objects it contains are freshly created,
     and will not be side-effected by subsequent calls to this function.

     Quitting is suppressed inside `read-key-sequence'.  In other words,
     a `C-g' typed while reading with this function is treated like any
     other character, and does not set `quit-flag'.  See Quitting.

     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.

     If the user selects a menu item while we are prompting for a key
     sequence, the returned value will be a vector of a single
     menu-selection event.  An error will be signalled if you pass this
     value to `lookup-key' or a related function.

     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 ----------

               => [#<keypress-event control-X> #<keypress-event control-F>]

   If an input character is an upper case letter and has no key binding,
but the 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.

Reading One Event
-----------------

   The lowest level functions for command input are those which read a
single event.  These functions often make a distinction between
"command events", which are user actions (keystrokes and mouse
actions), and other events, which serve as communication between Emacs
and the window system.

 - Function: next-event &optional EVENT PROMPT
     This function reads and returns the next available event from the
     window system or terminal driver, waiting if necessary until an
     event is available.  Pass this object to `dispatch-event' to
     handle it. If an event object is supplied, it is filled in and
     returned; otherwise a new event object will be created.

     Events can come directly from the user, from a keyboard macro, or
     from `unread-command-event'.

     In most cases, the function `next-command-event' is more
     appropriate.

 - Function: next-command-event &optional EVENT
     This function returns the next available "user" event from the
     window system or terminal driver.  Pass this object to
     `dispatch-event' to handle it.  If an event object is supplied, it
     is filled in and returned, otherwise a new event object will be
     created.

     The event returned will be a keyboard, mouse press, or mouse
     release event.  If there are non-command events available (mouse
     motion, sub-process output, etc) then these will be executed (with
     `dispatch-event') and discarded.  This function is provided as a
     convenience; it is equivalent to the Lisp code

          	(while (progn
          		 (next-event event)
          	         (not (or (key-press-event-p event)
          	                  (button-press-event-p event)
          	                  (button-release-event-p event)
          	                  (menu-event-p event))))
          	   (dispatch-event event))

     Here is what happens if you call `next-command-event' and then
     press the right-arrow function key:

          (next-command-event)
               => #<keypress-event right>

 - Function: read-char
     This function reads and returns a character of command input.  If a
     mouse click is detected, an error is signalled.  The character
     typed is returned as an ASCII value.  This function is retained for
     compatibility with Emacs 18, and is most likely the wrong thing
     for you to be using: consider using `next-command-event' instead.

 - Function: enqueue-eval-event FUNCTION OBJECT
     This function adds an eval event to the back of the queue.  The
     eval event will be the next event read after all pending events.

Dispatching an Event
--------------------

 - Function: dispatch-event EVENT
     Given an event object returned by `next-event', this function
     executes it.  This is the basic function that makes Emacs respond
     to user input; it also deals with notifications from the window
     system (such as Expose events).

Quoted Character Input
----------------------

   You can use the function `read-quoted-char' when you want the user
to specify a character, and allow the user to specify a control or meta
character conveniently with quoting or as an octal character code.  The
command `quoted-insert' calls this function.

 - Function: read-quoted-char &optional PROMPT
     This function is like `read-char', except that if the first
     character read is an octal digit (0-7), it reads up to two more
     octal digits (but stopping if a non-octal digit is found) and
     returns the character represented by those digits as an octal
     number.

     Quitting is suppressed when the first character is read, so that
     the user can enter a `C-g'.  See Quitting.

     If PROMPT is supplied, it specifies a string for prompting the
     user.  The prompt string is always printed in the echo area and
     followed by a single `-'.

     In the following example, the user types in the octal number 177
     (which is 127 in decimal).

          (read-quoted-char "What character")

          ---------- Echo Area ----------
          What character-`177'
          ---------- Echo Area ----------

               => 127

Peeking and Discarding
----------------------

   See also the variables `last-command-event' and `last-command-char'
(see Command Loop Info).

 - Variable: unread-command-event
     Set this to an event object to simulate the receipt of an event
     from the user.  Normally this is `nil'. (Under FSF Emacs 19, this
     variable is called `unread-command-events' and is a list of
     events.)

     The variable is used because in some cases a function reads a
     event and then decides not to use it.  Storing the event in this
     variable causes it to be processed normally by the command loop or
     when the functions to read command input are called.

     For example, the function that implements numeric prefix arguments
     reads any number of digits.  When it finds a non-digit event, it
     must unread the event so that it can be read normally by the
     command loop.  Likewise, incremental search uses this feature to
     unread events it does not recognize.

 - Function: input-pending-p
     This function determines whether any command input is currently
     available to be read.  It returns immediately, with value `t' if
     there is input, `nil' otherwise.  On rare occasions it may return
     `t' when no input is available.

 - Variable: last-input-event
     This variable is set to the last keyboard or mouse button event
     received.

     This variable is off limits: you may not set its value or modify
     the event that is its value, as it is destructively modified by
     `read-key-sequence'.  If you want to keep a pointer to this value,
     you must use `copy-event'.

     Note that this variable is an alias for `last-input-char' in FSF
     Emacs 19.

     In the example below, a character is read (the character `1').  It
     becomes the value of `last-input-event', while `C-e' (from the
     `C-x C-e' command used to evaluate this expression) remains the
     value of `last-command-event'.

          (progn (print (next-command-event))
                 (print last-command-event)
                 last-input-event)
               -| #<keypress-event 1>
               -| #<keypress-event control-E>
               => #<keypress-event 1>

 - Variable: last-input-char
     If the value of `last-input-event' is a keyboard event, then this
     is the nearest ASCII equivalent to it.  Remember that there is
     *not* a 1:1 mapping between keyboard events and ASCII characters:
     the set of keyboard events is much larger, so writing code that
     examines this variable to determine what key has been typed is bad
     practice, unless you are certain that it will be one of a small
     set of characters.

     This function exists for compatibility with Emacs version 18.

 - Function: discard-input
     This function discards the contents of the terminal input buffer
     and cancels any keyboard macro that might be in the process of
     definition.  It returns `nil'.

     In the following example, the user may type a number of characters
     right after starting the evaluation of the form.  After the
     `sleep-for' finishes sleeping, any characters that have been typed
     are discarded.

          (progn (sleep-for 2)
            (discard-input))
               => nil

Waiting for Elapsed Time or Input
=================================

   The waiting commands are designed to make Emacs wait for a certain
amount of time to pass or until there is input.  For example, you may
wish to pause in the middle of a computation to allow the user time to
view the display.  `sit-for' pauses and updates the screen, and returns
immediately if input comes in, while `sleep-for' pauses without
updating the screen.

   Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
two arguments to specify the time (one integer and one float value),
instead of a single argument that can be either an integer or a float.

 - Function: sit-for SECONDS &optional NODISP
     This function performs redisplay (provided there is no pending
     input from the user), then waits SECONDS seconds, or until input is
     available.  SECONDS may be a float, meaning a fractional part of a
     second.  The result is `t' if `sit-for' waited the full time with
     no input arriving (see `input-pending-p' in Peeking and Discarding).
     Otherwise, the value is `nil'.

     Redisplay is normally preempted if input arrives, and does not
     happen at all if input is available before it starts. (You can
     force screen updating in such a case by using `force-redisplay'.
     See Refresh Screen.) If there is no input pending, you can
     force an update with no delay by using `(sit-for 0)'.

     If NODISP is non-`nil', then `sit-for' does not redisplay, but it
     still returns as soon as input is available (or when the timeout
     elapses).

     The usual purpose of `sit-for' is to give the user time to read
     text that you display.

 - Function: sleep-for SECONDS
     This function simply pauses for SECONDS seconds without updating
     the display.  SECONDS may be a float, meaning pause for some
     fractional part of a second.  This function pays no attention to
     available input.  It returns `nil'.

     Use `sleep-for' when you wish to guarantee a delay.

   See Time of Day, for functions to get the current time.

Quitting
========

   Typing `C-g' while the command loop has run a Lisp function causes
Emacs to "quit" whatever it is doing.  This means that control returns
to the innermost active command loop.

   Typing `C-g' while the command loop is waiting for keyboard input
does not cause a quit; it acts as an ordinary input character.  In the
simplest case, you cannot tell the difference, because `C-g' normally
runs the command `keyboard-quit', whose effect is to quit.  However,
when `C-g' follows a prefix key, the result is an undefined key.  The
effect is to cancel the prefix key as well as any prefix argument.

   In the minibuffer, `C-g' has a different definition: it aborts out
of the minibuffer.  This means, in effect, that it exits the minibuffer
and then quits.  (Simply quitting would return to the command loop
*within* the minibuffer.)  The reason why `C-g' does not quit directly
when the command reader is reading input is so that its meaning can be
redefined in the minibuffer in this way.  `C-g' following a prefix key
is not redefined in the minibuffer, and it has its normal effect of
canceling the prefix key and prefix argument.  This too would not be
possible if `C-g' quit directly.

   `C-g' causes a quit by setting the variable `quit-flag' to a
non-`nil' value.  Emacs checks this variable at appropriate times and
quits if it is not `nil'.  Setting `quit-flag' non-`nil' in any way
thus causes a quit.

   At the level of C code, quits cannot happen just anywhere; only at
the special places which check `quit-flag'.  The reason for this is
that quitting at other places might leave an inconsistency in Emacs's
internal state.  Because quitting is delayed until a safe place,
quitting cannot make Emacs crash.

   Certain functions such as `read-key-sequence' or `read-quoted-char'
prevent quitting entirely even though they wait for input.  Instead of
quitting, `C-g' serves as the requested input.  In the case of
`read-key-sequence', this serves to bring about the special behavior of
`C-g' in the command loop.  In the case of `read-quoted-char', this is
so that `C-q' can be used to quote a `C-g'.

   You can prevent quitting for a portion of a Lisp function by binding
the variable `inhibit-quit' to a non-`nil' value.  Then, although `C-g'
still sets `quit-flag' to `t' as usual, the usual result of this--a
quit--is prevented.  Eventually, `inhibit-quit' will become `nil'
again, such as when its binding is unwound at the end of a `let' form.
At that time, if `quit-flag' is still non-`nil', the requested quit
happens immediately.  This behavior is ideal for a "critical section",
where you wish to make sure that quitting does not happen within that
part of the program.

   In some functions (such as `read-quoted-char'), `C-g' is handled in
a special way which does not involve quitting.  This is done by reading
the input with `inhibit-quit' bound to `t' and setting `quit-flag' to
`nil' before `inhibit-quit' becomes `nil' again.  This excerpt from the
definition of `read-quoted-char' shows how this is done; it also shows
that normal quitting is permitted after the first character of input.

     (defun read-quoted-char (&optional prompt)
       "...DOCUMENTATION..."
       (let ((count 0) (code 0) char)
         (while (< count 3)
           (let ((inhibit-quit (zerop count))
                 (help-form nil))
             (and prompt (message "%s-" prompt))
             (setq char (read-char))
             (if inhibit-quit (setq quit-flag nil)))
           ...)
         (logand 255 code)))

 - Variable: quit-flag
     If this variable is non-`nil', then Emacs quits immediately,
     unless `inhibit-quit' is non-`nil'.  Typing `C-g' sets `quit-flag'
     non-`nil', regardless of `inhibit-quit'.

 - Variable: inhibit-quit
     This variable determines whether Emacs should quit when `quit-flag'
     is set to a value other than `nil'.  If `inhibit-quit' is
     non-`nil', then `quit-flag' has no special effect.

 - Command: keyboard-quit
     This function signals the `quit' condition with `(signal 'quit
     nil)'.  This is the same thing that quitting does.  (See `signal'
     in Errors.)

   You can specify a character other than `C-g' to use for quitting.
See the function `set-input-mode' in Terminal Input.