@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 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../info/keymaps
+@setfilename ../../info/keymaps
@node Keymaps, Modes, Command Loop, Top
@chapter Keymaps
@cindex keymap
@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
@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
This section describes keymaps that are used during reading a key
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{function-key-map} and then
-against @code{key-translation-map}.
+being read, as it is read, against @code{input-decode-map}, then
+@code{local-function-key-map}, and then against @code{key-translation-map}.
-@defvar function-key-map
+@defvar input-decode-map
This variable holds a keymap that describes the character sequences sent
by function keys on an ordinary character terminal. This keymap has the
same structure as other keymaps, but is used differently: it specifies
translations to make while reading key sequences, rather than bindings
for key sequences.
-If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
+If @code{input-decode-map} ``binds'' a key sequence @var{k} to a vector
@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
key sequence, it is replaced with the events in @var{v}.
keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
that sequence of events into the single event @code{pf1}. We accomplish
this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
-@code{function-key-map}, when using a VT100.
+@code{input-decode-map}, when using a VT100.
Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
@key{ESC} O P}; later the function @code{read-key-sequence} translates
this back into @kbd{C-c @key{PF1}}, which it returns as the vector
@code{[?\C-c pf1]}.
-Entries in @code{function-key-map} are ignored if they conflict with
-bindings made in the minor mode, local, or global keymaps. The intent
-is that the character sequences that function keys send should not have
-command bindings in their own right---but if they do, the ordinary
-bindings take priority.
-
-The value of @code{function-key-map} is usually set up automatically
+The value of @code{input-decode-map} is usually set up automatically
according to the terminal's Terminfo or Termcap entry, but sometimes
those need help from terminal-specific Lisp files. Emacs comes with
terminal-specific files for many common terminals; their main purpose is
-to make entries in @code{function-key-map} beyond those that can be
+to make entries in @code{input-decode-map} beyond those that can be
deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
@end defvar
-@defvar key-translation-map
-This variable is another keymap used just like @code{function-key-map}
-to translate input events into other events. It differs from
-@code{function-key-map} in two ways:
+@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}.
-@itemize @bullet
-@item
-@code{key-translation-map} goes to work after @code{function-key-map} is
-finished; it receives the results of translation by
-@code{function-key-map}.
+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.
-@item
-Non-prefix bindings in @code{key-translation-map} override actual key
-bindings. For example, if @kbd{C-x f} has a non-prefix binding in
-@code{key-translation-map}, that translation takes effect even though
-@kbd{C-x f} also has a key binding in the global map.
-@end itemize
+@code{local-function-key-map} inherits from @code{function-key-map},
+but the latter should not be used directly.
+@end defvar
-Note however that actual key bindings can have an effect on
+@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{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{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.
+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{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
button in disabled state by applying an edge-detection algorithm to the
image.
+The @code{:rtl} property specifies an alternative image to use for
+right-to-left languages. Only the Gtk+ version of Emacs supports this
+at present.
+
The default tool bar is defined so that items specific to editing do not
appear for major modes whose command symbol has a @code{mode-class}
property of @code{special} (@pxref{Major Mode Conventions}). Major