Add doc/ dependencies on emacsver.texi.

[gnu-emacs] / doc / lispref / keymaps.texi

diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 125c4f0e706f296bf34d61f125bcda106687388d..e1052a9912e6aedb452c3224f0753198a53dd46a 100644 (file)
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -1,7 +1,8 @@
 @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 -*-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   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c   Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/keymaps
 @node Keymaps, Modes, Command Loop, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/keymaps
 @node Keymaps, Modes, Command Loop, Top


@@ -16,19 +17,19 @@ used to look up the next input event; this continues until a command
 is found.  The whole process is called @dfn{key lookup}.
 
 @menu
 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.
 * 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.
 * 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.
 * 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.


@@ -36,7 +37,7 @@ is found.  The whole process is called @dfn{key lookup}.
 * 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.
 * 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
 @end menu
 
 @node Key Sequences


@@ -487,14 +488,12 @@ prefix key.
 @code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
 key.
 
 @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.
 
 @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
 @item
 @cindex @kbd{C-x 6}
 @vindex 2C-mode-map


@@ -507,17 +506,28 @@ key.
 @code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
 key.
 
 @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.
 
 @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
 @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
 @end itemize
 
   The keymap binding of a prefix key is used for looking up the event


@@ -605,7 +615,9 @@ by a symbolic prefix), the active keymaps are determined based on the
 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
 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
 
   The @dfn{global keymap} holds the bindings of keys that are defined
 regardless of the current buffer, such as @kbd{C-f}.  The variable


@@ -768,9 +780,11 @@ out with.
 @end defvar
 
 @defun current-global-map
 @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
 
 @example
 @group


@@ -804,6 +818,10 @@ keymap.
 @end example
 @end defun
 
 @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
 @defun current-minor-mode-maps
 This function returns a list of the keymaps of currently enabled minor modes.
 @end defun


@@ -881,7 +899,7 @@ If non-@code{nil}, this variable holds a keymap to use instead of
 or overlay keymaps, and all the minor mode keymaps.
 
 This variable is always local to the current terminal and cannot be
 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
 
 incremental search mode.
 @end defvar
 


@@ -1162,7 +1180,7 @@ The argument @var{accept-defaults} controls checking for default
 bindings, as in @code{lookup-key} (above).
 @end defun
 
 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
 @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


@@ -1208,7 +1226,7 @@ meta-prefix-char                    ; @r{The default value.}
 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}}.
 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
 
 @node Changing Key Bindings
 @section Changing Key Bindings


@@ -1513,7 +1531,7 @@ specifies a list of keymaps to search in.  This argument is ignored if
 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
 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
 
 @defvar input-decode-map
 This variable holds a keymap that describes the character sequences sent


@@ -1545,33 +1563,36 @@ to make entries in @code{input-decode-map} beyond those that can be
 deduced from Termcap and Terminfo.  @xref{Terminal-Specific}.
 @end defvar
 
 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}.
 
 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.
 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
 @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
 
 The intent of @code{key-translation-map} is for users to map one
 character set to another, including ordinary characters normally bound


@@ -1579,11 +1600,10 @@ to @code{self-insert-command}.
 @end defvar
 
 @cindex key translation function
 @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
 
 The key translation function receives one argument, which is the prompt
 that was specified in @code{read-key-sequence}---or @code{nil} if the


@@ -1614,7 +1634,7 @@ to turn the character that follows into a Hyper character:
         symbol
       (cons symbol (cdr e)))))
 
         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
 
 @end group
 @end example
 


@@ -1940,11 +1960,11 @@ is active for the next input event, that activates the keyboard menu
 feature.
 
 @menu
 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
 * Tool Bar::                    A tool bar is a row of images.
 * Modifying Menus::             How to add new items to a menu.
 @end menu


@@ -2394,10 +2414,10 @@ Next we define the menu items:
 @smallexample
 (define-key menu-bar-replace-menu [tags-repl-continue]
   '(menu-item "Continue Replace" tags-loop-continue
 @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
 (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{}}
 (define-key menu-bar-replace-menu [separator-replace-tags]
   '(menu-item "--"))
 ;; @r{@dots{}}


@@ -2451,9 +2471,13 @@ can do it this way:
 @cindex menu bar
 
   Most window systems allow each frame to have a @dfn{menu bar}---a
 @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
 
   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


@@ -2471,13 +2495,6 @@ determining the menu bar contents.  That is, the menu bar is computed
 from the keymaps that would be active if @code{overriding-local-map}
 were @code{nil}.  @xref{Active Keymaps}.
 
 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
   Here's an example of setting up a menu bar item:
 
 @example


@@ -2516,8 +2533,8 @@ bar item:
 @end example
 
 @noindent
 @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
 menu bar item is to regain space for mode-specific items.
 
 @defvar menu-bar-final-items


@@ -2538,6 +2555,23 @@ advise you to ensure that the functions it calls do not take much time
 in the usual case.
 @end defvar
 
 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
 @node Tool Bar
 @subsection Tool bars
 @cindex tool bar


@@ -2623,8 +2657,8 @@ using an indirection through @code{tool-bar-map}.
 By default, the global map binds @code{[tool-bar]} as follows:
 @example
 (global-set-key [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
 @end example
 @noindent
 Thus the tool bar map is derived dynamically from the value of variable


@@ -2684,7 +2718,7 @@ specifies the local map to make the definition in.  The argument
 @code{tool-bar-add-item-from-menu}.
 @end defun
 
 @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 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.


@@ -2692,6 +2726,9 @@ 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 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
 @end defvar
 
 @defvar auto-raise-tool-bar-buttons