@c , Bugs and Todo List, Top, Top
-@node Edebug, Bugs and Todo List, Top, Top
+@node Edebug,, Compilation Errors, Debugging
@section Edebug
@cindex Edebug mode
In order to use Edebug to debug Lisp code, you must first
@dfn{instrument} the code. Instrumenting code inserts additional code
-into it, code which invokes Edebug at the proper places.
-
- Once a function is instrumented, any call to the function activates
-Edebug. This may or may not stop execution, depending on the Edebug
-execution mode in use. Some Edebug modes only update the display to
-indicate the progress of the evaluation without stopping execution.
+into it, to invoke Edebug at the proper places.
@kindex C-M-x
@findex eval-defun (Edebug)
@findex eval-expression (Edebug)
To remove instrumentation from a definition, simply reevaluate its
definition in a way that does not instrument. There are two ways of
-evaluating forms without instrumenting them: from a file with
+evaluating forms that never instrument them: from a file with
@code{load}, and from the minibuffer with @code{eval-expression}
(@kbd{M-ESC}).
@cindex Edebug execution modes
Edebug supports several execution modes for running the program you are
debugging. We call these alternatives @dfn{Edebug execution modes}; do
-not confuse them with major or minor modes. The current Edebug mode
+not confuse them with major or minor modes. The current Edebug execution mode
determines how far Edebug continues execution before stopping---whether
it stops at each stop point, or continues to the next breakpoint, for
example---and how much Edebug displays the progress of the evaluation
@end table
In general, the execution modes earlier in the above list run the
-program more slowly or stop sooner.
+program more slowly or stop sooner than the modes later in the list.
While executing or tracing, you can interrupt the execution by typing
any Edebug command. Edebug stops the program at the next stop point and
-then executes the command that you typed. For example, typing @kbd{t}
-during execution switches to trace mode at the next stop point. You can
-use @kbd{S} to stop execution without doing anything else.
+then executes the command you typed. For example, typing @kbd{t} during
+execution switches to trace mode at the next stop point. You can use
+@kbd{S} to stop execution without doing anything else.
If your function happens to read input, a character you type intending
to interrupt execution may be read by the function instead. You can
The @kbd{o} command continues ``out of'' an expression. It places a
temporary breakpoint at the end of the sexp containing point. If the
-containing sexp is a function definition itself, it continues until just
-before the last sexp in the definition. If that is where you are now,
-it returns from the function and then stops. In other words, this
+containing sexp is a function definition itself, @kbd{o} continues until
+just before the last sexp in the definition. If that is where you are
+now, it returns from the function and then stops. In other words, this
command does not exit the currently executing function unless you are
positioned after the last sexp.
The @kbd{i} command steps into the function or macro called by the list
-form after point. Note that the form need not be the one about to be
-evaluated. But if the form is a function call about to be evaluated,
-remember to use this command before any of the arguments are evaluated,
-since otherwise it will be too late.
+form after point, and stops at its first stop point. Note that the form
+need not be the one about to be evaluated. But if the form is a
+function call about to be evaluated, remember to use this command before
+any of the arguments are evaluated, since otherwise it will be too late.
The @kbd{i} command instruments the function or macro it's supposed to
step into, if it isn't instrumented already. This is convenient, but keep
execution.
@end table
->From the Edebug recursive edit, you may invoke commands that activate
+From the Edebug recursive edit, you may invoke commands that activate
Edebug again recursively. Any time Edebug is active, you can quit to
the top level with @kbd{q} or abort one recursive edit level with
@kbd{C-]}. You can display a backtrace of all the
mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
To find out where your breakpoints are, use the @kbd{B} command, which
-moves point to the next breakpoint in the definition following point, or
-to the first breakpoint if there are no following breakpoints. This
-command does not continue execution---it just moves point in the buffer.
+moves point to the next breakpoint following point, within the same
+function, or to the first breakpoint if there are no following
+breakpoints. This command does not continue execution---it just moves
+point in the buffer.
@menu
* Global Break Condition:: Breaking on an event.
might be quite distant from the offending variable reference. In that
case you might want to display a full backtrace (@pxref{Edebug Misc}).
+@c Edebug should be changed for the following: -- dan
If you change @code{debug-on-error} or @code{debug-on-quit} while
Edebug is active, these changes will be forgotten when Edebug becomes
inactive. Furthermore, during Edebug's recursive edit, these variables
are bound to the values they had outside of Edebug.
-@ignore @c I don't want to document something that works only partly -- rms.
-Edebug can also trap signals even if they are handled. If
-@code{debug-on-error} is a list of signal names, Edebug will stop when
-any of these errors are signaled. Edebug shows you the last known stop
-point just as for unhandled errors. After you continue execution, the
-error is signaled again (but without being caught by Edebug). Edebug
-can only trap errors that are handled if they are signaled in Lisp code
-(not subroutines) since it does so by temporarily replacing the
-@code{signal} function.
-@end ignore
-
@node Edebug Views
@subsection Edebug Views
These Edebug commands let you view aspects of the buffer and window
-status that obtained before entry to Edebug.
+status that obtained before entry to Edebug. The outside window
+configuration is the collection of windows and contents that were in
+effect outside of Edebug.
@table @kbd
@item v
-View the outside window configuration (@code{edebug-view-outside}).
+Temporarily view the outside window configuration
+(@code{edebug-view-outside}).
@item p
Temporarily display the outside current buffer with point at its outside
the current definition in the future.
@item W
-Forget the saved outside window configuration---so that the current
-window configuration will remain unchanged when you next exit Edebug (by
-continuing the program). Also toggle the @code{edebug-save-windows}
-variable.
-@ignore @c This text is implementation-oriented and doesn't emphasize
- what users really want to know.
-Toggle the @code{edebug-save-windows} variable which indicates whether
-the outside window configuration is saved and restored
-(@code{edebug-toggle-save-windows}). Also, each time it is toggled on,
-make the outside window configuration the same as the current window
-configuration.
-@end ignore
+@c Its function is not simply to forget the saved configuration -- dan
+Toggle whether Edebug saves and restores the outside window
+configuration (@code{edebug-toggle-save-windows}).
+
+With a prefix argument, @code{W} only toggles saving and restoring of
+the selected window. To specify a window that is not displaying the
+source code buffer, you must use @kbd{C-x X W} from the global keymap.
@end table
You can view the outside window configuration with @kbd{v} or just
it is not normally displayed. After moving point, you may wish to jump
back to the stop point with @kbd{w} from a source code buffer.
-@ignore I don't understand this -- rms
-If you type @kbd{W} twice, Edebug continues saving and restoring an
-outside window configuration, but updates it to match the current
-configuration. You can use this to add another buffer to be displayed
-whenever Edebug is active. However, the automatic redisplay of
-@samp{*edebug*} and @samp{*edebug-trace*} may conflict with the buffers
-you wish to see unless you have enough windows open.
-
-With a prefix argument, @code{W} only toggles saving and restoring of
-the selected window. To specify a window that is not displaying the
-source code buffer, you must use @kbd{C-x X W} from the global keymap.
-@end ignore
+Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
+saved outside window configuration---so that even if you turn saving
+back @emph{on}, the current window configuration remains unchanged when
+you next exit Edebug (by continuing the program). However, the
+automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may
+conflict with the buffers you wish to see unless you have enough windows
+open.
@node Edebug Eval
@subsection Evaluation
(@code{edebug-eval-last-sexp}).
@item C-c C-u
-Build a new evaluation list from contents of the buffer
+Build a new evaluation list from the contents of the buffer
(@code{edebug-update-eval-list}).
@item C-c C-d
The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
evaluation list, scanning the buffer and using the first expression of
-each group.
+each group. (The idea is that the second expression of the group is the
+value previously computed and displayed.)
Be careful not to add expressions that execute instrumented code since
that would cause an infinite loop.
@c There ought to be a way to fix this.
-Redisplaying the evaluation list works by inserting each expression in
-the buffer, followed by its current value. It also inserts comment
-lines so that each expression becomes its own group. Thus, if you type
-@kbd{C-c C-u} again without changing the buffer text, the evaluation
-list is effectively unchanged.
+Each entry to Edebug redisplays the evaluation list by inserting each
+expression in the buffer, followed by its current value. It also
+inserts comment lines so that each expression becomes its own group.
+Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
+the evaluation list is effectively unchanged.
If an error occurs during an evaluation from the evaluation list, the
error message is displayed in a string as if it were the result.
@subsection Trace Buffer
@cindex trace buffer
- Edebug can record an execution trace in a buffer named
+ Edebug can record an execution trace, storing it in a buffer named
@samp{*edebug-trace*}. This is a log of function calls and returns,
showing the function names and their arguments and values. To enable
trace recording, set @code{edebug-trace} to a non-@code{nil} value.
@defun edebug-trace format-string &rest format-args
This function inserts text in the trace buffer. It computes the text
with @code{(apply 'format @var{format-string} @var{format-args})}.
-It also inserts a newline to separate entries.
+It also appends a newline to separate entries.
@end defun
@code{edebug-tracing} and @code{edebug-trace} insert lines in the trace
Adding text to the trace buffer also scrolls its window to show the
last lines inserted.
-@ignore @c too vague
-There may be some display problems if you use
-tracing along with the evaluation list.
-@end ignore
-
@node Coverage Testing
@subsection Coverage Testing
This command displays the frequency count data for each line of the
current definition.
-The frequency counts appear comment lines after each line of code, and
+The frequency counts appear as comment lines after each line of code, and
you can undo all insertions with one @code{undo} command. The counts
-are appear under the @kbd{(} before an expression or the @kbd{)} after
+appear under the @kbd{(} before an expression or the @kbd{)} after
an expression, or on the last character of a symbol. Values do not appear if
they are equal to the previous count on the same line.
;# 0
@end example
-The comment lines show that @code{fac} has been called 6 times. The
-first @code{if} statement has returned 5 times with the same result each
+The comment lines show that @code{fac} was called 6 times. The
+first @code{if} statement returned 5 times with the same result each
time; the same is true of the condition on the second @code{if}.
-The recursive call of @code{fac} has not returned at all.
+The recursive call of @code{fac} did not return at all.
@node The Outside Context
explains precisely what context Edebug restores, and how Edebug fails to
be completely transparent.
-@c This can be fixed and should be
-The same mechanism that avoids masking certain variable's outside values
-also currently makes it impossible to set these variables within Edebug.
-
@menu
* Checking Whether to Stop:: When Edebug decides what to do.
* Edebug Display Update:: When Edebug updates the display.
@node Checking Whether to Stop
@subsubsection Checking Whether to Stop
-Whenever Edebug is entered just to think about whether to take some
-action, it needs to save and restore certain data.
+Whenever Edebug is entered, it needs to save and restore certain data
+before even deciding whether to make trace information or stop the
+program.
@itemize @bullet
@item
@node Edebug Display Update
@subsubsection Edebug Display Update
+@c This paragraph is not filled, because LaLiberte's conversion script
+@c needs an xref to be on just one line.
When Edebug needs to display something (e.g., in trace mode), it saves
-the current window configuration from ``outside'' Edebug (@pxref{Window
-Configurations,,, elisp, GNU Emacs Lisp Reference Manual}). When
-you exit Edebug (by continuing the program), it restores the previous
-window configuration.
+the current window configuration from ``outside'' Edebug
+(@pxref{Window Configurations}). When you exit Edebug (by continuing
+the program), it restores the previous window configuration.
Emacs redisplays only when it pauses. Usually, when you continue
execution, the program comes back into Edebug at a breakpoint or after
not restored, however, so that the display remains coherent within Edebug.
@item
-@vindex edebug-save-displayed-buffer-points
The value of point in each displayed buffer is saved and restored if
@code{edebug-save-displayed-buffer-points} is non-@code{nil}.
executing commands within Edebug and there is no way to reset
the key sequence from Lisp.
+Edebug cannot save and restore the value of
+@code{unread-command-events}. Entering Edebug while this variable has a
+nontrivial value can interfere with execution of the program you are
+debugging.
+
@item
Complex commands executed while in Edebug are added to the variable
@code{command-history}. In rare cases this can alter execution.
evaluated. (Evaluation may occur explicitly in the macro body, or when
the resulting expansion is evaluated, or any time later.) You must
explain the format of calls to each macro to enable Edebug to handle it.
-To do this, use @code{def-edebug-form-spec} to define the format of
+To do this, use @code{def-edebug-spec} to define the format of
calls to a given macro.
@deffn Macro def-edebug-spec macro specification
@menu
* Specification List:: How to specify complex patterns of evaluation.
* Backtracking:: What Edebug does when matching fails.
-@c * Debugging Backquote:: Debugging Backquote
* Specification Examples:: To help understand specifications.
@end menu
@table @code
@item sexp
-A single unevaluated Lisp object object.
+A single Lisp object, not unevaluated.
+@c "unevaluated expression" is not meaningful, because
+@c an expression is a Lisp object intended for evaluation.
@item form
A single evaluated expression, which is instrumented.
with the argument and the specification fails if the predicate returns
@code{nil}. In either case, that argument is not instrumented.
-@findex keywordp
-@findex lambda-list-keywordp
Some suitable predicates include @code{symbolp}, @code{integerp},
@code{stringp}, @code{vectorp}, and @code{atom}.
-@ignore
-, @code{keywordp}, and
-@code{lambda-list-keywordp}. The last two, defined in @file{edebug.el},
-test whether the argument is a symbol starting with @samp{@code{:}} and
-@samp{@code{&}} respectively.
-@end ignore
@item [@var{elements}@dots{}]
@cindex [@dots{}] (Edebug)
is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name
of @var{symbol} is the @var{string}, but the string form is preferred.
-@ignore
-@item '@var{symbol} @r{or} (quote @var{symbol})
-The argument should be the symbol @var{symbol}. But use a string
-specification instead.
-@end ignore
-
@item (vector @var{elements}@dots{})
The argument should be a vector whose elements must match the
@var{elements} in the specification. See the backquote example below.
example below. Also see the description of a @code{nil} specification
above for terminating such recursion.
-Note that a sublist specification of the form @code{(specs . nil)}
-means the same as @code{(specs)}, and @code{(specs .
-(sublist-elements@dots{}))} means the same as @code{(specs
+Note that a sublist specification written as @code{(specs . nil)}
+is equivalent to @code{(specs)}, and @code{(specs .
+(sublist-elements@dots{}))} is equivalent to @code{(specs
sublist-elements@dots{})}.
@end table
@item arg
The argument, a symbol, is the name of an argument of the defining form.
However, lambda list keywords (symbols starting with @samp{@code{&}})
-are not allowed. See @code{lambda-list} and the example below.
+are not allowed.
@item lambda-list
@cindex lambda-list (Edebug)
This matches a lambda list---the argument list of a lambda expression.
-The argument should be a list of symbols.
@item def-body
The argument is the body of code in a definition. This is like
@code{gate} specification. This is useful when you know that
no higher alternatives may apply.
-@ignore
-@node Debugging Backquote
-@subsubsection Debugging Backquote
-
-@findex ` (Edebug)
-@cindex backquote (Edebug)
-Backquote (@kbd{`}) is a macro that results in an expression that may or
-may not be evaluated. It is often used to simplify the definition of a
-macro to return an expression to be evaluated, but Edebug cannot know
-whether the resyult of backquote will be used in any other way.
-
-The forms inside unquotes (@code{,} and @code{,@@}) are evaluated, and
-Edebug instruments them.
-
-Edebug supports nested backquotes, but there is a limit on the support
-of quotes inside of backquotes. Forms quoted with @code{'} are not
-normally evaluated, but if the quoted form appears immediately within
-@code{,} and @code{,@@} forms, Edebug treats this as a backquoted form
-at the next higher level (even if there is not a next higher level; this
-is difficult to fix).
-
-@findex edebug-`
-If the backquoted forms are code to be evaluated, you can have Edebug
-instrument them by using @code{edebug-`} instead of the regular
-@code{`}. Unquoting forms can be used inside @code{edebug-`} anywhere a
-form is normally allowed. But @code{(, @var{form})} may be used in two
-other places specially recognized by Edebug: wherever a predicate
-specification would match, and at the head of a list form where the
-function name normally appears. The @var{form} inside a spliced
-unquote, @code{(,@@ @var{form})}, will be instrumented, but the unquote
-form itself will not be instrumented since this would interfere with the
-splicing.
-
-There is one other complication with using @code{edebug-`}. If the
-@code{edebug-`} call is in a macro and the macro may be called from code
-that is also instrumented, and if unquoted forms contain any macro
-arguments bound to instrumented forms, then you should modify the
-specification for the macro as follows: the specifications for those
-arguments must use @code{def-form} instead of @code{form}. (This is to
-reestablish the Edebugging context for those external forms.)
-
-For example, the @code{for} macro (@pxref{Problems with Macros,,, elisp,
-Emacs Lisp Reference Manual}) is shown here but with @code{edebug-`}
-substituted for regular @code{`}.
-
-@example
-(defmacro inc (var)
- (list 'setq var (list '1+ var)))
-
-(defmacro for (var from init to final do &rest body)
- (let ((tempvar (make-symbol "max")))
- (edebug-` (let (((, var) (, init))
- ((, tempvar) (, final)))
- (while (<= (, var) (, tempvar))
- (,@ body)
- (inc (, var)))))))
-@end example
-
-Here is the corresponding modified Edebug specification and a
-call of the macro:
-
-@example
-(def-edebug-spec for
- (symbolp "from" def-form "to" def-form "do" &rest def-form))
-
-(let ((n 5))
- (for i from n to (* n (+ n 1)) do
- (message "%s" i)))
-@end example
-
-After instrumenting the @code{for} macro and the macro call, Edebug
-first steps to the beginning of the macro call, then into the macro
-body, then through each of the unquoted expressions in the backquote
-showing the expressions that will be embedded. Then when the macro
-expansion is evaluated, Edebug will step through the @code{let} form and
-each time it gets to an unquoted form, it will jump back to an argument
-of the macro call to step through that expression. Finally stepping
-will continue after the macro call. Even more convoluted execution
-paths may result when using anonymous functions.
-
-@vindex edebug-unwrap-results
-When the result of an expression is an instrumented expression, it is
-difficult to see the expression inside the instrumentation. So
-you may want to set the option @code{edebug-unwrap-results} to a
-non-@code{nil} value while debugging such expressions, but it would slow
-Edebug down to always do this.
-
-@end ignore
@node Specification Examples
@subsubsection Specification Examples
since an expression argument it is actually evaluated outside of the
function body.
-@example
-(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec}
+@smallexample
+(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec.}
(def-edebug-spec defun
(&define name lambda-list
- [&optional stringp] ; @r{Match the doc string, if present.}
+ [&optional stringp] ; @r{Match the doc string, if present.}
[&optional ("interactive" interactive)]
def-body))
(def-edebug-spec interactive
(&optional &or stringp def-form)) ; @r{Notice: @code{def-form}}
-@end example
+@end smallexample
The specification for backquote below illustrates how to match
dotted lists and use @code{nil} to terminate recursion. It also
specification defined by Edebug does not support dotted lists because
doing so causes very deep recursion that could fail.)
-@example
-(def-edebug-spec ` (backquote-form)) ;; alias just for clarity
+@smallexample
+(def-edebug-spec ` (backquote-form)) ; @r{Alias just for clarity.}
(def-edebug-spec backquote-form
(&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
(backquote-form . [&or nil backquote-form])
(vector &rest backquote-form)
sexp))
-@end example
+@end smallexample
@node Edebug Options
@defopt edebug-all-defs
If this is non-@code{nil}, normal evaluation of defining forms such as
@code{defun} and @code{defmacro} instruments them for Edebug. This
-applies to @code{eval-defun}, @code{eval-region}, and
-@code{eval-current-buffer}. @xref{Instrumenting}.
+applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer},
+and @code{eval-current-buffer}.
+
+Use the command @kbd{M-x edebug-all-defs} to toggle the value of this
+option. @xref{Instrumenting}.
@end defopt
@defopt edebug-all-forms
-If this is non-@code{nil}, the commands @code{eval-defun}, @code{eval-region},
-and @code{eval-current-buffer} instrument all forms, even those that
-don't define anything.
+If this is non-@code{nil}, the commands @code{eval-defun},
+@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer}
+instrument all forms, even those that don't define anything.
+This doesn't apply to loading or evaluations in the minibuffer.
Use the command @kbd{M-x edebug-all-forms} to toggle the value of this
-option.
-@xref{Instrumenting}.
+option. @xref{Instrumenting}.
@end defopt
@defopt edebug-save-windows
@end defopt
@defopt edebug-save-displayed-buffer-points
-If non-@code{nil}, Edebug saves and restores point in all buffers.
+If this is non-@code{nil}, Edebug saves and restores point in all
+displayed buffers.
Saving and restoring point in other buffers is necessary if you are
debugging code that changes the point of a buffer which is displayed in
a non-selected window. If Edebug or the user then selects the window,
-the buffer's point will change to the window's point.
+point in that buffer will move to the window's value of point.
Saving and restoring point in all buffers is expensive, since it
requires selecting each window twice, so enable this only if you need
The default value is @code{nil}.
-Also see @code{edebug-tracing}.
-@xref{Tracing}.
+Also see @code{edebug-tracing}, in @xref{Trace Buffer}.
@end defopt
@defopt edebug-test-coverage
If you change the values of @code{edebug-on-error} or
@code{edebug-on-quit} while Edebug is active, their values won't be used
-until the @emph{next} time Edebug is invoked at a deeper command level.
-
-@ignore
-@defopt edebug-unwrap-results
-Non-@code{nil} if Edebug should unwrap results of expressions. This is
-useful when debugging macros where the results of expressions are
-instrumented expressions. But don't do this when results might be
-circular, or an infinite loop will result. @xref{Debugging Backquote}.
-@end defopt
-@end ignore
+until the @emph{next} time Edebug is invoked via a new command.
+@c Not necessarily a deeper command level.
+@c A new command is not precisely true, but that is close enough -- dan
@defopt edebug-global-break-condition
If non-@code{nil}, an expression to test for at every stop point.
If the result is non-nil, then break. Errors are ignored.
@xref{Global Break Condition}.
@end defopt
-
* Inheritance and Keymaps:: How one keymap can inherit the bindings
of another keymap.
* Prefix Keys:: Defining a key with a keymap as its definition.
-* Menu Keymaps:: A keymap can define a menu.
* Active Keymaps:: Each buffer has a local keymap
to override the standard (global) bindings.
A minor mode can also override them.
* 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.
+* Menu Keymaps:: A keymap can define a menu.
@end menu
@node Keymap Terminology
If the binding of a key sequence is a keymap, we call the key sequence
a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
-no more characters can be added to it). If the binding is @code{nil},
+no more events can be added to it). If the binding is @code{nil},
we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c},
@kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are
@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete
use for finding key bindings. These are the @dfn{global map}, which is
shared by all buffers; the @dfn{local keymap}, which is usually
associated with a specific major mode; and zero or more @dfn{minor mode
-keymaps} which belong to currently enabled minor modes. (Not all minor
+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. @xref{Active Keymaps},
Use the function @code{keymapp} (see below) to test whether an object is
a keymap.
- An ordinary element is a cons cell of the form @code{(@var{type} .@:
-@var{binding})}. This specifies one binding which applies to events of
-type @var{type}. Each ordinary binding applies to events of a
-particular @dfn{event type}, which is always a character or a symbol.
-@xref{Classifying Events}.
+ Each ordinary binding applies to events of a particular @dfn{event
+type}, which is always a character or a symbol. @xref{Classifying
+Events}.
+
+ An ordinary element of a keymap is a cons cell of the form
+@code{(@var{type} .@: @var{binding})}. This specifies one binding, for
+events of type @var{type}.
@cindex default key binding
@c Emacs 19 feature
If an element of a keymap is a vector, the vector counts as bindings
for all the @sc{ASCII} characters; vector element @var{n} is the binding
-for the character with code @var{n}. This is a more compact way to
+for the character with code @var{n}. This is a compact way to
record lots of bindings. A keymap with such a vector is called a
@dfn{full keymap}. Other keymaps are called @dfn{sparse keymaps}.
@defun keymapp object
This function returns @code{t} if @var{object} is a keymap, @code{nil}
-otherwise. Practically speaking, this function tests for a list whose
+otherwise. More precisely, this function tests for a list whose
@sc{car} is @code{keymap}.
@example
Here we describe the functions for creating keymaps.
@defun make-keymap &optional prompt
-This function creates and returns a new full keymap (i.e., one which
-contains a vector of length 128 for defining all the @sc{ASCII}
+This function creates and returns a new full keymap (i.e., one
+containing a vector of length 128 for defining all the @sc{ASCII}
characters). The new keymap initially binds all @sc{ASCII} characters
to @code{nil}, and does not bind any other kind of event.
@end defun
@defun copy-keymap keymap
-This function returns a copy of @var{keymap}. Any keymaps which
+This function returns a copy of @var{keymap}. Any keymaps that
appear directly as bindings in @var{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
@section Prefix Keys
@cindex prefix key
- A @dfn{prefix key} has an associated keymap which defines what to do
+ A @dfn{prefix key} has an associated keymap that defines what to do
with key sequences that start with the prefix key. For example,
-@kbd{C-x} is a prefix key, and it uses a keymap which is also stored in
+@kbd{C-x} is a prefix key, and it uses a keymap that is also stored in
the variable @code{ctl-x-map}. Here is a list of the standard prefix
keys of Emacs and their keymaps:
@cindex @kbd{C-x}
@vindex ctl-x-map
@findex Control-X-prefix
-@code{ctl-x-map} is the variable name for the map used for events
-that follow @kbd{C-x}. This map is also the function definition of
-@code{Control-X-prefix}.
+@code{ctl-x-map} is the map used for events that follow @kbd{C-x}. This
+map is also the function definition of @code{Control-X-prefix}.
@item
@cindex @kbd{C-x 4}
@item
@cindex @kbd{C-x 5}
@vindex ctl-x-5-map
-@code{ctl-x-5-map} used is for events that follow @kbd{C-x 5}.
+@code{ctl-x-5-map} is used for events that follow @kbd{C-x 5}.
@c Emacs 19 feature
@item
keymap for @kbd{C-x} commands. (The same keymap is also the value of
@code{ctl-x-map}.)
- Prefix key definitions of this sort can appear in any active keymap.
-The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as
-prefix keys appear in the global map, so these prefix keys are always
+ Prefix key definitions can appear in any active keymap. The
+definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{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. @xref{Active Keymaps}.
@defun define-prefix-command symbol
@cindex prefix command
- This function defines @var{symbol} as a prefix command: it creates a
+This function defines @var{symbol} as a prefix command: it creates a
full keymap and stores it as @var{symbol}'s function definition.
Storing the symbol as the binding of a key makes the key a prefix key
-which has a name. It also sets @var{symbol} as a variable, to have the
-keymap as its value. The function returns @var{symbol}.
+that has a name. The function also sets @var{symbol} as a variable, to
+have the keymap as its value. It returns @var{symbol}.
In Emacs version 18, only the function definition of @var{symbol} was
set, not the value as a variable.
@end defun
-@node Menu Keymaps
-@section Menu Keymaps
-@cindex menu keymaps
+@node Active Keymaps
+@section Active Keymaps
+@cindex active keymap
+@cindex global keymap
+@cindex local keymap
-@c Emacs 19 feature
-A keymap can define a menu as well as bindings for keyboard keys and
-mouse button. Menus are usually actuated with the mouse, but they can
-work with the keyboard also.
+ Emacs normally contains many keymaps; at any given time, just a few of
+them are @dfn{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.
-@menu
-* Defining Menus:: How to make a keymap that defines a menu.
-* Mouse Menus:: How users actuate the menu with the mouse.
-* Keyboard Menus:: How they actuate it with the keyboard.
-* Menu Example:: Making a simple menu.
-* Menu Bar:: How to customize the menu bar.
-* Modifying Menus:: How to add new items to a menu.
-@end menu
+ The @dfn{global keymap} holds the bindings of keys that are defined
+regardless of the current buffer, such as @kbd{C-f}. The variable
+@code{global-map} holds this keymap, which is always active.
-@node Defining Menus
-@subsection Defining Menus
-@cindex defining menus
-@cindex menu prompt string
-@cindex prompt string (of menu)
+ Each buffer may have another keymap, its @dfn{local keymap}, which may
+contain new or overriding definitions for keys. The current buffer's
+local keymap is always active except when @code{overriding-local-map}
+overrides it. Text properties can specify an alternative local map for
+certain parts of the buffer; see @ref{Special Properties}.
-A keymap is suitable for menu use if it has an @dfn{overall prompt
-string}, which is a string that appears as an element of the keymap.
-(@xref{Format of Keymaps}.) The string should describe the purpose of
-the menu. The easiest way to construct a keymap with a prompt string is
-to specify the string as an argument when you call @code{make-keymap} or
-@code{make-sparse-keymap} (@pxref{Creating Keymaps}).
+ Each minor mode may have a keymap; if it does, the keymap is active
+when the minor mode is enabled.
-The individual bindings in the menu keymap should have item
-strings; these strings become the items displayed in the menu. A
-binding with a item string looks like this:
+ The variable @code{overriding-local-map}, if non-@code{nil}, specifies
+another local keymap that overrides the buffer's local map and all the
+minor mode keymaps.
-@example
-(@var{string} . @var{real-binding})
-@end example
+ All the active keymaps are used together to determine what command to
+execute when a key is entered. Emacs searches these maps one by one, in
+order of decreasing precedence, until it finds a binding in one of the maps.
-The item string for a binding should be short---one or two words. It
-should describe the action of the command it corresponds to.
+ Normally, Emacs @emph{first} searches for the key in the minor mode
+maps (one map at a time); if they do not supply a binding for the key,
+Emacs searches the local map; if that too has no binding, Emacs then
+searches the global map. However, if @code{overriding-local-map} is
+non-@code{nil}, Emacs searches that map first, followed by the global
+map.
-As far as @code{define-key} is concerned, @var{string} is part of the
-event's binding. However, @code{lookup-key} returns just
-@var{real-binding}, and only @var{real-binding} is used for executing
-the key.
+ The procedure for searching a single keymap is called
+@dfn{key lookup}; see @ref{Key Lookup}.
-You can also supply a second string, called the help string, as follows:
+@cindex major mode keymap
+ 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 @code{local-set-key}, for
+example) is seen also in the other buffers that share that keymap.
-@example
-(@var{string} @var{help-string} . @var{real-binding})
-@end example
+ 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 @code{lisp-mode-map},
+@code{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.
-Currently Emacs does not actually use @var{help-string}; it knows only
-how to ignore @var{help-string} in order to extract @var{real-binding}.
-In the future we hope to make @var{help-string} serve as extended
-documentation for the menu item, available on request.
+ The minibuffer has local keymaps, too; they contain various completion
+and exit commands. @xref{Intro to Minibuffers}.
-If @var{real-binding} is @code{nil}, then @var{string} appears in the
-menu but cannot be selected.
+ @xref{Standard Keymaps}, for a list of standard keymaps.
-If @var{real-binding} is a symbol, and has a non-@code{nil}
-@code{menu-enable} property, that property is an expression which
-controls whether the menu item is enabled. Every time the keymap is
-used to display a menu, Emacs evaluates the expression, and it enables
-the menu item only if the expression's value is non-@code{nil}. When a
-menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
-cannot be selected with the mouse.
+@defvar global-map
+This variable contains the default global keymap that maps Emacs
+keyboard input to commands. The global keymap is normally this keymap.
+The default global keymap is a full keymap that binds
+@code{self-insert-command} to all of the printing characters.
-The order of items in the menu is the same as the order of bindings in
-the keymap. Since @code{define-key} puts new bindings at the front, you
-should define the menu items starting at the bottom of the menu and
-moving to the top, if you care about the order. When you add an item to
-an existing menu, you can specify its position in the menu using
-@code{define-key-after} (@pxref{Modifying Menus}).
+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.
+@end defvar
-You've probably noticed that menu items show the equivalent keyboard key
-sequence (if any) to invoke the same command. To save time on
-recalculation, menu display caches this information in a sublist in the
-binding, like this:
+@defun current-global-map
+This function returns the current global keymap. This is the
+same as the value of @code{global-map} unless you change one or the
+other.
-@c This line is not too long--rms.
@example
-(@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
+@group
+(current-global-map)
+@result{} (keymap [set-mark-command beginning-of-line @dots{}
+ delete-backward-char])
+@end group
@end example
+@end defun
-Don't put these sublists in the menu item yourself; menu display
-calculates them automatically. Don't add keyboard equivalents to the
-item string yourself, for that is redundant.
-
-@node Mouse Menus
-@subsection Menus and the Mouse
-
-The way to make a menu keymap produce a menu is to make it the
-definition of a prefix key.
-
-If the prefix key ends with a mouse event, Emacs handles the menu keymap
-by popping up a visible menu, so that the user can select a choice with
-the mouse. When the user clicks on a menu item, the event generated is
-whatever character or symbol has the binding which brought about that
-menu item. (A menu item may generate a series of events if the menu has
-multiple levels or comes from the menu bar.)
+@defun current-local-map
+This function returns the current buffer's local keymap, or @code{nil}
+if it has none. In the following example, the keymap for the
+@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
+in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse
+keymap.
-It's often best to use a button-down event to trigger the menu. Then
-the user can select a menu item by releasing the button.
+@example
+@group
+(current-local-map)
+@result{} (keymap
+ (10 . eval-print-last-sexp)
+ (9 . lisp-indent-line)
+ (127 . backward-delete-char-untabify)
+@end group
+@group
+ (27 keymap
+ (24 . eval-defun)
+ (17 . indent-sexp)))
+@end group
+@end example
+@end defun
-A single keymap can appear as multiple menu panes, if you explicitly
-arrange for this. The way to do this is to make a keymap for each pane,
-then create a binding for each of those maps in the main keymap of the
-menu. Give each of these bindings a item string that starts with
-@samp{@@}. The rest of the item string becomes the name of the pane.
-See the file @file{lisp/mouse.el} for an example of this. Any ordinary
-bindings with @samp{@@}-less item strings are grouped into one pane,
-which appears along with the other panes explicitly created for the
-submaps.
+@defun current-minor-mode-maps
+This function returns a list of the keymaps of currently enabled minor modes.
+@end defun
-X toolkit menus don't have panes; instead, they can have submenus.
-Every nested keymap becomes a submenu, whether the item string starts
-with @samp{@@} or not. In a toolkit version of Emacs, The only thing
-special about @samp{@@} at the beginning of an item string is that the
-@samp{@@} doesn't appear in the menu item.
+@defun use-global-map keymap
+This function makes @var{keymap} the new current global keymap. It
+returns @code{nil}.
-You can also get multiple panes from separate keymaps. The full
-definition of a prefix key always comes from merging the definitions
-supplied by the various active keymaps (minor mode, local, and
-global). When more than one of these keymaps is a menu, each of them
-makes a separate pane or panes. @xref{Active Keymaps}.
+It is very unusual to change the global keymap.
+@end defun
-In toolkit versions of Emacs, menus don't have panes, so submenus are
-used to represent the separate keymaps. Each keymap's contribution
-becomes one submenu.
+@defun use-local-map keymap
+This function makes @var{keymap} the new local keymap of the current
+buffer. If @var{keymap} is @code{nil}, then the buffer has no local
+keymap. @code{use-local-map} returns @code{nil}. Most major mode
+commands use this function.
+@end defun
-A Lisp program can explicitly pop up a menu and receive the user's
-choice. You can use keymaps for this also. @xref{Pop-Up Menus}.
+@c Emacs 19 feature
+@defvar 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:
-@node Keyboard Menus
-@subsection Menus and the Keyboard
+@example
+(@var{variable} . @var{keymap})
+@end example
-When a prefix key ending with a keyboard event (a character or function
-key) has a definition that is a menu keymap, the user can use the
-keyboard to choose a menu item.
+The keymap @var{keymap} is active whenever @var{variable} has a
+non-@code{nil} value. Typically @var{variable} is the variable that
+enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
-Emacs displays the menu alternatives (the item strings of the
-bindings) in the echo area. If they don't all fit at once, the user can
-type @key{SPC} to see the next line of alternatives. Successive uses of
-@key{SPC} eventually get to the end of the menu and then cycle around to
-the beginning.
+Note that elements of @code{minor-mode-map-alist} do not have the same
+structure as elements of @code{minor-mode-alist}. The map must be the
+@sc{cdr} of the element; a list with the map as the second element will
+not do.
-When the user has found the desired alternative from the menu, he or she
-should type the corresponding character---the one whose binding is that
-alternative.
+What's more, the keymap itself must appear in the @sc{cdr}. It does not
+work to store a variable in the @sc{cdr} and make the map the value of
+that variable.
-In a menu intended for keyboard use, each menu item must clearly
-indicate what character to type. The best convention to use is to make
-the character the first letter of the item string. That is something
-users will understand without being told.
+When more than one minor mode keymap is active, their order of priority
+is the order of @code{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.
-This way of using menus in an Emacs-like editor was inspired by the
-Hierarkey system.
+See also @code{minor-mode-key-binding} in @ref{Functions for Key
+Lookup}. See @ref{Keymaps and Minor Modes}, for more information about
+minor modes.
+@end defvar
-@defvar menu-prompt-more-char
-This variable specifies the character to use to ask to see
-the next line of a menu. Its initial value is 32, the code
-for @key{SPC}.
+@defvar overriding-local-map
+If non-@code{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.
@end defvar
-@node Menu Example
-@subsection Menu Example
+@node Key Lookup
+@section Key Lookup
+@cindex key lookup
+@cindex keymap entry
- Here is a simple example of how to set up a menu for mouse use.
+ @dfn{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.
-@example
-(defvar my-menu-map
- (make-sparse-keymap "Key Commands <==> Functions"))
-(fset 'help-for-keys my-menu-map)
-
-(define-key my-menu-map [bindings]
- '("List all keystroke commands" . describe-bindings))
-(define-key my-menu-map [key]
- '("Describe key briefly" . describe-key-briefly))
-(define-key my-menu-map [key-verbose]
- '("Describe key verbose" . describe-key))
-(define-key my-menu-map [function]
- '("Describe Lisp function" . describe-function))
-(define-key my-menu-map [where-is]
- '("Where is this command" . where-is))
-
-(define-key global-map [C-S-down-mouse-1] 'help-for-keys)
-@end example
-
- The symbols used in the key sequences bound in the menu are fictitious
-``function keys''; they don't appear on the keyboard, but that doesn't
-stop you from using them in the menu. Their names were chosen to be
-mnemonic, because they show up in the output of @code{where-is} and
-@code{apropos} to identify the corresponding menu items.
-
- However, if you want the menu to be usable from the keyboard as well,
-you must bind real @sc{ASCII} characters as well as fictitious function
-keys.
+ 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). @xref{Input
+Events}. Such a pseudo-key-sequence is insufficient for
+@code{command-execute}, but it is sufficient for looking up or rebinding
+a key.
-@node Menu Bar
-@subsection The Menu Bar
-@cindex menu bar
+ 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.
- Most window systems allow each frame to have a @dfn{menu bar}---a
-permanently displayed menu stretching horizontally across the top of the
-frame. The items of the menu bar are the subcommands of the fake
-``function key'' @code{menu-bar}, as defined by all the active keymaps.
+ Let's use the term @dfn{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
+@code{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:
- To add an item to the menu bar, invent a fake ``function key'' of your
-own (let's call it @var{key}), and make a binding for the key sequence
-@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap,
-so that pressing a button on the menu bar item leads to another menu.
+@table @asis
+@item @code{nil}
+@cindex @code{nil} in keymap
+@code{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 @code{nil}
+for that event type.
- When more than one active keymap defines the same fake function key
-for the menu bar, the item appears just once. If the user clicks on
-that menu bar item, it brings up a single, combined submenu containing
-all the subcommands of that item---the global subcommands, the local
-subcommands, and the minor mode subcommands, all together.
+@item @var{keymap}
+@cindex keymap in keymap
+The events used so far in the lookup form a prefix key. The next
+event of the key sequence is looked up in @var{keymap}.
- In order for a frame to display a menu bar, its @code{menu-bar-lines}
-parameter must be greater than zero. Emacs uses just one line for the
-menu bar itself; if you specify more than one line, the other lines
-serve to separate the menu bar from the windows in the frame. We
-recommend you try 1 or 2 as the value of @code{menu-bar-lines}. @xref{X
-Frame Parameters}.
+@item @var{command}
+@cindex command in keymap
+The events used so far in the lookup form a complete key,
+and @var{command} is its binding. @xref{What Is a Function}.
- Here's an example of setting up a menu bar item:
+@item @var{string}
+@itemx @var{vector}
+@cindex string in keymap
+The events used so far in the lookup form a complete key, whose
+binding is a keyboard macro. See @ref{Keyboard Macros}, for more
+information.
-@smallexample
-(modify-frame-parameters (selected-frame) '((menu-bar-lines . 2)))
+@item @var{list}
+@cindex list in keymap
+The meaning of a list depends on the types of the elements of the list.
-;; @r{Make a menu keymap (with a prompt string)}
-;; @r{and make it the menu bar item's definition.}
-(define-key global-map [menu-bar words]
- (cons "Words" (make-sparse-keymap "Words")))
+@itemize @bullet
+@item
+If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
+is a keymap, and is treated as a keymap (see above).
-@group
-;; @r{Define specific subcommands in the item's menu.}
-(define-key global-map
- [menu-bar words forward]
- '("Forward word" . forward-word))
-@end group
-@group
-(define-key global-map
- [menu-bar words backward]
- '("Backward word" . backward-word))
-@end group
-@end smallexample
+@item
+@cindex @code{lambda} in keymap
+If the @sc{car} of @var{list} is @code{lambda}, then the list is a
+lambda expression. This is presumed to be a command, and is treated as
+such (see above).
- A local keymap can cancel a menu bar item made by the global keymap by
-rebinding the same fake function key with @code{undefined} as the
-binding. For example, this is how Dired suppresses the @samp{Edit} menu
-bar item:
+@item
+If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
+type, then this is an @dfn{indirect entry}:
@example
-(define-key dired-mode-map [menu-bar edit] 'undefined)
+(@var{othermap} . @var{othertype})
@end example
-@noindent
-@code{edit} is the fake function key used by the global map for the
-@samp{Edit} menu bar item. The main reason to suppress a global
-menu bar item is to regain space for mode-specific items.
+When key lookup encounters an indirect entry, it looks up instead the
+binding of @var{othertype} in @var{othermap} and uses that.
-@defvar menu-bar-final-items
-Normally the menu bar shows global items followed by items defined by the
-local maps.
+This feature permits you to define one key as an alias for another key.
+For example, an entry whose @sc{car} is the keymap called @code{esc-map}
+and whose @sc{cdr} is 32 (the code for space) means, ``Use the global
+binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
+@end itemize
-This variable holds a list of fake function keys for items to display at
-the end of the menu bar rather than in normal sequence. The default
-value is @code{(help)}; thus, the @samp{Help} menu item normally appears
-at the end of the menu bar, following local menu items.
-@end defvar
+@item @var{symbol}
+@cindex symbol in keymap
+The function definition of @var{symbol} is used in place of
+@var{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.
-@node Modifying Menus
-@subsection Modifying Menus
+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 @code{command-execute}
+(@pxref{Interactive Call}).
- When you insert a new item in an existing menu, you probably want to
-put it in a particular place among the menu's existing items. If you
-use @code{define-key} to add the item, it normally goes at the front of
-the menu. To put it elsewhere, use @code{define-key-after}:
+@cindex @code{undefined} in keymap
+The symbol @code{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 @code{undefined}; but that command does the same
+thing that is done automatically for an undefined key: it rings the bell
+(by calling @code{ding}) but does not signal an error.
-@defun define-key-after map key binding after
-Define a binding in @var{map} for @var{key}, with value @var{binding},
-just like @code{define-key}, but position the binding in @var{map} after
-the binding for the key @var{after}. For example,
+@cindex preventing prefix key
+@code{undefined} is used in local keymaps to override a global key
+binding and make the key ``undefined'' locally. A local binding of
+@code{nil} would fail to do this because it would not override the
+global binding.
+
+@item @var{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.
+@end table
+
+ 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 @code{nil}.
+Here is an example of a sparse keymap with two characters bound to
+commands and one bound to another keymap. This map is the normal value
+of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
+127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
+@kbd{C-x}.
@example
-(define-key-after my-menu [drink]
- '("Drink" . drink-command) [eat])
+@group
+(keymap (9 . lisp-indent-line)
+ (127 . backward-delete-char-untabify)
+ (27 keymap (17 . indent-sexp) (24 . eval-defun)))
+@end group
@end example
-@noindent
-makes a binding for the fake function key @key{drink} and puts it
-right after the binding for @key{eat}.
-@end defun
-
-@node Active Keymaps
-@section Active Keymaps
-@cindex active keymap
-@cindex global keymap
-@cindex local keymap
+@node Functions for Key Lookup
+@section Functions for Key Lookup
- Emacs normally contains many keymaps; at any given time, just a few of
-them are @dfn{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.
+ Here are the functions and variables pertaining to key lookup.
- The @dfn{global keymap} holds the bindings of keys that are defined
-regardless of the current buffer, such as @kbd{C-f}. The variable
-@code{global-map} holds this keymap, which is always active.
+@defun lookup-key keymap key &optional accept-defaults
+This function returns the definition of @var{key} in @var{keymap}. If
+the string or vector @var{key} is not a valid key sequence according to
+the prefix keys specified in @var{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 @var{key} that compose a complete key.
- Each buffer may have another keymap, its @dfn{local keymap}, which may
-contain new or overriding definitions for keys. The current buffer's
-local keymap is always active except when @code{overriding-local-map}
-overrides it. Text properties can specify an alternative local map for
-certain parts of the buffer; see @ref{Special Properties}.
+@c Emacs 19 feature
+If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
+considers default bindings as well as bindings for the specific events
+in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
+the specific sequence @var{key}, ignoring default bindings except when
+you explicitly ask about them. (To do this, supply @code{t} as an
+element of @var{key}; see @ref{Format of Keymaps}.)
- Each minor mode may have a keymap; if it does, the keymap is active
-when the minor mode is enabled.
+All the other functions described in this chapter that look up keys use
+@code{lookup-key}.
- The variable @code{overriding-local-map}, if non-@code{nil}, specifies
-another local keymap that overrides the buffer's local map and all the
-minor mode keymaps.
+@example
+@group
+(lookup-key (current-global-map) "\C-x\C-f")
+ @result{} find-file
+@end group
+@group
+(lookup-key (current-global-map) "\C-x\C-f12345")
+ @result{} 2
+@end group
+@end example
- All the active keymaps are used together to determine what command to
-execute when a key is entered. Emacs searches these maps one by one, in
-order of decreasing precedence, until it finds a binding in one of the maps.
-
- Normally, Emacs @emph{first} searches for the key in the minor mode
-maps (one map at a time); if they do not supply a binding for the key,
-Emacs searches the local map; if that too has no binding, Emacs then
-searches the global map. However, if @code{overriding-local-map} is
-non-@code{nil}, Emacs searches that map first, followed by the global
-map.
-
- The procedure for searching a single keymap is called
-@dfn{key lookup}; see @ref{Key Lookup}.
-
-@cindex major mode keymap
- Since every buffer that uses the same major mode normally uses the
-very same local keymap, it may appear as if the keymap is local to the
-mode. A change to the local keymap of a buffer (using
-@code{local-set-key}, for example) will be 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 @code{lisp-mode-map},
-@code{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. @xref{Intro to Minibuffers}.
-
- @xref{Standard Keymaps}, for a list of standard keymaps.
-
-@defvar global-map
- This variable contains the default global keymap that maps Emacs
-keyboard input to commands. The global keymap is normally this keymap.
-The default global keymap is a full keymap that binds
-@code{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.
-@end defvar
-
-@defun current-global-map
- This function returns the current global keymap. This is the
-same as the value of @code{global-map} unless you change one or the
-other.
+ If @var{key} contains a meta character, that character is implicitly
+replaced by a two-character sequence: the value of
+@code{meta-prefix-char}, followed by the corresponding non-meta
+character. Thus, the first example below is handled by conversion into
+the second example.
@example
@group
-(current-global-map)
-@result{} (keymap [set-mark-command beginning-of-line @dots{}
- delete-backward-char])
+(lookup-key (current-global-map) "\M-f")
+ @result{} forward-word
+@end group
+@group
+(lookup-key (current-global-map) "\ef")
+ @result{} forward-word
@end group
@end example
+
+Unlike @code{read-key-sequence}, this function does not modify the
+specified events in ways that discard information (@pxref{Key Sequence
+Input}). In particular, it does not convert letters to lower case and
+it does not change drag events to clicks.
@end defun
-@defun current-local-map
- This function returns the current buffer's local keymap, or @code{nil}
-if it has none. In the following example, the keymap for the
-@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
-in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse
-keymap.
+@deffn Command undefined
+Used in keymaps to undefine keys. It calls @code{ding}, but does
+not cause an error.
+@end deffn
+
+@defun key-binding key &optional accept-defaults
+This function returns the binding for @var{key} in the current
+keymaps, trying all the active keymaps. The result is @code{nil} if
+@var{key} is undefined in the keymaps.
+
+@c Emacs 19 feature
+The argument @var{accept-defaults} controls checking for default
+bindings, as in @code{lookup-key} (above).
+
+An error is signaled if @var{key} is not a string or a vector.
@example
@group
-(current-local-map)
-@result{} (keymap
- (10 . eval-print-last-sexp)
- (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
-@end group
-@group
- (27 keymap
- (24 . eval-defun)
- (17 . indent-sexp)))
+(key-binding "\C-x\C-f")
+ @result{} find-file
@end group
@end example
@end defun
-@defun current-minor-mode-maps
-This function returns a list of the keymaps of currently enabled minor modes.
-@end defun
-
-@defun use-global-map keymap
- This function makes @var{keymap} the new current global keymap. It
-returns @code{nil}.
+@defun local-key-binding key &optional accept-defaults
+This function returns the binding for @var{key} in the current
+local keymap, or @code{nil} if it is undefined there.
- It is very unusual to change the global keymap.
+@c Emacs 19 feature
+The argument @var{accept-defaults} controls checking for default bindings,
+as in @code{lookup-key} (above).
@end defun
-@defun use-local-map keymap
- This function makes @var{keymap} the new local keymap of the current
-buffer. If @var{keymap} is @code{nil}, then the buffer has no local
-keymap. @code{use-local-map} returns @code{nil}. Most major mode
-commands use this function.
-@end defun
+@defun global-key-binding key &optional accept-defaults
+This function returns the binding for command @var{key} in the
+current global keymap, or @code{nil} if it is undefined there.
@c Emacs 19 feature
-@defvar 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:
+The argument @var{accept-defaults} controls checking for default bindings,
+as in @code{lookup-key} (above).
+@end defun
-@example
-(@var{variable} . @var{keymap})
-@end example
+@c Emacs 19 feature
+@defun minor-mode-key-binding key &optional accept-defaults
+This function returns a list of all the active minor mode bindings of
+@var{key}. More precisely, it returns an alist of pairs
+@code{(@var{modename} . @var{binding})}, where @var{modename} is the
+variable that enables the minor mode, and @var{binding} is @var{key}'s
+binding in that mode. If @var{key} has no minor-mode bindings, the
+value is @code{nil}.
-The keymap @var{keymap} is active whenever @var{variable} has a
-non-@code{nil} value. Typically @var{variable} is the variable which
-enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
+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.
-Note that elements of @code{minor-mode-map-alist} do not have the same
-structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the second element will
-not do.
+The argument @var{accept-defaults} controls checking for default
+bindings, as in @code{lookup-key} (above).
+@end defun
-What's more, the keymap itself must appear in the @sc{cdr}. It does not
-work to store a variable in the @sc{cdr} and make the map the value of
-that variable.
+@defvar meta-prefix-char
+@cindex @key{ESC}
+This variable is the meta-prefix character code. It is used when
+translating a meta character to a two-character sequence so it can be
+looked up in a keymap. For useful results, the value should be a prefix
+event (@pxref{Prefix Keys}). The default value is 27, which is the
+@sc{ASCII} code for @key{ESC}.
-When more than one minor mode keymap is active, their order of priority
-is the order of @code{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.
+As long as the value of @code{meta-prefix-char} remains 27, key
+lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
+defined as the @code{backward-word} command. However, if you set
+@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
+translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
+@code{switch-to-buffer} command.
-See also @code{minor-mode-key-binding} in @ref{Functions for Key
-Lookup}. See @ref{Keymaps and Minor Modes}, for more information about
-minor modes.
-@end defvar
+@smallexample
+@group
+meta-prefix-char ; @r{The default value.}
+ @result{} 27
+@end group
+@group
+(key-binding "\M-b")
+ @result{} backward-word
+@end group
+@group
+?\C-x ; @r{The print representation}
+ @result{} 24 ; @r{of a character.}
+@end group
+@group
+(setq meta-prefix-char 24)
+ @result{} 24
+@end group
+@group
+(key-binding "\M-b")
+ @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is}
+ ; @r{like typing @kbd{C-x b}.}
-@defvar overriding-local-map
-If non-@code{nil}, 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.
+(setq meta-prefix-char 27) ; @r{Avoid confusion!}
+ @result{} 27 ; @r{Restore the default value!}
+@end group
+@end smallexample
@end defvar
-@node Key Lookup
-@section Key Lookup
-@cindex key lookup
-@cindex keymap entry
+@node Changing Key Bindings
+@section Changing Key Bindings
+@cindex changing key bindings
+@cindex rebinding
- @dfn{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.
+ 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 @code{global-set-key} and @code{local-set-key} functions are
+convenient interfaces for these operations (@pxref{Key Binding
+Commands}). You can also use @code{define-key}, a more general
+function; then you must specify explicitly the map to change.
- Key lookup uses just the event types 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). @xref{Input
-Events}. Such a pseudo-key-sequence is insufficient for
-@code{command-execute}, but it is sufficient for looking up or rebinding
-a key.
+@cindex meta character key constants
+@cindex control character key constants
+ In writing the key sequence to rebind, it is good to use the special
+escape sequences for control and meta characters (@pxref{String Type}).
+The syntax @samp{\C-} means that the following character is a control
+character and @samp{\M-} means that the following character is a meta
+character. Thus, the string @code{"\M-x"} is read as containing a
+single @kbd{M-x}, @code{"\C-f"} is read as containing a single
+@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
+containing a single @kbd{C-M-x}. You can also use this escape syntax in
+vectors, as well as others that aren't allowed in strings; one example
+is @samp{[?\C-\H-x home]}. @xref{Character Type}.
- 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.
+ For the functions below, an error is signaled if @var{keymap} is not a
+keymap or if @var{key} is not a string or vector representing a key
+sequence. You can use event types (symbols) as shorthand for events
+that are lists.
- Let's use the term @dfn{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
-@code{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:
+@defun define-key keymap key binding
+This function sets the binding for @var{key} in @var{keymap}. (If
+@var{key} is more than one event long, the change is actually made
+in another keymap reached from @var{keymap}.) The argument
+@var{binding} can be any Lisp object, but only certain types are
+meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
+The value returned by @code{define-key} is @var{binding}.
-@table @asis
-@item @code{nil}
-@cindex @code{nil} in keymap
-@code{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 @code{nil}
-for that event type.
+@cindex invalid prefix key error
+@cindex key sequence error
+Every prefix of @var{key} must be a prefix key (i.e., bound to a
+keymap) or undefined; otherwise an error is signaled.
-@item @var{keymap}
-@cindex keymap in keymap
-The events used so far in the lookup form a prefix key. The next
-event of the key sequence is looked up in @var{keymap}.
+If some prefix of @var{key} is undefined, then @code{define-key} defines
+it as a prefix key so that the rest of @var{key} may be defined as
+specified.
+@end defun
-@item @var{command}
-@cindex command in keymap
-The events used so far in the lookup form a complete key,
-and @var{command} is its binding.
+ Here is an example that creates a sparse keymap and makes a number of
+bindings in it:
-@item @var{string}
-@itemx @var{vector}
-@cindex string in keymap
-The events used so far in the lookup form a complete key, whose
-binding is a keyboard macro. See @ref{Keyboard Macros}, for more
-information.
-
-@item @var{list}
-@cindex list in keymap
-The meaning of a list depends on the types of the elements of the list.
-
-@itemize @bullet
-@item
-If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
-is a keymap, and is treated as a keymap (see above).
-
-@item
-@cindex @code{lambda} in keymap
-If the @sc{car} of @var{list} is @code{lambda}, then the list is a
-lambda expression. This is presumed to be a command, and is treated as
-such (see above).
-
-@item
-If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
-type, then this is an @dfn{indirect entry}:
-
-@example
-(@var{othermap} . @var{othertype})
-@end example
-
-When key lookup encounters an indirect entry, it looks up instead the
-binding of @var{othertype} in @var{othermap} and uses that.
-
-This feature permits you to define one key as an alias for another key.
-For example, an entry whose @sc{car} is the keymap called @code{esc-map}
-and whose @sc{cdr} is 32 (the code for space) means, ``Use the global
-binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
-@end itemize
-
-@item @var{symbol}
-@cindex symbol in keymap
-The function definition of @var{symbol} is used in place of
-@var{symbol}. If that too is a symbol, then this process is repeated,
-any number of times. Ultimately this should lead to an object which 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 also 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 @code{command-execute}
-(@pxref{Interactive Call}).
-
-@cindex @code{undefined} in keymap
-The symbol @code{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 @code{undefined}; but that command does the same
-thing that is done automatically for an undefined key: it rings the bell
-(by calling @code{ding}) but does not signal an error.
-
-@cindex preventing prefix key
-@code{undefined} is used in local keymaps to override a global key
-binding and make the key ``undefined'' locally. A local binding of
-@code{nil} would fail to do this because it would not override the
-global binding.
-
-@item @var{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.
-@end table
-
- In short, a keymap entry may be a keymap, a command, a keyboard macro,
-a symbol which leads to one of them, or an indirection or @code{nil}.
-Here is an example of a sparse keymap with two characters bound to
-commands and one bound to another keymap. This map is the normal value
-of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
-127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
-@kbd{C-x}.
-
-@example
+@smallexample
@group
-(keymap (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
- (27 keymap (17 . indent-sexp) (24 . eval-defun)))
+(setq map (make-sparse-keymap))
+ @result{} (keymap)
@end group
-@end example
-
-@node Functions for Key Lookup
-@section Functions for Key Lookup
-
- Here are the functions and variables pertaining to key lookup.
-
-@defun lookup-key keymap key &optional accept-defaults
-This function returns the definition of @var{key} in @var{keymap}. If
-the string or vector @var{key} is not a valid key sequence according to
-the prefix keys specified in @var{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 @var{key} that compose a complete key.
-
-@c Emacs 19 feature
-If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
-considers default bindings as well as bindings for the specific events
-in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
-the specific sequence @var{key}, ignoring default bindings except when
-an element of @var{key} is @code{t}.
-
-All the other functions described in this chapter that look up keys use
-@code{lookup-key}.
-
-@example
@group
-(lookup-key (current-global-map) "\C-x\C-f")
- @result{} find-file
+(define-key map "\C-f" 'forward-char)
+ @result{} forward-char
@end group
@group
-(lookup-key (current-global-map) "\C-x\C-f12345")
- @result{} 2
+map
+ @result{} (keymap (6 . forward-char))
@end group
-@end example
-
- If @var{key} contains a meta character, that character is implicitly
-replaced by a two-character sequence: the value of
-@code{meta-prefix-char}, followed by the corresponding non-meta
-character. Thus, the first example below is handled by conversion into
-the second example.
-@example
@group
-(lookup-key (current-global-map) "\M-f")
+;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
+(define-key map "\C-xf" 'forward-word)
@result{} forward-word
@end group
@group
-(lookup-key (current-global-map) "\ef")
- @result{} forward-word
+map
+@result{} (keymap
+ (24 keymap ; @kbd{C-x}
+ (102 . forward-word)) ; @kbd{f}
+ (6 . forward-char)) ; @kbd{C-f}
@end group
-@end example
-
-Unlike @code{read-key-sequence}, this function does not modify the
-specified events in ways that discard information (@pxref{Key Sequence
-Input}). In particular, it does not convert letters to lower case and
-it does not change drag events to clicks.
-@end defun
-
-@deffn Command undefined
-Used in keymaps to undefine keys. It calls @code{ding}, but does
-not cause an error.
-@end deffn
-
-@defun key-binding key &optional accept-defaults
-This function returns the binding for @var{key} in the current
-keymaps, trying all the active keymaps. The result is @code{nil} if
-@var{key} is undefined in the keymaps.
-
-@c Emacs 19 feature
-The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key}.
-An error is signaled if @var{key} is not a string or a vector.
+@group
+;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
+(define-key map "\C-p" ctl-x-map)
+;; @code{ctl-x-map}
+@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
+@end group
-@example
@group
-(key-binding "\C-x\C-f")
- @result{} find-file
+;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
+(define-key map "\C-p\C-f" 'foo)
+@result{} 'foo
@end group
-@end example
-@end defun
+@group
+map
+@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
+ (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
+ (24 keymap
+ (102 . forward-word))
+ (6 . forward-char))
+@end group
+@end smallexample
-@defun local-key-binding key &optional accept-defaults
-This function returns the binding for @var{key} in the current
-local keymap, or @code{nil} if it is undefined there.
+@noindent
+Note that storing a new binding for @kbd{C-p C-f} actually works by
+changing an entry in @code{ctl-x-map}, and this has the effect of
+changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
+default global map.
-@c Emacs 19 feature
-The argument @var{accept-defaults} controls checking for default bindings,
-as in @code{lookup-key} (above).
-@end defun
+@defun substitute-key-definition olddef newdef keymap &optional oldmap
+@cindex replace bindings
+This function replaces @var{olddef} with @var{newdef} for any keys in
+@var{keymap} that were bound to @var{olddef}. In other words,
+@var{olddef} is replaced with @var{newdef} wherever it appears. The
+function returns @code{nil}.
-@defun global-key-binding key &optional accept-defaults
-This function returns the binding for command @var{key} in the
-current global keymap, or @code{nil} if it is undefined there.
+For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
+standard bindings:
-@c Emacs 19 feature
-The argument @var{accept-defaults} controls checking for default bindings,
-as in @code{lookup-key} (above).
-@end defun
+@smallexample
+@group
+(substitute-key-definition
+ 'find-file 'find-file-read-only (current-global-map))
+@end group
+@end smallexample
@c Emacs 19 feature
-@defun minor-mode-key-binding key &optional accept-defaults
-This function returns a list of all the active minor mode bindings of
-@var{key}. More precisely, it returns an alist of pairs
-@code{(@var{modename} . @var{binding})}, where @var{modename} is the the
-variable which enables the minor mode, and @var{binding} is @var{key}'s
-binding in that mode. If @var{key} has no minor-mode bindings, the
-value is @code{nil}.
+If @var{oldmap} is non-@code{nil}, then its bindings determine which
+keys to rebind. The rebindings still happen in @var{newmap}, not in
+@var{oldmap}. Thus, you can change one map under the control of the
+bindings in another. For example,
-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.
+@smallexample
+(substitute-key-definition
+ 'delete-backward-char 'my-funny-delete
+ my-map global-map)
+@end smallexample
-The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (above).
-@end defun
+@noindent
+puts the special deletion command in @code{my-map} for whichever keys
+are globally bound to the standard deletion command.
-@defvar meta-prefix-char
-@cindex @key{ESC}
-This variable is the meta-prefix character code. It is used when
-translating a meta character to a two-character sequence so it can be
-looked up in a keymap. For useful results, the value should be a prefix
-event (@pxref{Prefix Keys}). The default value is 27, which is the
-@sc{ASCII} code for @key{ESC}.
+@ignore
+@c Emacs 18 only
+Prefix keymaps that appear within @var{keymap} are not checked
+recursively for keys bound to @var{olddef}; they are not changed at all.
+Perhaps it would be better to check nested keymaps recursively.
+@end ignore
-As long as the value of @code{meta-prefix-char} remains 27, key
-lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
-defined as the @code{backward-word} command. However, if you set
-@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
-translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
-@code{switch-to-buffer} command.
-
-@smallexample
-@group
-meta-prefix-char ; @r{The default value.}
- @result{} 27
-@end group
-@group
-(key-binding "\M-b")
- @result{} backward-word
-@end group
-@group
-?\C-x ; @r{The print representation}
- @result{} 24 ; @r{of a character.}
-@end group
-@group
-(setq meta-prefix-char 24)
- @result{} 24
-@end group
-@group
-(key-binding "\M-b")
- @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is}
- ; @r{like typing @kbd{C-x b}.}
-
-(setq meta-prefix-char 27) ; @r{Avoid confusion!}
- @result{} 27 ; @r{Restore the default value!}
-@end group
-@end smallexample
-@end defvar
-
-@node Changing Key Bindings
-@section Changing Key Bindings
-@cindex changing key bindings
-@cindex rebinding
-
- The way to rebind a key is to change its entry in a keymap. If you
-change the global keymap, the change is effective in all buffers (except
-those that override 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 @code{global-set-key} and @code{local-set-key}
-functions are convenient interfaces for these operations. Or you can
-use @code{define-key} and specify explicitly which map to change.
-
- People often use @code{global-set-key} in their @file{.emacs} file for
-simple customization. For example,
-
-@smallexample
-(global-set-key "\C-x\C-\\" 'next-line)
-@end smallexample
-
-@noindent
-or
-
-@smallexample
-(global-set-key [?\C-x ?\C-\\] 'next-line)
-@end smallexample
-
-@noindent
-redefines @kbd{C-x C-\} to move down a line.
-
-@smallexample
-(global-set-key [M-mouse-1] 'mouse-set-point)
-@end smallexample
-
-@noindent
-redefines the first (leftmost) mouse button, typed with the Meta key, to
-set point where you click.
-
-@cindex meta character key constants
-@cindex control character key constants
- In writing the key sequence to rebind, it is useful to use the special
-escape sequences for control and meta characters (@pxref{String Type}).
-The syntax @samp{\C-} means that the following character is a control
-character and @samp{\M-} means that the following character is a meta
-character. Thus, the string @code{"\M-x"} is read as containing a
-single @kbd{M-x}, @code{"\C-f"} is read as containing a single
-@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
-containing a single @kbd{C-M-x}.
-
- For the functions below, an error is signaled if @var{keymap} is not a
-keymap or if @var{key} is not a string or vector representing a key
-sequence. You can use event types (symbols) as shorthand for events
-that are lists.
-
-@defun define-key keymap key binding
- This function sets the binding for @var{key} in @var{keymap}. (If
-@var{key} is more than one event long, the change is actually made
-in another keymap reached from @var{keymap}.) The argument
-@var{binding} can be any Lisp object, but only certain types are
-meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
-The value returned by @code{define-key} is @var{binding}.
-
-@cindex invalid prefix key error
-@cindex key sequence error
- Every prefix of @var{key} must be a prefix key (i.e., bound to a
-keymap) or undefined; otherwise an error is signaled.
-
-If some prefix of @var{key} is undefined, then @code{define-key} defines
-it as a prefix key so that the rest of @var{key} may be defined as
-specified.
-@end defun
-
- This example creates a sparse keymap and makes a number of bindings:
-
-@smallexample
-@group
-(setq map (make-sparse-keymap))
- @result{} (keymap)
-@end group
-@group
-(define-key map "\C-f" 'forward-char)
- @result{} forward-char
-@end group
-@group
-map
- @result{} (keymap (6 . forward-char))
-@end group
-
-@group
-;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
-(define-key map "\C-xf" 'forward-word)
- @result{} forward-word
-@end group
-@group
-map
-@result{} (keymap
- (24 keymap ; @kbd{C-x}
- (102 . forward-word)) ; @kbd{f}
- (6 . forward-char)) ; @kbd{C-f}
-@end group
-
-@group
-;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
-(define-key map "\C-p" ctl-x-map)
-;; @code{ctl-x-map}
-@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
-@end group
-
-@group
-;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
-(define-key map "\C-p\C-f" 'foo)
-@result{} 'foo
-@end group
-@group
-map
-@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
- (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
- (24 keymap
- (102 . forward-word))
- (6 . forward-char))
-@end group
-@end smallexample
-
-@noindent
-Note that storing a new binding for @kbd{C-p C-f} actually works by
-changing an entry in @code{ctl-x-map}, and this has the effect of
-changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
-default global map.
-
-@defun substitute-key-definition olddef newdef keymap &optional oldmap
-@cindex replace bindings
-This function replaces @var{olddef} with @var{newdef} for any keys in
-@var{keymap} that were bound to @var{olddef}. In other words,
-@var{olddef} is replaced with @var{newdef} wherever it appears. The
-function returns @code{nil}.
-
-For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
-standard bindings:
-
-@smallexample
-@group
-(substitute-key-definition
- 'find-file 'find-file-read-only (current-global-map))
-@end group
-@end smallexample
-
-@c Emacs 19 feature
-If @var{oldmap} is non-@code{nil}, then its bindings determine which
-keys to rebind. The rebindings still happen in @var{newmap}, not in
-@var{oldmap}. Thus, you can change one map under the control of the
-bindings in another. For example,
-
-@smallexample
-(substitute-key-definition
- 'delete-backward-char 'my-funny-delete
- my-map global-map)
-@end smallexample
-
-@noindent
-puts the special deletion command in @code{my-map} for whichever keys
-are globally bound to the standard deletion command.
-
-@ignore
-@c Emacs 18 only
-Prefix keymaps that appear within @var{keymap} are not checked
-recursively for keys bound to @var{olddef}; they are not changed at all.
-Perhaps it would be better to check nested keymaps recursively.
-@end ignore
-
-Here is an example showing a keymap before and after substitution:
+Here is an example showing a keymap before and after substitution:
@smallexample
@group
This section describes some convenient interactive interfaces for
changing key bindings. They work by calling @code{define-key}.
+ People often use @code{global-set-key} in their @file{.emacs} file for
+simple customization. For example,
+
+@smallexample
+(global-set-key "\C-x\C-\\" 'next-line)
+@end smallexample
+
+@noindent
+or
+
+@smallexample
+(global-set-key [?\C-x ?\C-\\] 'next-line)
+@end smallexample
+
+@noindent
+redefines @kbd{C-x C-\} to move down a line.
+
+@smallexample
+(global-set-key [M-mouse-1] 'mouse-set-point)
+@end smallexample
+
+@noindent
+redefines the first (leftmost) mouse button, typed with the Meta key, to
+set point where you click.
+
@deffn Command global-set-key key definition
- This function sets the binding of @var{key} in the current global map
+This function sets the binding of @var{key} in the current global map
to @var{definition}.
@smallexample
@deffn Command global-unset-key key
@cindex unbinding keys
- This function removes the binding of @var{key} from the current
+This function removes the binding of @var{key} from the current
global map.
-One use of this function is in preparation for defining a longer key
-which uses it implicitly as a prefix---which would not be allowed if
-@var{key} has a non-prefix binding. For example:
+One use of this function is in preparation for defining a longer key
+that uses @var{key} as a prefix---which would not be allowed if
+@var{key} has a non-prefix binding. For example:
+
+@smallexample
+@group
+(global-unset-key "\C-l")
+ @result{} nil
+@end group
+@group
+(global-set-key "\C-l\C-l" 'redraw-display)
+ @result{} nil
+@end group
+@end smallexample
+
+This function is implemented simply using @code{define-key}:
+
+@smallexample
+@group
+(global-unset-key @var{key})
+@equiv{}
+(define-key (current-global-map) @var{key} nil)
+@end group
+@end smallexample
+@end deffn
+
+@deffn Command local-set-key key definition
+This function sets the binding of @var{key} in the current local
+keymap to @var{definition}.
+
+@smallexample
+@group
+(local-set-key @var{key} @var{definition})
+@equiv{}
+(define-key (current-local-map) @var{key} @var{definition})
+@end group
+@end smallexample
+@end deffn
+
+@deffn Command local-unset-key key
+This function removes the binding of @var{key} from the current
+local map.
+
+@smallexample
+@group
+(local-unset-key @var{key})
+@equiv{}
+(define-key (current-local-map) @var{key} nil)
+@end group
+@end smallexample
+@end deffn
+
+@node Scanning Keymaps
+@section Scanning Keymaps
+
+ This section describes functions used to scan all the current keymaps
+for the sake of printing help information.
+
+@defun accessible-keymaps keymap &optional prefix
+This function returns a list of all the keymaps that can be accessed
+(via prefix keys) from @var{keymap}. The value is an association list
+with elements of the form @code{(@var{key} .@: @var{map})}, where
+@var{key} is a prefix key whose definition in @var{keymap} is
+@var{map}.
+
+The elements of the alist are ordered so that the @var{key} increases
+in length. The first element is always @code{("" .@: @var{keymap})},
+because the specified keymap is accessible from itself with a prefix of
+no events.
+
+If @var{prefix} is given, it should be a prefix key sequence; then
+@code{accessible-keymaps} includes only the submaps whose prefixes start
+with @var{prefix}. These elements look just as they do in the value of
+@code{(accessible-keymaps)}; the only difference is that some elements
+are omitted.
+
+In the example below, the returned alist indicates that the key
+@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
+definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
+(115 .@: foo))}.
+
+@smallexample
+@group
+(accessible-keymaps (current-local-map))
+@result{}(("" keymap
+ (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
+ (83 . center-paragraph)
+ (115 . center-line))
+ (9 . tab-to-tab-stop))
+@end group
+
+@group
+ ("^[" keymap
+ (83 . center-paragraph)
+ (115 . foo)))
+@end group
+@end smallexample
+
+In the following example, @kbd{C-h} is a prefix key that uses a sparse
+keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
+Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of
+the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of
+several dummy events used as prefixes for mouse actions in special parts
+of a window.
+
+@smallexample
+@group
+(accessible-keymaps (current-global-map))
+@result{} (("" keymap [set-mark-command beginning-of-line @dots{}
+ delete-backward-char])
+@end group
+@group
+ ("^H" keymap (118 . describe-variable) @dots{}
+ (8 . help-for-help))
+@end group
+@group
+ ("^X" keymap [x-flush-mouse-queue @dots{}
+ backward-kill-sentence])
+@end group
+@group
+ ("^[" keymap [mark-sexp backward-sexp @dots{}
+ backward-kill-word])
+@end group
+ ("^X4" keymap (15 . display-buffer) @dots{})
+@group
+ ([mode-line] keymap
+ (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
+@end group
+@end smallexample
+
+@noindent
+These are not all the keymaps you would see in an actual case.
+@end defun
+
+@defun where-is-internal command &optional keymap firstonly noindirect
+This function returns a list of key sequences (of any length) that are
+bound to @var{command} in a set of keymaps.
+
+The argument @var{command} can be any object; it is compared with all
+keymap entries using @code{eq}.
+
+If @var{keymap} is @code{nil}, then the maps used are the current active
+keymaps, disregarding @code{overriding-local-map} (that is, pretending
+its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the
+maps searched are @var{keymap} and the global keymap.
+
+Usually it's best to use @code{overriding-local-map} as the expression
+for @var{keymap}. Then @code{where-is-internal} searches precisely the
+keymaps that are active. To search only the global map, pass
+@code{(keymap)} (an empty keymap) as @var{keymap}.
+
+If @var{firstonly} is @code{non-ascii}, then the value is a single
+string representing the first key sequence found, rather than a list of
+all possible key sequences. If @var{firstonly} is @code{t}, then the
+value is the first key sequence, except that key sequences consisting
+entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII}
+characters) are preferred to all other key sequences.
+
+If @var{noindirect} is non-@code{nil}, @code{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 @code{where-is} (@pxref{Help, , Help, emacs,
+The GNU Emacs Manual}).
+
+@smallexample
+@group
+(where-is-internal 'describe-function)
+ @result{} ("\^hf" "\^hd")
+@end group
+@end smallexample
+@end defun
+
+@deffn Command describe-bindings prefix
+This function creates a listing of all defined keys and their
+definitions. It writes the listing in a buffer named @samp{*Help*} and
+displays it in a window.
+
+If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
+listing includes only keys that start with @var{prefix}.
+
+The listing describes meta characters as @key{ESC} followed by the
+corresponding non-meta character.
+
+When several characters with consecutive @sc{ASCII} codes have the
+same definition, they are shown together, as
+@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
+know the @sc{ASCII} codes to understand which characters this means.
+For example, in the default global map, the characters @samp{@key{SPC}
+..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32,
+@kbd{~} is @sc{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 @code{self-insert-command}.
+@end deffn
+
+@node Menu Keymaps
+@section Menu Keymaps
+@cindex menu keymaps
+
+@c Emacs 19 feature
+A keymap can define a menu as well as bindings for keyboard keys and
+mouse button. Menus are usually actuated with the mouse, but they can
+work with the keyboard also.
+
+@menu
+* Defining Menus:: How to make a keymap that defines a menu.
+* Mouse Menus:: How users actuate the menu with the mouse.
+* Keyboard Menus:: How they actuate it with the keyboard.
+* Menu Example:: Making a simple menu.
+* Menu Bar:: How to customize the menu bar.
+* Modifying Menus:: How to add new items to a menu.
+@end menu
+
+@node Defining Menus
+@subsection Defining Menus
+@cindex defining menus
+@cindex menu prompt string
+@cindex prompt string (of menu)
+
+A keymap is suitable for menu use if it has an @dfn{overall prompt
+string}, which is a string that appears as an element of the keymap.
+(@xref{Format of Keymaps}.) The string should describe the purpose of
+the menu. The easiest way to construct a keymap with a prompt string is
+to specify the string as an argument when you call @code{make-keymap} or
+@code{make-sparse-keymap} (@pxref{Creating Keymaps}).
+
+The individual bindings in the menu keymap should have item
+strings; these strings become the items displayed in the menu. A
+binding with an item string looks like this:
+
+@example
+(@var{string} . @var{real-binding})
+@end example
+
+The item string for a binding should be short---one or two words. It
+should describe the action of the command it corresponds to.
+
+As far as @code{define-key} is concerned, @var{string} is part of the
+event's binding. However, @code{lookup-key} returns just
+@var{real-binding}, and only @var{real-binding} is used for executing
+the key.
+
+You can also supply a second string, called the help string, as follows:
+
+@example
+(@var{string} @var{help-string} . @var{real-binding})
+@end example
+
+Currently Emacs does not actually use @var{help-string}; it knows only
+how to ignore @var{help-string} in order to extract @var{real-binding}.
+In the future we hope to make @var{help-string} serve as extended
+documentation for the menu item, available on request.
+
+If @var{real-binding} is @code{nil}, then @var{string} appears in the
+menu but cannot be selected.
+
+If @var{real-binding} is a symbol and has a non-@code{nil}
+@code{menu-enable} property, that property is an expression that
+controls whether the menu item is enabled. Every time the keymap is
+used to display a menu, Emacs evaluates the expression, and it enables
+the menu item only if the expression's value is non-@code{nil}. When a
+menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
+cannot be selected with the mouse.
+
+The order of items in the menu is the same as the order of bindings in
+the keymap. Since @code{define-key} puts new bindings at the front, you
+should define the menu items starting at the bottom of the menu and
+moving to the top, if you care about the order. When you add an item to
+an existing menu, you can specify its position in the menu using
+@code{define-key-after} (@pxref{Modifying Menus}).
+
+You've probably noticed that menu items show the equivalent keyboard key
+sequence (if any) to invoke the same command. To save time on
+recalculation, menu display caches this information in a sublist in the
+binding, like this:
+
+@c This line is not too long--rms.
+@example
+(@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
+@end example
+
+Don't put these sublists in the menu item yourself; menu display
+calculates them automatically. Don't add keyboard equivalents to the
+item strings in a mouse menu, since that is redundant.
+
+@node Mouse Menus
+@subsection Menus and the Mouse
+
+The way to make a menu keymap produce a menu is to make it the
+definition of a prefix key.
+
+If the prefix key ends with a mouse event, Emacs handles the menu keymap
+by popping up a visible menu, so that the user can select a choice with
+the mouse. When the user clicks on a menu item, the event generated is
+whatever character or symbol has the binding that brought about that
+menu item. (A menu item may generate a series of events if the menu has
+multiple levels or comes from the menu bar.)
+
+It's often best to use a button-down event to trigger the menu. Then
+the user can select a menu item by releasing the button.
+
+A single keymap can appear as multiple menu panes, if you explicitly
+arrange for this. The way to do this is to make a keymap for each pane,
+then create a binding for each of those maps in the main keymap of the
+menu. Give each of these bindings an item string that starts with
+@samp{@@}. The rest of the item string becomes the name of the pane.
+See the file @file{lisp/mouse.el} for an example of this. Any ordinary
+bindings with @samp{@@}-less item strings are grouped into one pane,
+which appears along with the other panes explicitly created for the
+submaps.
+
+X toolkit menus don't have panes; instead, they can have submenus.
+Every nested keymap becomes a submenu, whether the item string starts
+with @samp{@@} or not. In a toolkit version of Emacs, the only thing
+special about @samp{@@} at the beginning of an item string is that the
+@samp{@@} doesn't appear in the menu item.
+
+You can also get multiple panes from separate keymaps. The full
+definition of a prefix key always comes from merging the definitions
+supplied by the various active keymaps (minor mode, local, and
+global). When more than one of these keymaps is a menu, each of them
+makes a separate pane or panes. @xref{Active Keymaps}.
+
+In toolkit versions of Emacs, menus don't have panes, so submenus are
+used to represent the separate keymaps. Each keymap's contribution
+becomes one submenu.
+
+A Lisp program can explicitly pop up a menu and receive the user's
+choice. You can use keymaps for this also. @xref{Pop-Up Menus}.
+
+@node Keyboard Menus
+@subsection Menus and the Keyboard
+
+When a prefix key ending with a keyboard event (a character or function
+key) has a definition that is a menu keymap, the user can use the
+keyboard to choose a menu item.
+
+Emacs displays the menu alternatives (the item strings of the bindings)
+in the echo area. If they don't all fit at once, the user can type
+@key{SPC} to see the next line of alternatives. Successive uses of
+@key{SPC} eventually get to the end of the menu and then cycle around to
+the beginning. (The variable @code{menu-prompt-more-char} specifies
+which character is used for this; @key{SPC} is the default.)
+
+When the user has found the desired alternative from the menu, he or she
+should type the corresponding character---the one whose binding is that
+alternative.
+
+In a menu intended for keyboard use, each menu item must clearly
+indicate what character to type. The best convention to use is to make
+the character the first letter of the item string. That is something
+users will understand without being told.
+
+This way of using menus in an Emacs-like editor was inspired by the
+Hierarkey system.
-@smallexample
-@group
-(global-unset-key "\C-l")
- @result{} nil
-@end group
-@group
-(global-set-key "\C-l\C-l" 'redraw-display)
- @result{} nil
-@end group
-@end smallexample
+@defvar menu-prompt-more-char
+This variable specifies the character to use to ask to see
+the next line of a menu. Its initial value is 32, the code
+for @key{SPC}.
+@end defvar
-This function is implemented simply using @code{define-key}:
+@node Menu Example
+@subsection Menu Example
-@smallexample
-@group
-(global-unset-key @var{key})
-@equiv{}
-(define-key (current-global-map) @var{key} nil)
-@end group
-@end smallexample
-@end deffn
+ Here is a simple example of how to set up a menu for mouse use.
-@deffn Command local-set-key key definition
- This function sets the binding of @var{key} in the current local
-keymap to @var{definition}.
+@example
+(defvar my-menu-map
+ (make-sparse-keymap "Key Commands <==> Functions"))
+(fset 'help-for-keys my-menu-map)
-@smallexample
-@group
-(local-set-key @var{key} @var{definition})
-@equiv{}
-(define-key (current-local-map) @var{key} @var{definition})
-@end group
-@end smallexample
-@end deffn
+(define-key my-menu-map [bindings]
+ '("List all keystroke commands" . describe-bindings))
+(define-key my-menu-map [key]
+ '("Describe key briefly" . describe-key-briefly))
+(define-key my-menu-map [key-verbose]
+ '("Describe key verbose" . describe-key))
+(define-key my-menu-map [function]
+ '("Describe Lisp function" . describe-function))
+(define-key my-menu-map [where-is]
+ '("Where is this command" . where-is))
-@deffn Command local-unset-key key
- This function removes the binding of @var{key} from the current
-local map.
+(define-key global-map [C-S-down-mouse-1] 'help-for-keys)
+@end example
-@smallexample
-@group
-(local-unset-key @var{key})
-@equiv{}
-(define-key (current-local-map) @var{key} nil)
-@end group
-@end smallexample
-@end deffn
+ The symbols used in the key sequences bound in the menu are fictitious
+``function keys''; they don't appear on the keyboard, but that doesn't
+stop you from using them in the menu. Their names were chosen to be
+mnemonic, because they show up in the output of @code{where-is} and
+@code{apropos} to identify the corresponding menu items.
-@node Scanning Keymaps
-@section Scanning Keymaps
+ However, if you want the menu to be usable from the keyboard as well,
+you must bind real @sc{ASCII} characters as well as fictitious function
+keys.
- This section describes functions used to scan all the current keymaps
-for the sake of printing help information.
+@node Menu Bar
+@subsection The Menu Bar
+@cindex menu bar
-@defun accessible-keymaps keymap &optional prefix
-This function returns a list of all the keymaps that can be accessed
-(via prefix keys) from @var{keymap}. The value is an association list
-with elements of the form @code{(@var{key} .@: @var{map})}, where
-@var{key} is a prefix key whose definition in @var{keymap} is
-@var{map}.
+ Most window systems allow each frame to have a @dfn{menu bar}---a
+permanently displayed menu stretching horizontally across the top of the
+frame. The items of the menu bar are the subcommands of the fake
+``function key'' @code{menu-bar}, as defined by all the active keymaps.
-The elements of the alist are ordered so that the @var{key} increases
-in length. The first element is always @code{("" .@: @var{keymap})},
-because the specified keymap is accessible from itself with a prefix of
-no events.
+ To add an item to the menu bar, invent a fake ``function key'' of your
+own (let's call it @var{key}), and make a binding for the key sequence
+@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap,
+so that pressing a button on the menu bar item leads to another menu.
-If @var{prefix} is given, it should be a prefix key sequence; then
-@code{accessible-keymaps} includes only the submaps whose prefixes start
-with @var{prefix}. These elements look just as they do in the value of
-@code{(accessible-keymaps)}; the only difference is that some elements
-are omitted.
+ When more than one active keymap defines the same fake function key
+for the menu bar, the item appears just once. If the user clicks on
+that menu bar item, it brings up a single, combined submenu containing
+all the subcommands of that item---the global subcommands, the local
+subcommands, and the minor mode subcommands, all together.
-In the example below, the returned alist indicates that the key
-@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
-definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
-(115 .@: foo))}.
+ In order for a frame to display a menu bar, its @code{menu-bar-lines}
+parameter must be greater than zero. Emacs uses just one line for the
+menu bar itself; if you specify more than one line, the other lines
+serve to separate the menu bar from the windows in the frame. We
+recommend you try 1 or 2 as the value of @code{menu-bar-lines}. @xref{X
+Frame Parameters}.
-@smallexample
-@group
-(accessible-keymaps (current-local-map))
-@result{}(("" keymap
- (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
- (83 . center-paragraph)
- (115 . center-line))
- (9 . tab-to-tab-stop))
-@end group
+ Here's an example of setting up a menu bar item:
+@example
@group
- ("^[" keymap
- (83 . center-paragraph)
- (115 . foo)))
+(modify-frame-parameters (selected-frame)
+ '((menu-bar-lines . 2)))
@end group
-@end smallexample
-In the following example, @kbd{C-h} is a prefix key that uses a sparse
-keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
-Another prefix, @kbd{C-x 4}, uses a keymap which happens to be
-@code{ctl-x-4-map}. The event @code{mode-line} is one of several dummy
-events used as prefixes for mouse actions in special parts of a window.
-
-@smallexample
-@group
-(accessible-keymaps (current-global-map))
-@result{} (("" keymap [set-mark-command beginning-of-line @dots{}
- delete-backward-char])
-@end group
-@group
- ("^H" keymap (118 . describe-variable) @dots{}
- (8 . help-for-help))
-@end group
@group
- ("^X" keymap [x-flush-mouse-queue @dots{}
- backward-kill-sentence])
+;; @r{Make a menu keymap (with a prompt string)}
+;; @r{and make it the menu bar item's definition.}
+(define-key global-map [menu-bar words]
+ (cons "Words" (make-sparse-keymap "Words")))
@end group
+
@group
- ("^[" keymap [mark-sexp backward-sexp @dots{}
- backward-kill-word])
+;; @r{Define specific subcommands in the item's menu.}
+(define-key global-map
+ [menu-bar words forward]
+ '("Forward word" . forward-word))
@end group
- ("^X4" keymap (15 . display-buffer) @dots{})
@group
- ([mode-line] keymap
- (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
+(define-key global-map
+ [menu-bar words backward]
+ '("Backward word" . backward-word))
@end group
-@end smallexample
+@end example
-@noindent
-These are not all the keymaps you would see in an actual case.
-@end defun
+ A local keymap can cancel a menu bar item made by the global keymap by
+rebinding the same fake function key with @code{undefined} as the
+binding. For example, this is how Dired suppresses the @samp{Edit} menu
+bar item:
-@defun where-is-internal command &optional keymap firstonly noindirect
-This function returns a list of key sequences (of any length) that are
-bound to @var{command} in a set of keymaps.
+@example
+(define-key dired-mode-map [menu-bar edit] 'undefined)
+@end example
-The argument @var{command} can be any object; it is compared with all
-keymap entries using @code{eq}.
+@noindent
+@code{edit} is the fake function key used by the global map for the
+@samp{Edit} menu bar item. The main reason to suppress a global
+menu bar item is to regain space for mode-specific items.
-If @var{keymap} is @code{nil}, then the maps used are the current active
-keymaps, disregarding @code{overriding-local-map} (that is, pretending
-its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the
-maps searched are @var{keymap} and the global keymap.
+@defvar menu-bar-final-items
+Normally the menu bar shows global items followed by items defined by the
+local maps.
-Usually it's best to use @code{overriding-local-map} as the expression
-for @var{keymap}. Then @code{where-is-internal} searches precisely the
-keymaps that are active. To search only the global map, pass
-@code{(keymap)} (an empty keymap) as @var{keymap}.
+This variable holds a list of fake function keys for items to display at
+the end of the menu bar rather than in normal sequence. The default
+value is @code{(help)}; thus, the @samp{Help} menu item normally appears
+at the end of the menu bar, following local menu items.
+@end defvar
-If @var{firstonly} is @code{non-ascii}, then the value is a single
-string representing the first key sequence found, rather than a list of
-all possible key sequences. If @var{firstonly} is @code{t}, then the
-value is the first key sequence, except that key sequences consisting
-entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII}
-characters) are preferred to all other key sequences.
+@node Modifying Menus
+@subsection Modifying Menus
-If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
-follow indirections to other keymaps or slots. This makes it possible
-to search for an indirect definition itself.
+ When you insert a new item in an existing menu, you probably want to
+put it in a particular place among the menu's existing items. If you
+use @code{define-key} to add the item, it normally goes at the front of
+the menu. To put it elsewhere, use @code{define-key-after}:
-This function is used by @code{where-is} (@pxref{Help, , Help, emacs,
-The GNU Emacs Manual}).
+@defun define-key-after map key binding after
+Define a binding in @var{map} for @var{key}, with value @var{binding},
+just like @code{define-key}, but position the binding in @var{map} after
+the binding for the event @var{after}. For example,
-@smallexample
-@group
-(where-is-internal 'describe-function)
- @result{} ("\^hf" "\^hd")
-@end group
-@end smallexample
-@end defun
+@example
+(define-key-after my-menu [drink]
+ '("Drink" . drink-command) 'eat)
+@end example
-@deffn Command describe-bindings prefix
-This function creates a listing of all defined keys, and their
-definitions. It writes the listing in a buffer named @samp{*Help*} and
-displays it in a window.
+@noindent
+makes a binding for the fake function key @key{drink} and puts it
+right after the binding for @key{eat}.
-The listing describes meta characters as @key{ESC} followed by the
-corresponding non-meta character.
+Here is how to insert an item called @samp{Work} in the @samp{Signals}
+menu of Shell mode, after the item @code{break}:
-When several characters with consecutive @sc{ASCII} codes have the
-same definition, they are shown together, as
-@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
-know the @sc{ASCII} codes to understand which characters this means.
-For example, in the default global map, the characters @samp{@key{SPC}
-..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32,
-@kbd{~} is @sc{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 @code{self-insert-command}.
+@example
+(define-key-after
+ (lookup-key shell-mode-map [menu-bar signals])
+ [work] '("Work" . work-command) 'break)
+@end example
-If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
-listing includes only keys that start with @var{prefix}.
-@end deffn
+Note that @var{key} is a sequence containing just one event type, but
+@var{after} is just an event type (not a sequence).
+@end defun
projects / emacs.git / commitdiff