-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
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
+=================================
+
+ The wait functions are designed to 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 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
+ with no input arriving (see `input-pending-p' in *Note Peeking and
+ Discarding::). Otherwise, the value is `nil'.
+
+ The argument SECONDS need not be an integer. If it is a floating
+ point number, `sit-for' waits for a fractional number of seconds.
+
+ 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'.
+ *Note Refresh Screen::.) If there is no input pending, you can
+ force an update with no delay by using `(sit-for 0)'.
+
+ 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.
+
+ - Function: sleep-for seconds
+ This function simply pauses for SECONDS seconds without updating
+ the display. This function pays no attention to available input.
+ It returns `nil'.
+
+ The argument SECONDS need not be an integer. If it is a floating
+ point number, `sleep-for' waits for a fractional number of seconds.
+
+ Use `sleep-for' when you wish to guarantee a delay.
+
+ *Note Time of Day::, for functions to get the current time.
+
+\1f
File: lispref.info, Node: Quitting, Next: Prefix Command Arguments, Prev: Waiting, Up: Command Loop
Quitting
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
+_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
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
returned.
- Variable: current-prefix-arg
- This variable holds the raw prefix argument for the *current*
+ This variable holds the raw prefix argument for the _current_
command. Commands may examine it directly, but the usual way to
access it is with `(interactive "P")'.
- Variable: prefix-arg
The value of this variable is the raw prefix argument for the
- *next* editing command. Commands that specify prefix arguments for
+ _next_ editing command. Commands that specify prefix arguments for
the following command work by setting this variable.
Do not call the functions `universal-argument', `digit-argument', or
`negative-argument' unless you intend to let the user enter the prefix
-argument for the *next* command.
+argument for the _next_ command.
- Command: universal-argument
This command reads input and specifies a prefix argument for the
following command. Don't call this command yourself unless you
know what you are doing.
- - Command: digit-argument ARG
+ - Command: digit-argument arg
This command adds to the prefix argument for the following
command. The argument ARG is the raw prefix argument as it was
before this command; it is used to compute the updated prefix
argument. Don't call this command yourself unless you know what
you are doing.
- - Command: negative-argument ARG
+ - Command: negative-argument arg
This command adds to the numeric argument for the next command.
The argument ARG is the raw prefix argument as it was before this
command; its value is negated to form the new prefix argument.
`recursive-edit'. This function contains the command loop; it also
contains a call to `catch' with tag `exit', which makes it possible to
exit the recursive editing level by throwing to `exit' (*note Catch and
-Throw::.). If you throw a value other than `t', then `recursive-edit'
+Throw::). If you throw a value other than `t', then `recursive-edit'
returns normally to the function that called it. The command `C-M-c'
(`exit-recursive-edit') does this. Throwing a `t' value causes
`recursive-edit' to quit, so that control returns to the command loop
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
when a disabled command is invoked interactively. Disabling a command
has no effect on calling it as a function from Lisp programs.
- - Command: enable-command COMMAND
+ - Command: enable-command command
Allow COMMAND to be executed without special confirmation from now
on, and (if the user confirms) alter the user's `.emacs' file so
that this will apply to future sessions.
- - Command: disable-command COMMAND
+ - Command: disable-command command
Require special confirmation to execute COMMAND from now on, and
(if the user confirms) alter the user's `.emacs' file so that this
will apply to future sessions.
represented as a form to evaluate. It continues to accumulate all
complex commands for the duration of the editing session, but all
but the first (most recent) thirty elements are deleted when a
- garbage collection takes place (*note Garbage Collection::.).
+ garbage collection takes place (*note Garbage Collection::).
command-history
=> ((switch-to-buffer "chistory.texi")
(find-tag "repeat-complex-command"))
This history list is actually a special case of minibuffer history
-(*note Minibuffer History::.), with one special twist: the elements are
+(*note Minibuffer History::), with one special twist: the elements are
expressions rather than strings.
There are a number of commands devoted to the editing and recall of
considered a command and made the definition of a key. The Lisp
representation of a keyboard macro is a string or vector containing the
events. Don't confuse keyboard macros with Lisp macros (*note
-Macros::.).
+Macros::).
- - Function: execute-kbd-macro MACRO &optional COUNT
+ - Function: execute-kbd-macro macro &optional count
This function executes MACRO as a sequence of events. If MACRO is
a string or vector, then the events in it are executed exactly as
- if they had been input by the user. The sequence is *not*
+ if they had been input by the user. The sequence is _not_
expected to be a single key sequence; normally a keyboard macro
definition consists of several key sequences concatenated.
execution by the command loop). Given an event (or an event type) and a
keymap, XEmacs can get the event's definition. Events mapped in keymaps
include keypresses, button presses, and button releases (*note
-Events::.).
+Events::).
A sequence of input events that form a unit is called a "key
sequence", or "key" for short. A sequence of one event is always a key
bindings. Note that this is different from Emacs 18 and FSF Emacs,
where keymaps are lists.
- - Function: keymapp OBJECT
+ - Function: keymapp object
This function returns `t' if OBJECT is a keymap, `nil' otherwise.
\1f
Here we describe the functions for creating keymaps.
- - Function: make-keymap &optional NAME
+ - Function: make-keymap &optional name
This function constructs and returns a new keymap object. All
entries in it are `nil', meaning "command undefined".
as in `set-keymap-name'. This name is only a debugging
convenience; it is not used except when printing the keymap.
- - Function: make-sparse-keymap &optional NAME
+ - Function: make-sparse-keymap &optional name
This function constructs and returns a new keymap object. All
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,
as in `set-keymap-name'. This name is only a debugging
convenience; it is not used except when printing the keymap.
- - Function: set-keymap-name KEYMAP NEW-NAME
+ - Function: set-keymap-name keymap new-name
This function assigns a "name" to a keymap. The name is only a
debugging convenience; it is not used except when printing the
keymap.
- - Function: keymap-name KEYMAP
+ - Function: keymap-name keymap
This function returns the "name" of a keymap, as assigned using
`set-keymap-name'.
- - Function: copy-keymap KEYMAP
+ - Function: copy-keymap keymap
This function returns a copy of KEYMAP. Any keymaps that appear
directly as bindings in KEYMAP are also copied recursively, and so
on to any number of levels. However, recursive copying does not
`(current-global-map)' is the default parent of all keymaps.
- - Function: set-keymap-parents KEYMAP PARENTS
+ - Function: set-keymap-parents keymap parents
This function sets the parent keymaps of KEYMAP to the list
PARENTS.
`define-key' to change KEYMAP, that affects the bindings in that
map, but has no effect on any of the keymaps in PARENTS.
- - Function: keymap-parents KEYMAP
+ - Function: keymap-parents keymap
This function returns the list of parent keymaps of KEYMAP, or
`nil' if KEYMAP has no parents.
neither the keymap's parents nor the current global map are searched for
key bindings.
- - Function: set-keymap-default-binding KEYMAP COMMAND
+ - Function: set-keymap-default-binding keymap command
This function sets the default binding of KEYMAP to COMMAND, or
`nil' if no default is desired.
- - Function: keymap-default-binding KEYMAP
+ - Function: keymap-default-binding 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.
-
projects / chise / xemacs-chise.git- / blobdiff