@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2002, 2003,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
a key sequence as an argument can handle both representations.
In the string representation, alphanumeric characters ordinarily
-stand for themselves; for example, @code{"a"} represents @kbd{a} and
+stand for themselves; for example, @code{"a"} represents @kbd{a}
and @code{"2"} represents @kbd{2}. Control character events are
prefixed by the substring @code{"\C-"}, and meta characters by
@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
(24 . lisp-send-defun)
keymap
;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp)))
+ (17 . indent-sexp))
@end group
@group
;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
@xref{Standard Keymaps}, for a list of standard keymaps.
-@defun current-active-maps &optional olp
+@defun current-active-maps &optional olp position
This returns the list of active keymaps that would be used by the
command loop in the current circumstances to look up a key sequence.
Normally it ignores @code{overriding-local-map} and
-@code{overriding-terminal-local-map}, but if @var{olp} is
-non-@code{nil} then it pays attention to them.
+@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil}
+then it pays attention to them. @var{position} can optionally be either
+an event position as returned by @code{event-start} or a buffer
+position, and may change the keymaps as described for
+@code{key-binding}.
@end defun
@defun key-binding key &optional accept-defaults no-remap position
undefined in the keymaps.
The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (above).
+bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}).
When commands are remapped (@pxref{Remapping Commands}),
@code{key-binding} normally processes command remappings so as to
@node Searching Keymaps
@section Searching the Active Keymaps
+@cindex searching active keymaps for keys
After translation of event subsequences (@pxref{Translation
Keymaps}) Emacs looks for them in the active keymaps. Here is a
does matter for menu keymaps (@pxref{Menu Keymaps}).
@end defun
- Here is an example that creates a sparse keymap and makes a number of
+ This example creates a sparse keymap and makes a number of
bindings in it:
@smallexample
if an ordinary binding specifies @code{my-kill-line}, this keymap will
remap it to @code{my-other-kill-line}.
-@defun command-remapping command &optional position
+@defun command-remapping command &optional position keymaps
This function returns the remapping for @var{command} (a symbol),
given the current active keymaps. If @var{command} is not remapped
(which is the usual situation), or not a symbol, the function returns
@code{nil}. @code{position} can optionally specify a buffer position
or an event position to determine the keymaps to use, as in
@code{key-binding}.
+
+If the optional argument @code{keymaps} is non-@code{nil}, it
+specifies a list of keymaps to search in. This argument is ignored if
+@code{position} is non-@code{nil}.
@end defun
@node Translation Keymaps
@section Keymaps for Translating Sequences of Events
+@cindex keymaps for translating events
This section describes keymaps that are used during reading a key
sequence, to translate certain event sequences into others.
@smallexample
@group
(where-is-internal 'describe-function)
- @result{} ("\^hf" "\^hd")
+ @result{} ([8 102] [f1 102] [help 102]
+ [menu-bar help-menu describe describe-function])
@end group
@end smallexample
@end defun
string. Thus, the string need not be a constant. The third element,
@var{real-binding}, is the command to execute. The tail of the list,
@var{item-property-list}, has the form of a property list which contains
-other information. Here is a table of the properties that are supported:
+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
@item :enable @var{form}
safely be called at any time.
@end table
- When an equivalent key binding is cached, the binding looks like this.
-
-@example
-(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
- . @var{item-property-list})
-@end example
-
@node Menu Separators
@subsubsection Menu Separators
@cindex menu separators
@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
contracts automatically as needed to hold the specified contents.
+ If the value of @code{auto-resize-tool-bars} 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}.
+
The tool bar contents are controlled by a menu keymap attached to a
fake ``function key'' called @code{tool-bar} (much like the way the menu
bar is controlled). So you define a tool bar item using
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}.
@end defvar
@defvar auto-raise-tool-bar-buttons