+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- 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.
-
-\1f
-File: lispref.info, Node: Quitting, Next: Prefix Command Arguments, Prev: Waiting, Up: Command Loop
-
-Quitting
-========
-
- Typing `C-g' while a Lisp function is running causes XEmacs 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' always quit directly.
-
- When `C-g' does directly quit, it does so by setting the variable
-`quit-flag' to `t'. XEmacs 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, quitting cannot happen just anywhere; only
-at the special places that check `quit-flag'. The reason for this is
-that quitting at other places might leave an inconsistency in XEmacs's
-internal state. Because quitting is delayed until a safe place,
-quitting cannot make XEmacs 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 when you wish to make sure
-that quitting does not happen within a "critical section" of the
-program.
-
- In some functions (such as `read-quoted-char'), `C-g' is handled in
-a special way that 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 XEmacs quits immediately,
- unless `inhibit-quit' is non-`nil'. Typing `C-g' ordinarily sets
- `quit-flag' non-`nil', regardless of `inhibit-quit'.
-
- - Variable: inhibit-quit
- This variable determines whether XEmacs 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 *Note Errors::.)
-
- You can specify a character other than `C-g' to use for quitting.
-See the function `set-input-mode' in *Note Terminal Input::.
-
-\1f
-File: lispref.info, Node: Prefix Command Arguments, Next: Recursive Editing, Prev: Quitting, Up: Command Loop
-
-Prefix Command Arguments
-========================
-
- Most XEmacs commands can use a "prefix argument", a number specified
-before the command itself. (Don't confuse prefix arguments with prefix
-keys.) The prefix argument is at all times represented by a value,
-which may be `nil', meaning there is currently no prefix argument.
-Each command may use the prefix argument or ignore it.
-
- There are two representations of the prefix argument: "raw" and
-"numeric". The editor command loop uses the raw representation
-internally, and so do the Lisp variables that store the information, but
-commands can request either representation.
-
- Here are the possible values of a raw prefix argument:
-
- * `nil', meaning there is no prefix argument. Its numeric value is
- 1, but numerous commands make a distinction between `nil' and the
- integer 1.
-
- * An integer, which stands for itself.
-
- * A list of one element, which is an integer. This form of prefix
- argument results from one or a succession of `C-u''s with no
- digits. The numeric value is the integer in the list, but some
- commands make a distinction between such a list and an integer
- alone.
-
- * The symbol `-'. This indicates that `M--' or `C-u -' was typed,
- without following digits. The equivalent numeric value is -1, but
- some commands make a distinction between the integer -1 and the
- symbol `-'.
-
- We illustrate these possibilities by calling the following function
-with various prefixes:
-
- (defun display-prefix (arg)
- "Display the value of the raw prefix arg."
- (interactive "P")
- (message "%s" arg))
-
-Here are the results of calling `display-prefix' with various raw
-prefix arguments:
-
- M-x display-prefix -| nil
-
- C-u M-x display-prefix -| (4)
-
- C-u C-u M-x display-prefix -| (16)
-
- C-u 3 M-x display-prefix -| 3
-
- M-3 M-x display-prefix -| 3 ; (Same as `C-u 3'.)
-
- C-3 M-x display-prefix -| 3 ; (Same as `C-u 3'.)
-
- C-u - M-x display-prefix -| -
-
- M-- M-x display-prefix -| - ; (Same as `C-u -'.)
-
- C-- M-x display-prefix -| - ; (Same as `C-u -'.)
-
- C-u - 7 M-x display-prefix -| -7
-
- M-- 7 M-x display-prefix -| -7 ; (Same as `C-u -7'.)
-
- C-- 7 M-x display-prefix -| -7 ; (Same as `C-u -7'.)
-
- XEmacs uses two variables to store the prefix argument: `prefix-arg'
-and `current-prefix-arg'. Commands such as `universal-argument' that
-set up prefix arguments for other commands store them in `prefix-arg'.
-In contrast, `current-prefix-arg' conveys the prefix argument to the
-current command, so setting it has no effect on the prefix arguments
-for future commands.
-
- Normally, commands specify which representation to use for the prefix
-argument, either numeric or raw, in the `interactive' declaration.
-(*Note Using Interactive::.) Alternatively, functions may look at the
-value of the prefix argument directly in the variable
-`current-prefix-arg', but this is less clean.
-
- - Function: prefix-numeric-value ARG
- This function returns the numeric meaning of a valid raw prefix
- argument value, ARG. 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*
- 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
- 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.
-
- - 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
- 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
- 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.
- Don't call this command yourself unless you know what you are
- doing.
-
-\1f
-File: lispref.info, Node: Recursive Editing, Next: Disabling Commands, Prev: Prefix Command Arguments, Up: Command Loop
-
-Recursive Editing
-=================
-
- The XEmacs command loop is entered automatically when XEmacs starts
-up. This top-level invocation of the command loop never exits; it keeps
-running as long as XEmacs does. Lisp programs can also invoke the
-command loop. Since this makes more than one activation of the command
-loop, we call it "recursive editing". A recursive editing level has
-the effect of suspending whatever command invoked it and permitting the
-user to do arbitrary editing before resuming that command.
-
- The commands available during recursive editing are the same ones
-available in the top-level editing loop and defined in the keymaps.
-Only a few special commands exit the recursive editing level; the others
-return to the recursive editing level when they finish. (The special
-commands for exiting are always available, but they do nothing when
-recursive editing is not in progress.)
-
- All command loops, including recursive ones, set up all-purpose error
-handlers so that an error in a command run from the command loop will
-not exit the loop.
-
- Minibuffer input is a special kind of recursive editing. It has a
-few special wrinkles, such as enabling display of the minibuffer and the
-minibuffer window, but fewer than you might suppose. Certain keys
-behave differently in the minibuffer, but that is only because of the
-minibuffer's local map; if you switch windows, you get the usual XEmacs
-commands.
-
- To invoke a recursive editing level, call the function
-`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'
-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
-one level up. This is called "aborting", and is done by `C-]'
-(`abort-recursive-edit').
-
- Most applications should not use recursive editing, except as part of
-using the minibuffer. Usually it is more convenient for the user if you
-change the major mode of the current buffer temporarily to a special
-major mode, which should have a command to go back to the previous mode.
-(The `e' command in Rmail uses this technique.) Or, if you wish to
-give the user different text to edit "recursively", create and select a
-new buffer in a special mode. In this mode, define a command to
-complete the processing and go back to the previous buffer. (The `m'
-command in Rmail does this.)
-
- Recursive edits are useful in debugging. You can insert a call to
-`debug' into a function definition as a sort of breakpoint, so that you
-can look around when the function gets there. `debug' invokes a
-recursive edit but also provides the other features of the debugger.
-
- 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
- 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
- recursive editing level.
-
- In the following example, the function `simple-rec' first advances
- point one word, then enters a recursive edit, printing out a
- message in the echo area. The user can then do any editing
- desired, and then type `C-M-c' to exit and continue executing
- `simple-rec'.
-
- (defun simple-rec ()
- (forward-word 1)
- (message "Recursive edit in progress")
- (recursive-edit)
- (forward-word 1))
- => simple-rec
- (simple-rec)
- => nil
-
- - Command: exit-recursive-edit
- This function exits from the innermost recursive edit (including
- minibuffer input). Its definition is effectively `(throw 'exit
- nil)'.
-
- - Command: abort-recursive-edit
- This function aborts the command that requested the innermost
- recursive edit (including minibuffer input), by signaling `quit'
- after exiting the recursive edit. Its definition is effectively
- `(throw 'exit t)'. *Note Quitting::.
-
- - Command: top-level
- This function exits all recursive editing levels; it does not
- return a value, as it jumps completely out of any computation
- directly back to the main command loop.
-
- - Function: recursion-depth
- This function returns the current depth of recursive edits. When
- no recursive edit is active, it returns 0.
-
-\1f
-File: lispref.info, Node: Disabling Commands, Next: Command History, Prev: Recursive Editing, Up: Command Loop
-
-Disabling Commands
-==================
-
- "Disabling a command" marks the command as requiring user
-confirmation before it can be executed. Disabling is used for commands
-which might be confusing to beginning users, to prevent them from using
-the commands by accident.
-
- The low-level mechanism for disabling a command is to put a
-non-`nil' `disabled' property on the Lisp symbol for the command.
-These properties are normally set up by the user's `.emacs' file with
-Lisp expressions such as this:
-
- (put 'upcase-region 'disabled t)
-
-For a few commands, these properties are present by default and may be
-removed by the `.emacs' file.
-
- If the value of the `disabled' property is a string, the message
-saying the command is disabled includes that string. For example:
-
- (put 'delete-region 'disabled
- "Text deleted this way cannot be yanked back!\n")
-
- *Note Disabling: (xemacs)Disabling, for the details on what happens
-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
- 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
- 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.
-
- - Variable: disabled-command-hook
- This normal hook is run instead of a disabled command, when the
- user invokes the disabled command interactively. The hook
- functions can use `this-command-keys' to determine what the user
- typed to run the command, and thus find the command itself. *Note
- Hooks::.
-
- By default, `disabled-command-hook' contains a function that asks
- the user whether to proceed.
-
-\1f
-File: lispref.info, Node: Command History, Next: Keyboard Macros, Prev: Disabling Commands, Up: Command Loop
-
-Command History
-===============
-
- The command loop keeps a history of the complex commands that have
-been executed, to make it convenient to repeat these commands. A
-"complex command" is one for which the interactive argument reading
-uses the minibuffer. This includes any `M-x' command, any `M-:'
-command, and any command whose `interactive' specification reads an
-argument from the minibuffer. Explicit use of the minibuffer during
-the execution of the command itself does not cause the command to be
-considered complex.
-
- - Variable: command-history
- This variable's value is a list of recent complex commands, each
- 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::.).
-
- command-history
- => ((switch-to-buffer "chistory.texi")
- (describe-key "^X^[")
- (visit-tags-table "~/emacs/src/")
- (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
-expressions rather than strings.
-
- There are a number of commands devoted to the editing and recall of
-previous commands. The commands `repeat-complex-command', and
-`list-command-history' are described in the user manual (*note
-Repetition: (xemacs)Repetition.). Within the minibuffer, the history
-commands used are the same ones available in any minibuffer.
-
-\1f
-File: lispref.info, Node: Keyboard Macros, Prev: Command History, Up: Command Loop
-
-Keyboard Macros
-===============
-
- A "keyboard macro" is a canned sequence of input events that can be
-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::.).
-
- - 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*
- expected to be a single key sequence; normally a keyboard macro
- definition consists of several key sequences concatenated.
-
- If MACRO is a symbol, then its function definition is used in
- place of MACRO. If that is another symbol, this process repeats.
- Eventually the result should be a string or vector. If the result
- is not a symbol, string, or vector, an error is signaled.
-
- The argument COUNT is a repeat count; MACRO is executed that many
- times. If COUNT is omitted or `nil', MACRO is executed once. If
- it is 0, MACRO is executed over and over until it encounters an
- error or a failing search.
-
- - Variable: executing-macro
- This variable contains the string or vector that defines the
- keyboard macro that is currently executing. It is `nil' if no
- macro is currently executing. A command can test this variable to
- behave differently when run from an executing macro. Do not set
- this variable yourself.
-
- - Variable: defining-kbd-macro
- This variable indicates whether a keyboard macro is being defined.
- A command can test this variable to behave differently while a
- macro is being defined. The commands `start-kbd-macro' and
- `end-kbd-macro' set this variable--do not set it yourself.
-
- - Variable: last-kbd-macro
- This variable is the definition of the most recently defined
- keyboard macro. Its value is a string or vector, or `nil'.
-
- The commands are described in the user's manual (*note Keyboard
-Macros: (xemacs)Keyboard Macros.).
-
-\1f
-File: lispref.info, Node: Keymaps, Next: Menus, Prev: Command Loop, Up: Top
-
-Keymaps
-*******
-
- The bindings between input events and commands are recorded in data
-structures called "keymaps". Each binding in a keymap associates (or
-"binds") an individual event type either with another keymap or with a
-command. When an event is bound to a keymap, that keymap is used to
-look up the next input event; this continues until a command is found.
-The whole process is called "key lookup".
-
-* Menu:
-
-* Keymap Terminology:: Definitions of terms pertaining to keymaps.
-* Format of Keymaps:: What a keymap looks like as a Lisp object.
-* Creating Keymaps:: Functions to create and copy keymaps.
-* Inheritance and Keymaps:: How one keymap can inherit the bindings
- of another keymap.
-* Key Sequences:: How to specify key sequences.
-* Prefix Keys:: Defining a key with a keymap as its definition.
-* Active Keymaps:: Each buffer has a local keymap
- to override the standard (global) bindings.
- A minor mode can also override them.
-* Key Lookup:: How extracting elements from keymaps works.
-* Functions for Key Lookup:: How to request key lookup.
-* Changing Key Bindings:: Redefining a key in a keymap.
-* Key Binding Commands:: Interactive interfaces for redefining keys.
-* Scanning Keymaps:: Looking through all keymaps, for printing help.
-* Other Keymap Functions:: Miscellaneous keymap functions.
-
-\1f
-File: lispref.info, Node: Keymap Terminology, Next: Format of Keymaps, Up: Keymaps
-
-Keymap Terminology
-==================
-
- A "keymap" is a table mapping event types to definitions (which can
-be any Lisp objects, though only certain types are meaningful for
-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::.).
-
- 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
-sequence, and so are some multi-event sequences.
-
- A keymap determines a binding or definition for any key sequence. If
-the key sequence is a single event, its binding is the definition of the
-event in the keymap. The binding of a key sequence of more than one
-event is found by an iterative process: the binding of the first event
-is found, and must be a keymap; then the second event's binding is found
-in that keymap, and so on until all the events in the key sequence are
-used up.
-
- If the binding of a key sequence is a keymap, we call the key
-sequence a "prefix key". Otherwise, we call it a "complete key"
-(because no more events can be added to it). If the binding is `nil',
-we call the key "undefined". Examples of prefix keys are `C-c', `C-x',
-and `C-x 4'. Examples of defined complete keys are `X', <RET>, and
-`C-x 4 C-f'. Examples of undefined complete keys are `C-x C-g', and
-`C-c 3'. *Note Prefix Keys::, for more details.
-
- The rule for finding the binding of a key sequence assumes that the
-intermediate bindings (found for the events before the last) are all
-keymaps; if this is not so, the sequence of events does not form a
-unit--it is not really a key sequence. In other words, removing one or
-more events from the end of any valid key must always yield a prefix
-key. For example, `C-f C-n' is not a key; `C-f' is not a prefix key,
-so a longer sequence starting with `C-f' cannot be a key.
-
- Note that the set of possible multi-event key sequences depends on
-the bindings for prefix keys; therefore, it can be different for
-different keymaps, and can change when bindings are changed. However,
-a one-event sequence is always a key sequence, because it does not
-depend on any prefix keys for its well-formedness.
-
- At any time, several primary keymaps are "active"--that is, in use
-for finding key bindings. These are the "global map", which is shared
-by all buffers; the "local keymap", which is usually associated with a
-specific major mode; and zero or more "minor mode keymaps", which
-belong to currently enabled minor modes. (Not all minor modes have
-keymaps.) The local keymap bindings shadow (i.e., take precedence
-over) the corresponding global bindings. The minor mode keymaps shadow
-both local and global keymaps. *Note Active Keymaps::, for details.
-
-\1f
-File: lispref.info, Node: Format of Keymaps, Next: Creating Keymaps, Prev: Keymap Terminology, Up: Keymaps
-
-Format of Keymaps
-=================
-
- A keymap is a primitive type that associates events with their
-bindings. Note that this is different from Emacs 18 and FSF Emacs,
-where keymaps are lists.
-
- - Function: keymapp OBJECT
- This function returns `t' if OBJECT is a keymap, `nil' otherwise.
-
-\1f
-File: lispref.info, Node: Creating Keymaps, Next: Inheritance and Keymaps, Prev: Format of Keymaps, Up: Keymaps
-
-Creating Keymaps
-================
-
- Here we describe the functions for creating keymaps.
-
- - Function: make-keymap &optional NAME
- This function constructs and returns a new keymap object. All
- entries in it are `nil', meaning "command undefined".
-
- 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: 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
- 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
- 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
- This function returns the "name" of a keymap, as assigned using
- `set-keymap-name'.
-
- - 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
- take place when the definition of a character is a symbol whose
- function definition is a keymap; the same symbol appears in the
- new copy.
-
- (setq map (copy-keymap (current-local-map)))
- => #<keymap 3 entries 0x21f80>
-
- (eq map (current-local-map))
- => nil
-
-\1f
-File: lispref.info, Node: Inheritance and Keymaps, Next: Key Sequences, Prev: Creating Keymaps, Up: Keymaps
-
-Inheritance and Keymaps
-=======================
-
- A keymap can inherit the bindings of other keymaps. The other
-keymaps are called the keymap's "parents", and are set with
-`set-keymap-parents'. When searching for a binding for a key sequence
-in a particular keymap, that keymap itself will first be searched;
-then, if no binding was found in the map and it has parents, the first
-parent keymap will be searched; then that keymap's parent will be
-searched, and so on, until either a binding for the key sequence is
-found, or a keymap without a parent is encountered. At this point, the
-search will continue with the next parent of the most recently
-encountered keymap that has another parent, etc. Essentially, a
-depth-first search of all the ancestors of the keymap is conducted.
-
- `(current-global-map)' is the default parent of all keymaps.
-
- - Function: set-keymap-parents KEYMAP PARENTS
- This function sets the parent keymaps of KEYMAP to the list
- PARENTS.
-
- If you change the bindings in one of the keymaps in PARENTS using
- `define-key' or other key-binding functions, these changes are
- visible in KEYMAP unless shadowed by bindings in that map or in
- earlier-searched ancestors. The converse is not true: if you use
- `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
- This function returns the list of parent keymaps of KEYMAP, or
- `nil' if KEYMAP has no parents.
-
- As an alternative to specifying a parent, you can also specify a
-"default binding" that is used whenever a key is not otherwise bound in
-the keymap. This is useful for terminal emulators, for example, which
-may want to trap all keystrokes and pass them on in some modified
-format. Note that if you specify a default binding for a keymap,
-neither the keymap's parents nor the current global map are searched for
-key bindings.
-
- - 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
- 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.1 / blobdiff