@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 1998-2011 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/keymaps
@node Keymaps, Modes, Command Loop, Top
is found. The whole process is called @dfn{key lookup}.
@menu
-* Key Sequences:: Key sequences as Lisp objects.
+* Key Sequences:: Key sequences as Lisp objects.
* Keymap Basics:: Basic concepts of keymaps.
-* Format of Keymaps:: What a keymap looks like as a Lisp object.
-* Creating Keymaps:: Functions to create and copy keymaps.
-* Inheritance and Keymaps:: How one keymap can inherit the bindings
- of another keymap.
+* Format of Keymaps:: What a keymap looks like as a Lisp object.
+* Creating Keymaps:: Functions to create and copy keymaps.
+* Inheritance and Keymaps:: How one keymap can inherit the bindings
+ of another keymap.
* Prefix Keys:: Defining a key with a keymap as its definition.
* Active Keymaps:: How Emacs searches the active keymaps
for a key binding.
* Searching Keymaps:: A pseudo-Lisp summary of searching active maps.
* Controlling Active Maps:: Each buffer has a local keymap
to override the standard (global) bindings.
- A minor mode can also override them.
+ A minor mode can also override them.
* Key Lookup:: Finding a key's binding in one keymap.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
* Translation Keymaps:: Keymaps for translating sequences of events.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
-* Menu Keymaps:: Defining a menu as a keymap.
+* Menu Keymaps:: Defining a menu as a keymap.
@end menu
@node Key Sequences
@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
key.
-@c Emacs 19 feature
@item
@cindex @kbd{C-x 5}
@vindex ctl-x-5-map
@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
key.
-@c Emacs 19 feature
@item
@cindex @kbd{C-x 6}
@vindex 2C-mode-map
@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
key.
+@item
+@cindex @kbd{M-g}
+@vindex goto-map
+@code{goto-map} is the global keymap used for the @kbd{M-g} prefix
+key.
+
+@item
+@cindex @kbd{M-s}
+@vindex search-map
+@code{search-map} is the global keymap used for the @kbd{M-s} prefix
+key.
+
@item
@cindex @kbd{M-o}
@vindex facemenu-keymap
@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{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.
+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.
@end itemize
The keymap binding of a prefix key is used for looking up the event
position in that event. If the event happened on a string embedded
with a @code{display}, @code{before-string}, or @code{after-string}
property (@pxref{Special Properties}), the non-@code{nil} map
-properties of the string override those of the buffer.
+properties of the string override those of the buffer (if the
+underlying buffer text contains map properties in its text properties
+or overlays, they are ignored).
The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}. The variable
When commands are remapped (@pxref{Remapping Commands}),
@code{key-binding} normally processes command remappings so as to
-returns the remapped command that will actually be executed. However,
+return the remapped command that will actually be executed. However,
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
remappings and returns the binding directly specified for @var{key}.
them:
@lisp
-(or (if overriding-terminal-local-map
- (@var{find-in} overriding-terminal-local-map)
- (if overriding-local-map
- (@var{find-in} overriding-local-map)
- (or (@var{find-in} (get-char-property (point) 'keymap))
- (@var{find-in-any} emulation-mode-map-alists)
- (@var{find-in-any} minor-mode-overriding-map-alist)
- (@var{find-in-any} minor-mode-map-alist)
- (if (get-text-property (point) 'local-map)
- (@var{find-in} (get-char-property (point) 'local-map))
- (@var{find-in} (current-local-map))))))
+(or (cond
+ (overriding-terminal-local-map
+ (@var{find-in} overriding-terminal-local-map))
+ (overriding-local-map
+ (@var{find-in} overriding-local-map))
+ ((or (@var{find-in} (get-char-property (point) 'keymap))
+ (@var{find-in-any} emulation-mode-map-alists)
+ (@var{find-in-any} minor-mode-overriding-map-alist)
+ (@var{find-in-any} minor-mode-map-alist)
+ (if (get-text-property (point) 'local-map)
+ (@var{find-in} (get-char-property (point) 'local-map))
+ (@var{find-in} (current-local-map))))))
(@var{find-in} (current-global-map)))
@end lisp
@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.
+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.
+The return value is a reference, not a copy; if you use
+@code{define-key} or other functions on it you will alter global
+bindings.
@example
@group
@end example
@end defun
+@code{current-local-map} returns a reference to the local keymap, not
+a copy of it; if you use @code{define-key} or other functions on it
+you will alter local bindings.
+
@defun current-minor-mode-maps
This function returns a list of the keymaps of currently enabled minor modes.
@end defun
or overlay keymaps, and all the minor mode keymaps.
This variable is always local to the current terminal and cannot be
-buffer-local. @xref{Multiple Displays}. It is used to implement
+buffer-local. @xref{Multiple Terminals}. It is used to implement
incremental search mode.
@end defvar
bindings, as in @code{lookup-key} (above).
@end defun
-@defvar meta-prefix-char
+@defopt meta-prefix-char
@cindex @key{ESC}
This variable is the meta-prefix character code. It is used for
translating a meta character to a two-character sequence so it can be
This translation of one event into two happens only for characters, not
for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function
key, is not converted into @kbd{@key{ESC} @key{F1}}.
-@end defvar
+@end defopt
@node Changing Key Bindings
@section Changing Key Bindings
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.
+function; then you must explicitly specify the map to change.
When choosing the key sequences for Lisp programs to rebind, please
follow the Emacs conventions for use of various keys (@pxref{Key
@section Remapping Commands
@cindex remapping commands
- A special kind of key binding, using a special ``key sequence''
-which includes a command name, has the effect of @dfn{remapping} that
-command into another. Here's how it works. You make a key binding
-for a key sequence that starts with the dummy event @code{remap},
-followed by the command name you want to remap. Specify the remapped
-definition as the definition in this binding. The remapped definition
-is usually a command name, but it can be any valid definition for
-a key binding.
+ A special kind of key binding can be used to @dfn{remap} one command
+to another, without having to refer to the key sequence(s) bound to
+the original command. To use this feature, make a key binding for a
+key sequence that starts with the dummy event @code{remap}, followed
+by the command name you want to remap; for the binding, specify the
+new definition (usually a command name, but possibly any other valid
+definition for a key binding).
- Here's an example. Suppose that My mode uses special commands
-@code{my-kill-line} and @code{my-kill-word}, which should be invoked
-instead of @code{kill-line} and @code{kill-word}. It can establish
-this by making these two command-remapping bindings in its keymap:
+ For example, suppose My mode provides a special command
+@code{my-kill-line}, which should be invoked instead of
+@code{kill-line}. To establish this, its mode keymap should contain
+the following remapping:
@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
-(define-key my-mode-map [remap kill-word] 'my-kill-word)
@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
-@code{kill-line} (assuming nobody has changed it). But
-@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
-so instead of running @code{kill-line}, Emacs runs
-@code{my-kill-line}.
+@noindent
+Then, whenever @code{my-mode-map} is active, if the user types
+@kbd{C-k} (the default global key sequence for @code{kill-line}) Emacs
+will instead run @code{my-kill-line}.
-Remapping only works through a single level. In other words,
+ Note that remapping only takes place through active keymaps; for
+example, putting a remapping in a prefix keymap like @code{ctl-x-map}
+typically has no effect, as such keymaps are not themselves active.
+In addition, remapping only works through a single level; in the
+following example,
@smallexample
(define-key my-mode-map [remap kill-line] 'my-kill-line)
@end smallexample
@noindent
-does not have the effect of remapping @code{kill-line} into
-@code{my-other-kill-line}. If an ordinary key binding specifies
-@code{kill-line}, this keymap will remap it to @code{my-kill-line};
-if an ordinary binding specifies @code{my-kill-line}, this keymap will
-remap it to @code{my-other-kill-line}.
+@code{kill-line} is @emph{not} remapped to @code{my-other-kill-line}.
+Instead, if an ordinary key binding specifies @code{kill-line}, it is
+remapped to @code{my-kill-line}; if an ordinary binding specifies
+@code{my-kill-line}, it is remapped to @code{my-other-kill-line}.
+
+To undo the remapping of a command, remap it to @code{nil}; e.g.
+
+@smallexample
+(define-key my-mode-map [remap kill-line] nil)
+@end smallexample
@defun command-remapping command &optional position keymaps
This function returns the remapping for @var{command} (a symbol),
sequence, to translate certain event sequences into others.
@code{read-key-sequence} checks every subsequence of the key sequence
being read, as it is read, against @code{input-decode-map}, then
-@code{function-key-map}, and then against @code{key-translation-map}.
+@code{local-function-key-map}, and then against @code{key-translation-map}.
@defvar input-decode-map
This variable holds a keymap that describes the character sequences sent
deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
@end defvar
-@defvar function-key-map
+@defvar local-function-key-map
This variable holds a keymap similar to @code{input-decode-map} except
that it describes key sequences which should be translated to
alternative interpretations that are usually preferred. It applies
after @code{input-decode-map} and before @code{key-translation-map}.
-Entries in @code{function-key-map} are ignored if they conflict with
-bindings made in the minor mode, local, or global keymaps. I.e.
+Entries in @code{local-function-key-map} are ignored if they conflict
+with bindings made in the minor mode, local, or global keymaps. I.e.
the remapping only applies if the original key sequence would
otherwise not have any binding.
+
+@code{local-function-key-map} inherits from @code{function-key-map},
+but the latter should not be used directly.
@end defvar
@defvar key-translation-map
This variable is another keymap used just like @code{input-decode-map}
to translate input events into other events. It differs from
@code{input-decode-map} in that it goes to work after
-@code{function-key-map} is finished rather than before; it receives
-the results of translation by @code{function-key-map}.
-
-Just like @code{input-decode-map}, but unlike @code{function-key-map},
-this keymap is applied regardless of whether the input key-sequence
-has a normal binding. Note however that actual key bindings can have
-an effect on @code{key-translation-map}, even though they are
-overridden by it. Indeed, actual key bindings override
-@code{function-key-map} and thus may alter the key sequence that
-@code{key-translation-map} receives. Clearly, it is better to avoid
-this type of situation.
+@code{local-function-key-map} is finished rather than before; it
+receives the results of translation by @code{local-function-key-map}.
+
+Just like @code{input-decode-map}, but unlike
+@code{local-function-key-map}, this keymap is applied regardless of
+whether the input key-sequence has a normal binding. Note however
+that actual key bindings can have an effect on
+@code{key-translation-map}, even though they are overridden by it.
+Indeed, actual key bindings override @code{local-function-key-map} and
+thus may alter the key sequence that @code{key-translation-map}
+receives. Clearly, it is better to avoid this type of situation.
The intent of @code{key-translation-map} is for users to map one
character set to another, including ordinary characters normally bound
@end defvar
@cindex key translation function
-You can use @code{input-decode-map}, @code{function-key-map}, or
-@code{key-translation-map} for
-more than simple aliases, by using a function, instead of a key
-sequence, as the ``translation'' of a key. Then this function is called
-to compute the translation of that key.
+You can use @code{input-decode-map}, @code{local-function-key-map}, or
+@code{key-translation-map} for more than simple aliases, by using a
+function, instead of a key sequence, as the ``translation'' of a key.
+Then this function is called to compute the translation of that key.
The key translation function receives one argument, which is the prompt
that was specified in @code{read-key-sequence}---or @code{nil} if the
symbol
(cons symbol (cdr e)))))
-(define-key function-key-map "\C-ch" 'hyperify)
+(define-key local-function-key-map "\C-ch" 'hyperify)
@end group
@end example
@noindent
and your language environment is multibyte Latin-1, these commands
-actually bind the multibyte character with code 2294, not the unibyte
-Latin-1 character with code 246 (@kbd{M-v}). In order to use this
-binding, you need to enter the multibyte Latin-1 character as keyboard
-input. One way to do this is by using an appropriate input method
-(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).
-
- If you want to use a unibyte character in the key binding, you can
-construct the key sequence string using @code{multibyte-char-to-unibyte}
-or @code{string-make-unibyte} (@pxref{Converting Representations}).
+actually bind the multibyte character with code 246, not the byte
+code 246 (@kbd{M-v}) sent by a Latin-1 terminal. In order to use this
+binding, you need to teach Emacs how to decode the keyboard by using an
+appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU
+Emacs Manual}).
@deffn Command global-set-key key binding
This function sets the binding of @var{key} in the current global map
feature.
@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 users actuate the menu with the keyboard.
-* Menu Example:: Making a simple menu.
-* Menu Bar:: How to customize the menu bar.
+* Defining Menus:: How to make a keymap that defines a menu.
+* Mouse Menus:: How users actuate the menu with the mouse.
+* Keyboard Menus:: How users actuate the menu with the keyboard.
+* Menu Example:: Making a simple menu.
+* Menu Bar:: How to customize the menu bar.
* Tool Bar:: A tool bar is a row of images.
* Modifying Menus:: How to add new items to a menu.
@end menu
@cindex defining menus
@cindex menu prompt string
@cindex prompt string (of menu)
+@cindex menu item
A keymap acts as a menu if it has an @dfn{overall prompt string},
which is a string that appears as an element of the keymap.
of menus in advance. To force recalculation of the menu bar, call
@code{force-mode-line-update} (@pxref{Mode Line Format}).
- 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{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding})
-@end example
-
-@noindent
-Don't put these sublists in the menu item yourself; menu display
-calculates them automatically. Don't mention keyboard equivalents in
-the item strings themselves, since that is redundant.
-
@node Extended Menu Items
@subsubsection Extended Menu Items
@kindex menu-item
+@cindex extended menu item
An extended-format menu item is a more flexible and also cleaner
alternative to the simple format. You define an event type with a
@var{item-property-list}, has the form of a property list which contains
other information.
- When an equivalent keyboard key binding is cached, the extended menu
-item binding looks like this:
-
-@example
-(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
- . @var{item-property-list})
-@end example
-
Here is a table of the properties that are supported:
@table @code
@smallexample
(define-key menu-bar-replace-menu [tags-repl-continue]
'(menu-item "Continue Replace" tags-loop-continue
- :help "Continue last tags replace operation"))
+ :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"))
+ :help "Interactively replace a regexp in all tagged files"))
(define-key menu-bar-replace-menu [separator-replace-tags]
'(menu-item "--"))
;; @r{@dots{}}
@cindex 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 in the active keymaps.
+permanently displayed menu stretching horizontally across the top of
+the frame. (In order for a frame to display a menu bar, its
+@code{menu-bar-lines} parameter must be greater than zero.
+@xref{Layout Parameters}.)
+
+ The items of the menu bar are the subcommands of the fake ``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
from the keymaps that would be active if @code{overriding-local-map}
were @code{nil}. @xref{Active Keymaps}.
- 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 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:
@example
@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
+Here, @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.
@defvar menu-bar-final-items
in the usual case.
@end defvar
+Next to every menu bar item, Emacs displays a key binding that runs
+the same command (if such a key binding exists). This serves as a
+convenient hint for users who do not know the key binding. If a
+command has multiple bindings, Emacs normally displays the first one
+it finds. You can specify one particular key binding by assigning an
+@code{:advertised-binding} symbol property to the command. For
+instance, the following tells Emacs to show @kbd{C-/} for the
+@code{undo} menu item:
+
+@smallexample
+(put 'undo :advertised-binding [?\C-/])
+@end smallexample
+
+@noindent
+If the @code{:advertised-binding} property specifies a key binding
+that the command does not actually have, it is ignored.
+
@node Tool Bar
@subsection Tool bars
@cindex tool bar
By default, the global map binds @code{[tool-bar]} as follows:
@example
(global-set-key [tool-bar]
- '(menu-item "tool bar" ignore
- :filter (lambda (ignore) tool-bar-map)))
+ '(menu-item "tool bar" ignore
+ :filter (lambda (ignore) tool-bar-map)))
@end example
@noindent
Thus the tool bar map is derived dynamically from the value of variable
@code{tool-bar-add-item-from-menu}.
@end defun
-@defvar auto-resize-tool-bar
+@defvar auto-resize-tool-bars
If this variable is non-@code{nil}, the tool bar automatically resizes to
show all defined tool bar items---but not larger than a quarter of the
frame's height.
If the value is @code{grow-only}, the tool bar expands automatically,
but does not contract automatically. To contract the tool bar, the
user has to redraw the frame by entering @kbd{C-l}.
+
+If Emacs is built with GTK or Nextstep, the tool bar can only show one
+line, so this variable has no effect.
@end defvar
@defvar auto-raise-tool-bar-buttons
[work] '("Work" . work-command) 'break)
@end example
@end defun
-
-@ignore
- arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794
-@end ignore
HCoop / bpt / emacs.git / blobdiff