X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/cd7e5dd67d8b2a04e48a01714f7f5e7d87c97d4d..99543e8b33e5914918a8caa9b1c5b5cf5400c57b:/lispref/keymaps.texi diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 8b2644c4fb..5509b35b79 100644 --- a/lispref/keymaps.texi +++ b/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, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/keymaps @node Keymaps, Modes, Command Loop, Top @@ -10,7 +10,7 @@ The bindings between input events and commands are recorded in data structures called @dfn{keymaps}. Each binding in a keymap associates -(or @dfn{binds}) an individual event type either to another keymap or to +(or @dfn{binds}) an individual event type, either to another keymap or to a command. When an event type is bound to a keymap, that keymap is used to look up the next input event; this continues until a command is found. The whole process is called @dfn{key lookup}. @@ -202,24 +202,29 @@ lisp-mode-map @end group @group (keymap - ;; @key{TAB} - (9 . lisp-indent-line) + (3 keymap + ;; @kbd{C-c C-z} + (26 . run-lisp)) @end group @group - ;; @key{DEL} - (127 . backward-delete-char-untabify) + (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))) @end group @group - (3 keymap - ;; @kbd{C-c C-l} - (12 . run-lisp)) + ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} + keymap + ;; @key{DEL} + (127 . backward-delete-char-untabify) @end group @group (27 keymap ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp) - ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}} - (24 . lisp-send-defun))) + (17 . indent-sexp)) + (9 . lisp-indent-line)) @end group @end example @@ -252,18 +257,16 @@ satisfies @code{keymapp}. Here we describe the functions for creating keymaps. -@c ??? This should come after make-sparse-keymap -@defun make-keymap &optional prompt -This function creates and returns a new full keymap. That keymap -contains a char-table (@pxref{Char-Tables}) with slots for all -characters without modifiers. The new keymap initially binds all -these characters to @code{nil}, and does not bind any other kind of -event. +@defun make-sparse-keymap &optional prompt +This function creates and returns a new sparse keymap with no entries. +(A sparse keymap is the kind of keymap you usually want.) The new +keymap does not contain a char-table, unlike @code{make-keymap}, and +does not bind any events. @example @group -(make-keymap) - @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap]) +(make-sparse-keymap) + @result{} (keymap) @end group @end example @@ -272,18 +275,23 @@ the keymap. The prompt string should be provided for menu keymaps (@pxref{Defining Menus}). @end defun -@defun make-sparse-keymap &optional prompt -This function creates and returns a new sparse keymap with no entries. -The new keymap does not contain a char-table, unlike @code{make-keymap}, -and does not bind any events. The argument @var{prompt} specifies a -prompt string, as in @code{make-keymap}. +@defun make-keymap &optional prompt +This function creates and returns a new full keymap. That keymap +contains a char-table (@pxref{Char-Tables}) with slots for all +characters without modifiers. The new keymap initially binds all +these characters to @code{nil}, and does not bind any other kind of +event. The argument @var{prompt} specifies a +prompt string, as in @code{make-sparse-keymap}. @example @group -(make-sparse-keymap) - @result{} (keymap) +(make-keymap) + @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap]) @end group @end example + +A full keymap is more efficient than a sparse keymap when it holds +lots of bindings; for just a few, the sparse keymap is better. @end defun @defun copy-keymap keymap @@ -451,16 +459,16 @@ key. key. @item -@cindex @kbd{M-g} +@cindex @kbd{M-o} @vindex facemenu-keymap -@code{facemenu-keymap} is the global keymap used for the @kbd{M-g} +@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{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{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. @end itemize The keymap binding of a prefix key is used for looking up the event @@ -565,8 +573,8 @@ additional active keymaps through the variable text or overlay property. If that is non-@code{nil}, it is the first keymap to be processed, in normal circumstances. - However, there are also special circumstances, ways programs can -substitute other keymaps for some of those. The variable + However, there are also special ways for program can to substitute +other keymaps for some of those. The variable @code{overriding-local-map}, if non-@code{nil}, specifies a keymap that replaces all the usual active keymaps except the global keymap. Another way to do this is with @code{overriding-terminal-local-map}; @@ -661,6 +669,7 @@ commands use this function. @c Emacs 19 feature @defvar minor-mode-map-alist +@anchor{Definition of minor-mode-map-alist} This variable is an alist describing keymaps that may or may not be active according to the values of certain variables. Its elements look like this: @@ -679,8 +688,8 @@ structure as elements of @code{minor-mode-alist}. The map must be the not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose function definition is a keymap. -When more than one minor mode keymap is active, their order of priority -is the order of @code{minor-mode-map-alist}. But you should design +When more than one minor mode keymap is active, the earlier one in +@code{minor-mode-map-alist} takes priority. 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. @@ -763,8 +772,8 @@ part of key lookup. Key lookup uses just the event type of each event in the key sequence; the rest of the event is ignored. In fact, a key sequence used for key -lookup may designate mouse events with just their types (symbols) -instead of with entire mouse events (lists). @xref{Input Events}. Such +lookup may designate a mouse event with just its types (a symbol) +instead of the entire event (a list). @xref{Input Events}. Such a ``key-sequence'' is insufficient for @code{command-execute} to run, but it is sufficient for looking up or rebinding a key. @@ -1113,10 +1122,11 @@ key name). For example, @code{(control ?a)} is equivalent to @code{C-H-left}. One advantage of such lists 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 + 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 -that are lists. +that are lists. The @code{kbd} macro (@pxref{Keymap Terminology}) is +a convenient way to specify the key sequence. @defun define-key keymap key binding This function sets the binding for @var{key} in @var{keymap}. (If @@ -1328,10 +1338,10 @@ a key binding. instead of @code{kill-line} and @code{kill-word}. It can establish this by making these two command-remapping bindings in its keymap: -@example +@smallexample (define-key my-mode-map [remap kill-line] 'my-kill-line) (define-key my-mode-map [remap kill-word] 'my-kill-word) -@end example +@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 @@ -1342,10 +1352,10 @@ so instead of running @code{kill-line}, Emacs runs Remapping only works through a single level. In other words, -@example +@smallexample (define-key my-mode-map [remap kill-line] 'my-kill-line) (define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) -@end example +@end smallexample @noindent does not have the effect of remapping @code{kill-line} into @@ -1396,7 +1406,7 @@ redefines @kbd{C-x C-\} to move down a line. @end smallexample @noindent -redefines the first (leftmost) mouse button, typed with the Meta key, to +redefines the first (leftmost) mouse button, entered with the Meta key, to set point where you click. @cindex non-@acronym{ASCII} text in keybindings @@ -1428,15 +1438,15 @@ input. One way to do this is by using an appropriate input method construct the key sequence string using @code{multibyte-char-to-unibyte} or @code{string-make-unibyte} (@pxref{Converting Representations}). -@deffn Command global-set-key key definition +@deffn Command global-set-key key binding This function sets the binding of @var{key} in the current global map -to @var{definition}. +to @var{binding}. @smallexample @group -(global-set-key @var{key} @var{definition}) +(global-set-key @var{key} @var{binding}) @equiv{} -(define-key (current-global-map) @var{key} @var{definition}) +(define-key (current-global-map) @var{key} @var{binding}) @end group @end smallexample @end deffn @@ -1472,15 +1482,15 @@ This function is implemented simply using @code{define-key}: @end smallexample @end deffn -@deffn Command local-set-key key definition +@deffn Command local-set-key key binding This function sets the binding of @var{key} in the current local -keymap to @var{definition}. +keymap to @var{binding}. @smallexample @group -(local-set-key @var{key} @var{definition}) +(local-set-key @var{key} @var{binding}) @equiv{} -(define-key (current-local-map) @var{key} @var{definition}) +(define-key (current-local-map) @var{key} @var{binding}) @end group @end smallexample @end deffn @@ -1743,7 +1753,7 @@ 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 Gtk+ support.@footnote{In this case, the text is first +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.} @@ -1903,6 +1913,10 @@ This property provides a way to compute the menu item dynamically. The property value @var{filter-fn} should be a function of one argument; when it is called, its argument will be @var{real-binding}. The function should return the binding to use instead. + +Emacs can call this function at any time that it does redisplay or +operates on menu data structures, so you should write it so it can +safely be called at any time. @end table @node Menu Separators @@ -1924,8 +1938,8 @@ where @var{separator-type} is a string starting with two or more dashes. That specifies the default kind of separator. (For compatibility, @code{""} and @code{-} also count as separators.) - Starting in Emacs 21, certain other values of @var{separator-type} -specify a different style of separator. Here is a table of them: + Certain other values of @var{separator-type} specify a different +style of separator. Here is a table of them: @table @code @item "--no-line" @@ -2044,13 +2058,8 @@ with @samp{@@} or not. In a toolkit version of Emacs, the only thing special about @samp{@@} at the beginning of an item string is that the @samp{@@} doesn't appear in the menu item. - You can also produce multiple panes or submenus from separate keymaps. -The full definition of a prefix key always comes from merging the -definitions supplied by the various active keymaps (minor mode, local, -and global). When more than one of these keymaps is a menu, each of -them makes a separate pane or panes (when Emacs does not use an -X-toolkit) or a separate submenu (when using an X-toolkit). -@xref{Active Keymaps}. + Multiple keymaps that define the same menu prefix key produce +separate panes or separate submenus. @node Keyboard Menus @subsection Menus and the Keyboard @@ -2094,29 +2103,29 @@ for @key{SPC}. @cindex menu definition example Here is a complete example of defining a menu keymap. It is the -definition of the @samp{Print} submenu in the @samp{Tools} menu in the -menu bar, and it uses the simple menu item format (@pxref{Simple Menu -Items}). First we create the keymap, and give it a name: +definition of the @samp{Replace} submenu in the @samp{Edit} menu in +the menu bar, and it uses the extended menu item format +(@pxref{Extended Menu Items}). First we create the keymap, and give +it a name: -@example -(defvar menu-bar-print-menu (make-sparse-keymap "Print")) -@end example +@smallexample +(defvar menu-bar-replace-menu (make-sparse-keymap "Replace")) +@end smallexample @noindent Next we define the menu items: -@example -(define-key menu-bar-print-menu [ps-print-region] - '("Postscript Print Region" . ps-print-region-with-faces)) -(define-key menu-bar-print-menu [ps-print-buffer] - '("Postscript Print Buffer" . ps-print-buffer-with-faces)) -(define-key menu-bar-print-menu [separator-ps-print] - '("--")) -(define-key menu-bar-print-menu [print-region] - '("Print Region" . print-region)) -(define-key menu-bar-print-menu [print-buffer] - '("Print Buffer" . print-buffer)) -@end example +@smallexample +(define-key menu-bar-replace-menu [tags-repl-continue] + '(menu-item "Continue Replace" tags-loop-continue + :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")) +(define-key menu-bar-replace-menu [separator-replace-tags] + '(menu-item "--")) +;; @r{@dots{}} +@end smallexample @noindent Note the symbols which the bindings are ``made for''; these appear @@ -2136,58 +2145,29 @@ typed with the keyboard. The binding whose definition is @code{("--")} is a separator line. Like a real menu item, the separator has a key symbol, in this case -@code{separator-ps-print}. If one menu has two separators, they must -have two different key symbols. - - Here is code to define enable conditions for two of the commands in -the menu: - -@example -(put 'print-region 'menu-enable 'mark-active) -(put 'ps-print-region-with-faces 'menu-enable 'mark-active) -@end example +@code{separator-replace-tags}. If one menu has two separators, they +must have two different key symbols. Here is how we make this menu appear as an item in the parent menu: @example -(define-key menu-bar-tools-menu [print] - (cons "Print" menu-bar-print-menu)) +(define-key menu-bar-edit-menu [replace] + (list 'menu-item "Replace" menu-bar-replace-menu)) @end example @noindent Note that this incorporates the submenu keymap, which is the value of -the variable @code{menu-bar-print-menu}, rather than the symbol -@code{menu-bar-print-menu} itself. Using that symbol in the parent menu -item would be meaningless because @code{menu-bar-print-menu} is not a -command. +the variable @code{menu-bar-replace-menu}, rather than the symbol +@code{menu-bar-replace-menu} itself. Using that symbol in the parent +menu item would be meaningless because @code{menu-bar-replace-menu} is +not a command. - If you wanted to attach the same print menu to a mouse click, you + If you wanted to attach the same replace menu to a mouse click, you can do it this way: @example (define-key global-map [C-S-down-mouse-1] - menu-bar-print-menu) -@end example - - We could equally well use an extended menu item (@pxref{Extended Menu -Items}) for @code{print-region}, like this: - -@example -(define-key menu-bar-print-menu [print-region] - '(menu-item "Print Region" print-region - :enable mark-active)) -@end example - -@noindent -With the extended menu item, the enable condition is specified -inside the menu item itself. If we wanted to make this -item disappear from the menu entirely when the mark is inactive, -we could do it this way: - -@example -(define-key menu-bar-print-menu [print-region] - '(menu-item "Print Region" print-region - :visible mark-active)) + menu-bar-replace-menu) @end example @node Menu Bar @@ -2197,7 +2177,7 @@ we could do it this way: 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 by all the active keymaps. +``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 @@ -2219,7 +2199,7 @@ were @code{nil}. @xref{Active Keymaps}. 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{Window Frame +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: @@ -2275,9 +2255,11 @@ at the end of the menu bar, following local menu items. @end defvar @defvar menu-bar-update-hook -This normal hook is run whenever the user clicks on the menu bar, before -displaying a submenu. You can use it to update submenus whose contents -should vary. +This normal hook is run by redisplay to update the menu bar contents, +before redisplaying the menu bar. You can use it to update submenus +whose contents should vary. Since this hook is run frequently, we +advise you to ensure that the functions it calls do not take much time +in the usual case. @end defvar @node Tool Bar @@ -2286,7 +2268,7 @@ should vary. 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. Emacs supports tool bars starting with version 21. +bar. 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