+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 an
+ 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
+========
+
+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 raw
+ This function returns the numeric meaning of a valid raw prefix
+ 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_
+ 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').
+
+ - 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
+ 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, 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
+ 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 &optional buffer
+ This function returns BUFFER's local keymap, or `nil' if it has
+ none. BUFFER defaults to the current buffer.
+
+ 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.
+
+\1f
+File: lispref.info, Node: Key Lookup, Next: Functions for Key Lookup, Prev: Active Keymaps, Up: Keymaps
+
+Key Lookup
+==========
+
+"Key lookup" is the process of finding the binding of a key sequence
+from a given keymap. Actual execution of the binding is not part of
+key lookup.
+
+ Key lookup uses just the event type of each event in the key
+sequence; the rest of the event is ignored. In fact, a key sequence
+used for key lookup may designate mouse events with just their types
+(symbols) instead of with entire mouse events (lists). *Note Events::.
+Such a pseudo-key-sequence is insufficient for `command-execute', but
+it is sufficient for looking up or rebinding a key.
+
+ When the key sequence consists of multiple events, key lookup
+processes the events sequentially: 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. (The binding thus found for the last event may or may not be a
+keymap.) Thus, the process of key lookup is defined in terms of a
+simpler process for looking up a single event in a keymap. How that is
+done depends on the type of object associated with the event in that
+keymap.
+
+ Let's use the term "keymap entry" to describe the value found by
+looking up an event type in a keymap. (This doesn't include the item
+string and other extra elements in menu key bindings because
+`lookup-key' and other key lookup functions don't include them in the
+returned value.) While any Lisp object may be stored in a keymap as a
+keymap entry, not all make sense for key lookup. Here is a list of the
+meaningful kinds of keymap entries:
+
+`nil'
+ `nil' means that the events used so far in the lookup form an
+ undefined key. When a keymap fails to mention an event type at
+ all, and has no default binding, that is equivalent to a binding
+ of `nil' for that event type.
+
+KEYMAP
+ The events used so far in the lookup form a prefix key. The next
+ event of the key sequence is looked up in KEYMAP.
+
+COMMAND
+ The events used so far in the lookup form a complete key, and
+ COMMAND is its binding. *Note What Is a Function::.
+
+ARRAY
+ The array (either a string or a vector) is a keyboard macro. The
+ events used so far in the lookup form a complete key, and the
+ array is its binding. See *Note Keyboard Macros::, for more
+ information. (Note that you cannot use a shortened form of a key
+ sequence here, such as `(control y)'; you must use the full form
+ `[(control y)]'. *Note Key Sequences::.)
+
+LIST
+ The meaning of a list depends on the types of the elements of the
+ list.
+
+ * If the CAR of LIST is `lambda', then the list is a lambda
+ expression. This is presumed to be a command, and is treated
+ as such (see above).
+
+ * If the CAR of LIST is a keymap and the CDR is an event type,
+ then this is an "indirect entry":
+
+ (OTHERMAP . OTHERTYPE)
+
+ When key lookup encounters an indirect entry, it looks up
+ instead the binding of OTHERTYPE in OTHERMAP and uses that.
+
+ This feature permits you to define one key as an alias for
+ another key. For example, an entry whose CAR is the keymap
+ called `esc-map' and whose CDR is 32 (the code for <SPC>)
+ means, "Use the global binding of `Meta-<SPC>', whatever that
+ may be."
+
+SYMBOL
+ The function definition of SYMBOL is used in place of SYMBOL. If
+ that too is a symbol, then this process is repeated, any number of
+ times. Ultimately this should lead to an object that is a keymap,
+ a command or a keyboard macro. A list is allowed if it is a
+ keymap or a command, but indirect entries are not understood when
+ found via symbols.
+
+ Note that keymaps and keyboard macros (strings and vectors) are not
+ valid functions, so a symbol with a keymap, string, or vector as
+ its function definition is invalid as a function. It is, however,
+ valid as a key binding. If the definition is a keyboard macro,
+ then the symbol is also valid as an argument to `command-execute'
+ (*note Interactive Call::).
+
+ The symbol `undefined' is worth special mention: it means to treat
+ the key as undefined. Strictly speaking, the key is defined, and
+ its binding is the command `undefined'; but that command does the
+ same thing that is done automatically for an undefined key: it
+ rings the bell (by calling `ding') but does not signal an error.
+
+ `undefined' is used in local keymaps to override a global key
+ binding and make the key "undefined" locally. A local binding of
+ `nil' would fail to do this because it would not override the
+ global binding.
+
+ANYTHING ELSE
+ If any other type of object is found, the events used so far in the
+ lookup form a complete key, and the object is its binding, but the
+ binding is not executable as a command.
+
+ In short, a keymap entry may be a keymap, a command, a keyboard
+macro, a symbol that leads to one of them, or an indirection or `nil'.
+
+\1f
+File: lispref.info, Node: Functions for Key Lookup, Next: Changing Key Bindings, Prev: Key Lookup, Up: Keymaps
+
+Functions for Key Lookup
+========================
+
+Here are the functions and variables pertaining to key lookup.
+
+ - Function: lookup-key keymap key &optional accept-defaults
+ This function returns the definition of KEY in KEYMAP. If the
+ string or vector KEY is not a valid key sequence according to the
+ prefix keys specified in KEYMAP (which means it is "too long" and
+ has extra events at the end), then the value is a number, the
+ number of events at the front of KEY that compose a complete key.
+
+ If ACCEPT-DEFAULTS is non-`nil', then `lookup-key' considers
+ default bindings as well as bindings for the specific events in
+ KEY. Otherwise, `lookup-key' reports only bindings for the
+ specific sequence KEY, ignoring default bindings except when you
+ explicitly ask about them.
+
+ All the other functions described in this chapter that look up
+ keys use `lookup-key'.
+
+ (lookup-key (current-global-map) "\C-x\C-f")
+ => find-file
+ (lookup-key (current-global-map) "\C-x\C-f12345")
+ => 2
+
+ If KEY begins with the character whose value is contained in
+ `meta-prefix-char', that character is implicitly removed and the
+ <META> modifier added to the key. Thus, the first example below is
+ handled by conversion into the second example.
+
+ (lookup-key (current-global-map) "\ef")
+ => forward-word
+ (lookup-key (current-global-map) "\M-f")
+ => forward-word
+
+ Unlike `read-key-sequence', this function does not modify the
+ specified events in ways that discard information (*note Key
+ Sequence Input::). In particular, it does not convert letters to
+ lower case.
+
+ - Command: undefined
+ Used in keymaps to undefine keys. If a key sequence is defined to
+ this, invoking this key sequence causes a "key undefined" error,
+ just as if the key sequence had no binding.
+
+ - Function: key-binding key &optional accept-defaults
+ This function returns the binding for KEY in the current keymaps,
+ trying all the active keymaps. The result is `nil' if KEY is
+ undefined in the keymaps.
+
+ The argument ACCEPT-DEFAULTS controls checking for default
+ bindings, as in `lookup-key' (above).
+
+ (key-binding "\C-x\C-f")
+ => find-file
+ (key-binding '(control home))
+ => beginning-of-buffer
+ (key-binding [escape escape escape])
+ => keyboard-escape-quit
+
+ - Function: local-key-binding keys &optional accept-defaults
+ This function returns the binding for KEYS in the current local
+ keymap, or `nil' if it is undefined there.
+
+ The argument ACCEPT-DEFAULTS controls checking for default
+ bindings, as in `lookup-key' (above).
+
+ - Function: global-key-binding keys &optional accept-defaults
+ This function returns the binding for command KEYS in the current
+ global keymap, or `nil' if it is undefined there.
+
+ The argument ACCEPT-DEFAULTS controls checking for default
+ bindings, as in `lookup-key' (above).
+
+ - Function: minor-mode-key-binding key &optional accept-defaults
+ This function returns a list of all the active minor mode bindings
+ of KEY. More precisely, it returns an alist of pairs `(MODENAME .
+ BINDING)', where MODENAME is the variable that enables the minor
+ mode, and BINDING is KEY's binding in that mode. If KEY has no
+ minor-mode bindings, the value is `nil'.
+
+ If the first binding is not a prefix command, all subsequent
+ bindings from other minor modes are omitted, since they would be
+ completely shadowed. Similarly, the list omits non-prefix
+ bindings that follow prefix bindings.
+
+ The argument ACCEPT-DEFAULTS controls checking for default
+ bindings, as in `lookup-key' (above).
+
+ - Variable: meta-prefix-char
+ This variable is the meta-prefix character code. It is used when
+ translating a two-character sequence to a meta character so it can
+ be looked up in a keymap. For useful results, the value should be
+ a prefix event (*note Prefix Keys::). The default value is `?\^['
+ (integer 27), which is the ASCII character usually produced by the
+ <ESC> key.
+
+ As long as the value of `meta-prefix-char' remains `?\^[', key
+ lookup translates `<ESC> b' into `M-b', which is normally defined
+ as the `backward-word' command. However, if you set
+ `meta-prefix-char' to `?\^X' (i.e. the keystroke `C-x') or its
+ equivalent ASCII code `24', then XEmacs will translate `C-x b'
+ (whose standard binding is the `switch-to-buffer' command) into
+ `M-b'.
+
+ meta-prefix-char ; The default value.
+ => ?\^[ ; Under XEmacs 20.
+ => 27 ; Under XEmacs 19.
+ (key-binding "\eb")
+ => backward-word
+ ?\C-x ; The print representation
+ ; of a character.
+ => ?\^X ; Under XEmacs 20.
+ => 24 ; Under XEmacs 19.
+ (setq meta-prefix-char 24)
+ => 24
+ (key-binding "\C-xb")
+ => backward-word ; Now, typing `C-x b' is
+ ; like typing `M-b'.
+
+ (setq meta-prefix-char ?\e) ; Avoid confusion!
+ ; Restore the default value!
+ => ?\^[ ; Under XEmacs 20.
+ => 27 ; Under XEmacs 19.
+
+\1f
+File: lispref.info, Node: Changing Key Bindings, Next: Key Binding Commands, Prev: Functions for Key Lookup, Up: Keymaps
+
+Changing Key Bindings
+=====================
+
+The way to rebind a key is to change its entry in a keymap. If you
+change a binding in the global keymap, the change is effective in all
+buffers (though it has no direct effect in buffers that shadow the
+global binding with a local one). If you change the current buffer's
+local map, that usually affects all buffers using the same major mode.
+The `global-set-key' and `local-set-key' functions are convenient
+interfaces for these operations (*note Key Binding Commands::). You
+can also use `define-key', a more general function; then you must
+specify explicitly the map to change.
+
+ The way to specify the key sequence that you want to rebind is
+described above (*note Key Sequences::).
+
+ For the functions below, an error is signaled if KEYMAP is not a
+keymap or if KEY is not a string or vector representing a key sequence.
+You can use event types (symbols) as shorthand for events that are
+lists.
+
+ - Function: define-key keymap key binding
+ This function sets the binding for KEY in KEYMAP. (If KEY is more
+ than one event long, the change is actually made in another keymap
+ reached from KEYMAP.) The argument BINDING can be any Lisp
+ object, but only certain types are meaningful. (For a list of
+ meaningful types, see *Note Key Lookup::.) The value returned by
+ `define-key' is BINDING.
+
+ Every prefix of KEY must be a prefix key (i.e., bound to a keymap)
+ or undefined; otherwise an error is signaled.
+
+ If some prefix of KEY is undefined, then `define-key' defines it
+ as a prefix key so that the rest of KEY may be defined as
+ specified.
+
+ Here is an example that creates a sparse keymap and makes a number of
+bindings in it:
+
+ (setq map (make-sparse-keymap))
+ => #<keymap 0 entries 0xbee>
+ (define-key map "\C-f" 'forward-char)
+ => forward-char
+ map
+ => #<keymap 1 entry 0xbee>
+ (describe-bindings-internal map)
+ => ; (Inserted in buffer)
+ C-f forward-char
+
+ ;; Build sparse submap for `C-x' and bind `f' in that.
+ (define-key map "\C-xf" 'forward-word)
+ => forward-word
+ map
+ => #<keymap 2 entries 0xbee>
+ (describe-bindings-internal map)
+ => ; (Inserted in buffer)
+ C-f forward-char
+ C-x << Prefix Command >>
+
+ C-x f forward-word
+
+ ;; Bind `C-p' to the `ctl-x-map'.
+ (define-key map "\C-p" ctl-x-map)
+ ;; `ctl-x-map'
+ => #<keymap Control-X-prefix 77 entries 0x3bf>
+
+ ;; Bind `C-f' to `foo' in the `ctl-x-map'.
+ (define-key map "\C-p\C-f" 'foo)
+ => foo
+ map
+ => #<keymap 3 entries 0xbee>
+ (describe-bindings-internal map)
+ => ; (Inserted in buffer)
+ C-f forward-char
+ C-p << Prefix command Control-X-prefix >>
+ C-x << Prefix Command >>
+
+ C-p tab indent-rigidly
+ C-p $ set-selective-display
+ C-p ' expand-abbrev
+ C-p ( start-kbd-macro
+ C-p ) end-kbd-macro
+ ...
+ C-p C-x exchange-point-and-mark
+ C-p C-z suspend-or-iconify-emacs
+ C-p M-escape repeat-complex-command
+ C-p M-C-[ repeat-complex-command
+
+ C-x f forward-word
+
+ C-p 4 . find-tag-other-window
+ ...
+ C-p 4 C-o display-buffer
+
+ C-p 5 0 delete-frame
+ ...
+ C-p 5 C-f find-file-other-frame
+
+ ...
+
+ C-p a i g inverse-add-global-abbrev
+ C-p a i l inverse-add-mode-abbrev
+
+Note that storing a new binding for `C-p C-f' actually works by
+changing an entry in `ctl-x-map', and this has the effect of changing
+the bindings of both `C-p C-f' and `C-x C-f' in the default global map.
+
+ - Function: substitute-key-definition olddef newdef keymap &optional
+ oldmap prefix
+ This function replaces OLDDEF with NEWDEF for any keys in KEYMAP
+ that were bound to OLDDEF. In other words, OLDDEF is replaced
+ with NEWDEF wherever it appears. Prefix keymaps are checked
+ recursively.
+
+ The function returns `nil'.
+
+ For example, this redefines `C-x C-f', if you do it in an XEmacs
+ with standard bindings:
+
+ (substitute-key-definition
+ 'find-file 'find-file-read-only (current-global-map))
+
+ If OLDMAP is non-`nil', then its bindings determine which keys to
+ rebind. The rebindings still happen in KEYMAP, not in OLDMAP.
+ Thus, you can change one map under the control of the bindings in
+ another. For example,
+
+ (substitute-key-definition
+ 'delete-backward-char 'my-funny-delete
+ my-map global-map)
+
+ puts the special deletion command in `my-map' for whichever keys
+ are globally bound to the standard deletion command.
+
+ If argument PREFIX is non-`nil', then only those occurrences of
+ OLDDEF found in keymaps accessible through the keymap bound to
+ PREFIX in KEYMAP are redefined. See also `accessible-keymaps'.
+
+
+ - Function: suppress-keymap keymap &optional nodigits
+ This function changes the contents of the full keymap KEYMAP by
+ making all the printing characters undefined. More precisely, it
+ binds them to the command `undefined'. This makes ordinary
+ insertion of text impossible. `suppress-keymap' returns `nil'.
+
+ If NODIGITS is `nil', then `suppress-keymap' defines digits to run
+ `digit-argument', and `-' to run `negative-argument'. Otherwise
+ it makes them undefined like the rest of the printing characters.
+
+ The `suppress-keymap' function does not make it impossible to
+ modify a buffer, as it does not suppress commands such as `yank'
+ and `quoted-insert'. To prevent any modification of a buffer, make
+ it read-only (*note Read Only Buffers::).
+
+ Since this function modifies KEYMAP, you would normally use it on
+ a newly created keymap. Operating on an existing keymap that is
+ used for some other purpose is likely to cause trouble; for
+ example, suppressing `global-map' would make it impossible to use
+ most of XEmacs.
+
+ Most often, `suppress-keymap' is used to initialize local keymaps
+ of modes such as Rmail and Dired where insertion of text is not
+ desirable and the buffer is read-only. Here is an example taken
+ from the file `emacs/lisp/dired.el', showing how the local keymap
+ for Dired mode is set up:
+
+ ...
+ (setq dired-mode-map (make-keymap))
+ (suppress-keymap dired-mode-map)
+ (define-key dired-mode-map "r" 'dired-rename-file)
+ (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
+ (define-key dired-mode-map "d" 'dired-flag-file-deleted)
+ (define-key dired-mode-map "v" 'dired-view-file)
+ (define-key dired-mode-map "e" 'dired-find-file)
+ (define-key dired-mode-map "f" 'dired-find-file)
+ ...
+
+\1f
+File: lispref.info, Node: Key Binding Commands, Next: Scanning Keymaps, Prev: Changing Key Bindings, Up: Keymaps
+
+Commands for Binding Keys
+=========================
+
+This section describes some convenient interactive interfaces for
+changing key bindings. They work by calling `define-key'.
+
+ People often use `global-set-key' in their `.emacs' file for simple
+customization. For example,
+
+ (global-set-key "\C-x\C-\\" 'next-line)
+
+or
+
+ (global-set-key [(control ?x) (control ?\\)] 'next-line)
+
+or
+
+ (global-set-key [?\C-x ?\C-\\] 'next-line)
+
+redefines `C-x C-\' to move down a line.
+
+ (global-set-key [(meta button1)] 'mouse-set-point)
+
+redefines the first (leftmost) mouse button, typed with the Meta key, to
+set point where you click.
+
+ - Command: global-set-key key definition
+ This function sets the binding of KEY in the current global map to
+ DEFINITION.
+
+ (global-set-key KEY DEFINITION)
+ ==
+ (define-key (current-global-map) KEY DEFINITION)
+
+ - Command: global-unset-key key
+ This function removes the binding of KEY from the current global
+ map.
+
+ One use of this function is in preparation for defining a longer
+ key that uses KEY as a prefix--which would not be allowed if KEY
+ has a non-prefix binding. For example:
+
+ (global-unset-key "\C-l")
+ => nil
+ (global-set-key "\C-l\C-l" 'redraw-display)
+ => nil
+
+ This function is implemented simply using `define-key':
+
+ (global-unset-key KEY)
+ ==
+ (define-key (current-global-map) KEY nil)
+
+ - Command: local-set-key key definition
+ This function sets the binding of KEY in the current local keymap
+ to DEFINITION.
+
+ (local-set-key KEY DEFINITION)
+ ==
+ (define-key (current-local-map) KEY DEFINITION)
+
+ - Command: local-unset-key key
+ This function removes the binding of KEY from the current local
+ map.
+
+ (local-unset-key KEY)
+ ==
+ (define-key (current-local-map) KEY nil)
+
+\1f
+File: lispref.info, Node: Scanning Keymaps, Next: Other Keymap Functions, Prev: Key Binding Commands, Up: Keymaps
+
+Scanning Keymaps
+================
+
+This section describes functions used to scan all the current keymaps,
+or all keys within a keymap, for the sake of printing help information.
+
+ - Function: accessible-keymaps keymap &optional prefix
+ This function returns a list of all the keymaps that can be
+ accessed (via prefix keys) from KEYMAP. The value is an
+ association list with elements of the form `(KEY . MAP)', where
+ KEY is a prefix key whose definition in KEYMAP is MAP.
+
+ The elements of the alist are ordered so that the KEY increases in
+ length. The first element is always `([] . KEYMAP)', because the
+ specified keymap is accessible from itself with a prefix of no
+ events.
+
+ If PREFIX is given, it should be a prefix key sequence; then
+ `accessible-keymaps' includes only the submaps whose prefixes start
+ with PREFIX. These elements look just as they do in the value of
+ `(accessible-keymaps)'; the only difference is that some elements
+ are omitted.
+
+ In the example below, the returned alist indicates that the key
+ `C-x', which is displayed as `[(control x)]', is a prefix key
+ whose definition is the keymap `#<keymap ((control x) #<keymap
+ emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>'. (The strange
+ notation for the keymap's name indicates that this is an internal
+ submap of `emacs-lisp-mode-map'. This is because
+ `lisp-interaction-mode-map' has set up `emacs-lisp-mode-map' as
+ its parent, and `lisp-interaction-mode-map' defines no key
+ sequences beginning with `C-x'.)
+
+ (current-local-map)
+ => #<keymap lisp-interaction-mode-map 5 entries 0x558>
+ (accessible-keymaps (current-local-map))
+ =>(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
+ ([(control x)] .
+ #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
+ 1 entry 0x8a2>))
+
+ The following example shows the results of calling
+ `accessible-keymaps' on a large, complex keymap. Notice how some
+ keymaps were given explicit names using `set-keymap-name'; those
+ submaps without explicit names are given descriptive names
+ indicating their relationship to their enclosing keymap.
+
+ (accessible-keymaps (current-global-map))
+ => (([] . #<keymap global-map 639 entries 0x221>)
+ ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
+ ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
+ ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
+ ([(meta escape)] .
+ #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
+ 3 entries 0x3e0>)
+ ([(meta control \[)] .
+ #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
+ 3 entries 0x3e0>)
+ ([f1] . #<keymap help-map 33 entries 0x4ec>)
+ ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
+ ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
+ ([(control x) \6] . #<keymap 13 entries 0x4d2>)
+ ([(control x) a] .
+ #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
+ 8 entries 0x3ef>)
+ ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
+ ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
+ ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
+ ([(control x) a i] .
+ #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
+ 8 entries 0x3ef>)
+ 2 entries 0x3f5>))
+
+ - Function: map-keymap function keymap &optional sort-first
+ This function applies FUNCTION to each element of KEYMAP.
+ FUNCTION will be called with two arguments: a key-description
+ list, and the binding. The order in which the elements of the
+ keymap are passed to the function is unspecified. If the function
+ inserts new elements into the keymap, it may or may not be called
+ with them later. No element of the keymap will ever be passed to
+ the function more than once.
+
+ The function will not be called on elements of this keymap's
+ parents (*note Inheritance and Keymaps::) or upon keymaps which
+ are contained within this keymap (multi-character definitions).
+ It will be called on <META> characters since they are not really
+ two-character sequences.
+
+ If the optional third argument SORT-FIRST is non-`nil', then the
+ elements of the keymap will be passed to the mapper function in a
+ canonical order. Otherwise, they will be passed in hash (that is,
+ random) order, which is faster.
+
+ - Function: keymap-fullness keymap
+ This function returns the number of bindings in the keymap.
+
+ - Function: where-is-internal definition &optional keymaps firstonly
+ noindirect event-or-keys
+ This function returns a list of key sequences (of any length) that
+ are bound to DEFINITION in a set of keymaps.
+
+ The argument DEFINITION can be any object; it is compared with all
+ keymap entries using `eq'.
+
+ KEYMAPS can be either a keymap (meaning search in that keymap and
+ the current global keymap) or a list of keymaps (meaning search in
+ exactly those keymaps and no others). If KEYMAPS is nil, search
+ in the currently applicable maps for EVENT-OR-KEYS.
+
+ If KEYMAPS is a keymap, then the maps searched are KEYMAPS and the
+ global keymap. If KEYMAPS is a list of keymaps, then the maps
+ searched are exactly those keymaps, and no others. If KEYMAPS is
+ `nil', then the maps used are the current active keymaps for
+ EVENT-OR-KEYS (this is equivalent to specifying `(current-keymaps
+ EVENT-OR-KEYS)' as the argument to KEYMAPS).
+
+ If FIRSTONLY is non-`nil', then the value is a single vector
+ representing the first key sequence found, rather than a list of
+ all possible key sequences.
+
+ If NOINDIRECT is non-`nil', `where-is-internal' doesn't follow
+ indirect keymap bindings. This makes it possible to search for an
+ indirect definition itself.
+
+ This function is used by `where-is' (*note Help: (xemacs)Help.).
+
+ (where-is-internal 'describe-function)
+ => ([(control h) d] [(control h) f] [f1 d] [f1 f])
+
+ - Function: describe-bindings-internal map &optional all shadow prefix
+ mouse-only-p
+ This function inserts (into the current buffer) a list of all
+ defined keys and their definitions in MAP. Optional second
+ argument ALL says whether to include even "uninteresting"
+ definitions, i.e. symbols with a non-`nil' `suppress-keymap'
+ property. Third argument SHADOW is a list of keymaps whose
+ bindings shadow those of map; if a binding is present in any
+ shadowing map, it is not printed. Fourth argument PREFIX, if
+ non-`nil', should be a key sequence; only bindings which start
+ with that key sequence will be printed. Fifth argument
+ MOUSE-ONLY-P says to only print bindings for mouse clicks.
+
+ `describe-bindings-internal' is used to implement the help command
+`describe-bindings'.
+
+ - Command: describe-bindings &optional prefix mouse-only-p
+ This function creates a listing of all defined keys and their
+ definitions. It writes the listing in a buffer named `*Help*' and
+ displays it in a window.
+
+ If optional argument PREFIX is non-`nil', it should be a prefix
+ key; then the listing includes only keys that start with PREFIX.
+
+ When several characters with consecutive ASCII codes have the same
+ definition, they are shown together, as `FIRSTCHAR..LASTCHAR'. In
+ this instance, you need to know the ASCII codes to understand
+ which characters this means. For example, in the default global
+ map, the characters `<SPC> .. ~' are described by a single line.
+ <SPC> is ASCII 32, `~' is ASCII 126, and the characters between
+ them include all the normal printing characters, (e.g., letters,
+ digits, punctuation, etc.); all these characters are bound to
+ `self-insert-command'.
+
+ If the second optional argument MOUSE-ONLY-P (prefix arg,
+ interactively) is non-`nil' then only the mouse bindings are
+ displayed.
+
+\1f
+File: lispref.info, Node: Other Keymap Functions, Prev: Scanning Keymaps, Up: Keymaps
+
+Other Keymap Functions
+======================
+
+ - Function: set-keymap-prompt keymap new-prompt
+ This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or
+ `nil' if no prompt is desired. The prompt is shown in the
+ echo-area when reading a key-sequence to be looked-up in this
+ keymap.
+
+ - Function: keymap-prompt keymap &optional use-inherited
+ This function returns the "prompt" of the given keymap. If
+ USE-INHERITED is non-`nil', any parent keymaps will also be
+ searched for a prompt.
+
+\1f
+File: lispref.info, Node: Menus, Next: Dialog Boxes, Prev: Keymaps, Up: Top
+
+Menus
+*****
+
+* Menu:
+
+* Menu Format:: Format of a menu description.
+* Menubar Format:: How to specify a menubar.
+* Menubar:: Functions for controlling the menubar.
+* Modifying Menus:: Modifying a menu description.
+* Pop-Up Menus:: Functions for specifying pop-up menus.
+* Menu Filters:: Filter functions for the default menubar.
+* Menu Accelerators:: Using and controlling menu accelerator keys
+* Buffers Menu:: The menu that displays the list of buffers.
+
+\1f
+File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus
+
+Format of Menus
+===============
+
+A menu is described using a "menu description", which is a list of menu
+items, keyword-value pairs, strings, and submenus. The menu
+description specifies which items are present in the menu, what function
+each item invokes, and whether the item is selectable or not. Pop-up
+menus are directly described with a menu description, while menubars are
+described slightly differently (see below).
+
+ The first element of a menu must be a string, which is the name of
+the menu. This is the string that will be displayed in the parent menu
+or menubar, if any. This string is not displayed in the menu itself,
+except in the case of the top level pop-up menu, where there is no
+parent. In this case, the string will be displayed at the top of the
+menu if `popup-menu-titles' is non-`nil'.
+
+ Immediately following the first element there may optionally be up
+to four keyword-value pairs, as follows:
+
+`:included FORM'
+ This can be used to control the visibility of a menu. The form is
+ evaluated and the menu will be omitted if the result is `nil'.
+
+`:config SYMBOL'
+ This is an efficient shorthand for `:included (memq SYMBOL
+ menubar-configuration)'. See the variable `menubar-configuration'.
+
+`:filter FUNCTION'
+ A menu filter is used to sensitize or incrementally create a
+ submenu only when it is selected by the user and not every time
+ the menubar is activated. The filter function is passed the list
+ of menu items in the submenu and must return a list of menu items
+ to be used for the menu. It is called only when the menu is about
+ to be displayed, so other menus may already be displayed. Vile
+ and terrible things will happen if a menu filter function changes
+ the current buffer, window, or frame. It also should not raise,
+ lower, or iconify any frames. Basically, the filter function
+ should have no side-effects.
+
+`:accelerator KEY'
+ A menu accelerator is a keystroke which can be pressed while the
+ menu is visible which will immediately activate the item. KEY
+ must be a char or the symbol name of a key. *Note Menu
+ Accelerators::.
+
+ The rest of the menu consists of elements as follows:
+
+ * A "menu item", which is a vector in the following form:
+
+ `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]'
+
+ NAME is a string, the name of the menu item; it is the string to
+ display on the menu. It is filtered through the resource
+ database, so it is possible for resources to override what string
+ is actually displayed.
+
+ CALLBACK is a form that will be invoked when the menu item is
+ selected. If the callback of a menu item is a symbol, then it
+ must name a command. It will be invoked with
+ `call-interactively'. If it is a list, then it is evaluated with
+ `eval'.
+
+ The valid keywords and their meanings are described below.
+
+ Note that for compatibility purposes, the form
+
+ `[ NAME CALLBACK ACTIVE-P ]'
+
+ is also accepted and is equivalent to
+
+ `[ NAME CALLBACK :active ACTIVE-P ]'
+
+ and the form
+
+ `[ NAME CALLBACK ACTIVE-P SUFFIX]'
+
+ is accepted and is equivalent to
+
+ `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]'
+
+ However, these older forms are deprecated and should generally not
+ be used.
+
+ * If an element of a menu is a string, then that string will be
+ presented in the menu as unselectable text.
+
+ * If an element of a menu is a string consisting solely of hyphens,
+ then that item will be presented as a solid horizontal line.
+
+ * If an element of a menu is a string beginning with `--:', then a
+ particular sort of horizontal line will be displayed, as follows:
+
+ `"--:singleLine"'
+ A solid horizontal line. This is equivalent to a string
+ consisting solely of hyphens.
+
+ `"--:doubleLine"'
+ A solid double horizontal line.
+
+ `"--:singleDashedLine"'
+ A dashed horizontal line.
+
+ `"--:doubleDashedLine"'
+ A dashed double horizontal line.
+
+ `"--:noLine"'
+ No line (but a small space is left).
+
+ `"--:shadowEtchedIn"'
+ A solid horizontal line with a 3-d recessed appearance.
+
+ `"--:shadowEtchedOut"'
+ A solid horizontal line with a 3-d pushed-out appearance.
+
+ `"--:shadowDoubleEtchedIn"'
+ A solid double horizontal line with a 3-d recessed appearance.
+
+ `"--:shadowDoubleEtchedOut"'
+ A solid double horizontal line with a 3-d pushed-out
+ appearance.
+
+ `"--:shadowEtchedInDash"'
+ A dashed horizontal line with a 3-d recessed appearance.
+
+ `"--:shadowEtchedOutDash"'
+ A dashed horizontal line with a 3-d pushed-out appearance.
+
+ `"--:shadowDoubleEtchedInDash"'
+ A dashed double horizontal line with a 3-d recessed
+ appearance.
+
+ `"--:shadowDoubleEtchedOutDash"'
+ A dashed double horizontal line with a 3-d pushed-out
+ appearance.
+
+ * If an element of a menu is a list, it is treated as a submenu.
+ The name of that submenu (the first element in the list) will be
+ used as the name of the item representing this menu on the parent.
+
+ The possible keywords are as follows:
+
+:active FORM
+ FORM will be evaluated when the menu that this item is a part of
+ is about to be displayed, and the item will be selectable only if
+ the result is non-`nil'. If the item is unselectable, it will
+ usually be displayed grayed-out to indicate this.
+
+:suffix FORM
+ FORM will be evaluated when the menu that this item is a part of
+ is about to be displayed, and the resulting string is appended to
+ the displayed name. This provides a convenient way of adding the
+ name of a command's "argument" to the menu, like `Kill Buffer
+ NAME'.
+
+:keys STRING
+ Normally, the keyboard equivalents of commands in menus are
+ displayed when the "callback" is a symbol. This can be used to
+ specify keys for more complex menu items. It is passed through
+ `substitute-command-keys' first.
+
+:style STYLE
+ Specifies what kind of object this menu item is. STYLE be one of
+ the symbols
+
+ `nil'
+ A normal menu item.
+
+ `toggle'
+ A toggle button.
+
+ `radio'
+ A radio button.
+
+ `button'
+ A menubar button.
+
+ The only difference between toggle and radio buttons is how they
+ are displayed. But for consistency, a toggle button should be
+ used when there is one option whose value can be turned on or off,
+ and radio buttons should be used when there is a set of mutually
+ exclusive options. When using a group of radio buttons, you
+ should arrange for no more than one to be marked as selected at a
+ time.
+
+:selected FORM
+ Meaningful only when STYLE is `toggle', `radio' or `button'. This
+ specifies whether the button will be in the selected or unselected
+ state. FORM is evaluated, as for `:active'.
+
+:included FORM
+ This can be used to control the visibility of a menu item. The
+ form is evaluated and the menu item is only displayed if the
+ result is non-`nil'. Note that this is different from `:active':
+ If `:active' evaluates to `nil', the item will be displayed grayed
+ out, while if `:included' evaluates to `nil', the item will be
+ omitted entirely.
+
+:config SYMBOL
+ This is an efficient shorthand for `:included (memq SYMBOL
+ menubar-configuration)'. See the variable `menubar-configuration'.
+
+:accelerator KEY
+ A menu accelerator is a keystroke which can be pressed while the
+ menu is visible which will immediately activate the item. KEY
+ must be a char or the symbol name of a key. *Note Menu
+ Accelerators::.
+
+ - Variable: menubar-configuration
+ This variable holds a list of symbols, against which the value of
+ the `:config' tag for each menubar item will be compared. If a
+ menubar item has a `:config' tag, then it is omitted from the
+ menubar if that tag is not a member of the `menubar-configuration'
+ list.
+
+ For example:
+
+ ("File"
+ :filter file-menu-filter ; file-menu-filter is a function that takes
+ ; one argument (a list of menu items) and
+ ; returns a list of menu items
+ [ "Save As..." write-file]
+ [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ]
+ [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ]
+ )
+
+\1f
+File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus
+
+Format of the Menubar
+=====================
+
+A menubar is a list of menus, menu items, and strings. The format is
+similar to that of a menu, except:
+
+ * The first item need not be a string, and is not treated specially.
+
+ * A string consisting solely of hyphens is not treated specially.
+
+ * If an element of a menubar is `nil', then it is used to represent
+ the division between the set of menubar items which are flush-left
+ and those which are flush-right. (Note: this isn't completely
+ implemented yet.)
+
+\1f
+File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus
+
+Menubar
+=======
+
+ - Variable: current-menubar
+ This variable holds the description of the current menubar. This
+ may be buffer-local. When the menubar is changed, the function
+ `set-menubar-dirty-flag' has to be called in order for the menubar
+ to be updated on the screen.
+
+ - Constant: default-menubar
+ This variable holds the menubar description of the menubar that is
+ visible at startup. This is the value that `current-menubar' has
+ at startup.
+
+ - Function: set-menubar-dirty-flag
+ This function tells XEmacs that the menubar widget has to be
+ updated. Changes to the menubar will generally not be visible
+ until this function is called.
+
+ The following convenience functions are provided for setting the
+menubar. They are equivalent to doing the appropriate action to change
+`current-menubar', and then calling `set-menubar-dirty-flag'. Note
+that these functions copy their argument using `copy-sequence'.
+
+ - Function: set-menubar menubar
+ This function sets the default menubar to be MENUBAR (*note Menu
+ Format::). This is the menubar that will be visible in buffers
+ that have not defined their own, buffer-local menubar.
+
+ - Function: set-buffer-menubar menubar
+ This function sets the buffer-local menubar to be MENUBAR. This
+ does not change the menubar in any buffers other than the current
+ one.
+
+ Miscellaneous:
+
+ - Variable: menubar-show-keybindings
+ If true, the menubar will display keyboard equivalents. If false,
+ only the command names will be displayed.
+
+ - Variable: activate-menubar-hook
+ Function or functions called before a menubar menu is pulled down.
+ These functions are called with no arguments, and should
+ interrogate and modify the value of `current-menubar' as desired.
+
+ The functions on this hook are invoked after the mouse goes down,
+ but before the menu is mapped, and may be used to activate,
+ deactivate, add, or delete items from the menus. However, using a
+ filter (with the `:filter' keyword in a menu description) is
+ generally a more efficient way of accomplishing the same thing,
+ because the filter is invoked only when the actual menu goes down.
+ With a complex menu, there can be a quite noticeable and
+ sometimes aggravating delay if all menu modification is
+ implemented using the `activate-menubar-hook'. See above.
+
+ These functions may return the symbol `t' to assert that they have
+ made no changes to the menubar. If any other value is returned,
+ the menubar is recomputed. If `t' is returned but the menubar has
+ been changed, then the changes may not show up right away.
+ Returning `nil' when the menubar has not changed is not so bad;
+ more computation will be done, but redisplay of the menubar will
+ still be performed optimally.
+
+ - Variable: menu-no-selection-hook
+ Function or functions to call when a menu or dialog box is
+ dismissed without a selection having been made.
+
+\1f
+File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus
+
+Modifying Menus
+===============
+
+The following functions are provided to modify the menubar of one of its
+submenus. Note that these functions modify the menu in-place, rather
+than copying it and making a new menu.
+
+ Some of these functions take a "menu path", which is a list of
+strings identifying the menu to be modified. For example, `("File")'
+names the top-level "File" menu. `("File" "Foo")' names a hypothetical
+submenu of "File".
+
+ Others take a "menu item path", which is similar to a menu path but
+also specifies a particular item to be modified. For example, `("File"
+"Save")' means the menu item called "Save" under the top-level "File"
+menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under
+the "Foo" submenu of "Menu".
+
+ - Function: add-submenu menu-path submenu &optional before in-menu
+ This function adds a menu to the menubar or one of its submenus.
+ If the named menu exists already, it is changed.
+
+ MENU-PATH identifies the menu under which the new menu should be
+ inserted. If MENU-PATH is `nil', then the menu will be added to
+ the menubar itself.
+
+ SUBMENU is the new menu to add (*note Menu Format::).
+
+ BEFORE, if provided, is the name of a menu before which this menu
+ should be added, if this menu is not on its parent already. If
+ the menu is already present, it will not be moved.
+
+ If IN-MENU is present use that instead of `current-menubar' as the
+ menu to change.
+
+ - Function: add-menu-button menu-path menu-leaf &optional before
+ in-menu
+ This function adds a menu item to some menu, creating the menu
+ first if necessary. If the named item exists already, it is
+ changed.
+
+ MENU-PATH identifies the menu under which the new menu item should
+ be inserted.
+
+ MENU-LEAF is a menubar leaf node (*note Menu Format::).
+
+ BEFORE, if provided, is the name of a menu before which this item
+ should be added, if this item is not on the menu already. If the
+ item is already present, it will not be moved.
+
+ If IN-MENU is present use that instead of `current-menubar' as the
+ menu to change.
+
+ - Function: delete-menu-item menu-item-path &optional from-menu
+ This function removes the menu item specified by MENU-ITEM-PATH
+ from the menu hierarchy.
+
+ If FROM-MENU is present use that instead of `current-menubar' as
+ the menu to change.
+
+ - Function: enable-menu-item menu-item-path
+ This function makes the menu item specified by MENU-ITEM-PATH be
+ selectable.
+
+ - Function: disable-menu-item menu-item-path
+ This function makes the menu item specified by MENU-ITEM-PATH be
+ unselectable.
+
+ - Function: relabel-menu-item menu-item-path new-name
+ This function changes the string of the menu item specified by
+ MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be
+ printed as from now on.
+
+ The following function can be used to search for a particular item in
+a menubar specification, given a path to the item.
+
+ - Function: find-menu-item menubar menu-item-path &optional parent
+ This function searches MENUBAR for the item given by
+ MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
+ of MENUBAR). This function returns `(ITEM . PARENT)', where
+ PARENT is the immediate parent of the item found (a menu
+ description), and ITEM is either a vector, list, or string,
+ depending on the nature of the menu item.
+
+ This function signals an error if the item is not found.
+
+ The following deprecated functions are also documented, so that
+existing code can be understood. You should not use these functions in
+new code.
+
+ - Function: add-menu menu-path menu-name menu-items &optional before
+ This function adds a menu to the menubar or one of its submenus.
+ If the named menu exists already, it is changed. This is
+ obsolete; use `add-submenu' instead.
+
+ MENU-PATH identifies the menu under which the new menu should be
+ inserted. If MENU-PATH is `nil', then the menu will be added to
+ the menubar itself.
+
+ MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
+ a list of menu items, strings, and submenus. These two arguments
+ are the same as the first and following elements of a menu
+ description (*note Menu Format::).
+
+ BEFORE, if provided, is the name of a menu before which this menu
+ should be added, if this menu is not on its parent already. If the
+ menu is already present, it will not be moved.
+
+ - Function: add-menu-item menu-path item-name function enabled-p
+ &optional before
+ This function adds a menu item to some menu, creating the menu
+ first if necessary. If the named item exists already, it is
+ changed. This is obsolete; use `add-menu-button' instead.
+
+ MENU-PATH identifies the menu under which the new menu item should
+ be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
+ second, and third elements of a menu item vector (*note Menu
+ Format::).
+
+ BEFORE, if provided, is the name of a menu item before which this
+ item should be added, if this item is not on the menu already. If
+ the item is already present, it will not be moved.
+
+\1f
+File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus
+
+Menu Filters
+============
+
+The following filter functions are provided for use in
+`default-menubar'. You may want to use them in your own menubar
+description.
+
+ - Function: file-menu-filter menu-items
+ This function changes the arguments and sensitivity of these File
+ menu items:
+
+ `Delete Buffer'
+ Has the name of the current buffer appended to it.
+
+ `Print Buffer'
+ Has the name of the current buffer appended to it.
+
+ `Pretty-Print Buffer'
+ Has the name of the current buffer appended to it.
+
+ `Save Buffer'
+ Has the name of the current buffer appended to it, and is
+ sensitive only when the current buffer is modified.
+
+ `Revert Buffer'
+ Has the name of the current buffer appended to it, and is
+ sensitive only when the current buffer has a file.
+
+ `Delete Frame'
+ Sensitive only when there is more than one visible frame.
+
+ - Function: edit-menu-filter menu-items
+ This function changes the arguments and sensitivity of these Edit
+ menu items:
+
+ `Cut'
+ Sensitive only when XEmacs owns the primary X Selection (if
+ `zmacs-regions' is `t', this is equivalent to saying that
+ there is a region selected).
+
+ `Copy'
+ Sensitive only when XEmacs owns the primary X Selection.
+
+ `Clear'
+ Sensitive only when XEmacs owns the primary X Selection.
+
+ `Paste'
+ Sensitive only when there is an owner for the X Clipboard
+ Selection.
+
+ `Undo'
+ Sensitive only when there is undo information. While in the
+ midst of an undo, this is changed to `Undo More'.
+
+ - Function: buffers-menu-filter menu-items
+ This function sets up the Buffers menu. *Note Buffers Menu::, for
+ more information.
+
+\1f
+File: lispref.info, Node: Pop-Up Menus, Next: Menu Filters, Prev: Modifying Menus, Up: Menus
+
+Pop-Up Menus
+============
+
+ - Function: popup-menu menu-description &optional event
+ This function pops up a menu specified by MENU-DESCRIPTION, which
+ is a menu description (*note Menu Format::). The menu is
+ displayed at the current mouse position.
+
+ - Function: popup-menu-up-p
+ This function returns `t' if a pop-up menu is up, `nil' otherwise.
+
+ - Variable: popup-menu-titles
+ If true (the default), pop-up menus will have title bars at the
+ top.
+
+ Some machinery is provided that attempts to provide a higher-level
+mechanism onto pop-up menus. This only works if you do not redefine
+the binding for button3.
+
+ - Command: popup-mode-menu
+ This function pops up a menu of global and mode-specific commands.
+ The menu is computed by combining `global-popup-menu' and
+ `mode-popup-menu'. This is the default binding for button3. You
+ should generally not change this binding.
+
+ - Variable: global-popup-menu
+ This holds the global popup menu. This is present in all modes.
+ (This is `nil' by default.)
+
+ - Variable: mode-popup-menu
+ The mode-specific popup menu. Automatically buffer local. This
+ is appended to the default items in `global-popup-menu'.
+
+ - Constant: default-popup-menu
+ This holds the default value of `mode-popup-menu'.
+
+ - Variable: activate-popup-menu-hook
+ Function or functions run before a mode-specific popup menu is made
+ visible. These functions are called with no arguments, and should
+ interrogate and modify the value of `global-popup-menu' or
+ `mode-popup-menu' as desired. Note: this hook is only run if you
+ use `popup-mode-menu' for activating the global and mode-specific
+ commands; if you have your own binding for button3, this hook
+ won't be run.
+
+ The following convenience functions are provided for displaying
+pop-up menus.
+
+ - Command: popup-buffer-menu event
+ This function pops up a copy of the `Buffers' menu (from the
+ menubar) where the mouse is clicked. It should be bound to a
+ mouse button event.
+
+ - Command: popup-menubar-menu event
+ This function pops up a copy of menu that also appears in the
+ menubar. It should be bound to a mouse button event.
+
+\1f
+File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus
+
+Menu Accelerators
+=================
+
+Menu accelerators are keyboard shortcuts for accessing the menubar.
+Accelerator keys can be specified for menus as well as for menu items.
+An accelerator key for a menu is used to activate that menu when it
+appears as a submenu of another menu. An accelerator key for a menu
+item is used to activate that item.
+
+* Menu:
+
+* Creating Menu Accelerators:: How to add accelerator keys to a menu.
+* Keyboard Menu Traversal:: How to use and modify the keys which are used
+ to traverse the menu structure.
+* Menu Accelerator Functions:: Functions for working with menu accelerators.
+
+\1f
+File: lispref.info, Node: Creating Menu Accelerators, Next: Keyboard Menu Traversal, Up: Menu Accelerators
+
+Creating Menu Accelerators
+--------------------------
+
+Menu accelerators are specified as part of the menubar format using the
+:accelerator tag to specify a key or by placing "%_" in the menu or
+menu item name prior to the letter which is to be used as the
+accelerator key. The advantage of the second method is that the menu
+rendering code then knows to draw an underline under that character,
+which is the canonical way of indicating an accelerator key to a user.
+
+ For example, the command
+
+ (add-submenu nil '("%_Test"
+ ["One" (insert "1") :accelerator ?1 :active t]
+ ["%_Two" (insert "2")]
+ ["%_3" (insert "3")]))
+
+ will add a new menu to the top level menubar. The new menu can be
+reached by pressing "t" while the top level menubar is active. When
+the menu is active, pressing "1" will activate the first item and
+insert the character "1" into the buffer. Pressing "2" will activate
+the second item and insert the character "2" into the buffer. Pressing
+"3" will activate the third item and insert the character "3" into the
+buffer.
+
+ It is possible to activate the top level menubar itself using
+accelerator keys. *Note Menu Accelerator Functions::.
+
+\1f
+File: lispref.info, Node: Keyboard Menu Traversal, Next: Menu Accelerator Functions, Prev: Creating Menu Accelerators, Up: Menu Accelerators
+
+Keyboard Menu Traversal
+-----------------------
+
+In addition to immediately activating a menu or menu item, the keyboard
+can be used to traverse the menus without activating items. The
+keyboard arrow keys, the return key and the escape key are defined to
+traverse the menus in a way that should be familiar to users of any of
+a certain family of popular PC operating systems.
+
+ This behavior can be changed by modifying the bindings in
+menu-accelerator-map. At this point, the online help is your best bet
+for more information about how to modify the menu traversal keys.
+
+\1f
+File: lispref.info, Node: Menu Accelerator Functions, Prev: Keyboard Menu Traversal, Up: Menu Accelerators
+
+Menu Accelerator Functions
+--------------------------
+
+ - Command: accelerate-menu
+ Make the menubar immediately active and place the cursor on the
+ left most entry in the top level menu. Menu items can be selected
+ as usual.
+
+ - Variable: menu-accelerator-enabled
+ Whether menu accelerator keys can cause the menubar to become
+ active.
+
+ If `menu-force' or `menu-fallback', then menu accelerator keys can
+ be used to activate the top level menu. Once the menubar becomes
+ active, the accelerator keys can be used regardless of the value
+ of this variable.
+
+ `menu-force' is used to indicate that the menu accelerator key
+ takes precedence over bindings in the current keymap(s).
+ `menu-fallback' means that bindings in the current keymap take
+ precedence over menu accelerator keys. Thus a top level menu with
+ an accelerator of "T" would be activated on a keypress of Meta-t
+ if `menu-accelerator-enabled' is `menu-force'. However, if
+ `menu-accelerator-enabled' is `menu-fallback', then Meta-t will
+ not activate the menubar and will instead run the function
+ transpose-words, to which it is normally bound.
+
+ The default value is `nil'.
+
+ See also `menu-accelerator-modifiers' and
+ `menu-accelerator-prefix'.
+
+ - Variable: menu-accelerator-map
+ Keymap consulted to determine the commands to run in response to
+ keypresses occurring while the menubar is active. *Note Keyboard
+ Menu Traversal::.
+
+ - Variable: menu-accelerator-modifiers
+ A list of modifier keys which must be pressed in addition to a
+ valid menu accelerator in order for the top level menu to be
+ activated in response to a keystroke. The default value of
+ `(meta)' mirrors the usage of the alt key as a menu accelerator in
+ popular PC operating systems.
+
+ The modifier keys in `menu-accelerator-modifiers' must match
+ exactly the modifiers present in the keypress. The only exception
+ is that the shift modifier is accepted in conjunction with
+ alphabetic keys even if it is not a menu accelerator modifier.
+
+ See also `menu-accelerator-enabled' and `menu-accelerator-prefix'.
+
+ - Variable: menu-accelerator-prefix
+ Prefix key(s) that must be typed before menu accelerators will be
+ activated. Must be a valid key descriptor.
+
+ The default value is `nil'.
+
+ (setq menu-accelerator-prefix ?\C-x)
+ (setq menu-accelerator-modifiers '(meta control))
+ (setq menu-accelerator-enabled 'menu-force)
+ (add-submenu nil '("%_Test"
+ ["One" (insert "1") :accelerator ?1 :active t]
+ ["%_Two" (insert "2")]
+ ["%_3" (insert "3")]))
+
+ will add the menu "Test" to the top level menubar. Pressing C-x
+followed by C-M-T will activate the menubar and display the "Test"
+menu. Pressing C-M-T by itself will not activate the menubar. Neither
+will pressing C-x followed by anything else.
+
+\1f
+File: lispref.info, Node: Buffers Menu, Prev: Menu Accelerators, Up: Menus
+
+Buffers Menu
+============
+
+The following options control how the `Buffers' menu is displayed.
+This is a list of all (or a subset of) the buffers currently in
+existence, and is updated dynamically.
+
+ - User Option: buffers-menu-max-size
+ This user option holds the maximum number of entries which may
+ appear on the `Buffers' menu. If this is 10, then only the ten
+ most-recently-selected buffers will be shown. If this is `nil',
+ then all buffers will be shown. Setting this to a large number or
+ `nil' will slow down menu responsiveness.
+
+ - Function: format-buffers-menu-line buffer
+ This function returns a string to represent BUFFER in the
+ `Buffers' menu. `nil' means the buffer shouldn't be listed. You
+ can redefine this.
+
+ - User Option: complex-buffers-menu-p
+ If true, the `Buffers' menu will contain several commands, as
+ submenus of each buffer line. If this is false, then there will
+ be only one command: select that buffer.
+
+ - User Option: buffers-menu-switch-to-buffer-function
+ This user option holds the function to call to select a buffer
+ from the `Buffers' menu. `switch-to-buffer' is a good choice, as
+ is `pop-to-buffer'.
+
+\1f
+File: lispref.info, Node: Dialog Boxes, Next: Toolbar, Prev: Menus, Up: Top
+
+Dialog Boxes
+************
+
+* Menu:
+
+* Dialog Box Format::
+* Dialog Box Functions::
+
+\1f
+File: lispref.info, Node: Dialog Box Format, Next: Dialog Box Functions, Up: Dialog Boxes
+
+Dialog Box Format
+=================
+
+A dialog box description is a list.
+
+ * The first element of the list is a string to display in the dialog
+ box.
+
+ * The rest of the elements are descriptions of the dialog box's
+ buttons. Each one is a vector of three elements:
+ - The first element is the text of the button.
+
+ - The second element is the "callback".
+
+ - The third element is `t' or `nil', whether this button is
+ selectable.
+
+ If the callback of a button is a symbol, then it must name a command.
+It will be invoked with `call-interactively'. If it is a list, then it
+is evaluated with `eval'.
+
+ One (and only one) of the buttons may be `nil'. This marker means
+that all following buttons should be flushright instead of flushleft.
+
+ The syntax, more precisely:
+
+ form := <something to pass to `eval'>
+ command := <a symbol or string, to pass to `call-interactively'>
+ callback := command | form
+ active-p := <t, nil, or a form to evaluate to decide whether this
+ button should be selectable>
+ name := <string>
+ partition := 'nil'
+ button := '[' name callback active-p ']'
+ dialog := '(' name [ button ]+ [ partition [ button ]+ ] ')'
+
+\1f
+File: lispref.info, Node: Dialog Box Functions, Prev: Dialog Box Format, Up: Dialog Boxes
+
+Dialog Box Functions
+====================
+
+ - Function: popup-dialog-box dbox-desc
+ This function pops up a dialog box. DBOX-DESC describes how the
+ dialog box will appear (*note Dialog Box Format::).
+
+ *Note Yes-or-No Queries::, for functions to ask a yes/no question
+using a dialog box.
+
+\1f
+File: lispref.info, Node: Toolbar, Next: Gutter, Prev: Dialog Boxes, Up: Top
+
+Toolbar
+*******
+
+* Menu:
+
+* Toolbar Intro:: An introduction.
+* Creating Toolbar:: How to create a toolbar.
+* Toolbar Descriptor Format:: Accessing and modifying a toolbar's
+ properties.
+* Specifying the Toolbar:: Setting a toolbar's contents.
+* Other Toolbar Variables:: Controlling the size of toolbars.
+
+\1f
+File: lispref.info, Node: Toolbar Intro, Next: Creating Toolbar, Up: Toolbar
+
+Toolbar Intro
+=============
+
+A "toolbar" is a bar of icons displayed along one edge of a frame. You
+can view a toolbar as a series of menu shortcuts--the most common menu
+options can be accessed with a single click rather than a series of
+clicks and/or drags to select the option from a menu. Consistent with
+this, a help string (called the "help-echo") describing what an icon in
+the toolbar (called a "toolbar button") does, is displayed in the
+minibuffer when the mouse is over the button.
+
+ In XEmacs, a toolbar can be displayed along any of the four edges of
+the frame, and two or more different edges can be displaying toolbars
+simultaneously. The contents, thickness, and visibility of the
+toolbars can be controlled separately, and the values can be
+per-buffer, per-frame, etc., using specifiers (*note Specifiers::).
+
+ Normally, there is one toolbar displayed in a frame. Usually, this
+is the standard toolbar, but certain modes will override this and
+substitute their own toolbar. In some cases (e.g. the VM package), a
+package will supply its own toolbar along a different edge from the
+standard toolbar, so that both can be visible at once. This standard
+toolbar is usually positioned along the top of the frame, but this can
+be changed using `set-default-toolbar-position'.
+
+ Note that, for each of the toolbar properties (contents, thickness,
+and visibility), there is a separate specifier for each of the four
+toolbar positions (top, bottom, left, and right), and an additional
+specifier for the "default" toolbar, i.e. the toolbar whose position is
+controlled by `set-default-toolbar-position'. The way this works is
+that `set-default-toolbar-position' arranges things so that the
+appropriate position-specific specifiers for the default position
+inherit from the corresponding default specifiers. That way, if the
+position-specific specifier does not give a value (which it usually
+doesn't), then the value from the default specifier applies. If you
+want to control the default toolbar, you just change the default
+specifiers, and everything works. A package such as VM that wants to
+put its own toolbar in a different location from the default just sets
+the position-specific specifiers, and if the user sets the default
+toolbar to the same position, it will just not be visible.
+
+\1f
+File: lispref.info, Node: Creating Toolbar, Next: Toolbar Descriptor Format, Prev: Toolbar Intro, Up: Toolbar
+
+Creating Toolbar
+================
+
+ - Function: make-toolbar-specifier spec-list
+ Return a new `toolbar' specifier object with the given
+ specification list. SPEC-LIST can be a list of specifications
+ (each of which is a cons of a locale and a list of instantiators),
+ a single instantiator, or a list of instantiators. *Note
+ Specifiers::, for more information about specifiers.
+
+ Toolbar specifiers are used to specify the format of a toolbar.
+ The values of the variables `default-toolbar', `top-toolbar',
+ `left-toolbar', `right-toolbar', and `bottom-toolbar' are always
+ toolbar specifiers.
+
+ Valid toolbar instantiators are called "toolbar descriptors" and
+ are lists of vectors. See `default-toolbar' for a description of
+ the exact format.
+
+\1f
+File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar
+
+Toolbar Descriptor Format
+=========================
+
+The contents of a toolbar are specified using a "toolbar descriptor".
+The format of a toolbar descriptor is a list of "toolbar button
+descriptors". Each toolbar button descriptor is a vector in one of the
+following formats:
+
+ * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
+
+ * `[:style 2D-OR-3D]'
+
+ * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
+
+ * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
+
+ Optionally, one of the toolbar button descriptors may be `nil'
+instead of a vector; this signifies the division between the toolbar
+buttons that are to be displayed flush-left, and the buttons to be
+displayed flush-right.
+
+ The first vector format above specifies a normal toolbar button; the
+others specify blank areas in the toolbar.
+
+ For the first vector format:
+
+ * GLYPH-LIST should be a list of one to six glyphs (as created by
+ `make-glyph') or a symbol whose value is such a list. The first
+ glyph, which must be provided, is the glyph used to display the
+ toolbar button when it is in the "up" (not pressed) state. The
+ optional second glyph is for displaying the button when it is in
+ the "down" (pressed) state. The optional third glyph is for when
+ the button is disabled. The last three glyphs are for displaying
+ the button in the "up", "down", and "disabled" states,
+ respectively, but are used when the user has called for captioned
+ toolbar buttons (using `toolbar-buttons-captioned-p'). The
+ function `toolbar-make-button-list' is useful in creating these
+ glyph lists.
+
+ * Even if you do not provide separate down-state and disabled-state
+ glyphs, the user will still get visual feedback to indicate which
+ state the button is in. Buttons in the up-state are displayed
+ with a shadowed border that gives a raised appearance to the
+ button. Buttons in the down-state are displayed with shadows that
+ give a recessed appearance. Buttons in the disabled state are
+ displayed with no shadows, giving a 2-d effect.
+
+ * If some of the toolbar glyphs are not provided, they inherit as
+ follows:
+
+ UP: up
+ DOWN: down -> up
+ DISABLED: disabled -> up
+ CAP-UP: cap-up -> up
+ CAP-DOWN: cap-down -> cap-up -> down -> up
+ CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
+
+ * The second element FUNCTION is a function to be called when the
+ toolbar button is activated (i.e. when the mouse is released over
+ the toolbar button, if the press occurred in the toolbar). It can
+ be any form accepted by `call-interactively', since this is how it
+ is invoked.
+
+ * The third element ENABLED-P specifies whether the toolbar button
+ is enabled (disabled buttons do nothing when they are activated,
+ and are displayed differently; see above). It should be either a
+ boolean or a form that evaluates to a boolean.
+
+ * The fourth element HELP, if non-`nil', should be a string. This
+ string is displayed in the echo area when the mouse passes over the
+ toolbar button.
+
+ For the other vector formats (specifying blank areas of the toolbar):
+
+ * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
+ whether the area is displayed with shadows (giving it a raised,
+ 3-d appearance) or without shadows (giving it a flat appearance).
+
+ * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
+ area. If omitted, it defaults to a device-specific value (8
+ pixels for X devices).
+
+ - Function: toolbar-make-button-list up &optional down disabled cap-up
+ cap-down cap-disabled
+ This function calls `make-glyph' on each arg and returns a list of
+ the results. This is useful for setting the first argument of a
+ toolbar button descriptor (typically, the result of this function
+ is assigned to a symbol, which is specified as the first argument
+ of the toolbar button descriptor).
+
+ - Function: check-toolbar-button-syntax button &optional noerror
+ Verify the syntax of entry BUTTON in a toolbar description list.
+ If you want to verify the syntax of a toolbar description list as a
+ whole, use `check-valid-instantiator' with a specifier type of
+ `toolbar'.
+
+\1f
+File: lispref.info, Node: Specifying the Toolbar, Next: Other Toolbar Variables, Prev: Toolbar Descriptor Format, Up: Toolbar
+
+Specifying the Toolbar
+======================
+
+In order to specify the contents of a toolbar, set one of the specifier
+variables `default-toolbar', `top-toolbar', `bottom-toolbar',
+`left-toolbar', or `right-toolbar'. These are specifiers, which means
+you set them with `set-specifier' and query them with `specifier-specs'
+or `specifier-instance'. You will get an error if you try to set them
+using `setq'. The valid instantiators for these specifiers are toolbar
+descriptors, as described above. *Note Specifiers::, for more
+information.
+
+ Most of the time, you will set `default-toolbar', which allows the
+user to choose where the toolbar should go.
+
+ - Specifier: default-toolbar
+ The position of this toolbar is specified in the function
+ `default-toolbar-position'. If the corresponding
+ position-specific toolbar (e.g. `top-toolbar' if
+ `default-toolbar-position' is `top') does not specify a toolbar in
+ a particular domain, then the value of `default-toolbar' in that
+ domain, of any, will be used instead.
+
+ Note that the toolbar at any particular position will not be
+displayed unless its thickness (width or height, depending on
+orientation) is non-zero and its visibility status is true. The
+thickness is controlled by the specifiers `top-toolbar-height',
+`bottom-toolbar-height', `left-toolbar-width', and
+`right-toolbar-width', and the visibility status is controlled by the
+specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
+`left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
+Toolbar Variables::).
+
+ - Function: set-default-toolbar-position position
+ This function sets the position that the `default-toolbar' will be
+ displayed at. Valid positions are the symbols `top', `bottom',
+ `left' and `right'. What this actually does is set the fallback
+ specifier for the position-specific specifier corresponding to the
+ given position to `default-toolbar', and set the fallbacks for the
+ other position-specific specifiers to `nil'. It also does the
+ same thing for the position-specific thickness and visibility
+ specifiers, which inherit from one of `default-toolbar-height' or
+ `default-toolbar-width', and from `default-toolbar-visible-p',
+ respectively (*note Other Toolbar Variables::).
+
+ - Function: default-toolbar-position
+ This function returns the position that the `default-toolbar' will
+ be displayed at.
+
+ You can also explicitly set a toolbar at a particular position. When
+redisplay determines what to display at a particular position in a
+particular domain (i.e. window), it first consults the position-specific
+toolbar. If that does not yield a toolbar descriptor, the
+`default-toolbar' is consulted if `default-toolbar-position' indicates
+this position.
+
+ - Specifier: top-toolbar
+ Specifier for the toolbar at the top of the frame.
+
+ - Specifier: bottom-toolbar
+ Specifier for the toolbar at the bottom of the frame.
+
+ - Specifier: left-toolbar
+ Specifier for the toolbar at the left edge of the frame.
+
+ - Specifier: right-toolbar
+ Specifier for the toolbar at the right edge of the frame.
+
+ - Function: toolbar-specifier-p object
+ This function returns non-`nil' if OBJECT is a toolbar specifier.
+ Toolbar specifiers are the actual objects contained in the toolbar
+ variables described above, and their valid instantiators are
+ toolbar descriptors (*note Toolbar Descriptor Format::).
+
+\1f
+File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar
+
+Other Toolbar Variables
+=======================
+
+The variables to control the toolbar thickness, visibility status, and
+captioned status are all specifiers. *Note Specifiers::.
+
+ - Specifier: default-toolbar-height
+ This specifies the height of the default toolbar, if it's oriented
+ horizontally. The position of the default toolbar is specified by
+ the function `set-default-toolbar-position'. If the corresponding
+ position-specific toolbar thickness specifier (e.g.
+ `top-toolbar-height' if `default-toolbar-position' is `top') does
+ not specify a thickness in a particular domain (a window or a
+ frame), then the value of `default-toolbar-height' or
+ `default-toolbar-width' (depending on the toolbar orientation) in
+ that domain, if any, will be used instead.
+
+ - Specifier: default-toolbar-width
+ This specifies the width of the default toolbar, if it's oriented
+ vertically. This behaves like `default-toolbar-height'.
+
+ Note that `default-toolbar-height' is only used when
+`default-toolbar-position' is `top' or `bottom', and
+`default-toolbar-width' is only used when `default-toolbar-position' is
+`left' or `right'.
+
+ - Specifier: top-toolbar-height
+ This specifies the height of the top toolbar.
+
+ - Specifier: bottom-toolbar-height
+ This specifies the height of the bottom toolbar.
+
+ - Specifier: left-toolbar-width
+ This specifies the width of the left toolbar.
+
+ - Specifier: right-toolbar-width
+ This specifies the width of the right toolbar.
+
+ Note that all of the position-specific toolbar thickness specifiers
+have a fallback value of zero when they do not correspond to the
+default toolbar. Therefore, you will have to set a non-zero thickness
+value if you want a position-specific toolbar to be displayed.
+
+ - Specifier: default-toolbar-visible-p
+ This specifies whether the default toolbar is visible. The
+ position of the default toolbar is specified by the function
+ `set-default-toolbar-position'. If the corresponding
+ position-specific toolbar visibility specifier (e.g.
+ `top-toolbar-visible-p' if `default-toolbar-position' is `top')
+ does not specify a visible-p value in a particular domain (a
+ window or a frame), then the value of `default-toolbar-visible-p'
+ in that domain, if any, will be used instead.
+
+ - Specifier: top-toolbar-visible-p
+ This specifies whether the top toolbar is visible.
+
+ - Specifier: bottom-toolbar-visible-p
+ This specifies whether the bottom toolbar is visible.
+
+ - Specifier: left-toolbar-visible-p
+ This specifies whether the left toolbar is visible.
+
+ - Specifier: right-toolbar-visible-p
+ This specifies whether the right toolbar is visible.
+
+ `default-toolbar-visible-p' and all of the position-specific toolbar
+visibility specifiers have a fallback value of true.
+
+ Internally, toolbar thickness and visibility specifiers are
+instantiated in both window and frame domains, for different purposes.
+The value in the domain of a frame's selected window specifies the
+actual toolbar thickness or visibility that you will see in that frame.
+The value in the domain of a frame itself specifies the toolbar
+thickness or visibility that is used in frame geometry calculations.
+
+ Thus, for example, if you set the frame width to 80 characters and
+the left toolbar width for that frame to 68 pixels, then the frame will
+be sized to fit 80 characters plus a 68-pixel left toolbar. If you then
+set the left toolbar width to 0 for a particular buffer (or if that
+buffer does not specify a left toolbar or has a `nil' value specified
+for `left-toolbar-visible-p'), you will find that, when that buffer is
+displayed in the selected window, the window will have a width of 86 or
+87 characters--the frame is sized for a 68-pixel left toolbar but the
+selected window specifies that the left toolbar is not visible, so it is
+expanded to take up the slack.
+
+ - Specifier: toolbar-buttons-captioned-p
+ Whether toolbar buttons are captioned. This affects which glyphs
+ from a toolbar button descriptor are chosen. *Note Toolbar
+ Descriptor Format::.
+
+ You can also reset the toolbar to what it was when XEmacs started up.
+
+ - Constant: initial-toolbar-spec
+ The toolbar descriptor used to initialize `default-toolbar' at
+ startup.
+
+\1f
+File: lispref.info, Node: Gutter, Next: Scrollbars, Prev: Toolbar, Up: Top
+
+Gutter
+******
+
+A gutter is a rectangle displayed along one edge of a frame. It can
+contain arbitrary text or graphics.
+
+* Menu:
+
+* Gutter Intro:: An introduction.
+* Creating Gutter:: How to create a gutter.
+* Gutter Descriptor Format:: Accessing and modifying a gutter's
+ properties.
+* Specifying a Gutter:: Setting a gutter's contents.
+* Other Gutter Variables:: Controlling the size of gutters.
+* Common Gutter Widgets:: Things to put in gutters.
+
+\1f
+File: lispref.info, Node: Gutter Intro, Next: Creating Gutter, Prev: Gutter, Up: Gutter
+
+Gutter Intro
+============
+
+A "gutter" is a rectangle displayed along one edge of a frame. It can
+contain arbitrary text or graphics. It could be considered a
+generalization of a toolbar, although toolbars are not currently
+implemented using gutters.
+
+ In XEmacs, a gutter can be displayed along any of the four edges of
+the frame, and two or more different edges can be displaying gutters
+simultaneously. The contents, thickness, and visibility of the gutters
+can be controlled separately, and the values can be per-buffer,
+per-frame, etc., using specifiers (*note Specifiers::).
+
+ Normally, there is one gutter displayed in a frame. Usually, this is
+the default gutter, containing buffer tabs, but modes cab override this
+and substitute their own gutter. This default gutter is usually
+positioned along the top of the frame, but this can be changed using
+`set-default-gutter-position'.
+
+ Note that, for each of the gutter properties (contents, thickness,
+and visibility), there is a separate specifier for each of the four
+gutter positions (top, bottom, left, and right), and an additional
+specifier for the "default" gutter, i.e. the gutter whose position is
+controlled by `set-default-gutter-position'. The way this works is
+that `set-default-gutter-position' arranges things so that the
+appropriate position-specific specifiers for the default position
+inherit from the corresponding default specifiers. That way, if the
+position-specific specifier does not give a value (which it usually
+doesn't), then the value from the default specifier applies. If you
+want to control the default gutter, you just change the default
+specifiers, and everything works. A package such as VM that wants to
+put its own gutter in a different location from the default just sets
+the position-specific specifiers, and if the user sets the default
+gutter to the same position, it will just not be visible.
+
+\1f
+File: lispref.info, Node: Creating Gutter, Next: Gutter Descriptor Format, Prev: Gutter Intro, Up: Gutter
+
+Creating Gutter
+===============
+
+ - Function: make-gutter-specifier spec-list
+ Return a new `gutter' specifier object with the given specification
+ list. SPEC-LIST can be a list of specifications (each of which is
+ a cons of a locale and a list of instantiators), a single
+ instantiator, or a list of instantiators. *Note Specifiers::, for
+ more information about specifiers.
+
+ Gutter specifiers are used to specify the format of a gutter. The
+ values of the variables `default-gutter', `top-gutter',
+ `left-gutter', `right-gutter', and `bottom-gutter' are always
+ gutter specifiers.
+
+ Valid gutter instantiators are called "gutter descriptors" and are
+ either strings or property-lists of strings. See `default-gutter'
+ for a description of the exact format.
+
+ - Function: make-gutter-size-specifier spec-list
+ Return a new `gutter-size' specifier object with the given spec
+ list. SPEC-LIST can be a list of specifications (each of which is
+ a cons of a locale and a list of instantiators), a single
+ instantiator, or a list of instantiators. *Note Specifiers::, for
+ more information about specifiers.
+
+ Gutter-size specifiers are used to specify the size of a gutter.
+ The values of the variables `default-gutter-size',
+ `top-gutter-size', `left-gutter-size', `right-gutter-size', and
+ `bottom-gutter-size' are always gutter-size specifiers.
+
+ Valid gutter-size instantiators are either integers or the special
+ symbol `autodetect'. If a gutter-size is set to `autodetect' them
+ the size of the gutter will be adjusted to just accommodate the
+ gutters contents. `autodetect' only works for top and bottom
+ gutters.
+
+ - Function: make-gutter-visible-specifier spec-list
+ Return a new `gutter-visible' specifier object with the given spec
+ list. SPEC-LIST can be a list of specifications (each of which is
+ a cons of a locale and a list of instantiators), a single
+ instantiator, or a list of instantiators. *Note Specifiers::, for
+ more information about specifiers.
+
+ Gutter-visible specifiers are used to specify the visibility of a
+ gutter. The values of the variables `default-gutter-visible-p',
+ `top-gutter-visible-p', `left-gutter-visible-p',
+ `right-gutter-visible-p', and `bottom-gutter-visible-p' are always
+ gutter-visible specifiers.
+
+ Valid gutter-visible instantiators are `t', `nil' or a list of
+ symbols. If a gutter-visible instantiator is set to a list of
+ symbols, and the corresponding gutter specification is a
+ property-list strings, then elements of the gutter specification
+ will only be visible if the corresponding symbol occurs in the
+ gutter-visible instantiator.
+
+\1f
+File: lispref.info, Node: Gutter Descriptor Format, Next: Specifying a Gutter, Prev: Creating Gutter, Up: Gutter
+
+Gutter Descriptor Format
+========================
+
+The contents of a gutter are specified using a "gutter descriptor".
+The format of a gutter descriptor is a list of "gutter button
+descriptors". Each gutter button descriptor is a vector in one of the
+following formats:
+
+ * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
+
+ * `[:style 2D-OR-3D]'
+
+ * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
+
+ * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
+
+ Optionally, one of the gutter button descriptors may be `nil'
+instead of a vector; this signifies the division between the gutter
+buttons that are to be displayed flush-left, and the buttons to be
+displayed flush-right.
+
+ The first vector format above specifies a normal gutter button; the
+others specify blank areas in the gutter.
+
+ For the first vector format:
+
+ * GLYPH-LIST should be a list of one to six glyphs (as created by
+ `make-glyph') or a symbol whose value is such a list. The first
+ glyph, which must be provided, is the glyph used to display the
+ gutter button when it is in the "up" (not pressed) state. The
+ optional second glyph is for displaying the button when it is in
+ the "down" (pressed) state. The optional third glyph is for when
+ the button is disabled. The last three glyphs are for displaying
+ the button in the "up", "down", and "disabled" states,
+ respectively, but are used when the user has called for captioned
+ gutter buttons (using `gutter-buttons-captioned-p'). The function
+ `gutter-make-button-list' is useful in creating these glyph lists.
+
+ * Even if you do not provide separate down-state and disabled-state
+ glyphs, the user will still get visual feedback to indicate which
+ state the button is in. Buttons in the up-state are displayed
+ with a shadowed border that gives a raised appearance to the
+ button. Buttons in the down-state are displayed with shadows that
+ give a recessed appearance. Buttons in the disabled state are
+ displayed with no shadows, giving a 2-d effect.
+
+ * If some of the gutter glyphs are not provided, they inherit as
+ follows:
+
+ UP: up
+ DOWN: down -> up
+ DISABLED: disabled -> up
+ CAP-UP: cap-up -> up
+ CAP-DOWN: cap-down -> cap-up -> down -> up
+ CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
+
+ * The second element FUNCTION is a function to be called when the
+ gutter button is activated (i.e. when the mouse is released over
+ the gutter button, if the press occurred in the gutter). It can
+ be any form accepted by `call-interactively', since this is how it
+ is invoked.
+
+ * The third element ENABLED-P specifies whether the gutter button is
+ enabled (disabled buttons do nothing when they are activated, and
+ are displayed differently; see above). It should be either a
+ boolean or a form that evaluates to a boolean.
+
+ * The fourth element HELP, if non-`nil', should be a string. This
+ string is displayed in the echo area when the mouse passes over the
+ gutter button.
+
+ For the other vector formats (specifying blank areas of the gutter):
+
+ * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
+ whether the area is displayed with shadows (giving it a raised,
+ 3-d appearance) or without shadows (giving it a flat appearance).
+
+ * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
+ area. If omitted, it defaults to a device-specific value (8
+ pixels for X devices).
+
+ - Function: gutter-make-button-list up &optional down disabled cap-up
+ cap-down cap-disabled
+ This function calls `make-glyph' on each arg and returns a list of
+ the results. This is useful for setting the first argument of a
+ gutter button descriptor (typically, the result of this function
+ is assigned to a symbol, which is specified as the first argument
+ of the gutter button descriptor).
+
+ - Function: check-gutter-button-syntax button &optional noerror
+ Verify the syntax of entry BUTTON in a gutter description list.
+ If you want to verify the syntax of a gutter description list as a
+ whole, use `check-valid-instantiator' with a specifier type of
+ `gutter'.
+
+\1f
+File: lispref.info, Node: Specifying a Gutter, Next: Other Gutter Variables, Prev: Gutter Descriptor Format, Up: Gutter
+
+Specifying a Gutter
+===================
+
+In order to specify the contents of a gutter, set one of the specifier
+variables `default-gutter', `top-gutter', `bottom-gutter',
+`left-gutter', or `right-gutter'. These are specifiers, which means
+you set them with `set-specifier' and query them with `specifier-specs'
+or `specifier-instance'. You will get an error if you try to set them
+using `setq'. The valid instantiators for these specifiers are gutter
+descriptors, as described above. *Note Specifiers::, for more
+information.
+
+ Most of the time, you will set `default-gutter', which allows the
+user to choose where the gutter should go.
+
+ - Specifier: default-gutter
+ The position of this gutter is specified in the function
+ `default-gutter-position'. If the corresponding position-specific
+ gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
+ does not specify a gutter in a particular domain, then the value
+ of `default-gutter' in that domain, of any, will be used instead.
+
+ Note that the gutter at any particular position will not be displayed
+unless its thickness (width or height, depending on orientation) is
+non-zero and its visibility status is true. The thickness is controlled
+by the specifiers `top-gutter-height', `bottom-gutter-height',
+`left-gutter-width', and `right-gutter-width', and the visibility
+status is controlled by the specifiers `top-gutter-visible-p',
+`bottom-gutter-visible-p', `left-gutter-visible-p', and
+`right-gutter-visible-p' (*note Other Gutter Variables::).
+
+ - Function: set-default-gutter-position position
+ This function sets the position that the `default-gutter' will be
+ displayed at. Valid positions are the symbols `top', `bottom',
+ `left' and `right'. What this actually does is set the fallback
+ specifier for the position-specific specifier corresponding to the
+ given position to `default-gutter', and set the fallbacks for the
+ other position-specific specifiers to `nil'. It also does the
+ same thing for the position-specific thickness and visibility
+ specifiers, which inherit from one of `default-gutter-height' or
+ `default-gutter-width', and from `default-gutter-visible-p',
+ respectively (*note Other Gutter Variables::).
+
+ - Function: default-gutter-position
+ This function returns the position that the `default-gutter' will
+ be displayed at.
+
+ You can also explicitly set a gutter at a particular position. When
+redisplay determines what to display at a particular position in a
+particular domain (i.e. window), it first consults the position-specific
+gutter. If that does not yield a gutter descriptor, the
+`default-gutter' is consulted if `default-gutter-position' indicates
+this position.
+
+ - Specifier: top-gutter
+ Specifier for the gutter at the top of the frame.
+
+ - Specifier: bottom-gutter
+ Specifier for the gutter at the bottom of the frame.
+
+ - Specifier: left-gutter
+ Specifier for the gutter at the left edge of the frame.
+
+ - Specifier: right-gutter
+ Specifier for the gutter at the right edge of the frame.
+
+ - Function: gutter-specifier-p object
+ This function returns non-`nil' if OBJECT is a gutter specifier.
+ Gutter specifiers are the actual objects contained in the gutter
+ variables described above, and their valid instantiators are
+ gutter descriptors (*note Gutter Descriptor Format::).
+
+\1f
+File: lispref.info, Node: Other Gutter Variables, Next: Common Gutter Widgets, Prev: Specifying a Gutter, Up: Gutter
+
+Other Gutter Variables
+======================
+
+The variables to control the gutter thickness, visibility status, and
+captioned status are all specifiers. *Note Specifiers::.
+
+ - Specifier: default-gutter-height
+ This specifies the height of the default gutter, if it's oriented
+ horizontally. The position of the default gutter is specified by
+ the function `set-default-gutter-position'. If the corresponding
+ position-specific gutter thickness specifier (e.g.
+ `top-gutter-height' if `default-gutter-position' is `top') does
+ not specify a thickness in a particular domain (a window or a
+ frame), then the value of `default-gutter-height' or
+ `default-gutter-width' (depending on the gutter orientation) in
+ that domain, if any, will be used instead.
+
+ - Specifier: default-gutter-width
+ This specifies the width of the default gutter, if it's oriented
+ vertically. This behaves like `default-gutter-height'.
+
+ Note that `default-gutter-height' is only used when
+`default-gutter-position' is `top' or `bottom', and
+`default-gutter-width' is only used when `default-gutter-position' is
+`left' or `right'.
+
+ - Specifier: top-gutter-height
+ This specifies the height of the top gutter.
+
+ - Specifier: bottom-gutter-height
+ This specifies the height of the bottom gutter.
+
+ - Specifier: left-gutter-width
+ This specifies the width of the left gutter.
+
+ - Specifier: right-gutter-width
+ This specifies the width of the right gutter.
+
+ Note that all of the position-specific gutter thickness specifiers
+have a fallback value of zero when they do not correspond to the
+default gutter. Therefore, you will have to set a non-zero thickness
+value if you want a position-specific gutter to be displayed.
+
+ - Specifier: default-gutter-visible-p
+ This specifies whether the default gutter is visible. The
+ position of the default gutter is specified by the function
+ `set-default-gutter-position'. If the corresponding
+ position-specific gutter visibility specifier (e.g.
+ `top-gutter-visible-p' if `default-gutter-position' is `top') does
+ not specify a visible-p value in a particular domain (a window or
+ a frame), then the value of `default-gutter-visible-p' in that
+ domain, if any, will be used instead.
+
+ - Specifier: top-gutter-visible-p
+ This specifies whether the top gutter is visible.
+
+ - Specifier: bottom-gutter-visible-p
+ This specifies whether the bottom gutter is visible.
+
+ - Specifier: left-gutter-visible-p
+ This specifies whether the left gutter is visible.
+
+ - Specifier: right-gutter-visible-p
+ This specifies whether the right gutter is visible.
+
+ `default-gutter-visible-p' and all of the position-specific gutter
+visibility specifiers have a fallback value of true.
+
+ Internally, gutter thickness and visibility specifiers are
+instantiated in both window and frame domains, for different purposes.
+The value in the domain of a frame's selected window specifies the
+actual gutter thickness or visibility that you will see in that frame.
+The value in the domain of a frame itself specifies the gutter
+thickness or visibility that is used in frame geometry calculations.
+
+ Thus, for example, if you set the frame width to 80 characters and
+the left gutter width for that frame to 68 pixels, then the frame will
+be sized to fit 80 characters plus a 68-pixel left gutter. If you then
+set the left gutter width to 0 for a particular buffer (or if that
+buffer does not specify a left gutter or has a `nil' value specified for
+`left-gutter-visible-p'), you will find that, when that buffer is
+displayed in the selected window, the window will have a width of 86 or
+87 characters - the frame is sized for a 68-pixel left gutter but the
+selected window specifies that the left gutter is not visible, so it is
+expanded to take up the slack.
+
+ - Specifier: gutter-buttons-captioned-p
+ Whether gutter buttons are captioned. This affects which glyphs
+ from a gutter button descriptor are chosen. *Note Gutter
+ Descriptor Format::.
+
+ You can also reset the gutter to what it was when XEmacs started up.
+
+ - Constant: initial-gutter-spec
+ The gutter descriptor used to initialize `default-gutter' at
+ startup.
+
+\1f
+File: lispref.info, Node: Common Gutter Widgets, Prev: Other Gutter Variables, Up: Gutter
+
+Common Gutter Widgets
+=====================
+
+A gutter can contain arbitrary text. So, for example, in an Info
+buffer you could put the title of the current node in the top gutter,
+and it would not scroll out of view in a long node. (This is an
+artificial example, since usually the node name is sufficiently
+descriptive, and Info puts that in the mode line.)
+
+ A more common use for the gutter is to hold some kind of active
+widget. The buffer-tab facility, available in all XEmacs frames,
+creates an array of file-folder-like tabs, which the user can click with
+the mouse to switch buffers. W3 uses a progress-bar widget in the
+bottom gutter to give a visual indication of the progress of
+time-consuming operations like downloading.
+
+* Menu:
+
+* Buffer Tabs:: Tabbed divider index metaphor for switching buffers.
+* Progress Bars:: Visual indication of operation progress.
+
+\1f
+File: lispref.info, Node: Buffer Tabs, Next: Progress Bars, Up: Common Gutter Widgets
+
+Buffer Tabs
+-----------
+
+Not documented yet.
+
+\1f
+File: lispref.info, Node: Progress Bars, Prev: Buffer Tabs, Up: Common Gutter Widgets
+
+Progress Bars
+-------------
+
+Not documented yet.
+
+\1f
+File: lispref.info, Node: Scrollbars, Next: Drag and Drop, Prev: Gutter, Up: Top
+
+Scrollbars
+**********
+
+Not yet documented.
+
+\1f
+File: lispref.info, Node: Drag and Drop, Next: Modes, Prev: Scrollbars, Up: Top
+
+Drag and Drop
+*************
+
+_WARNING_: the Drag'n'Drop API is still under development and the
+interface may change! The current implementation is considered
+experimental.
+
+ Drag'n'drop is a way to transfer information between multiple
+applications. To do this several GUIs define their own protocols.
+Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
+To catch all these protocols, XEmacs provides a generic API.
+
+ One prime idea behind the API is to use a data interface that is
+transparent for all systems. The author thinks that this is best
+archived by using URL and MIME data, cause any internet enabled system
+must support these for email already. XEmacs also already provides
+powerful interfaces to support these types of data (tm and w3).
+
+* Menu:
+
+* Supported Protocols:: Which low-level protocols are supported.
+* Drop Interface:: How XEmacs handles a drop from another application.
+* Drag Interface:: Calls to initiate a drag from XEmacs.
+
+\1f
+File: lispref.info, Node: Supported Protocols, Next: Drop Interface, Up: Drag and Drop