X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/87b2d5ff029e93b27ab4887608788fd3d2b8c7e7..ebfa69444dce5d5d807aaf0b067cd01259b85e51:/lispref/keymaps.texi diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 02bada65bc..e8edf59b2a 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -74,7 +74,7 @@ intermediate bindings (found for the events before the last) are all 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 @@ -207,6 +207,7 @@ otherwise. More precisely, this function tests for a list whose 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} @@ -570,9 +571,8 @@ is the order of @code{minor-mode-map-alist}. But you should design 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 @@ -582,6 +582,31 @@ keymap, if any, overrides all other maps that would have been active, 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 @@ -635,12 +660,11 @@ event of the key sequence is looked up in @var{keymap}. 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 @@ -670,7 +694,7 @@ binding of @var{othertype} in @var{othermap} and uses that. 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 @@ -913,6 +937,17 @@ containing a single @kbd{C-M-x}. You can also use this escape syntax in 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 @@ -1123,6 +1158,13 @@ or (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. @@ -1378,6 +1420,13 @@ the menu. The easiest way to construct a keymap with a prompt string is to specify the string as an argument when you call @code{make-keymap} or @code{make-sparse-keymap} (@pxref{Creating Keymaps}). +The order of items in the menu is the same as the order of bindings in +the keymap. Since @code{define-key} puts new bindings at the front, you +should define the menu items starting at the bottom of the menu and +moving to the top, if you care about the order. When you add an item to +an existing menu, you can specify its position in the menu using +@code{define-key-after} (@pxref{Modifying Menus}). + The individual bindings in the menu keymap should have item strings; these strings become the items displayed in the menu. A binding with an item string looks like this: @@ -1402,8 +1451,8 @@ You can also supply a second string, called the help string, as follows: 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. @@ -1416,12 +1465,22 @@ the menu item only if the expression's value is non-@code{nil}. When a menu item is disabled, it is displayed in a ``fuzzy'' fashion, and cannot be selected with the mouse. -The order of items in the menu is the same as the order of bindings in -the keymap. Since @code{define-key} puts new bindings at the front, you -should define the menu items starting at the bottom of the menu and -moving to the top, if you care about the order. When you add an item to -an existing menu, you can specify its position in the menu using -@code{define-key-after} (@pxref{Modifying Menus}). +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 +@code{toggle-read-only} and gives them different enable conditions: + +@example +(defalias 'make-read-only 'toggle-read-only) +(put 'make-read-only 'menu-enable '(not buffer-read-only)) +(defalias 'make-writable 'toggle-read-only) +(put 'make-writable 'menu-enable 'buffer-read-only) +@end example You've probably noticed that menu items show the equivalent keyboard key sequence (if any) to invoke the same command. To save time on @@ -1437,6 +1496,11 @@ Don't put these sublists in the menu item yourself; menu display calculates them automatically. Don't add keyboard equivalents to the item strings in a mouse menu, since that is redundant. +If an alias command has no keyboard equivalent itself, menus show the +keyboard equivalent of its underlying command. In the example above, +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 @subsection Menus and the Mouse @@ -1500,10 +1564,14 @@ When the user has found the desired alternative from the menu, he or she 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. @@ -1568,12 +1636,17 @@ that menu bar item, it brings up a single, combined submenu containing 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: @@ -1638,7 +1711,10 @@ the menu. To put it elsewhere, use @code{define-key-after}: @defun define-key-after map key binding after Define a binding in @var{map} for @var{key}, with value @var{binding}, just like @code{define-key}, but position the binding in @var{map} after -the binding for the event @var{after}. For example, +the binding for the event @var{after}. The argument @var{key} should +be of length one---a vector or string with just one element. + +For example, @example (define-key-after my-menu [drink]