X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/402fe42394c7a6f89991420d50ae475e447f5c7b..5ad1bc4dead80db3e81a6855714bc0b5817f5fc0:/lispref/keymaps.texi diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 12246f0b23..59e2e19966 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -1,6 +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 +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2004 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/keymaps @@ -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}. @@ -103,16 +103,19 @@ representation; it is also convenient to use @code{kbd}: This macro converts the text @var{keyseq-text} (a string constant) into a key sequence (a string or vector constant). The contents of @var{keyseq-text} should describe the key sequence using the syntax -used in this manual: +used in this manual. More precisely, it uses the same syntax that +Edit Macro mode uses for editing keyboard macros (@pxref{Edit Keyboard +Macro,,, emacs, The GNU Emacs Manual}). @example (kbd "C-x") @result{} "\C-x" (kbd "C-x C-f") @result{} "\C-x\C-f" -(kbd "C-c C-c") @result{} "\C-c\C-c" (kbd "C-x 4 C-f") @result{} "\C-x4\C-f" (kbd "X") @result{} "X" (kbd "RET") @result{} "\^M" -(kbd "C-c 3") @result{} "\C-c3" +(kbd "C-c SPC") @result{} "\C-c@ " +(kbd " SPC") @result{} [f1 32] +(kbd "C-M-") @result{} [C-M-down] @end example @end defmac @@ -144,7 +147,8 @@ This specifies a @dfn{default key binding}; any event not bound by other elements of the keymap is given @var{binding} as its binding. Default bindings allow a keymap to bind all possible event types without having to enumerate all of them. A keymap that has a default binding -completely masks any lower-precedence keymap. +completely masks any lower-precedence keymap, except for events +explicitly bound to @code{nil} (see below). @item @var{char-table} If an element of a keymap is a char-table, it counts as holding @@ -198,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 @@ -251,17 +260,15 @@ satisfies @code{keymapp}. @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 384 slots: the first -128 slots are for defining all the @acronym{ASCII} characters, the next 128 -slots are for 8-bit European characters, and each one of the final 128 -slots is for one character set of non-@acronym{ASCII} characters supported by -Emacs. The new keymap initially binds all these characters to -@code{nil}, and does not bind any other kind of event. +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. @example @group (make-keymap) - @result{} (keymap [nil nil nil @dots{} nil nil]) + @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap]) @end group @end example @@ -449,16 +456,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 @@ -509,6 +516,7 @@ active keymap. @defun define-prefix-command symbol &optional mapvar prompt @cindex prefix command +@anchor{Definition of define-prefix-command} This function prepares @var{symbol} for use as a prefix key's binding: it creates a sparse keymap and stores it as @var{symbol}'s function definition. Subsequently binding a key sequence to @var{symbol} will @@ -529,41 +537,46 @@ string for the keymap. The prompt string should be given for menu keymaps @cindex global keymap @cindex local keymap - Emacs normally contains many keymaps; at any given time, just a few of -them are @dfn{active} in that they participate in the interpretation -of user input. These are the global keymap, the current buffer's -local keymap, and the keymaps of any enabled minor modes. + Emacs normally contains many keymaps; at any given time, just a few +of them are @dfn{active} in 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. (Searching a single keymap for a +binding is called @dfn{key lookup}; see @ref{Key Lookup}.) + + 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. The @dfn{global keymap} holds the bindings of keys that are defined regardless of the current buffer, such as @kbd{C-f}. The variable @code{global-map} holds this keymap, which is always active. - Each buffer may have another keymap, its @dfn{local keymap}, which may -contain new or overriding definitions for keys. The current buffer's -local keymap is always active except when @code{overriding-local-map} -overrides it. Text properties can specify an alternative local map for -certain parts of the buffer; see @ref{Special Properties}. + Each buffer may have another keymap, its @dfn{local keymap}, which +may contain new or overriding definitions for keys. The current +buffer's local keymap is always active except when +@code{overriding-local-map} overrides it. The @code{local-map} text +or overlay property can specify an alternative local keymap for certain +parts of the buffer; see @ref{Special Properties}. Each minor mode can have a keymap; if it does, the keymap is active -when the minor mode is enabled. - - The variable @code{overriding-local-map}, if non-@code{nil}, specifies -another local keymap that overrides the buffer's local map and all the -minor mode keymaps. Modes for emulation can specify additional -active keymaps through the variable @code{emulation-mode-map-alists}. - - All the active keymaps are used together to determine what command to -execute when a key is entered. Emacs searches these maps one by one, in -order of decreasing precedence, until it finds a binding in one of the -maps. The procedure for searching a single keymap is called @dfn{key -lookup}; see @ref{Key Lookup}. - - Normally, Emacs first searches for the key in the minor mode maps, in -the order specified by @code{minor-mode-map-alist}; if they do not -supply a binding for the key, Emacs searches the local map; if that too -has no binding, Emacs then searches the global map. However, if -@code{overriding-local-map} is non-@code{nil}, Emacs searches that map -first, before the global map. +when the minor mode is enabled. Modes for emulation can specify +additional active keymaps through the variable +@code{emulation-mode-map-alists}. + + The highest precedence normal keymap comes from the @code{keymap} +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 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}; +it operates on a per-terminal basis. These variables are documented +below. @cindex major mode keymap Since every buffer that uses the same major mode normally uses the @@ -572,7 +585,7 @@ change to the local keymap of a buffer (using @code{local-set-key}, for example) is seen also in the other buffers that share that keymap. The local keymaps that are used for Lisp mode and some other major -modes exist even if they have not yet been used. These local maps are +modes exist even if they have not yet been used. These local keymaps are the values of variables such as @code{lisp-mode-map}. For most major modes, which are less frequently used, the local keymap is constructed only when the mode is used for the first time in a session. @@ -591,7 +604,7 @@ keyboard input to commands. The global keymap is normally this keymap. The default global keymap is a full keymap that binds @code{self-insert-command} to all of the printing characters. -It is normal practice to change the bindings in the global map, but you +It is normal practice to change the bindings in the global keymap, but you should not assign this variable any value other than the keymap it starts out with. @end defvar @@ -671,8 +684,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. @@ -698,15 +711,15 @@ all buffers. @defvar overriding-local-map If non-@code{nil}, this variable holds a keymap to use instead of the -buffer's local keymap and instead of all the minor mode keymaps. This -keymap, if any, overrides all other maps that would have been active, -except for the current global map. +buffer's local keymap, any text property or overlay keymaps, and any +minor mode keymaps. This keymap, if specified, overrides all other +maps that would have been active, except for the current global map. @end defvar @defvar overriding-terminal-local-map If non-@code{nil}, this variable holds a keymap to use instead of -@code{overriding-local-map}, the buffer's local keymap and all the minor -mode keymaps. +@code{overriding-local-map}, the buffer's local keymap, text property +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 @@ -755,8 +768,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. @@ -977,9 +990,12 @@ An error is signaled if @var{key} is not a string or a vector. @end example @end defun -@defun current-active-maps +@defun current-active-maps &optional olp This returns the list of keymaps that would be used by the command -loop in the current circumstances to look up a key sequence. +loop in the current circumstances to look up a key sequence. Normally +it ignores @code{overriding-local-map} and +@code{overriding-terminal-local-map}, but if @var{olp} is +non-@code{nil} then it pays attention to them. @end defun @defun local-key-binding key &optional accept-defaults @@ -1102,10 +1118,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 @@ -1191,7 +1208,7 @@ changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the default global map. The function @code{substitute-key-definition} scans a keymap for -keys that have a certain binding and rebind them with a different +keys that have a certain binding and rebinds them with a different binding. Another feature you can use for similar effects, but which is often cleaner, is to add a binding that remaps a command (@pxref{Remapping Commands}). @@ -1255,9 +1272,10 @@ map @defun suppress-keymap keymap &optional nodigits @cindex @code{self-insert-command} override This function changes the contents of the full keymap @var{keymap} by -making all the printing characters undefined. More precisely, it binds -them to the command @code{undefined}. This makes ordinary insertion of -text impossible. @code{suppress-keymap} returns @code{nil}. +remapping @code{self-insert-command} to the command @code{undefined} +(@pxref{Remapping Commands}). This has the effect of undefining all +printing characters, thus making ordinary insertion of text impossible. +@code{suppress-keymap} returns @code{nil}. If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines digits to run @code{digit-argument}, and @kbd{-} to run @@ -1324,7 +1342,7 @@ this by making these two command-remapping bindings in its keymap: 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-mode-map}, +@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}. @@ -1337,15 +1355,16 @@ Remapping only works through a single level. In other words, @noindent does not have the effect of remapping @code{kill-line} into -@code{my-other-kill-line}. If an ordinary key binding specifies +@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}. @defun command-remapping command -This function returns the remapping for @var{command}, given the -current active keymaps. If @var{command} is not remapped (which is -the usual situation), the function returns @code{nil}. +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}. @end defun @node Key Binding Commands @@ -1383,7 +1402,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 @@ -1409,7 +1428,7 @@ 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}). +(@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} @@ -1499,7 +1518,7 @@ association list with elements of the form @code{(@var{key} .@: @var{keymap} is @var{map}. The elements of the alist are ordered so that the @var{key} increases -in length. The first element is always @code{("" .@: @var{keymap})}, +in length. The first element is always @code{([] .@: @var{keymap})}, because the specified keymap is accessible from itself with a prefix of no events. @@ -1517,7 +1536,7 @@ definition is the sparse keymap @code{(keymap (83 .@: center-paragraph) @smallexample @group (accessible-keymaps (current-local-map)) -@result{}(("" keymap +@result{}(([] keymap (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} (83 . center-paragraph) (115 . center-line)) @@ -1541,7 +1560,7 @@ of a window. @smallexample @group (accessible-keymaps (current-global-map)) -@result{} (("" keymap [set-mark-command beginning-of-line @dots{} +@result{} (([] keymap [set-mark-command beginning-of-line @dots{} delete-backward-char]) @end group @group @@ -1572,6 +1591,8 @@ The function @code{map-keymap} calls @var{function} once for each binding in @var{keymap}. It passes two arguments, the event type and the value of the binding. If @var{keymap} has a parent, the parent's bindings are included as well. +This works recursively: if the parent has itself a parent, then the +grandparent's bindings are also included and so on. This function is the cleanest way to examine all the bindings in a keymap. @@ -1580,7 +1601,7 @@ in a keymap. @defun where-is-internal command &optional keymap firstonly noindirect no-remap This function is a subroutine used by the @code{where-is} command (@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list -of key sequences (of any length) that are bound to @var{command} in a +of all key sequences (of any length) that are bound to @var{command} in a set of keymaps. The argument @var{command} can be any object; it is compared with all @@ -1588,7 +1609,7 @@ keymap entries using @code{eq}. If @var{keymap} is @code{nil}, then the maps used are the current active keymaps, disregarding @code{overriding-local-map} (that is, pretending -its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the +its value is @code{nil}). If @var{keymap} is a keymap, then the maps searched are @var{keymap} and the global keymap. If @var{keymap} is a list of keymaps, only those keymaps are searched. @@ -1598,11 +1619,12 @@ keymaps that are active. To search only the global map, pass @code{(keymap)} (an empty keymap) as @var{keymap}. If @var{firstonly} is @code{non-ascii}, then the value is a single -string representing the first key sequence found, rather than a list of +vector representing the first key sequence found, rather than a list of all possible key sequences. If @var{firstonly} is @code{t}, then the value is the first key sequence, except that key sequences consisting entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} -characters) are preferred to all other key sequences. +characters) are preferred to all other key sequences and that the +return value can never be a menu binding. If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't follow indirect keymap bindings. This makes it possible to search for @@ -1623,7 +1645,7 @@ other command. However, if @var{no-remap} is non-@code{nil}. @end smallexample @end defun -@deffn Command describe-bindings &optional prefix +@deffn Command describe-bindings &optional prefix buffer-or-name This function creates a listing of all current key bindings, and displays it in a buffer named @samp{*Help*}. The text is grouped by modes---minor modes first, then the major mode, then global bindings. @@ -1643,6 +1665,10 @@ For example, in the default global map, the characters @samp{@key{SPC} @kbd{~} is @acronym{ASCII} 126, and the characters between them include all the normal printing characters, (e.g., letters, digits, punctuation, etc.@:); all these characters are bound to @code{self-insert-command}. + +If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a +buffer name. Then @code{describe-bindings} lists that buffer's bindings, +instead of the current buffer's. @end deffn @node Menu Keymaps @@ -1681,8 +1707,9 @@ 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}, -@code{make-sparse-keymap} or @code{define-prefix-command} -(@pxref{Creating Keymaps}). +@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or +@code{define-prefix-command} (@pxref{Definition of define-prefix-command}). + @defun keymap-prompt keymap This function returns the overall prompt string of @var{keymap}, @@ -1722,7 +1749,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,8 +1930,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" @@ -2023,13 +2050,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 @@ -2073,29 +2095,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 @@ -2107,60 +2129,37 @@ functioning of the menu itself, but they are ``echoed'' in the echo area when the user selects from the menu, and they appear in the output of @code{where-is} and @code{apropos}. + The menu in this example is intended for use with the mouse. If a +menu is intended for use with the keyboard, that is, if it is bound to +a key sequence ending with a keyboard event, then the menu items +should be bound to characters or ``real'' function keys, that can be +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 @@ -2170,7 +2169,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 @@ -2248,9 +2247,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 @@ -2259,7 +2260,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 @@ -2389,7 +2390,7 @@ property list elements to add to the menu item specification. This function is used for making non-global tool bar items. Use it like @code{tool-bar-add-item-from-menu} except that @var{in-map} specifies the local map to make the definition in. The argument -@var{from-map} si like the @var{map} argument of +@var{from-map} is like the @var{map} argument of @code{tool-bar-add-item-from-menu}. @end defun