Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events
+
+Converting Events
+-----------------
+
+ XEmacs 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 key-description &optional event console
+ use-console-meta-flag
+ This function converts a keystroke description to an event
+ structure. KEY-DESCRIPTION is the specification of a key stroke,
+ 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>.
+
+ Note that KEY-DESCRIPTION can be an integer, a character, a symbol
+ such as `clear' or a list such as `(control backspace)'.
+
+ If optional arg EVENT is non-`nil', it is modified; otherwise, a
+ new event object is created. In both cases, the event is returned.
+
+ Optional third arg CONSOLE is the console to store in the event,
+ and defaults to the selected console.
+
+ If KEY-DESCRIPTION is an integer or character, the high bit may be
+ interpreted as the meta key. (This is done for backward
+ compatibility in lots of places.) If USE-CONSOLE-META-FLAG is
+ `nil', this will always be the case. If USE-CONSOLE-META-FLAG is
+ non-`nil', the `meta' flag for CONSOLE affects whether the high
+ bit is interpreted as a meta key. (See `set-input-mode'.) If you
+ don't want this silly meta interpretation done, you should pass in
+ a list containing the character.
+
+ 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 (*note variable
+ `character-set-property': Keymaps.) 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.
+
+\1f
+File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop
+
+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 *Note Temporary Displays::, and
+`sit-for' in *Note Waiting::. *Note Terminal Input::, for functions
+and variables for controlling terminal input modes and debugging
+terminal input.
+
+ For higher-level input facilities, see *Note Minibuffers::.
+
+* Menu:
+
+* Key Sequence Input:: How to read one key sequence.
+* Reading One Event:: How to read just one event.
+* Dispatching an Event:: What to do with an event once it has been read.
+* Quoted Character Input:: Asking the user to specify a character.
+* Peeking and Discarding:: How to reread or throw away input events.
+
+\1f
+File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input
+
+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 &optional continue-echo
+ dont-downcase-last
+ This function reads a sequence of keystrokes or mouse clicks and
+ returns it as a vector of event objects read. 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 so will not be side-effected by subsequent calls to this
+ function).
+
+ 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::.
+
+ 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.
+
+ Second optional arg CONTINUE-ECHO non-`nil' means this key echoes
+ as a continuation of the previous key.
+
+ Third optional arg DONT-DOWNCASE-LAST non-`nil' means do not
+ convert the last event to lower case. (Normally any upper case
+ event is converted to lower case if the original event is
+ undefined and the lower case equivalent is defined.) This argument
+ is provided mostly for FSF compatibility; the equivalent effect
+ can be achieved more generally by binding
+ `retry-undefined-key-binding-unshifted' to `nil' around the call
+ to `read-key-sequence'.
+
+ 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 (a misc-user 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 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.
+
+\1f
+File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input
+
+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 XEmacs
+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-events'.
+
+ In most cases, the function `next-command-event' is more
+ appropriate.
+
+ - Function: next-command-event &optional event prompt
+ 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.
+
+\1f
+File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input
+
+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 XEmacs respond
+ to user input; it also deals with notifications from the window
+ system (such as Expose events).
+
+\1f
+File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input
+
+Quoted Character Input
+----------------------
+
+ You can use the function `read-quoted-char' to ask the user to
+specify a character, and allow the user to specify a control or meta
+character conveniently, either literally or as an octal character code.
+The command `quoted-insert' uses 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 in octal.
+
+ Quitting is suppressed when the first character is read, so that
+ the user can enter a `C-g'. *Note Quitting::.
+
+ If PROMPT is supplied, it specifies a string for prompting the
+ user. The prompt string is always displayed in the echo area,
+ 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
+
+\1f
+File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input
+
+Miscellaneous Event Input Features
+----------------------------------
+
+ This section describes how to "peek ahead" at events without using
+them up, how to check for pending input, and how to discard pending
+input.
+
+ See also the variables `last-command-event' and `last-command-char'
+(*Note Command Loop Info::).
+
+ - Variable: unread-command-events
+ This variable holds a list of events waiting to be read as command
+ input. The events are used in the order they appear in the list,
+ and removed one by one as they are used.
+
+ The variable is needed 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 by the functions to read command input.
+
+ 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 with no special meaning in a search, because these
+ events should exit the search and then execute normally.
+
+
+ - Variable: unread-command-event
+ This variable holds a single event to be read as command input.
+
+ This variable is mostly obsolete now that you can use
+ `unread-command-events' instead; it exists only to support programs
+ written for versions of XEmacs prior to 19.12.
+
+ - 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 available 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.
+
+ 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, `discard-input' discards any
+ characters typed during the sleep.
+
+ (progn (sleep-for 2)
+ (discard-input))
+ => nil
+
+\1f
File: lispref.info, Node: Waiting, Next: Quitting, Prev: Reading Input, Up: Command Loop
Waiting for Elapsed Time or Input
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
+ - Function: sit-for seconds &optional nodisplay
This function performs redisplay (provided there is no pending
input from the user), then waits SECONDS seconds, or until input is
available. The result is `t' if `sit-for' waited the full time
*Note 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).
+ If NODISPLAY 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.
value of the prefix argument directly in the variable
`current-prefix-arg', but this is less clean.
- - Function: prefix-numeric-value arg
+ - Function: prefix-numeric-value raw
This function returns the numeric meaning of a valid raw prefix
- argument value, ARG. The argument may be a symbol, a number, or a
+ argument value, RAW. The argument may be a symbol, a number, or a
list. If it is `nil', the value 1 is returned; if it is `-', the
value -1 is returned; if it is a number, that number is returned;
if it is a list, the CAR of that list (which should be a number) is
Recursive editing levels are also used when you type `C-r' in
`query-replace' or use `C-x q' (`kbd-macro-query').
- - Function: recursive-edit
+ - Command: recursive-edit
This function invokes the editor command loop. It is called
automatically by the initialization of XEmacs, to let the user
begin editing. When called from a Lisp program, it enters a
entries in it are `nil', meaning "command undefined". The only
difference between this function and `make-keymap' is that this
function returns a "smaller" keymap (one that is expected to
- contain fewer entries). As keymaps dynamically resize, the
+ contain fewer entries). As keymaps dynamically resize, this
distinction is not great.
Optional argument NAME specifies a name to assign to the keymap,
This function returns the default binding of KEYMAP, or `nil' if
it has none.
-\1f
-File: lispref.info, Node: Key Sequences, Next: Prefix Keys, Prev: Inheritance and Keymaps, Up: Keymaps
-
-Key Sequences
-=============
-
- Contrary to popular belief, the world is not ASCII. When running
-under a window manager, XEmacs can tell the difference between, for
-example, the keystrokes `control-h', `control-shift-h', and
-`backspace'. You can, in fact, bind different commands to each of
-these.
-
- A "key sequence" is a set of keystrokes. A "keystroke" is a keysym
-and some set of modifiers (such as <CONTROL> and <META>). A "keysym"
-is what is printed on the keys on your keyboard.
-
- A keysym may be represented by a symbol, or (if and only if it is
-equivalent to an ASCII character in the range 32 - 255) by a character
-or its equivalent ASCII code. The `A' key may be represented by the
-symbol `A', the character `?A', or by the number 65. The `break' key
-may be represented only by the symbol `break'.
-
- A keystroke may be represented by a list: the last element of the
-list is the key (a symbol, character, or number, as above) and the
-preceding elements are the symbolic names of modifier keys (<CONTROL>,
-<META>, <SUPER>, <HYPER>, <ALT>, and <SHIFT>). Thus, the sequence
-`control-b' is represented by the forms `(control b)', `(control ?b)',
-and `(control 98)'. A keystroke may also be represented by an event
-object, as returned by the `next-command-event' and `read-key-sequence'
-functions.
-
- Note that in this context, the keystroke `control-b' is _not_
-represented by the number 2 (the ASCII code for `^B') or the character
-`?\^B'. See below.
-
- The <SHIFT> modifier is somewhat of a special case. You should not
-(and cannot) use `(meta shift a)' to mean `(meta A)', since for
-characters that have ASCII equivalents, the state of the shift key is
-implicit in the keysym (`a' vs. `A'). You also cannot say `(shift =)'
-to mean `+', as that sort of thing varies from keyboard to keyboard.
-The <SHIFT> modifier is for use only with characters that do not have a
-second keysym on the same key, such as `backspace' and `tab'.
-
- A key sequence is a vector of keystrokes. As a degenerate case,
-elements of this vector may also be keysyms if they have no modifiers.
-That is, the `A' keystroke is represented by all of these forms:
-
- A ?A 65 (A) (?A) (65)
- [A] [?A] [65] [(A)] [(?A)] [(65)]
-
- the `control-a' keystroke is represented by these forms:
-
- (control A) (control ?A) (control 65)
- [(control A)] [(control ?A)] [(control 65)]
-
- the key sequence `control-c control-a' is represented by these forms:
-
- [(control c) (control a)] [(control ?c) (control ?a)]
- [(control 99) (control 65)] etc.
-
- Mouse button clicks work just like keypresses: `(control button1)'
-means pressing the left mouse button while holding down the control
-key. `[(control c) (shift button3)]' means `control-c', hold <SHIFT>,
-click right.
-
- Commands may be bound to the mouse-button up-stroke rather than the
-down-stroke as well. `button1' means the down-stroke, and `button1up'
-means the up-stroke. Different commands may be bound to the up and
-down strokes, though that is probably not what you want, so be careful.
-
- For backward compatibility, a key sequence may also be represented by
-a string. In this case, it represents the key sequence(s) that would
-produce that sequence of ASCII characters in a purely ASCII world. For
-example, a string containing the ASCII backspace character, `"\^H"',
-would represent two key sequences: `(control h)' and `backspace'.
-Binding a command to this will actually bind both of those key
-sequences. Likewise for the following pairs:
-
- control h backspace
- control i tab
- control m return
- control j linefeed
- control [ escape
- control @ control space
-
- After binding a command to two key sequences with a form like
-
- (define-key global-map "\^X\^I" 'command-1)
-
-it is possible to redefine only one of those sequences like so:
-
- (define-key global-map [(control x) (control i)] 'command-2)
- (define-key global-map [(control x) tab] 'command-3)
-
- Of course, all of this applies only when running under a window
-system. If you're talking to XEmacs through a TTY connection, you
-don't get any of these features.
-
- - Function: event-matches-key-specifier-p event key-specifier
- This function returns non-`nil' if EVENT matches KEY-SPECIFIER,
- which can be any valid form representing a key sequence. This can
- be useful, e.g., to determine if the user pressed `help-char' or
- `quit-char'.
-
-\1f
-File: lispref.info, Node: Prefix Keys, Next: Active Keymaps, Prev: Key Sequences, Up: Keymaps
-
-Prefix Keys
-===========
-
- A "prefix key" has an associated keymap that defines what to do with
-key sequences that start with the prefix key. For example, `C-x' is a
-prefix key, and it uses a keymap that is also stored in the variable
-`ctl-x-map'. Here is a list of the standard prefix keys of XEmacs and
-their keymaps:
-
- * `help-map' is used for events that follow `C-h'.
-
- * `mode-specific-map' is for events that follow `C-c'. This map is
- not actually mode specific; its name was chosen to be informative
- for the user in `C-h b' (`display-bindings'), where it describes
- the main use of the `C-c' prefix key.
-
- * `ctl-x-map' is the map used for events that follow `C-x'. This
- map is also the function definition of `Control-X-prefix'.
-
- * `ctl-x-4-map' is used for events that follow `C-x 4'.
-
- * `ctl-x-5-map' is used for events that follow `C-x 5'.
-
- * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have
- no special name.
-
- * `esc-map' is an evil hack that is present for compatibility
- purposes with Emacs 18. Defining a key in `esc-map' is equivalent
- to defining the same key in `global-map' but with the <META>
- prefix added. You should _not_ use this in your code. (This map is
- also the function definition of `ESC-prefix'.)
-
- The binding of a prefix key is the keymap to use for looking up the
-events that follow the prefix key. (It may instead be a symbol whose
-function definition is a keymap. The effect is the same, but the symbol
-serves as a name for the prefix key.) Thus, the binding of `C-x' is
-the symbol `Control-X-prefix', whose function definition is the keymap
-for `C-x' commands. (The same keymap is also the value of `ctl-x-map'.)
-
- Prefix key definitions can appear in any active keymap. The
-definitions of `C-c', `C-x', `C-h' and <ESC> as prefix keys appear in
-the global map, so these prefix keys are always available. Major and
-minor modes can redefine a key as a prefix by putting a prefix key
-definition for it in the local map or the minor mode's map. *Note
-Active Keymaps::.
-
- If a key is defined as a prefix in more than one active map, then its
-various definitions are in effect merged: the commands defined in the
-minor mode keymaps come first, followed by those in the local map's
-prefix definition, and then by those from the global map.
-
- In the following example, we make `C-p' a prefix key in the local
-keymap, in such a way that `C-p' is identical to `C-x'. Then the
-binding for `C-p C-f' is the function `find-file', just like `C-x C-f'.
-The key sequence `C-p 6' is not found in any active keymap.
-
- (use-local-map (make-sparse-keymap))
- => nil
- (local-set-key "\C-p" ctl-x-map)
- => nil
- (key-binding "\C-p\C-f")
- => find-file
-
- (key-binding "\C-p6")
- => nil
-
- - Function: define-prefix-command symbol &optional mapvar
- This function defines SYMBOL as a prefix command: it creates a
- keymap and stores it as SYMBOL's function definition. Storing the
- symbol as the binding of a key makes the key a prefix key that has
- a name. If optional argument MAPVAR is not specified, it also
- sets SYMBOL as a variable, to have the keymap as its value. (If
- MAPVAR is given and is not `t', its value is stored as the value
- of SYMBOL.) The function returns SYMBOL.
-
- In Emacs version 18, only the function definition of SYMBOL was
- set, not the value as a variable.
-
-\1f
-File: lispref.info, Node: Active Keymaps, Next: Key Lookup, Prev: Prefix Keys, Up: Keymaps
-
-Active Keymaps
-==============
-
- XEmacs normally contains many keymaps; at any given time, just a few
-of them are "active" in that they participate in the interpretation of
-user input. These are the global keymap, the current buffer's local
-keymap, and the keymaps of any enabled minor modes.
-
- The "global keymap" holds the bindings of keys that are defined
-regardless of the current buffer, such as `C-f'. The variable
-`global-map' holds this keymap, which is always active.
-
- Each buffer may have another keymap, its "local keymap", which may
-contain new or overriding definitions for keys. The current buffer's
-local keymap is always active except when `overriding-local-map' or
-`overriding-terminal-local-map' overrides it. Extents and text
-properties can specify an alternative local map for certain parts of the
-buffer; see *Note Extents and Events::.
-
- Each minor mode may have a keymap; if it does, the keymap is active
-when the minor mode is enabled.
-
- The variable `overriding-local-map' and
-`overriding-terminal-local-map', if non-`nil', specify other local
-keymaps that override the buffer's local map and all the minor mode
-keymaps.
-
- All the active keymaps are used together to determine what command to
-execute when a key is entered. XEmacs searches these maps one by one,
-in order of decreasing precedence, until it finds a binding in one of
-the maps.
-
- More specifically:
-
- For key-presses, the order of keymaps searched is:
-
- * the `keymap' property of any extent(s) or text properties at point;
-
- * any applicable minor-mode maps;
-
- * the current local map of the current buffer;
-
- * the current global map.
-
- For mouse-clicks, the order of keymaps searched is:
-
- * the current local map of the `mouse-grabbed-buffer' if any;
-
- * the `keymap' property of any extent(s) at the position of the click
- (this includes modeline extents);
-
- * the `modeline-map' of the buffer corresponding to the modeline
- under the mouse (if the click happened over a modeline);
-
- * the value of `toolbar-map' in the current buffer (if the click
- happened over a toolbar);
-
- * the current local map of the buffer under the mouse (does not
- apply to toolbar clicks);
-
- * any applicable minor-mode maps;
-
- * the current global map.
-
- Note that if `overriding-local-map' or
-`overriding-terminal-local-map' is non-`nil', _only_ those two maps and
-the current global map are searched.
-
- The procedure for searching a single keymap is called "key lookup";
-see *Note Key Lookup::.
-
- Since every buffer that uses the same major mode normally uses the
-same local keymap, you can think of the keymap as local to the mode. A
-change to the local keymap of a buffer (using `local-set-key', for
-example) is seen also in the other buffers that share that keymap.
-
- The local keymaps that are used for Lisp mode, C mode, and several
-other major modes exist even if they have not yet been used. These
-local maps are the values of the variables `lisp-mode-map',
-`c-mode-map', and so on. For most other modes, which are less
-frequently used, the local keymap is constructed only when the mode is
-used for the first time in a session.
-
- The minibuffer has local keymaps, too; they contain various
-completion and exit commands. *Note Intro to Minibuffers::.
-
- *Note Standard Keymaps::, for a list of standard keymaps.
-
- - Function: current-keymaps &optional event-or-keys
- This function returns a list of the current keymaps that will be
- searched for bindings. This lists keymaps such as the current
- local map and the minor-mode maps, but does not list the parents
- of those keymaps. EVENT-OR-KEYS controls which keymaps will be
- listed. If EVENT-OR-KEYS is a mouse event (or a vector whose last
- element is a mouse event), the keymaps for that mouse event will
- be listed. Otherwise, the keymaps for key presses will be listed.
-
- - Variable: global-map
- This variable contains the default global keymap that maps XEmacs
- keyboard input to commands. The global keymap is normally this
- keymap. The default global keymap is a full keymap that binds
- `self-insert-command' to all of the printing characters.
-
- It is normal practice to change the bindings in the global map,
- but you should not assign this variable any value other than the
- keymap it starts out with.
-
- - Function: current-global-map
- This function returns the current global keymap. This is the same
- as the value of `global-map' unless you change one or the other.
-
- (current-global-map)
- => #<keymap global-map 639 entries 0x221>
-
- - Function: current-local-map
- This function returns the current buffer's local keymap, or `nil'
- if it has none. In the following example, the keymap for the
- `*scratch*' buffer (using Lisp Interaction mode) has a number of
- entries, including one prefix key, `C-x'.
-
- (current-local-map)
- => #<keymap lisp-interaction-mode-map 5 entries 0x558>
- (describe-bindings-internal (current-local-map))
- => ; Inserted into the buffer:
- backspace backward-delete-char-untabify
- linefeed eval-print-last-sexp
- delete delete-char
- C-j eval-print-last-sexp
- C-x << Prefix Command >>
- M-tab lisp-complete-symbol
- M-; lisp-indent-for-comment
- M-C-i lisp-complete-symbol
- M-C-q indent-sexp
- M-C-x eval-defun
- Alt-backspace backward-kill-sexp
- Alt-delete kill-sexp
-
- C-x x edebug-defun
-
- - Function: current-minor-mode-maps
- This function returns a list of the keymaps of currently enabled
- minor modes.
-
- - Function: use-global-map keymap
- This function makes KEYMAP the new current global keymap. It
- returns `nil'.
-
- It is very unusual to change the global keymap.
-
- - Function: use-local-map keymap &optional buffer
- This function makes KEYMAP the new local keymap of BUFFER. BUFFER
- defaults to the current buffer. If KEYMAP is `nil', then the
- buffer has no local keymap. `use-local-map' returns `nil'. Most
- major mode commands use this function.
-
- - Variable: minor-mode-map-alist
- This variable is an alist describing keymaps that may or may not be
- active according to the values of certain variables. Its elements
- look like this:
-
- (VARIABLE . KEYMAP)
-
- The keymap KEYMAP is active whenever VARIABLE has a non-`nil'
- value. Typically VARIABLE is the variable that enables or
- disables a minor mode. *Note Keymaps and Minor Modes::.
-
- Note that elements of `minor-mode-map-alist' do not have the same
- structure as elements of `minor-mode-alist'. The map must be the
- CDR of the element; a list with the map as the second element will
- not do.
-
- What's more, the keymap itself must appear in the CDR. It does not
- work to store a variable in the CDR and make the map the value of
- that variable.
-
- When more than one minor mode keymap is active, their order of
- priority is the order of `minor-mode-map-alist'. But you should
- design minor modes so that they don't interfere with each other.
- If you do this properly, the order will not matter.
-
- See also `minor-mode-key-binding', above. See *Note Keymaps and
- Minor Modes::, for more information about minor modes.
-
- - Variable: modeline-map
- This variable holds the keymap consulted for mouse-clicks on the
- modeline of a window. This variable may be buffer-local; its
- value will be looked up in the buffer of the window whose modeline
- was clicked upon.
-
- - Variable: toolbar-map
- This variable holds the keymap consulted for mouse-clicks over a
- toolbar.
-
- - Variable: mouse-grabbed-buffer
- If non-`nil', a buffer which should be consulted first for all
- mouse activity. When a mouse-click is processed, it will first be
- looked up in the local-map of this buffer, and then through the
- normal mechanism if there is no binding for that click. This
- buffer's value of `mode-motion-hook' will be consulted instead of
- the `mode-motion-hook' of the buffer of the window under the mouse.
- You should _bind_ this, not set it.
-
- - Variable: overriding-local-map
- If non-`nil', this variable holds a keymap to use instead of the
- buffer's local keymap and instead of all the minor mode keymaps.
- This keymap, if any, overrides all other maps that would have been
- active, except for the current global map.
-
- - Variable: overriding-terminal-local-map
- If non-`nil', this variable holds a keymap to use instead of the
- buffer's local keymap and instead of all the minor mode keymaps,
- but for the selected console only. (In other words, this variable
- is always console-local; putting a keymap here only applies to
- keystrokes coming from the selected console. *Note Consoles and
- Devices::.) This keymap, if any, overrides all other maps that
- would have been active, except for the current global map.
-