X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/7c420169baa7c50428589cca7f8eda71b462eb15..a53925272ef3021c4536eff5ddb8b27b64d2b93b:/doc/lispref/keymaps.texi diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 4ecdaf0fa5..669f058ef1 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1,8 +1,6 @@ @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, 2008, 2009, 2010 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/keymaps @node Keymaps, Modes, Command Loop, Top @@ -175,13 +173,11 @@ ordinary binding applies to events of a particular @dfn{event type}, which is always a character or a symbol. @xref{Classifying Events}. In this kind of binding, @var{binding} is a command. -@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding}) +@item (@var{type} @var{item-name} .@: @var{binding}) This specifies a binding which is also a simple menu item that -displays as @var{item-name} in the menu. @var{cache}, if present, -caches certain information for display in the menu. @xref{Simple Menu -Items}. +displays as @var{item-name} in the menu. @xref{Simple Menu Items}. -@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding}) +@item (@var{type} @var{item-name} @var{help-string} .@: @var{binding}) This is a simple menu item with help string @var{help-string}. @item (@var{type} menu-item .@: @var{details}) @@ -236,8 +232,9 @@ other input events; thus, @kbd{M-@key{end}} has nothing to do with @kbd{@key{ESC} @key{end}}. Here as an example is the local keymap for Lisp mode, a sparse -keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c -C-l}, @kbd{M-C-q}, and @kbd{M-C-x}. +keymap. It defines bindings for @key{DEL}, @kbd{C-c C-z}, +@kbd{C-M-q}, and @kbd{C-M-x} (the actual value also contains a menu +binding, which is omitted here for the sake of brevity). @example @group @@ -252,11 +249,8 @@ lisp-mode-map @end group @group (27 keymap - ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}} - (24 . lisp-send-defun) - keymap - ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp)) + ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}} + (24 . lisp-send-defun)) @end group @group ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} @@ -266,9 +260,8 @@ lisp-mode-map @end group @group (27 keymap - ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp)) - (9 . lisp-indent-line)) + ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}} + (17 . indent-sexp))) @end group @end example @@ -434,6 +427,34 @@ for every numeric character code without modifier bits, even if it is @code{nil}, so these character's bindings are never inherited from the parent keymap. +@cindex keymap inheritance from multiple maps + Sometimes you want to make a keymap that inherits from more than one +map. You can use the function @code{make-composed-keymap} for this. + +@defun make-composed-keymap maps &optional parent +This function returns a new keymap composed of the existing keymap(s) +@var{maps}, and optionally inheriting from a parent keymap +@var{parent}. @var{maps} can be a single keymap or a list of more +than one. When looking up a key in the resulting new map, Emacs +searches in each of the @var{maps} in turn, and then in @var{parent}, +stopping at the first match. A @code{nil} binding in any one of +@var{maps} overrides any binding in @var{parent}, but it does not +override any non-@code{nil} binding in any other of the @var{maps}. +@end defun + +@noindent For example, here is how Emacs sets the parent of +@code{help-mode-map}, such that it inherits from both +@code{button-buffer-map} and @code{special-mode-map}: + +@example +(defvar help-mode-map + (let ((map (make-sparse-keymap))) + (set-keymap-parent map (make-composed-keymap button-buffer-map + special-mode-map)) + ... map) ... ) +@end example + + @node Prefix Keys @section Prefix Keys @cindex prefix key @@ -665,7 +686,7 @@ and exit commands. @xref{Intro to Minibuffers}. Emacs has other keymaps that are used in a different way---translating events within @code{read-key-sequence}. @xref{Translation Keymaps}. - @xref{Standard Keymaps}, for a list of standard keymaps. + @xref{Standard Keymaps}, for a list of some standard keymaps. @defun current-active-maps &optional olp position This returns the list of active keymaps that would be used by the @@ -688,7 +709,7 @@ 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 -returns the remapped command that will actually be executed. However, +return 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}. @@ -720,50 +741,39 @@ 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-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-char-property (point) 'local-map)) - (@var{find-in} (current-local-map)))))) +(or (cond + (overriding-terminal-local-map + (@var{find-in} overriding-terminal-local-map)) + (overriding-local-map + (@var{find-in} overriding-local-map)) + ((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-char-property (point) 'local-map)) + (@var{find-in} (current-local-map)))))) (@var{find-in} (current-global-map))) @end lisp @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 -The function finally found may be remapped -(@pxref{Remapping Commands}). - -@item -Characters that are bound to @code{self-insert-command} are translated -according to @code{translation-table-for-input} before insertion. - -@item -@code{current-active-maps} returns a list of the -currently active keymaps at point. - -@item -When a match is found (@pxref{Key Lookup}), if the binding in 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. + + When a match is found (@pxref{Key Lookup}), if the binding in the keymap is a function, the search is over. However if the keymap entry is a symbol with a value or a string, Emacs replaces the input key sequences with the variable's value or the string, and restarts the search of the active keymaps. -@end enumerate + + The function finally found might also be remapped. @xref{Remapping +Commands}. @node Controlling Active Maps @section Controlling the Active Keymaps @@ -1061,21 +1071,9 @@ lookup form a complete key, and the object is its binding, but the binding is not executable as a command. @end table - In short, a keymap entry may be a keymap, a command, a keyboard macro, -a symbol that leads to one of them, or an indirection or @code{nil}. -Here is an example of a sparse keymap with two characters bound to -commands and one bound to another keymap. This map is the normal value -of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB}, -127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for -@kbd{C-x}. - -@example -@group -(keymap (9 . lisp-indent-line) - (127 . backward-delete-char-untabify) - (27 keymap (17 . indent-sexp) (24 . eval-defun))) -@end group -@end example + In short, a keymap entry may be a keymap, a command, a keyboard +macro, a symbol that leads to one of them, or an indirection or +@code{nil}. @node Functions for Key Lookup @section Functions for Key Lookup @@ -1241,7 +1239,7 @@ local map, that usually affects all buffers using the same major mode. The @code{global-set-key} and @code{local-set-key} functions are convenient interfaces for these operations (@pxref{Key Binding Commands}). You can also use @code{define-key}, a more general -function; then you must specify explicitly the map to change. +function; then you must explicitly specify the map to change. When choosing the key sequences for Lisp programs to rebind, please follow the Emacs conventions for use of various keys (@pxref{Key @@ -1445,23 +1443,21 @@ that is used for some other purpose is likely to cause trouble; for example, suppressing @code{global-map} would make it impossible to use most of Emacs. -Most often, @code{suppress-keymap} is used to initialize local -keymaps of modes such as Rmail and Dired where insertion of text is not -desirable and the buffer is read-only. Here is an example taken from -the file @file{emacs/lisp/dired.el}, showing how the local keymap for -Dired mode is set up: +This function can be used to initialize the local keymap of a major +mode for which insertion of text is not desirable. But usually such a +mode should be derived from @code{special-mode} (@pxref{Basic Major +Modes}); then its keymap will automatically inherit from +@code{special-mode-map}, which is already suppressed. Here is how +@code{special-mode-map} is defined: @smallexample @group -(setq dired-mode-map (make-keymap)) -(suppress-keymap dired-mode-map) -(define-key dired-mode-map "r" 'dired-rename-file) -(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) -(define-key dired-mode-map "d" 'dired-flag-file-deleted) -(define-key dired-mode-map "v" 'dired-view-file) -(define-key dired-mode-map "e" 'dired-find-file) -(define-key dired-mode-map "f" 'dired-find-file) -@dots{} +(defvar special-mode-map + (let ((map (make-sparse-keymap))) + (suppress-keymap map) + (define-key map "q" 'quit-window) + @dots{} + map)) @end group @end smallexample @end defun @@ -1470,33 +1466,33 @@ Dired mode is set up: @section Remapping Commands @cindex remapping commands - A special kind of key binding, using a special ``key sequence'' -which includes a command name, has the effect of @dfn{remapping} that -command into another. Here's how it works. You make a key binding -for a key sequence that starts with the dummy event @code{remap}, -followed by the command name you want to remap. Specify the remapped -definition as the definition in this binding. The remapped definition -is usually a command name, but it can be any valid definition for -a key binding. + A special kind of key binding can be used to @dfn{remap} one command +to another, without having to refer to the key sequence(s) bound to +the original command. To use this feature, make a key binding for a +key sequence that starts with the dummy event @code{remap}, followed +by the command name you want to remap; for the binding, specify the +new definition (usually a command name, but possibly any other valid +definition for a key binding). - Here's an example. Suppose that My mode uses special commands -@code{my-kill-line} and @code{my-kill-word}, which should be invoked -instead of @code{kill-line} and @code{kill-word}. It can establish -this by making these two command-remapping bindings in its keymap: + For example, suppose My mode provides a special command +@code{my-kill-line}, which should be invoked instead of +@code{kill-line}. To establish this, its mode keymap should contain +the following remapping: @smallexample (define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap kill-word] 'my-kill-word) @end smallexample -Whenever @code{my-mode-map} is an active keymap, if the user types -@kbd{C-k}, Emacs will find the standard global binding of -@code{kill-line} (assuming nobody has changed it). But -@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line}, -so instead of running @code{kill-line}, Emacs runs -@code{my-kill-line}. +@noindent +Then, whenever @code{my-mode-map} is active, if the user types +@kbd{C-k} (the default global key sequence for @code{kill-line}) Emacs +will instead run @code{my-kill-line}. -Remapping only works through a single level. In other words, + Note that remapping only takes place through active keymaps; for +example, putting a remapping in a prefix keymap like @code{ctl-x-map} +typically has no effect, as such keymaps are not themselves active. +In addition, remapping only works through a single level; in the +following example, @smallexample (define-key my-mode-map [remap kill-line] 'my-kill-line) @@ -1504,11 +1500,16 @@ Remapping only works through a single level. In other words, @end smallexample @noindent -does not have the effect of remapping @code{kill-line} into -@code{my-other-kill-line}. If an ordinary key binding specifies -@code{kill-line}, this keymap will remap it to @code{my-kill-line}; -if an ordinary binding specifies @code{my-kill-line}, this keymap will -remap it to @code{my-other-kill-line}. +@code{kill-line} is @emph{not} remapped to @code{my-other-kill-line}. +Instead, if an ordinary key binding specifies @code{kill-line}, it is +remapped to @code{my-kill-line}; if an ordinary binding specifies +@code{my-kill-line}, it is remapped to @code{my-other-kill-line}. + +To undo the remapping of a command, remap it to @code{nil}; e.g. + +@smallexample +(define-key my-mode-map [remap kill-line] nil) +@end smallexample @defun command-remapping command &optional position keymaps This function returns the remapping for @var{command} (a symbol), @@ -1701,15 +1702,11 @@ or @noindent and your language environment is multibyte Latin-1, these commands -actually bind the multibyte character with code 2294, not the unibyte -Latin-1 character with code 246 (@kbd{M-v}). In order to use this -binding, you need to enter the multibyte Latin-1 character as keyboard -input. One way to do this is by using an appropriate input method -(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}). - - If you want to use a unibyte character in the key binding, you can -construct the key sequence string using @code{multibyte-char-to-unibyte} -or @code{string-make-unibyte} (@pxref{Converting Representations}). +actually bind the multibyte character with code 246, not the byte +code 246 (@kbd{M-v}) sent by a Latin-1 terminal. In order to use this +binding, you need to teach Emacs how to decode the keyboard by using an +appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU +Emacs Manual}). @deffn Command global-set-key key binding This function sets the binding of @var{key} in the current global map @@ -1974,6 +1971,7 @@ feature. @cindex defining menus @cindex menu prompt string @cindex prompt string (of menu) +@cindex menu item 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. @@ -2018,8 +2016,10 @@ an existing menu, you can specify its position in the menu using various features. * Menu Separators:: Drawing a horizontal line through a menu. * Alias Menu Items:: Using command aliases in menu items. +* Toolkit Differences:: Not all toolkits provide the same features. @end menu + @node Simple Menu Items @subsubsection Simple Menu Items @@ -2033,12 +2033,10 @@ event type (it doesn't matter what event type) to a binding like this: @noindent The @sc{car}, @var{item-string}, is the string to be displayed in the menu. It should be short---preferably one to three words. It should -describe the action of the command it corresponds to. Note that it is -not generally possible to display non-@acronym{ASCII} text in menus. It will -work for keyboard menus and will work to a large extent when Emacs is -built with the Gtk+ toolkit.@footnote{In this case, the text is first -encoded using the @code{utf-8} coding system and then rendered by the -toolkit as it sees fit.} +describe the action of the command it corresponds to. Note that not +all graphical toolkits can display non-@acronym{ASCII} text in menus +(it will work for keyboard menus and will work to a large extent with +the GTK+ toolkit). You can also supply a second string, called the help string, as follows: @@ -2075,6 +2073,7 @@ of menus in advance. To force recalculation of the menu bar, call @node Extended Menu Items @subsubsection Extended Menu Items @kindex menu-item +@cindex extended menu item An extended-format menu item is a more flexible and also cleaner alternative to the simple format. You define an event type with a @@ -2260,6 +2259,17 @@ the double-dash and replacing each single dash with capitalization of the following word. Thus, @code{"--:singleLine"}, is equivalent to @code{"--single-line"}. + You can use a longer form to specify keywords such as @code{:enable} +and @code{:visible} for a menu separator: + +@code{(menu-item @var{separator-type} nil . @var{item-property-list})} + +For example: + +@example +(menu-item "--" nil :visible (boundp 'foo)) +@end example + Some systems and display toolkits don't really handle all of these separator types. If you use a type that isn't supported, the menu displays a similar kind of separator that is supported. @@ -2296,6 +2306,28 @@ itself). To request this, give the alias symbol a non-@code{nil} causes menu items for @code{make-read-only} and @code{make-writable} to show the keyboard bindings for @code{toggle-read-only}. +@node Toolkit Differences +@subsubsection Toolkit Differences + +The various toolkits with which you can build Emacs do not all support +the same set of features for menus. Some code works as expected with +one toolkit, but not under another. + +One example is menu actions or buttons in a top-level menu bar. The +following works with the Lucid toolkit or on MS Windows, but not with +GTK or Nextstep, where clicking on the item has no effect. + +@example +(defun menu-action-greet () + (interactive) + (message "Hello Emacs User!")) + +(defun top-level-menu () + (interactive) + (define-key lisp-interaction-mode-map [menu-bar m] + '(menu-item "Action Button" menu-action-greet))) +@end example + @node Mouse Menus @subsection Menus and the Mouse @@ -2353,18 +2385,6 @@ this; @key{SPC} is the default.) 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. 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. - @defvar menu-prompt-more-char This variable specifies the character to use to ask to see the next line of a menu. Its initial value is 32, the code @@ -2447,21 +2467,17 @@ can do it this way: @subsection The Menu Bar @cindex menu bar - Most window systems allow each frame to have a @dfn{menu bar}---a -permanently displayed menu stretching horizontally across the top of -the frame. (In order for a frame to display a menu bar, its -@code{menu-bar-lines} parameter must be greater than zero. -@xref{Layout Parameters}.) - - The items of the menu bar are the subcommands of the fake ``function -key'' @code{menu-bar}, as defined in the active keymaps. + On graphical displays, there is usually a @dfn{menu bar} at the top +of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu +bar items are subcommands of the fake ``function key'' +@code{menu-bar}, as defined in the active keymaps. To add an item to the menu bar, invent a fake ``function key'' of your own (let's call it @var{key}), and make a binding for the key sequence @code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, so that pressing a button on the menu bar item leads to another menu. - When more than one active keymap defines the same fake function key + When more than one active keymap defines the same ``function key'' for the menu bar, the item appears just once. If the user clicks on that menu bar item, it brings up a single, combined menu containing all the subcommands of that item---the global subcommands, the local @@ -2475,11 +2491,6 @@ were @code{nil}. @xref{Active Keymaps}. Here's an example of setting up a menu bar item: @example -@group -(modify-frame-parameters (selected-frame) - '((menu-bar-lines . 2))) -@end group - @group ;; @r{Make a menu keymap (with a prompt string)} ;; @r{and make it the menu bar item's definition.} @@ -2553,20 +2564,17 @@ that the command does not actually have, it is ignored. @subsection Tool bars @cindex tool bar - A @dfn{tool bar} is a row of icons at the top of a frame, that execute -commands when you click on them---in effect, a kind of graphical menu -bar. + A @dfn{tool bar} is a row of clickable icons at the top of a frame, +just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs +Manual}. - The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar}) -controls how many lines' worth of height to reserve for the tool bar. A -zero value suppresses the tool bar. If the value is nonzero, and -@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}. + On each frame, the frame parameter @code{tool-bar-lines} controls +how many lines' worth of height to reserve for the tool bar. A zero +value suppresses the tool bar. If the value is nonzero, and +@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 is @code{grow-only}, the tool bar expands automatically, +but does not contract automatically. 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 @@ -2618,9 +2626,18 @@ 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 +right-to-left languages. Only the GTK+ version of Emacs supports this at present. +Like the menu bar, the tool bar can display separators (@pxref{Menu +Separators}). Tool bar separators are vertical rather than +horizontal, though, and only a single style is supported. They are +represented in the tool bar keymap by @code{(menu-item "--")} entries; +properties like @code{:visible} are not supported for tool bar +separators. Separators are rendered natively in GTK+ and Nextstep +tool bars; in the other cases, they are rendered using an image of a +vertical line. + 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 @@ -2632,18 +2649,20 @@ using an indirection through @code{tool-bar-map}. @defvar tool-bar-map By default, the global map binds @code{[tool-bar]} as follows: + @example (global-set-key [tool-bar] - '(menu-item "tool bar" ignore - :filter (lambda (ignore) tool-bar-map))) + `(menu-item ,(purecopy "tool bar") ignore + :filter tool-bar-make-keymap)) @end example + @noindent -Thus the tool bar map is derived dynamically from the value of variable -@code{tool-bar-map} and you should normally adjust the default (global) -tool bar by changing that map. Major modes may replace the global bar -completely by making @code{tool-bar-map} buffer-local and set to a -keymap containing only the desired items. Info mode provides an -example. +The function @code{tool-bar-make-keymap}, in turn, derives the actual +tool bar map dynamically from the value of the variable +@code{tool-bar-map}. Hence, you should normally adjust the default +(global) tool bar by changing that map. Some major modes, such as +Info mode, completely replace the global tool bar by making +@code{tool-bar-map} buffer-local and setting it to a different keymap. @end defvar There are two convenience functions for defining tool bar items, as @@ -2796,7 +2815,3 @@ menu of Shell mode, after the item @code{break}: [work] '("Work" . work-command) 'break) @end example @end defun - -@ignore - arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794 -@end ignore