@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2002, 2003,
+@c 2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
The bindings between input events and commands are recorded in data
structures called @dfn{keymaps}. Each binding in a keymap associates
-(or @dfn{binds}) an individual event type either to another keymap or to
+(or @dfn{binds}) an individual event type, either to another keymap or to
a command. When an event type is bound to a keymap, that keymap is used
to look up the next input event; this continues until a command is
found. The whole process is called @dfn{key lookup}.
@end group
@group
(keymap
- ;; @key{TAB}
- (9 . lisp-indent-line)
+ (3 keymap
+ ;; @kbd{C-c C-z}
+ (26 . run-lisp))
@end group
@group
- ;; @key{DEL}
- (127 . backward-delete-char-untabify)
+ (27 keymap
+ ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
+ (24 . lisp-send-defun)
+ keymap
+ ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
+ (17 . indent-sexp)))
@end group
@group
- (3 keymap
- ;; @kbd{C-c C-l}
- (12 . run-lisp))
+ ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
+ keymap
+ ;; @key{DEL}
+ (127 . backward-delete-char-untabify)
@end group
@group
(27 keymap
;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp)
- ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
- (24 . lisp-send-defun)))
+ (17 . indent-sexp))
+ (9 . lisp-indent-line))
@end group
@end example
Here we describe the functions for creating keymaps.
-@c ??? This should come after make-sparse-keymap
-@defun make-keymap &optional prompt
-This function creates and returns a new full keymap. That keymap
-contains a char-table (@pxref{Char-Tables}) with slots for all
-characters without modifiers. The new keymap initially binds all
-these characters to @code{nil}, and does not bind any other kind of
-event.
+@defun make-sparse-keymap &optional prompt
+This function creates and returns a new sparse keymap with no entries.
+(A sparse keymap is the kind of keymap you usually want.) The new
+keymap does not contain a char-table, unlike @code{make-keymap}, and
+does not bind any events.
@example
@group
-(make-keymap)
- @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
+(make-sparse-keymap)
+ @result{} (keymap)
@end group
@end example
(@pxref{Defining Menus}).
@end defun
-@defun make-sparse-keymap &optional prompt
-This function creates and returns a new sparse keymap with no entries.
-The new keymap does not contain a char-table, unlike @code{make-keymap},
-and does not bind any events. The argument @var{prompt} specifies a
-prompt string, as in @code{make-keymap}.
+@defun make-keymap &optional prompt
+This function creates and returns a new full keymap. That keymap
+contains a char-table (@pxref{Char-Tables}) with slots for all
+characters without modifiers. The new keymap initially binds all
+these characters to @code{nil}, and does not bind any other kind of
+event. The argument @var{prompt} specifies a
+prompt string, as in @code{make-sparse-keymap}.
@example
@group
-(make-sparse-keymap)
- @result{} (keymap)
+(make-keymap)
+ @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
@end group
@end example
+
+A full keymap is more efficient than a sparse keymap when it holds
+lots of bindings; for just a few, the sparse keymap is better.
@end defun
@defun copy-keymap keymap
key.
@item
-@cindex @kbd{M-g}
+@cindex @kbd{M-o}
@vindex facemenu-keymap
-@code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
+@code{facemenu-keymap} is the global keymap used for the @kbd{M-o}
prefix key.
@c Emacs 19 feature
@item
-The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x
-@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have no
-special names.
+The other Emacs prefix keys are @kbd{M-g}, @kbd{C-x @@}, @kbd{C-x a i},
+@kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps
+that have no special names.
@end itemize
The keymap binding of a prefix key is used for looking up the event
text or overlay property. If that is non-@code{nil}, it is the first
keymap to be processed, in normal circumstances.
- However, there are also special circumstances, ways programs can
-substitute other keymaps for some of those. The variable
+ However, there are also special ways for program can to substitute
+other keymaps for some of those. The variable
@code{overriding-local-map}, if non-@code{nil}, specifies a keymap
that replaces all the usual active keymaps except the global keymap.
Another way to do this is with @code{overriding-terminal-local-map};
@c Emacs 19 feature
@defvar minor-mode-map-alist
+@anchor{Definition of 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:
not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose
function definition is a keymap.
-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
+When more than one minor mode keymap is active, the earlier one in
+@code{minor-mode-map-alist} takes priority. 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.
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
+lookup may designate a mouse event with just its types (a symbol)
+instead of the entire event (a list). @xref{Input Events}. Such
a ``key-sequence'' is insufficient for @code{command-execute} to run,
but it is sufficient for looking up or rebinding a key.
@code{C-H-left}. One advantage of such lists is that the precise
numeric codes for the modifier bits don't appear in compiled files.
- 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
+ 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.
+that are lists. The @code{kbd} macro (@pxref{Keymap Terminology}) is
+a convenient way to specify the key sequence.
@defun define-key keymap key binding
This function sets the binding for @var{key} in @var{keymap}. (If
@defun suppress-keymap keymap &optional nodigits
@cindex @code{self-insert-command} override
This function changes the contents of the full keymap @var{keymap} by
-making all the printing characters undefined. More precisely, it binds
-them to the command @code{undefined}. This makes ordinary insertion of
-text impossible. @code{suppress-keymap} returns @code{nil}.
+remapping @code{self-insert-command} to the command @code{undefined}
+(@pxref{Remapping Commands}). This has the effect of undefining all
+printing characters, thus making ordinary insertion of text impossible.
+@code{suppress-keymap} returns @code{nil}.
If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
digits to run @code{digit-argument}, and @kbd{-} to run
instead of @code{kill-line} and @code{kill-word}. It can establish
this by making these two command-remapping bindings in its keymap:
-@example
+@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap kill-word] 'my-kill-word)
-@end example
+@end smallexample
Whenever @code{my-mode-map} is an active keymap, if the user types
@kbd{C-k}, Emacs will find the standard global binding of
Remapping only works through a single level. In other words,
-@example
+@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
-@end example
+@end smallexample
@noindent
does not have the effect of remapping @code{kill-line} into
@end smallexample
@noindent
-redefines the first (leftmost) mouse button, typed with the Meta key, to
+redefines the first (leftmost) mouse button, entered with the Meta key, to
set point where you click.
@cindex non-@acronym{ASCII} text in keybindings
construct the key sequence string using @code{multibyte-char-to-unibyte}
or @code{string-make-unibyte} (@pxref{Converting Representations}).
-@deffn Command global-set-key key definition
+@deffn Command global-set-key key binding
This function sets the binding of @var{key} in the current global map
-to @var{definition}.
+to @var{binding}.
@smallexample
@group
-(global-set-key @var{key} @var{definition})
+(global-set-key @var{key} @var{binding})
@equiv{}
-(define-key (current-global-map) @var{key} @var{definition})
+(define-key (current-global-map) @var{key} @var{binding})
@end group
@end smallexample
@end deffn
@end smallexample
@end deffn
-@deffn Command local-set-key key definition
+@deffn Command local-set-key key binding
This function sets the binding of @var{key} in the current local
-keymap to @var{definition}.
+keymap to @var{binding}.
@smallexample
@group
-(local-set-key @var{key} @var{definition})
+(local-set-key @var{key} @var{binding})
@equiv{}
-(define-key (current-local-map) @var{key} @var{definition})
+(define-key (current-local-map) @var{key} @var{binding})
@end group
@end smallexample
@end deffn
describe the action of the command it corresponds to. Note that it is
not generally possible to display non-@acronym{ASCII} text in menus. It will
work for keyboard menus and will work to a large extent when Emacs is
-built with Gtk+ support.@footnote{In this case, the text is first
+built with the Gtk+ toolkit.@footnote{In this case, the text is first
encoded using the @code{utf-8} coding system and then rendered by the
toolkit as it sees fit.}
The property value @var{filter-fn} should be a function of one argument;
when it is called, its argument will be @var{real-binding}. The
function should return the binding to use instead.
+
+Emacs can call this function at any time that it does redisplay or
+operates on menu data structures, so you should write it so it can
+safely be called at any time.
@end table
@node Menu Separators
That specifies the default kind of separator. (For compatibility,
@code{""} and @code{-} also count as separators.)
- Starting in Emacs 21, certain other values of @var{separator-type}
-specify a different style of separator. Here is a table of them:
+ Certain other values of @var{separator-type} specify a different
+style of separator. Here is a table of them:
@table @code
@item "--no-line"
special about @samp{@@} at the beginning of an item string is that the
@samp{@@} doesn't appear in the menu item.
- You can also produce multiple panes or submenus 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 (when Emacs does not use an
-X-toolkit) or a separate submenu (when using an X-toolkit).
-@xref{Active Keymaps}.
+ Multiple keymaps that define the same menu prefix key produce
+separate panes or separate submenus.
@node Keyboard Menus
@subsection Menus and the Keyboard
@cindex menu definition example
Here is a complete example of defining a menu keymap. It is the
-definition of the @samp{Print} submenu in the @samp{Tools} menu in the
-menu bar, and it uses the simple menu item format (@pxref{Simple Menu
-Items}). First we create the keymap, and give it a name:
+definition of the @samp{Replace} submenu in the @samp{Edit} menu in
+the menu bar, and it uses the extended menu item format
+(@pxref{Extended Menu Items}). First we create the keymap, and give
+it a name:
-@example
-(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
-@end example
+@smallexample
+(defvar menu-bar-replace-menu (make-sparse-keymap "Replace"))
+@end smallexample
@noindent
Next we define the menu items:
-@example
-(define-key menu-bar-print-menu [ps-print-region]
- '("Postscript Print Region" . ps-print-region-with-faces))
-(define-key menu-bar-print-menu [ps-print-buffer]
- '("Postscript Print Buffer" . ps-print-buffer-with-faces))
-(define-key menu-bar-print-menu [separator-ps-print]
- '("--"))
-(define-key menu-bar-print-menu [print-region]
- '("Print Region" . print-region))
-(define-key menu-bar-print-menu [print-buffer]
- '("Print Buffer" . print-buffer))
-@end example
+@smallexample
+(define-key menu-bar-replace-menu [tags-repl-continue]
+ '(menu-item "Continue Replace" tags-loop-continue
+ :help "Continue last tags replace operation"))
+(define-key menu-bar-replace-menu [tags-repl]
+ '(menu-item "Replace in tagged files" tags-query-replace
+ :help "Interactively replace a regexp in all tagged files"))
+(define-key menu-bar-replace-menu [separator-replace-tags]
+ '(menu-item "--"))
+;; @r{@dots{}}
+@end smallexample
@noindent
Note the symbols which the bindings are ``made for''; these appear
The binding whose definition is @code{("--")} is a separator line.
Like a real menu item, the separator has a key symbol, in this case
-@code{separator-ps-print}. If one menu has two separators, they must
-have two different key symbols.
-
- Here is code to define enable conditions for two of the commands in
-the menu:
-
-@example
-(put 'print-region 'menu-enable 'mark-active)
-(put 'ps-print-region-with-faces 'menu-enable 'mark-active)
-@end example
+@code{separator-replace-tags}. If one menu has two separators, they
+must have two different key symbols.
Here is how we make this menu appear as an item in the parent menu:
@example
-(define-key menu-bar-tools-menu [print]
- (cons "Print" menu-bar-print-menu))
+(define-key menu-bar-edit-menu [replace]
+ (list 'menu-item "Replace" menu-bar-replace-menu))
@end example
@noindent
Note that this incorporates the submenu keymap, which is the value of
-the variable @code{menu-bar-print-menu}, rather than the symbol
-@code{menu-bar-print-menu} itself. Using that symbol in the parent menu
-item would be meaningless because @code{menu-bar-print-menu} is not a
-command.
+the variable @code{menu-bar-replace-menu}, rather than the symbol
+@code{menu-bar-replace-menu} itself. Using that symbol in the parent
+menu item would be meaningless because @code{menu-bar-replace-menu} is
+not a command.
- If you wanted to attach the same print menu to a mouse click, you
+ If you wanted to attach the same replace menu to a mouse click, you
can do it this way:
@example
(define-key global-map [C-S-down-mouse-1]
- menu-bar-print-menu)
-@end example
-
- We could equally well use an extended menu item (@pxref{Extended Menu
-Items}) for @code{print-region}, like this:
-
-@example
-(define-key menu-bar-print-menu [print-region]
- '(menu-item "Print Region" print-region
- :enable mark-active))
-@end example
-
-@noindent
-With the extended menu item, the enable condition is specified
-inside the menu item itself. If we wanted to make this
-item disappear from the menu entirely when the mark is inactive,
-we could do it this way:
-
-@example
-(define-key menu-bar-print-menu [print-region]
- '(menu-item "Print Region" print-region
- :visible mark-active))
+ menu-bar-replace-menu)
@end example
@node Menu Bar
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.
+``function key'' @code{menu-bar}, as defined in the active keymaps.
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
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 1 or 2 as the value of @code{menu-bar-lines}. @xref{Window Frame
+recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout
Parameters}.
Here's an example of setting up a menu bar item:
@end defvar
@defvar menu-bar-update-hook
-This normal hook is run whenever the user clicks on the menu bar, before
-displaying a submenu. You can use it to update submenus whose contents
-should vary.
+This normal hook is run by redisplay to update the menu bar contents,
+before redisplaying the menu bar. You can use it to update submenus
+whose contents should vary. Since this hook is run frequently, we
+advise you to ensure that the functions it calls do not take much time
+in the usual case.
@end defvar
@node Tool Bar
A @dfn{tool bar} is a row of icons at the top of a frame, that execute
commands when you click on them---in effect, a kind of graphical menu
-bar. Emacs supports tool bars starting with version 21.
+bar.
The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
controls how many lines' worth of height to reserve for the tool bar. A