1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus
58 A menu is described using a "menu description", which is a list of
59 menu items, keyword-value pairs, strings, and submenus. The menu
60 description specifies which items are present in the menu, what function
61 each item invokes, and whether the item is selectable or not. Pop-up
62 menus are directly described with a menu description, while menubars are
63 described slightly differently (see below).
65 The first element of a menu must be a string, which is the name of
66 the menu. This is the string that will be displayed in the parent menu
67 or menubar, if any. This string is not displayed in the menu itself,
68 except in the case of the top level pop-up menu, where there is no
69 parent. In this case, the string will be displayed at the top of the
70 menu if `popup-menu-titles' is non-`nil'.
72 Immediately following the first element there may optionally be up
73 to four keyword-value pairs, as follows:
76 This can be used to control the visibility of a menu. The form is
77 evaluated and the menu will be omitted if the result is `nil'.
80 This is an efficient shorthand for `:included (memq SYMBOL
81 menubar-configuration)'. See the variable `menubar-configuration'.
84 A menu filter is used to sensitize or incrementally create a
85 submenu only when it is selected by the user and not every time
86 the menubar is activated. The filter function is passed the list
87 of menu items in the submenu and must return a list of menu items
88 to be used for the menu. It is called only when the menu is about
89 to be displayed, so other menus may already be displayed. Vile
90 and terrible things will happen if a menu filter function changes
91 the current buffer, window, or frame. It also should not raise,
92 lower, or iconify any frames. Basically, the filter function
93 should have no side-effects.
96 A menu accelerator is a keystroke which can be pressed while the
97 menu is visible which will immediately activate the item. KEY
98 must be a char or the symbol name of a key. *Note Menu
101 The rest of the menu consists of elements as follows:
103 * A "menu item", which is a vector in the following form:
105 `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]'
107 NAME is a string, the name of the menu item; it is the string to
108 display on the menu. It is filtered through the resource
109 database, so it is possible for resources to override what string
110 is actually displayed.
112 CALLBACK is a form that will be invoked when the menu item is
113 selected. If the callback of a menu item is a symbol, then it
114 must name a command. It will be invoked with
115 `call-interactively'. If it is a list, then it is evaluated with
118 The valid keywords and their meanings are described below.
120 Note that for compatibility purposes, the form
122 `[ NAME CALLBACK ACTIVE-P ]'
124 is also accepted and is equivalent to
126 `[ NAME CALLBACK :active ACTIVE-P ]'
130 `[ NAME CALLBACK ACTIVE-P SUFFIX]'
132 is accepted and is equivalent to
134 `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]'
136 However, these older forms are deprecated and should generally not
139 * If an element of a menu is a string, then that string will be
140 presented in the menu as unselectable text.
142 * If an element of a menu is a string consisting solely of hyphens,
143 then that item will be presented as a solid horizontal line.
145 * If an element of a menu is a string beginning with `--:', then a
146 particular sort of horizontal line will be displayed, as follows:
149 A solid horizontal line. This is equivalent to a string
150 consisting solely of hyphens.
153 A solid double horizontal line.
155 `"--:singleDashedLine"'
156 A dashed horizontal line.
158 `"--:doubleDashedLine"'
159 A dashed double horizontal line.
162 No line (but a small space is left).
164 `"--:shadowEtchedIn"'
165 A solid horizontal line with a 3-d recessed appearance.
167 `"--:shadowEtchedOut"'
168 A solid horizontal line with a 3-d pushed-out appearance.
170 `"--:shadowDoubleEtchedIn"'
171 A solid double horizontal line with a 3-d recessed appearance.
173 `"--:shadowDoubleEtchedOut"'
174 A solid double horizontal line with a 3-d pushed-out
177 `"--:shadowEtchedInDash"'
178 A dashed horizontal line with a 3-d recessed appearance.
180 `"--:shadowEtchedOutDash"'
181 A dashed horizontal line with a 3-d pushed-out appearance.
183 `"--:shadowDoubleEtchedInDash"'
184 A dashed double horizontal line with a 3-d recessed
187 `"--:shadowDoubleEtchedOutDash"'
188 A dashed double horizontal line with a 3-d pushed-out
191 * If an element of a menu is a list, it is treated as a submenu.
192 The name of that submenu (the first element in the list) will be
193 used as the name of the item representing this menu on the parent.
195 The possible keywords are as follows:
198 FORM will be evaluated when the menu that this item is a part of
199 is about to be displayed, and the item will be selectable only if
200 the result is non-`nil'. If the item is unselectable, it will
201 usually be displayed grayed-out to indicate this.
204 FORM will be evaluated when the menu that this item is a part of
205 is about to be displayed, and the resulting string is appended to
206 the displayed name. This provides a convenient way of adding the
207 name of a command's "argument" to the menu, like `Kill Buffer
211 Normally, the keyboard equivalents of commands in menus are
212 displayed when the "callback" is a symbol. This can be used to
213 specify keys for more complex menu items. It is passed through
214 `substitute-command-keys' first.
217 Specifies what kind of object this menu item is. STYLE be one of
232 The only difference between toggle and radio buttons is how they
233 are displayed. But for consistency, a toggle button should be
234 used when there is one option whose value can be turned on or off,
235 and radio buttons should be used when there is a set of mutually
236 exclusive options. When using a group of radio buttons, you
237 should arrange for no more than one to be marked as selected at a
241 Meaningful only when STYLE is `toggle', `radio' or `button'. This
242 specifies whether the button will be in the selected or unselected
243 state. FORM is evaluated, as for `:active'.
246 This can be used to control the visibility of a menu item. The
247 form is evaluated and the menu item is only displayed if the
248 result is non-`nil'. Note that this is different from `:active':
249 If `:active' evaluates to `nil', the item will be displayed grayed
250 out, while if `:included' evaluates to `nil', the item will be
254 This is an efficient shorthand for `:included (memq SYMBOL
255 menubar-configuration)'. See the variable `menubar-configuration'.
258 A menu accelerator is a keystroke which can be pressed while the
259 menu is visible which will immediately activate the item. KEY
260 must be a char or the symbol name of a key. *Note Menu
263 - Variable: menubar-configuration
264 This variable holds a list of symbols, against which the value of
265 the `:config' tag for each menubar item will be compared. If a
266 menubar item has a `:config' tag, then it is omitted from the
267 menubar if that tag is not a member of the `menubar-configuration'
273 :filter file-menu-filter ; file-menu-filter is a function that takes
274 ; one argument (a list of menu items) and
275 ; returns a list of menu items
276 [ "Save As..." write-file]
277 [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ]
278 [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ]
282 File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus
284 Format of the Menubar
285 =====================
287 A menubar is a list of menus, menu items, and strings. The format is
288 similar to that of a menu, except:
290 * The first item need not be a string, and is not treated specially.
292 * A string consisting solely of hyphens is not treated specially.
294 * If an element of a menubar is `nil', then it is used to represent
295 the division between the set of menubar items which are flush-left
296 and those which are flush-right. (Note: this isn't completely
300 File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus
305 - Variable: current-menubar
306 This variable holds the description of the current menubar. This
307 may be buffer-local. When the menubar is changed, the function
308 `set-menubar-dirty-flag' has to be called in order for the menubar
309 to be updated on the screen.
311 - Constant: default-menubar
312 This variable holds the menubar description of the menubar that is
313 visible at startup. This is the value that `current-menubar' has
316 - Function: set-menubar-dirty-flag
317 This function tells XEmacs that the menubar widget has to be
318 updated. Changes to the menubar will generally not be visible
319 until this function is called.
321 The following convenience functions are provided for setting the
322 menubar. They are equivalent to doing the appropriate action to change
323 `current-menubar', and then calling `set-menubar-dirty-flag'. Note
324 that these functions copy their argument using `copy-sequence'.
326 - Function: set-menubar menubar
327 This function sets the default menubar to be MENUBAR (*note Menu
328 Format::). This is the menubar that will be visible in buffers
329 that have not defined their own, buffer-local menubar.
331 - Function: set-buffer-menubar menubar
332 This function sets the buffer-local menubar to be MENUBAR. This
333 does not change the menubar in any buffers other than the current
338 - Variable: menubar-show-keybindings
339 If true, the menubar will display keyboard equivalents. If false,
340 only the command names will be displayed.
342 - Variable: activate-menubar-hook
343 Function or functions called before a menubar menu is pulled down.
344 These functions are called with no arguments, and should
345 interrogate and modify the value of `current-menubar' as desired.
347 The functions on this hook are invoked after the mouse goes down,
348 but before the menu is mapped, and may be used to activate,
349 deactivate, add, or delete items from the menus. However, using a
350 filter (with the `:filter' keyword in a menu description) is
351 generally a more efficient way of accomplishing the same thing,
352 because the filter is invoked only when the actual menu goes down.
353 With a complex menu, there can be a quite noticeable and
354 sometimes aggravating delay if all menu modification is
355 implemented using the `activate-menubar-hook'. See above.
357 These functions may return the symbol `t' to assert that they have
358 made no changes to the menubar. If any other value is returned,
359 the menubar is recomputed. If `t' is returned but the menubar has
360 been changed, then the changes may not show up right away.
361 Returning `nil' when the menubar has not changed is not so bad;
362 more computation will be done, but redisplay of the menubar will
363 still be performed optimally.
365 - Variable: menu-no-selection-hook
366 Function or functions to call when a menu or dialog box is
367 dismissed without a selection having been made.
370 File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus
375 The following functions are provided to modify the menubar of one of
376 its submenus. Note that these functions modify the menu in-place,
377 rather than copying it and making a new menu.
379 Some of these functions take a "menu path", which is a list of
380 strings identifying the menu to be modified. For example, `("File")'
381 names the top-level "File" menu. `("File" "Foo")' names a hypothetical
384 Others take a "menu item path", which is similar to a menu path but
385 also specifies a particular item to be modified. For example, `("File"
386 "Save")' means the menu item called "Save" under the top-level "File"
387 menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under
388 the "Foo" submenu of "Menu".
390 - Function: add-submenu menu-path submenu &optional before in-menu
391 This function adds a menu to the menubar or one of its submenus.
392 If the named menu exists already, it is changed.
394 MENU-PATH identifies the menu under which the new menu should be
395 inserted. If MENU-PATH is `nil', then the menu will be added to
398 SUBMENU is the new menu to add (*note Menu Format::).
400 BEFORE, if provided, is the name of a menu before which this menu
401 should be added, if this menu is not on its parent already. If
402 the menu is already present, it will not be moved.
404 If IN-MENU is present use that instead of `current-menubar' as the
407 - Function: add-menu-button menu-path menu-leaf &optional before
409 This function adds a menu item to some menu, creating the menu
410 first if necessary. If the named item exists already, it is
413 MENU-PATH identifies the menu under which the new menu item should
416 MENU-LEAF is a menubar leaf node (*note Menu Format::).
418 BEFORE, if provided, is the name of a menu before which this item
419 should be added, if this item is not on the menu already. If the
420 item is already present, it will not be moved.
422 If IN-MENU is present use that instead of `current-menubar' as the
425 - Function: delete-menu-item menu-item-path &optional from-menu
426 This function removes the menu item specified by MENU-ITEM-PATH
427 from the menu hierarchy.
429 If FROM-MENU is present use that instead of `current-menubar' as
432 - Function: enable-menu-item menu-item-path
433 This function makes the menu item specified by MENU-ITEM-PATH be
436 - Function: disable-menu-item menu-item-path
437 This function makes the menu item specified by MENU-ITEM-PATH be
440 - Function: relabel-menu-item menu-item-path new-name
441 This function changes the string of the menu item specified by
442 MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be
443 printed as from now on.
445 The following function can be used to search for a particular item in
446 a menubar specification, given a path to the item.
448 - Function: find-menu-item menubar menu-item-path &optional parent
449 This function searches MENUBAR for the item given by
450 MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
451 of MENUBAR). This function returns `(ITEM . PARENT)', where
452 PARENT is the immediate parent of the item found (a menu
453 description), and ITEM is either a vector, list, or string,
454 depending on the nature of the menu item.
456 This function signals an error if the item is not found.
458 The following deprecated functions are also documented, so that
459 existing code can be understood. You should not use these functions in
462 - Function: add-menu menu-path menu-name menu-items &optional before
463 This function adds a menu to the menubar or one of its submenus.
464 If the named menu exists already, it is changed. This is
465 obsolete; use `add-submenu' instead.
467 MENU-PATH identifies the menu under which the new menu should be
468 inserted. If MENU-PATH is `nil', then the menu will be added to
471 MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
472 a list of menu items, strings, and submenus. These two arguments
473 are the same as the first and following elements of a menu
474 description (*note Menu Format::).
476 BEFORE, if provided, is the name of a menu before which this menu
477 should be added, if this menu is not on its parent already. If the
478 menu is already present, it will not be moved.
480 - Function: add-menu-item menu-path item-name function enabled-p
482 This function adds a menu item to some menu, creating the menu
483 first if necessary. If the named item exists already, it is
484 changed. This is obsolete; use `add-menu-button' instead.
486 MENU-PATH identifies the menu under which the new menu item should
487 be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
488 second, and third elements of a menu item vector (*note Menu
491 BEFORE, if provided, is the name of a menu item before which this
492 item should be added, if this item is not on the menu already. If
493 the item is already present, it will not be moved.
496 File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus
501 The following filter functions are provided for use in
502 `default-menubar'. You may want to use them in your own menubar
505 - Function: file-menu-filter menu-items
506 This function changes the arguments and sensitivity of these File
510 Has the name of the current buffer appended to it.
513 Has the name of the current buffer appended to it.
515 `Pretty-Print Buffer'
516 Has the name of the current buffer appended to it.
519 Has the name of the current buffer appended to it, and is
520 sensitive only when the current buffer is modified.
523 Has the name of the current buffer appended to it, and is
524 sensitive only when the current buffer has a file.
527 Sensitive only when there is more than one visible frame.
529 - Function: edit-menu-filter menu-items
530 This function changes the arguments and sensitivity of these Edit
534 Sensitive only when XEmacs owns the primary X Selection (if
535 `zmacs-regions' is `t', this is equivalent to saying that
536 there is a region selected).
539 Sensitive only when XEmacs owns the primary X Selection.
542 Sensitive only when XEmacs owns the primary X Selection.
545 Sensitive only when there is an owner for the X Clipboard
549 Sensitive only when there is undo information. While in the
550 midst of an undo, this is changed to `Undo More'.
552 - Function: buffers-menu-filter menu-items
553 This function sets up the Buffers menu. *Note Buffers Menu::, for
557 File: lispref.info, Node: Pop-Up Menus, Next: Menu Filters, Prev: Modifying Menus, Up: Menus
562 - Function: popup-menu menu-description &optional event
563 This function pops up a menu specified by MENU-DESCRIPTION, which
564 is a menu description (*note Menu Format::). The menu is
565 displayed at the current mouse position.
567 - Function: popup-menu-up-p
568 This function returns `t' if a pop-up menu is up, `nil' otherwise.
570 - Variable: popup-menu-titles
571 If true (the default), pop-up menus will have title bars at the
574 Some machinery is provided that attempts to provide a higher-level
575 mechanism onto pop-up menus. This only works if you do not redefine
576 the binding for button3.
578 - Command: popup-mode-menu
579 This function pops up a menu of global and mode-specific commands.
580 The menu is computed by combining `global-popup-menu' and
581 `mode-popup-menu'. This is the default binding for button3. You
582 should generally not change this binding.
584 - Variable: global-popup-menu
585 This holds the global popup menu. This is present in all modes.
586 (This is `nil' by default.)
588 - Variable: mode-popup-menu
589 The mode-specific popup menu. Automatically buffer local. This
590 is appended to the default items in `global-popup-menu'.
592 - Constant: default-popup-menu
593 This holds the default value of `mode-popup-menu'.
595 - Variable: activate-popup-menu-hook
596 Function or functions run before a mode-specific popup menu is made
597 visible. These functions are called with no arguments, and should
598 interrogate and modify the value of `global-popup-menu' or
599 `mode-popup-menu' as desired. Note: this hook is only run if you
600 use `popup-mode-menu' for activating the global and mode-specific
601 commands; if you have your own binding for button3, this hook
604 The following convenience functions are provided for displaying
607 - Command: popup-buffer-menu event
608 This function pops up a copy of the `Buffers' menu (from the
609 menubar) where the mouse is clicked. It should be bound to a
612 - Command: popup-menubar-menu event
613 This function pops up a copy of menu that also appears in the
614 menubar. It should be bound to a mouse button event.
617 File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus
622 Menu accelerators are keyboard shortcuts for accessing the menubar.
623 Accelerator keys can be specified for menus as well as for menu items.
624 An accelerator key for a menu is used to activate that menu when it
625 appears as a submenu of another menu. An accelerator key for a menu
626 item is used to activate that item.
630 * Creating Menu Accelerators:: How to add accelerator keys to a menu.
631 * Keyboard Menu Traversal:: How to use and modify the keys which are used
632 to traverse the menu structure.
633 * Menu Accelerator Functions:: Functions for working with menu accelerators.
636 File: lispref.info, Node: Creating Menu Accelerators, Next: Keyboard Menu Traversal, Up: Menu Accelerators
638 Creating Menu Accelerators
639 --------------------------
641 Menu accelerators are specified as part of the menubar format using
642 the :accelerator tag to specify a key or by placing "%_" in the menu or
643 menu item name prior to the letter which is to be used as the
644 accelerator key. The advantage of the second method is that the menu
645 rendering code then knows to draw an underline under that character,
646 which is the canonical way of indicating an accelerator key to a user.
648 For example, the command
650 (add-submenu nil '("%_Test"
651 ["One" (insert "1") :accelerator ?1 :active t]
652 ["%_Two" (insert "2")]
653 ["%_3" (insert "3")]))
655 will add a new menu to the top level menubar. The new menu can be
656 reached by pressing "t" while the top level menubar is active. When
657 the menu is active, pressing "1" will activate the first item and
658 insert the character "1" into the buffer. Pressing "2" will activate
659 the second item and insert the character "2" into the buffer. Pressing
660 "3" will activate the third item and insert the character "3" into the
663 It is possible to activate the top level menubar itself using
664 accelerator keys. *Note Menu Accelerator Functions::.
667 File: lispref.info, Node: Keyboard Menu Traversal, Next: Menu Accelerator Functions, Prev: Creating Menu Accelerators, Up: Menu Accelerators
669 Keyboard Menu Traversal
670 -----------------------
672 In addition to immediately activating a menu or menu item, the
673 keyboard can be used to traverse the menus without activating items.
674 The keyboard arrow keys, the return key and the escape key are defined
675 to traverse the menus in a way that should be familiar to users of any
676 of a certain family of popular PC operating systems.
678 This behavior can be changed by modifying the bindings in
679 menu-accelerator-map. At this point, the online help is your best bet
680 for more information about how to modify the menu traversal keys.
683 File: lispref.info, Node: Menu Accelerator Functions, Prev: Keyboard Menu Traversal, Up: Menu Accelerators
685 Menu Accelerator Functions
686 --------------------------
688 - Command: accelerate-menu
689 Make the menubar immediately active and place the cursor on the
690 left most entry in the top level menu. Menu items can be selected
693 - Variable: menu-accelerator-enabled
694 Whether menu accelerator keys can cause the menubar to become
697 If `menu-force' or `menu-fallback', then menu accelerator keys can
698 be used to activate the top level menu. Once the menubar becomes
699 active, the accelerator keys can be used regardless of the value
702 `menu-force' is used to indicate that the menu accelerator key
703 takes precedence over bindings in the current keymap(s).
704 `menu-fallback' means that bindings in the current keymap take
705 precedence over menu accelerator keys. Thus a top level menu with
706 an accelerator of "T" would be activated on a keypress of Meta-t
707 if MENU-ACCELERATOR-ENABLED is `menu-force'. However, if
708 MENU-ACCELERATOR-ENABLED is `menu-fallback', then Meta-t will not
709 activate the menubar and will instead run the function
710 transpose-words, to which it is normally bound.
712 The default value is `nil'.
714 See also MENU-ACCELERATOR-MODIFIERS and MENU-ACCELERATOR-PREFIX.
716 - Variable: menu-accelerator-map
717 Keymap consulted to determine the commands to run in response to
718 keypresses occurring while the menubar is active. *Note Keyboard
721 - Variable: menu-accelerator-modifiers
722 A list of modifier keys which must be pressed in addition to a
723 valid menu accelerator in order for the top level menu to be
724 activated in response to a keystroke. The default value of
725 `(meta)' mirrors the usage of the alt key as a menu accelerator in
726 popular PC operating systems.
728 The modifier keys in MENU-ACCELERATOR-MODIFIERS must match exactly
729 the modifiers present in the keypress. The only exception is that
730 the shift modifier is accepted in conjunction with alphabetic keys
731 even if it is not a menu accelerator modifier.
733 See also MENU-ACCELERATOR-ENABLED and MENU-ACCELERATOR-PREFIX.
735 - Variable: menu-accelerator-prefix
736 Prefix key(s) that must be typed before menu accelerators will be
737 activated. Must be a valid key descriptor.
739 The default value is `nil'.
741 (setq menu-accelerator-prefix ?\C-x)
742 (setq menu-accelerator-modifiers '(meta control))
743 (setq menu-accelerator-enabled 'menu-force)
744 (add-submenu nil '("%_Test"
745 ["One" (insert "1") :accelerator ?1 :active t]
746 ["%_Two" (insert "2")]
747 ["%_3" (insert "3")]))
749 will add the menu "Test" to the top level menubar. Pressing C-x
750 followed by C-M-T will activate the menubar and display the "Test"
751 menu. Pressing C-M-T by itself will not activate the menubar. Neither
752 will pressing C-x followed by anything else.
755 File: lispref.info, Node: Buffers Menu, Prev: Menu Accelerators, Up: Menus
760 The following options control how the `Buffers' menu is displayed.
761 This is a list of all (or a subset of) the buffers currently in
762 existence, and is updated dynamically.
764 - User Option: buffers-menu-max-size
765 This user option holds the maximum number of entries which may
766 appear on the `Buffers' menu. If this is 10, then only the ten
767 most-recently-selected buffers will be shown. If this is `nil',
768 then all buffers will be shown. Setting this to a large number or
769 `nil' will slow down menu responsiveness.
771 - Function: format-buffers-menu-line buffer
772 This function returns a string to represent BUFFER in the
773 `Buffers' menu. `nil' means the buffer shouldn't be listed. You
776 - User Option: complex-buffers-menu-p
777 If true, the `Buffers' menu will contain several commands, as
778 submenus of each buffer line. If this is false, then there will
779 be only one command: select that buffer.
781 - User Option: buffers-menu-switch-to-buffer-function
782 This user option holds the function to call to select a buffer
783 from the `Buffers' menu. `switch-to-buffer' is a good choice, as
787 File: lispref.info, Node: Dialog Boxes, Next: Toolbar, Prev: Menus, Up: Top
794 * Dialog Box Format::
795 * Dialog Box Functions::
798 File: lispref.info, Node: Dialog Box Format, Next: Dialog Box Functions, Up: Dialog Boxes
803 A dialog box description is a list.
805 * The first element of the list is a string to display in the dialog
808 * The rest of the elements are descriptions of the dialog box's
809 buttons. Each one is a vector of three elements:
810 - The first element is the text of the button.
812 - The second element is the "callback".
814 - The third element is `t' or `nil', whether this button is
817 If the callback of a button is a symbol, then it must name a command.
818 It will be invoked with `call-interactively'. If it is a list, then it
819 is evaluated with `eval'.
821 One (and only one) of the buttons may be `nil'. This marker means
822 that all following buttons should be flushright instead of flushleft.
824 The syntax, more precisely:
826 form := <something to pass to `eval'>
827 command := <a symbol or string, to pass to `call-interactively'>
828 callback := command | form
829 active-p := <t, nil, or a form to evaluate to decide whether this
830 button should be selectable>
833 button := '[' name callback active-p ']'
834 dialog := '(' name [ button ]+ [ partition [ button ]+ ] ')'
837 File: lispref.info, Node: Dialog Box Functions, Prev: Dialog Box Format, Up: Dialog Boxes
842 - Function: popup-dialog-box dbox-desc
843 This function pops up a dialog box. DBOX-DESC describes how the
844 dialog box will appear (*note Dialog Box Format::).
846 *Note Yes-or-No Queries::, for functions to ask a yes/no question
850 File: lispref.info, Node: Toolbar, Next: Gutter, Prev: Dialog Boxes, Up: Top
857 * Toolbar Intro:: An introduction.
858 * Creating Toolbar:: How to create a toolbar.
859 * Toolbar Descriptor Format:: Accessing and modifying a toolbar's
861 * Specifying the Toolbar:: Setting a toolbar's contents.
862 * Other Toolbar Variables:: Controlling the size of toolbars.
865 File: lispref.info, Node: Toolbar Intro, Next: Creating Toolbar, Up: Toolbar
870 A "toolbar" is a bar of icons displayed along one edge of a frame.
871 You can view a toolbar as a series of menu shortcuts--the most common
872 menu options can be accessed with a single click rather than a series
873 of clicks and/or drags to select the option from a menu. Consistent
874 with this, a help string (called the "help-echo") describing what an
875 icon in the toolbar (called a "toolbar button") does, is displayed in
876 the minibuffer when the mouse is over the button.
878 In XEmacs, a toolbar can be displayed along any of the four edges of
879 the frame, and two or more different edges can be displaying toolbars
880 simultaneously. The contents, thickness, and visibility of the
881 toolbars can be controlled separately, and the values can be
882 per-buffer, per-frame, etc., using specifiers (*note Specifiers::).
884 Normally, there is one toolbar displayed in a frame. Usually, this
885 is the standard toolbar, but certain modes will override this and
886 substitute their own toolbar. In some cases (e.g. the VM package), a
887 package will supply its own toolbar along a different edge from the
888 standard toolbar, so that both can be visible at once. This standard
889 toolbar is usually positioned along the top of the frame, but this can
890 be changed using `set-default-toolbar-position'.
892 Note that, for each of the toolbar properties (contents, thickness,
893 and visibility), there is a separate specifier for each of the four
894 toolbar positions (top, bottom, left, and right), and an additional
895 specifier for the "default" toolbar, i.e. the toolbar whose position is
896 controlled by `set-default-toolbar-position'. The way this works is
897 that `set-default-toolbar-position' arranges things so that the
898 appropriate position-specific specifiers for the default position
899 inherit from the corresponding default specifiers. That way, if the
900 position-specific specifier does not give a value (which it usually
901 doesn't), then the value from the default specifier applies. If you
902 want to control the default toolbar, you just change the default
903 specifiers, and everything works. A package such as VM that wants to
904 put its own toolbar in a different location from the default just sets
905 the position-specific specifiers, and if the user sets the default
906 toolbar to the same position, it will just not be visible.
909 File: lispref.info, Node: Creating Toolbar, Next: Toolbar Descriptor Format, Prev: Toolbar Intro, Up: Toolbar
914 - Function: make-toolbar-specifier spec-list
915 Return a new `toolbar' specifier object with the given
916 specification list. SPEC-LIST can be a list of specifications
917 (each of which is a cons of a locale and a list of instantiators),
918 a single instantiator, or a list of instantiators. *Note
919 Specifiers::, for more information about specifiers.
921 Toolbar specifiers are used to specify the format of a toolbar.
922 The values of the variables `default-toolbar', `top-toolbar',
923 `left-toolbar', `right-toolbar', and `bottom-toolbar' are always
926 Valid toolbar instantiators are called "toolbar descriptors" and
927 are lists of vectors. See `default-toolbar' for a description of
931 File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar
933 Toolbar Descriptor Format
934 =========================
936 The contents of a toolbar are specified using a "toolbar descriptor".
937 The format of a toolbar descriptor is a list of "toolbar button
938 descriptors". Each toolbar button descriptor is a vector in one of the
941 * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
943 * `[:style 2D-OR-3D]'
945 * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
947 * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
949 Optionally, one of the toolbar button descriptors may be `nil'
950 instead of a vector; this signifies the division between the toolbar
951 buttons that are to be displayed flush-left, and the buttons to be
952 displayed flush-right.
954 The first vector format above specifies a normal toolbar button; the
955 others specify blank areas in the toolbar.
957 For the first vector format:
959 * GLYPH-LIST should be a list of one to six glyphs (as created by
960 `make-glyph') or a symbol whose value is such a list. The first
961 glyph, which must be provided, is the glyph used to display the
962 toolbar button when it is in the "up" (not pressed) state. The
963 optional second glyph is for displaying the button when it is in
964 the "down" (pressed) state. The optional third glyph is for when
965 the button is disabled. The last three glyphs are for displaying
966 the button in the "up", "down", and "disabled" states,
967 respectively, but are used when the user has called for captioned
968 toolbar buttons (using `toolbar-buttons-captioned-p'). The
969 function `toolbar-make-button-list' is useful in creating these
972 * Even if you do not provide separate down-state and disabled-state
973 glyphs, the user will still get visual feedback to indicate which
974 state the button is in. Buttons in the up-state are displayed
975 with a shadowed border that gives a raised appearance to the
976 button. Buttons in the down-state are displayed with shadows that
977 give a recessed appearance. Buttons in the disabled state are
978 displayed with no shadows, giving a 2-d effect.
980 * If some of the toolbar glyphs are not provided, they inherit as
985 DISABLED: disabled -> up
987 CAP-DOWN: cap-down -> cap-up -> down -> up
988 CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up
990 * The second element FUNCTION is a function to be called when the
991 toolbar button is activated (i.e. when the mouse is released over
992 the toolbar button, if the press occurred in the toolbar). It can
993 be any form accepted by `call-interactively', since this is how it
996 * The third element ENABLED-P specifies whether the toolbar button
997 is enabled (disabled buttons do nothing when they are activated,
998 and are displayed differently; see above). It should be either a
999 boolean or a form that evaluates to a boolean.
1001 * The fourth element HELP, if non-`nil', should be a string. This
1002 string is displayed in the echo area when the mouse passes over the
1005 For the other vector formats (specifying blank areas of the toolbar):
1007 * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
1008 whether the area is displayed with shadows (giving it a raised,
1009 3-d appearance) or without shadows (giving it a flat appearance).
1011 * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
1012 area. If omitted, it defaults to a device-specific value (8
1013 pixels for X devices).
1015 - Function: toolbar-make-button-list up &optional down disabled cap-up
1016 cap-down cap-disabled
1017 This function calls `make-glyph' on each arg and returns a list of
1018 the results. This is useful for setting the first argument of a
1019 toolbar button descriptor (typically, the result of this function
1020 is assigned to a symbol, which is specified as the first argument
1021 of the toolbar button descriptor).
1023 - Function: check-toolbar-button-syntax button &optional noerror
1024 Verify the syntax of entry BUTTON in a toolbar description list.
1025 If you want to verify the syntax of a toolbar description list as a
1026 whole, use `check-valid-instantiator' with a specifier type of
1030 File: lispref.info, Node: Specifying the Toolbar, Next: Other Toolbar Variables, Prev: Toolbar Descriptor Format, Up: Toolbar
1032 Specifying the Toolbar
1033 ======================
1035 In order to specify the contents of a toolbar, set one of the
1036 specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar',
1037 `left-toolbar', or `right-toolbar'. These are specifiers, which means
1038 you set them with `set-specifier' and query them with `specifier-specs'
1039 or `specifier-instance'. You will get an error if you try to set them
1040 using `setq'. The valid instantiators for these specifiers are toolbar
1041 descriptors, as described above. *Note Specifiers::, for more
1044 Most of the time, you will set `default-toolbar', which allows the
1045 user to choose where the toolbar should go.
1047 - Specifier: default-toolbar
1048 The position of this toolbar is specified in the function
1049 `default-toolbar-position'. If the corresponding
1050 position-specific toolbar (e.g. `top-toolbar' if
1051 `default-toolbar-position' is `top') does not specify a toolbar in
1052 a particular domain, then the value of `default-toolbar' in that
1053 domain, of any, will be used instead.
1055 Note that the toolbar at any particular position will not be
1056 displayed unless its thickness (width or height, depending on
1057 orientation) is non-zero and its visibility status is true. The
1058 thickness is controlled by the specifiers `top-toolbar-height',
1059 `bottom-toolbar-height', `left-toolbar-width', and
1060 `right-toolbar-width', and the visibility status is controlled by the
1061 specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
1062 `left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
1063 Toolbar Variables::).
1065 - Function: set-default-toolbar-position position
1066 This function sets the position that the `default-toolbar' will be
1067 displayed at. Valid positions are the symbols `top', `bottom',
1068 `left' and `right'. What this actually does is set the fallback
1069 specifier for the position-specific specifier corresponding to the
1070 given position to `default-toolbar', and set the fallbacks for the
1071 other position-specific specifiers to `nil'. It also does the
1072 same thing for the position-specific thickness and visibility
1073 specifiers, which inherit from one of `default-toolbar-height' or
1074 `default-toolbar-width', and from `default-toolbar-visible-p',
1075 respectively (*note Other Toolbar Variables::).
1077 - Function: default-toolbar-position
1078 This function returns the position that the `default-toolbar' will
1081 You can also explicitly set a toolbar at a particular position. When
1082 redisplay determines what to display at a particular position in a
1083 particular domain (i.e. window), it first consults the position-specific
1084 toolbar. If that does not yield a toolbar descriptor, the
1085 `default-toolbar' is consulted if `default-toolbar-position' indicates
1088 - Specifier: top-toolbar
1089 Specifier for the toolbar at the top of the frame.
1091 - Specifier: bottom-toolbar
1092 Specifier for the toolbar at the bottom of the frame.
1094 - Specifier: left-toolbar
1095 Specifier for the toolbar at the left edge of the frame.
1097 - Specifier: right-toolbar
1098 Specifier for the toolbar at the right edge of the frame.
1100 - Function: toolbar-specifier-p object
1101 This function returns non-`nil' if OBJECT is a toolbar specifier.
1102 Toolbar specifiers are the actual objects contained in the toolbar
1103 variables described above, and their valid instantiators are
1104 toolbar descriptors (*note Toolbar Descriptor Format::).
1107 File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar
1109 Other Toolbar Variables
1110 =======================
1112 The variables to control the toolbar thickness, visibility status,
1113 and captioned status are all specifiers. *Note Specifiers::.
1115 - Specifier: default-toolbar-height
1116 This specifies the height of the default toolbar, if it's oriented
1117 horizontally. The position of the default toolbar is specified by
1118 the function `set-default-toolbar-position'. If the corresponding
1119 position-specific toolbar thickness specifier (e.g.
1120 `top-toolbar-height' if `default-toolbar-position' is `top') does
1121 not specify a thickness in a particular domain (a window or a
1122 frame), then the value of `default-toolbar-height' or
1123 `default-toolbar-width' (depending on the toolbar orientation) in
1124 that domain, if any, will be used instead.
1126 - Specifier: default-toolbar-width
1127 This specifies the width of the default toolbar, if it's oriented
1128 vertically. This behaves like `default-toolbar-height'.
1130 Note that `default-toolbar-height' is only used when
1131 `default-toolbar-position' is `top' or `bottom', and
1132 `default-toolbar-width' is only used when `default-toolbar-position' is
1135 - Specifier: top-toolbar-height
1136 This specifies the height of the top toolbar.
1138 - Specifier: bottom-toolbar-height
1139 This specifies the height of the bottom toolbar.
1141 - Specifier: left-toolbar-width
1142 This specifies the width of the left toolbar.
1144 - Specifier: right-toolbar-width
1145 This specifies the width of the right toolbar.
1147 Note that all of the position-specific toolbar thickness specifiers
1148 have a fallback value of zero when they do not correspond to the
1149 default toolbar. Therefore, you will have to set a non-zero thickness
1150 value if you want a position-specific toolbar to be displayed.
1152 - Specifier: default-toolbar-visible-p
1153 This specifies whether the default toolbar is visible. The
1154 position of the default toolbar is specified by the function
1155 `set-default-toolbar-position'. If the corresponding
1156 position-specific toolbar visibility specifier (e.g.
1157 `top-toolbar-visible-p' if `default-toolbar-position' is `top')
1158 does not specify a visible-p value in a particular domain (a
1159 window or a frame), then the value of `default-toolbar-visible-p'
1160 in that domain, if any, will be used instead.
1162 - Specifier: top-toolbar-visible-p
1163 This specifies whether the top toolbar is visible.
1165 - Specifier: bottom-toolbar-visible-p
1166 This specifies whether the bottom toolbar is visible.
1168 - Specifier: left-toolbar-visible-p
1169 This specifies whether the left toolbar is visible.
1171 - Specifier: right-toolbar-visible-p
1172 This specifies whether the right toolbar is visible.
1174 `default-toolbar-visible-p' and all of the position-specific toolbar
1175 visibility specifiers have a fallback value of true.
1177 Internally, toolbar thickness and visibility specifiers are
1178 instantiated in both window and frame domains, for different purposes.
1179 The value in the domain of a frame's selected window specifies the
1180 actual toolbar thickness or visibility that you will see in that frame.
1181 The value in the domain of a frame itself specifies the toolbar
1182 thickness or visibility that is used in frame geometry calculations.
1184 Thus, for example, if you set the frame width to 80 characters and
1185 the left toolbar width for that frame to 68 pixels, then the frame will
1186 be sized to fit 80 characters plus a 68-pixel left toolbar. If you then
1187 set the left toolbar width to 0 for a particular buffer (or if that
1188 buffer does not specify a left toolbar or has a `nil' value specified
1189 for `left-toolbar-visible-p'), you will find that, when that buffer is
1190 displayed in the selected window, the window will have a width of 86 or
1191 87 characters--the frame is sized for a 68-pixel left toolbar but the
1192 selected window specifies that the left toolbar is not visible, so it is
1193 expanded to take up the slack.
1195 - Specifier: toolbar-buttons-captioned-p
1196 Whether toolbar buttons are captioned. This affects which glyphs
1197 from a toolbar button descriptor are chosen. *Note Toolbar
1198 Descriptor Format::.
1200 You can also reset the toolbar to what it was when XEmacs started up.
1202 - Constant: initial-toolbar-spec
1203 The toolbar descriptor used to initialize `default-toolbar' at
1207 File: lispref.info, Node: Gutter, Next: Scrollbars, Prev: Toolbar, Up: Top
1212 A gutter is a rectangle displayed along one edge of a frame. It can
1213 contain arbitrary text or graphics.
1217 * Gutter Intro:: An introduction.
1218 * Creating Gutter:: How to create a gutter.
1219 * Gutter Descriptor Format:: Accessing and modifying a gutter's
1221 * Specifying a Gutter:: Setting a gutter's contents.
1222 * Other Gutter Variables:: Controlling the size of gutters.
1223 * Common Gutter Widgets:: Things to put in gutters.