X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/430d2ee2919b2d4693780f2474ba40148442d206..b13254e712fb4adec9b05dc4ac6928dc6c3f78de:/doc/lispref/keymaps.texi diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 7f3c7a466c..e1052a9912 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1,7 +1,8 @@ @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 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/keymaps @node Keymaps, Modes, Command Loop, Top @@ -16,19 +17,19 @@ used to look up the next input event; this continues until a command is found. The whole process is called @dfn{key lookup}. @menu -* Key Sequences:: Key sequences as Lisp objects. +* Key Sequences:: Key sequences as Lisp objects. * Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. +* Format of Keymaps:: What a keymap looks like as a Lisp object. +* Creating Keymaps:: Functions to create and copy keymaps. +* Inheritance and Keymaps:: How one keymap can inherit the bindings + of another keymap. * Prefix Keys:: Defining a key with a keymap as its definition. * Active Keymaps:: How Emacs searches the active keymaps for a key binding. * Searching Keymaps:: A pseudo-Lisp summary of searching active maps. * Controlling Active Maps:: Each buffer has a local keymap to override the standard (global) bindings. - A minor mode can also override them. + A minor mode can also override them. * Key Lookup:: Finding a key's binding in one keymap. * Functions for Key Lookup:: How to request key lookup. * Changing Key Bindings:: Redefining a key in a keymap. @@ -36,7 +37,7 @@ is found. The whole process is called @dfn{key lookup}. * Translation Keymaps:: Keymaps for translating sequences of events. * Key Binding Commands:: Interactive interfaces for redefining keys. * Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. +* Menu Keymaps:: Defining a menu as a keymap. @end menu @node Key Sequences @@ -487,14 +488,12 @@ prefix key. @code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix key. -@c Emacs 19 feature @item @cindex @kbd{C-x 5} @vindex ctl-x-5-map @code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix key. -@c Emacs 19 feature @item @cindex @kbd{C-x 6} @vindex 2C-mode-map @@ -507,17 +506,28 @@ key. @code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix key. +@item +@cindex @kbd{M-g} +@vindex goto-map +@code{goto-map} is the global keymap used for the @kbd{M-g} prefix +key. + +@item +@cindex @kbd{M-s} +@vindex search-map +@code{search-map} is the global keymap used for the @kbd{M-s} prefix +key. + @item @cindex @kbd{M-o} @vindex facemenu-keymap @code{facemenu-keymap} is the global keymap used for the @kbd{M-o} prefix key. -@c Emacs 19 feature @item -The other Emacs prefix keys are @kbd{M-g}, @kbd{C-x @@}, @kbd{C-x a i}, -@kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps -that have no special names. +The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x +@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have +no special names. @end itemize The keymap binding of a prefix key is used for looking up the event @@ -605,7 +615,9 @@ 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. +properties of the string override those of the buffer (if the +underlying buffer text contains map properties in its text properties +or overlays, they are ignored). The @dfn{global keymap} holds the bindings of keys that are defined regardless of the current buffer, such as @kbd{C-f}. The variable @@ -768,9 +780,11 @@ out with. @end defvar @defun current-global-map -This function returns the current global keymap. This is the -same as the value of @code{global-map} unless you change one or the -other. +This function returns the current global keymap. This is the same as +the value of @code{global-map} unless you change one or the other. +The return value is a reference, not a copy; if you use +@code{define-key} or other functions on it you will alter global +bindings. @example @group @@ -804,6 +818,10 @@ keymap. @end example @end defun +@code{current-local-map} returns a reference to the local keymap, not +a copy of it; if you use @code{define-key} or other functions on it +you will alter local bindings. + @defun current-minor-mode-maps This function returns a list of the keymaps of currently enabled minor modes. @end defun @@ -881,7 +899,7 @@ If non-@code{nil}, this variable holds a keymap to use instead of or overlay keymaps, 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 +buffer-local. @xref{Multiple Terminals}. It is used to implement incremental search mode. @end defvar @@ -1162,7 +1180,7 @@ The argument @var{accept-defaults} controls checking for default bindings, as in @code{lookup-key} (above). @end defun -@defvar meta-prefix-char +@defopt meta-prefix-char @cindex @key{ESC} This variable is the meta-prefix character code. It is used for translating a meta character to a two-character sequence so it can be @@ -1208,7 +1226,7 @@ meta-prefix-char ; @r{The default value.} This translation of one event into two happens only for characters, not for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function key, is not converted into @kbd{@key{ESC} @key{F1}}. -@end defvar +@end defopt @node Changing Key Bindings @section Changing Key Bindings @@ -1513,7 +1531,7 @@ specifies a list of keymaps to search in. This argument is ignored if sequence, to translate certain event sequences into others. @code{read-key-sequence} checks every subsequence of the key sequence being read, as it is read, against @code{input-decode-map}, then -@code{function-key-map}, and then against @code{key-translation-map}. +@code{local-function-key-map}, and then against @code{key-translation-map}. @defvar input-decode-map This variable holds a keymap that describes the character sequences sent @@ -1545,33 +1563,36 @@ to make entries in @code{input-decode-map} beyond those that can be deduced from Termcap and Terminfo. @xref{Terminal-Specific}. @end defvar -@defvar function-key-map +@defvar local-function-key-map This variable holds a keymap similar to @code{input-decode-map} except that it describes key sequences which should be translated to alternative interpretations that are usually preferred. It applies after @code{input-decode-map} and before @code{key-translation-map}. -Entries in @code{function-key-map} are ignored if they conflict with -bindings made in the minor mode, local, or global keymaps. I.e. +Entries in @code{local-function-key-map} are ignored if they conflict +with bindings made in the minor mode, local, or global keymaps. I.e. the remapping only applies if the original key sequence would otherwise not have any binding. + +@code{local-function-key-map} inherits from @code{function-key-map}, +but the latter should not be used directly. @end defvar @defvar key-translation-map This variable is another keymap used just like @code{input-decode-map} to translate input events into other events. It differs from @code{input-decode-map} in that it goes to work after -@code{function-key-map} is finished rather than before; it receives -the results of translation by @code{function-key-map}. - -Just like @code{input-decode-map}, but unlike @code{function-key-map}, -this keymap is applied regardless of whether the input key-sequence -has a normal binding. Note however that actual key bindings can have -an effect on @code{key-translation-map}, even though they are -overridden by it. Indeed, actual key bindings override -@code{function-key-map} and thus may alter the key sequence that -@code{key-translation-map} receives. Clearly, it is better to avoid -this type of situation. +@code{local-function-key-map} is finished rather than before; it +receives the results of translation by @code{local-function-key-map}. + +Just like @code{input-decode-map}, but unlike +@code{local-function-key-map}, this keymap is applied regardless of +whether the input key-sequence has a normal binding. Note however +that actual key bindings can have an effect on +@code{key-translation-map}, even though they are overridden by it. +Indeed, actual key bindings override @code{local-function-key-map} and +thus may alter the key sequence that @code{key-translation-map} +receives. Clearly, it is better to avoid this type of situation. The intent of @code{key-translation-map} is for users to map one character set to another, including ordinary characters normally bound @@ -1579,11 +1600,10 @@ to @code{self-insert-command}. @end defvar @cindex key translation function -You can use @code{input-decode-map}, @code{function-key-map}, or -@code{key-translation-map} for -more than simple aliases, by using a function, instead of a key -sequence, as the ``translation'' of a key. Then this function is called -to compute the translation of that key. +You can use @code{input-decode-map}, @code{local-function-key-map}, or +@code{key-translation-map} for more than simple aliases, by using a +function, instead of a key sequence, as the ``translation'' of a key. +Then this function is called to compute the translation of that key. The key translation function receives one argument, which is the prompt that was specified in @code{read-key-sequence}---or @code{nil} if the @@ -1614,7 +1634,7 @@ to turn the character that follows into a Hyper character: symbol (cons symbol (cdr e))))) -(define-key function-key-map "\C-ch" 'hyperify) +(define-key local-function-key-map "\C-ch" 'hyperify) @end group @end example @@ -1940,11 +1960,11 @@ 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 users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. +* Defining Menus:: How to make a keymap that defines a menu. +* Mouse Menus:: How users actuate the menu with the mouse. +* 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. * Modifying Menus:: How to add new items to a menu. @end menu @@ -2394,10 +2414,10 @@ Next we define the menu items: @smallexample (define-key menu-bar-replace-menu [tags-repl-continue] '(menu-item "Continue Replace" tags-loop-continue - :help "Continue last tags replace operation")) + :help "Continue last tags replace operation")) (define-key menu-bar-replace-menu [tags-repl] '(menu-item "Replace in tagged files" tags-query-replace - :help "Interactively replace a regexp in all tagged files")) + :help "Interactively replace a regexp in all tagged files")) (define-key menu-bar-replace-menu [separator-replace-tags] '(menu-item "--")) ;; @r{@dots{}} @@ -2451,9 +2471,13 @@ can do it this way: @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. The items of the menu bar are the subcommands of the fake -``function key'' @code{menu-bar}, as defined in the active keymaps. +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. 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 @@ -2471,13 +2495,6 @@ 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 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout -Parameters}. - Here's an example of setting up a menu bar item: @example @@ -2516,8 +2533,8 @@ bar item: @end example @noindent -@code{edit} is the fake function key used by the global map for the -@samp{Edit} menu bar item. The main reason to suppress a global +Here, @code{edit} is the fake function key used by the global map for +the @samp{Edit} menu bar item. The main reason to suppress a global menu bar item is to regain space for mode-specific items. @defvar menu-bar-final-items @@ -2538,6 +2555,23 @@ advise you to ensure that the functions it calls do not take much time in the usual case. @end defvar +Next to every menu bar item, Emacs displays a key binding that runs +the same command (if such a key binding exists). This serves as a +convenient hint for users who do not know the key binding. If a +command has multiple bindings, Emacs normally displays the first one +it finds. You can specify one particular key binding by assigning an +@code{:advertised-binding} symbol property to the command. For +instance, the following tells Emacs to show @kbd{C-/} for the +@code{undo} menu item: + +@smallexample +(put 'undo :advertised-binding [?\C-/]) +@end smallexample + +@noindent +If the @code{:advertised-binding} property specifies a key binding +that the command does not actually have, it is ignored. + @node Tool Bar @subsection Tool bars @cindex tool bar @@ -2606,6 +2640,10 @@ If @var{image} is a single image specification, Emacs draws the tool bar 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 +at present. + 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 @@ -2619,8 +2657,8 @@ using an indirection through @code{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 "tool bar" ignore + :filter (lambda (ignore) tool-bar-map))) @end example @noindent Thus the tool bar map is derived dynamically from the value of variable @@ -2680,7 +2718,7 @@ specifies the local map to make the definition in. The argument @code{tool-bar-add-item-from-menu}. @end defun -@defvar auto-resize-tool-bar +@defvar auto-resize-tool-bars 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. @@ -2688,6 +2726,9 @@ 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}. + +If Emacs is built with GTK or Nextstep, the tool bar can only show one +line, so this variable has no effect. @end defvar @defvar auto-raise-tool-bar-buttons