X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/68e7476278a3dc4bd13dab63cc23bc0e671e5525..97d8273fa2687731d652687cf6b4c7c48dd0661a:/doc/lispref/keymaps.texi diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 7f3c7a466c..6d4c95fca3 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1,7 +1,7 @@ @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 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/keymaps @node Keymaps, Modes, Command Loop, Top @@ -487,14 +487,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 +505,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 +614,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 +779,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 +817,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 +898,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 @@ -1513,7 +1530,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 +1562,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 +1599,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 +1633,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 @@ -2606,6 +2625,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