keymaps; if this is not so, the sequence of events does not form a
unit---it is not really a key sequence. In other words, removing one or
more events from the end of any valid key must always yield a prefix
-key. For example, @kbd{C-f C-f} is not a key; @kbd{C-f} is not a prefix
+key. For example, @kbd{C-f C-n} is not a key; @kbd{C-f} is not a prefix
key, so a longer sequence starting with @kbd{C-f} cannot be a key.
Note that the set of possible multi-event key sequences depends on the
Here we describe the functions for creating keymaps.
+@c ??? This should come after makr-sparse-keymap
@defun make-keymap &optional prompt
This function creates and returns a new full keymap (i.e., one
containing a vector of length 128 for defining all the @sc{ASCII}
minor modes so that they don't interfere with each other. If you do
this properly, the order will not matter.
-See also @code{minor-mode-key-binding} in @ref{Functions for Key
-Lookup}. See @ref{Keymaps and Minor Modes}, for more information about
-minor modes.
+See also @code{minor-mode-key-binding}, above. See @ref{Keymaps and
+Minor Modes}, for more information about minor modes.
@end defvar
@defvar overriding-local-map
except for the current global map.
@end defvar
+@defvar overriding-terminal-local-map
+If non-@code{nil}, this variable holds a keymap to use instead of
+@code{overriding-local-map}, the buffer's local keymap 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
+incremental search mode.
+@end defvar
+
+@defvar overriding-local-map-menu-flag
+If this variable is non-@code{nil}, the value of
+@code{overriding-local-map} or @code{overriding-terminal-local-map} can
+affect the display of the menu bar. The default value is @code{nil}, so
+those map variables have no effect on the menu bar.
+
+Note that these two map variables do affect the execution of key
+sequences entered using the menu bar, even if they do not affect the
+menu bar display. So if a menu bar key sequence comes in, you should
+clear the variables before looking up and executing that key sequence.
+Modes that use the variables would typically do this anyway; normally
+they respond to events that they do not handle by ``unreading'' them and
+exiting.
+@end defvar
+
@node Key Lookup
@section Key Lookup
@cindex key lookup
The events used so far in the lookup form a complete key,
and @var{command} is its binding. @xref{What Is a Function}.
-@item @var{string}
-@itemx @var{vector}
+@item @var{array}
@cindex string in keymap
-The events used so far in the lookup form a complete key, whose
-binding is a keyboard macro. See @ref{Keyboard Macros}, for more
-information.
+The array (either a string or a vector) is a keyboard macro. The events
+used so far in the lookup form a complete key, and the array is its
+binding. See @ref{Keyboard Macros}, for more information.
@item @var{list}
@cindex list in keymap
This feature permits you to define one key as an alias for another key.
For example, an entry whose @sc{car} is the keymap called @code{esc-map}
-and whose @sc{cdr} is 32 (the code for space) means, ``Use the global
+and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
@end itemize
vectors, as well as others that aren't allowed in strings; one example
is @samp{[?\C-\H-x home]}. @xref{Character Type}.
+ The key definition and lookup functions accept an alternate syntax for
+event types in a key sequence that is a vector: you can use a list
+containing modifier names plus one base event (a character or function
+key name). For example, @code{(control ?a)} is equivalent to
+@code{?\C-a} and @code{(hyper control left)} is equivalent to
+@code{C-H-left}.
+
+ One advantage of using a list to represent the event type 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
sequence. You can use event types (symbols) as shorthand for events
(global-set-key [?\C-x ?\C-\\] 'next-line)
@end smallexample
+@noindent
+or
+
+@smallexample
+(global-set-key [(control ?x) (control ?\\)] 'next-line)
+@end smallexample
+
@noindent
redefines @kbd{C-x C-\} to move down a line.
Currently Emacs does not actually use @var{help-string}; it knows only
how to ignore @var{help-string} in order to extract @var{real-binding}.
-In the future we hope to make @var{help-string} serve as extended
-documentation for the menu item, available on request.
+In the future we may use @var{help-string} as extended documentation for
+the menu item, available on request.
If @var{real-binding} is @code{nil}, then @var{string} appears in the
menu but cannot be selected.
menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
cannot be selected with the mouse.
+The menu bar does not recalculate which items are enabled every time you
+look at a menu. This is because the X toolkit requires the whole tree
+of menus in advance. To force recalculation of the menu bar, call
+@code{force-mode-line-update} (@pxref{Mode Line Format}).
+
Sometimes it is useful to make menu items that use the ``same'' command
but with different enable conditions. You can do this by defining alias
commands. Here's an example that makes two aliases for
If an alias command has no keyboard equivalent itself, menus show the
keyboard equivalent of its underlying command. In the example above,
-menus items defined to run @code{make-read-only} or @code{make-writable}
+menu items defined to run @code{make-read-only} or @code{make-writable}
would show the keyboard equivalents of @code{toggle-read-only}.
@node Mouse Menus
should type the corresponding character---the one whose binding is that
alternative.
+@ignore
In a menu intended for keyboard use, each menu item must clearly
indicate what character to type. The best convention to use is to make
-the character the first letter of the item string. That is something
-users will understand without being told.
+the character the first letter of the item string---that is something
+users will understand without being told. We plan to change this; by
+the time you read this manual, keyboard menus may explicitly name the
+key for each alternative.
+@end ignore
This way of using menus in an Emacs-like editor was inspired by the
Hierarkey system.
all the subcommands of that item---the global subcommands, the local
subcommands, and the minor mode subcommands, all together.
+ The variable @code{overriding-local-map} is normally ignored when
+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}.
+
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 you try 1 or 2 as the value of @code{menu-bar-lines}. @xref{X
-Frame Parameters}.
+recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{X Frame
+Parameters}.
Here's an example of setting up a menu bar item:
HCoop / bpt / emacs.git / blobdiff