diff options
Diffstat (limited to 'lispref/keymaps.texi')
| -rw-r--r-- | lispref/keymaps.texi | 140 |
1 files changed, 72 insertions, 68 deletions
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index c626b46e544..a3bd320a676 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -295,9 +295,13 @@ does not bind any events. @end group @end example -If you specify @var{prompt}, that becomes the overall prompt string for -the keymap. The prompt string should be provided for menu keymaps -(@pxref{Defining Menus}). +If you specify @var{prompt}, that becomes the overall prompt string +for the keymap. You should specify this only for menu keymaps +(@pxref{Defining Menus}). A keymap with an overall prompt string will +always present a mouse menu or a keyboard menu if it is active for +looking up the next input event. Don't specify an overall prompt string +for the main map of a major or minor mode, because that would cause +the command loop to present a keyboard menu every time. @end defun @defun make-keymap &optional prompt @@ -569,35 +573,19 @@ string for the keymap. The prompt string should be given for menu keymaps of them are @dfn{active}, meaning that they participate in the interpretation of user input. All the active keymaps are used together to determine what command to execute when a key is entered. -Emacs searches these keymaps one by one, in a standard order, until it -finds a binding in one of the keymaps. Normally the active keymaps are the @code{keymap} property keymap, the keymaps of any enabled minor modes, the current buffer's local -keymap, and the global keymap, in that order. Therefore, Emacs -searches for each input key sequence in all these keymaps. Here is a -pseudo-Lisp description of how this process works: - -@lisp -(or (if overriding-terminal-local-map - (@var{find-in} overriding-terminal-local-map) - (if overriding-local-map - (@var{find-in} overriding-local-map) - (or (@var{find-in} (get-text-property (point) 'keymap)) - (@var{find-in-any} emulation-mode-map-alists) - (@var{find-in-any} minor-mode-overriding-map-alist) - (@var{find-in-any} minor-mode-map-alist) - (if (get-text-property (point) 'local-map) - (@var{find-in} (get-text-property (point) 'local-map)) - (@var{find-in} (current-local-map)))))) - (@var{find-in} (current-global-map))) -@end lisp +keymap, and the global keymap, in that order. Emacs searches for each +input key sequence in all these keymaps. @xref{Searching Keymaps}, +for more details of this procedure. -@noindent -Here, the pseudo-function @var{find-in} means to look up the key -sequence in a single map, and @var{find-in-any} means to search the -appropriate keymaps from an alist. (Searching a single keymap for a -binding is called @dfn{key lookup}; see @ref{Key Lookup}.) + When the key sequence starts with a mouse event (optionally preceded +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 +properties of the string override those of the buffer. The @dfn{global keymap} holds the bindings of keys that are defined regardless of the current buffer, such as @kbd{C-f}. The variable @@ -655,25 +643,28 @@ Normally it ignores @code{overriding-local-map} and non-@code{nil} then it pays attention to them. @end defun -@defun key-binding key &optional accept-defaults no-remap +@defun key-binding key &optional accept-defaults no-remap position This function returns the binding for @var{key} according to the current active keymaps. The result is @code{nil} if @var{key} is undefined in the keymaps. -@c Emacs 19 feature The argument @var{accept-defaults} controls checking for default bindings, as in @code{lookup-key} (above). -When @var{key} is a vector containing an input event, such as a mouse -click, @code{key-binding} first looks for the binding in the keymaps -that would be active at the position where the click was done. - When commands are remapped (@pxref{Remapping Commands}), @code{key-binding} normally processes command remappings so as to returns the remapped command that will actually be executed. However, if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores remappings and returns the binding directly specified for @var{key}. +If @var{key} starts with a mouse event (perhaps following a prefix +event), the maps to be consulted are determined based on the event's +position. Otherwise, they are determined based on the value of point. +However, you can override either of them by specifying @var{position}. +If @var{position} is non-@code{nil}, it should be either a buffer +position or an event position like the value of @code{event-start}. +Then the maps consulted are determined based on @var{position}. + An error is signaled if @var{key} is not a string or a vector. @example @@ -687,21 +678,22 @@ An error is signaled if @var{key} is not a string or a vector. @node Searching Keymaps @section Searching the Active Keymaps - After translation of event subsequences (@pxref{Translation Keymaps}) -Emacs looks for them in the active keymaps. Here is a pseudo-Lisp -description of the order in which the active keymaps are searched: + After translation of event subsequences (@pxref{Translation +Keymaps}) Emacs looks for them in the active keymaps. Here is a +pseudo-Lisp description of the order and conditions for searching +them: @lisp (or (if overriding-terminal-local-map (@var{find-in} overriding-terminal-local-map) (if overriding-local-map (@var{find-in} overriding-local-map) - (or (@var{find-in} (get-text-property (point) 'keymap)) + (or (@var{find-in} (get-char-property (point) 'keymap)) (@var{find-in-any} emulation-mode-map-alists) (@var{find-in-any} minor-mode-overriding-map-alist) (@var{find-in-any} minor-mode-map-alist) (if (get-text-property (point) 'local-map) - (@var{find-in} (get-text-property (point) 'local-map)) + (@var{find-in} (get-char-property (point) 'local-map)) (@var{find-in} (current-local-map)))))) (@var{find-in} (current-global-map))) @end lisp @@ -709,6 +701,12 @@ description of the order in which the active keymaps are searched: @noindent The @var{find-in} and @var{find-in-any} are pseudo functions that search in one keymap and in an alist of keymaps, respectively. +(Searching a single keymap for a binding is called @dfn{key lookup}; +see @ref{Key Lookup}.) If the key sequence starts with a mouse event, +or a symbolic prefix event followed by a mouse event, that event's +position is used instead of point and the current buffer. Mouse +events on an embedded string use non-@code{nil} text properties from +that string instead of the buffer. @enumerate @item @@ -1470,11 +1468,13 @@ does not have the effect of remapping @code{kill-line} into if an ordinary binding specifies @code{my-kill-line}, this keymap will remap it to @code{my-other-kill-line}. -@defun command-remapping command +@defun command-remapping command &optional position 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{nil}. @code{position} can optionally specify a buffer position +or an event position to determine the keymaps to use, as in +@code{key-binding}. @end defun @node Translation Keymaps @@ -1904,15 +1904,16 @@ instead of the current buffer's. @section Menu Keymaps @cindex menu keymaps -@c Emacs 19 feature -A keymap can define a menu as well as bindings for keyboard keys and -mouse button. Menus are usually actuated with the mouse, but they can -work with the keyboard also. +A keymap can operate as a menu as well as defining bindings for +keyboard keys and mouse buttons. Menus are usually actuated with the +mouse, but they can function with the keyboard also. If a menu keymap +is active for the next input event, that activates the keyboard 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 they actuate it with the keyboard. +* 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. @@ -1925,20 +1926,21 @@ work with the keyboard also. @cindex menu prompt string @cindex prompt string (of menu) -A keymap is suitable for menu use if it has an @dfn{overall prompt -string}, which is a string that appears as an element of the keymap. +A keymap acts as a menu if it has an @dfn{overall prompt string}, +which is a string that appears as an element of the keymap. (@xref{Format of Keymaps}.) The string should describe the purpose of the menu's commands. Emacs displays the overall prompt string as the menu title in some cases, depending on the toolkit (if any) used for displaying menus.@footnote{It is required for menus which do not use a -toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the overall -prompt string. +toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the +overall prompt string. -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}, +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}, @code{make-sparse-keymap} (@pxref{Creating Keymaps}), or -@code{define-prefix-command} (@pxref{Definition of define-prefix-command}). - +@code{define-prefix-command} (@pxref{Definition of +define-prefix-command}). If you do not want the keymap to operate as +a menu, don't specify a prompt string for it. @defun keymap-prompt keymap This function returns the overall prompt string of @var{keymap}, @@ -2296,21 +2298,23 @@ separate panes or separate submenus. @node Keyboard Menus @subsection Menus and the Keyboard -When a prefix key ending with a keyboard event (a character or function -key) has a definition that is a menu keymap, the user can use the -keyboard to choose a menu item. + When a prefix key ending with a keyboard event (a character or +function key) has a definition that is a menu keymap, the keymap +operates as a keyboard menu; the user specifies the next event by +choosing a menu item with the keyboard. -Emacs displays the menu's overall prompt string followed by the -alternatives (the item strings of the bindings) in the echo area. If -the bindings don't all fit at once, the user can type @key{SPC} to see -the next line of alternatives. Successive uses of @key{SPC} eventually -get to the end of the menu and then cycle around to the beginning. (The -variable @code{menu-prompt-more-char} specifies which character is used -for this; @key{SPC} is the default.) + Emacs displays the keyboard menu with the map's overall prompt +string, followed by the alternatives (the item strings of the map's +bindings), in the echo area. If the bindings don't all fit at once, +the user can type @key{SPC} to see the next line of alternatives. +Successive uses of @key{SPC} eventually get to the end of the menu and +then cycle around to the beginning. (The variable +@code{menu-prompt-more-char} specifies which character is used for +this; @key{SPC} is the default.) -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. + 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 @@ -2321,7 +2325,7 @@ 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 + This way of using menus in an Emacs-like editor was inspired by the Hierarkey system. @defvar menu-prompt-more-char |