This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY * Lispref: (lispref). XEmacs Lisp Reference Manual. END-INFO-DIR-ENTRY Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: Menu Format, Next: Menubar Format, Up: Menus Format of Menus =============== A menu is described using a "menu description", which is a list of menu items, keyword-value pairs, strings, and submenus. The menu description specifies which items are present in the menu, what function each item invokes, and whether the item is selectable or not. Pop-up menus are directly described with a menu description, while menubars are described slightly differently (see below). The first element of a menu must be a string, which is the name of the menu. This is the string that will be displayed in the parent menu or menubar, if any. This string is not displayed in the menu itself, except in the case of the top level pop-up menu, where there is no parent. In this case, the string will be displayed at the top of the menu if `popup-menu-titles' is non-`nil'. Immediately following the first element there may optionally be up to four keyword-value pairs, as follows: `:included FORM' This can be used to control the visibility of a menu. The form is evaluated and the menu will be omitted if the result is `nil'. `:config SYMBOL' This is an efficient shorthand for `:included (memq SYMBOL menubar-configuration)'. See the variable `menubar-configuration'. `:filter FUNCTION' A menu filter is used to sensitize or incrementally create a submenu only when it is selected by the user and not every time the menubar is activated. The filter function is passed the list of menu items in the submenu and must return a list of menu items to be used for the menu. It is called only when the menu is about to be displayed, so other menus may already be displayed. Vile and terrible things will happen if a menu filter function changes the current buffer, window, or frame. It also should not raise, lower, or iconify any frames. Basically, the filter function should have no side-effects. `:accelerator KEY' A menu accelerator is a keystroke which can be pressed while the menu is visible which will immediately activate the item. KEY must be a char or the symbol name of a key. *Note Menu Accelerators::. The rest of the menu consists of elements as follows: * A "menu item", which is a vector in the following form: `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]' NAME is a string, the name of the menu item; it is the string to display on the menu. It is filtered through the resource database, so it is possible for resources to override what string is actually displayed. CALLBACK is a form that will be invoked when the menu item is selected. If the callback of a menu item is a symbol, then it must name a command. It will be invoked with `call-interactively'. If it is a list, then it is evaluated with `eval'. The valid keywords and their meanings are described below. Note that for compatibility purposes, the form `[ NAME CALLBACK ACTIVE-P ]' is also accepted and is equivalent to `[ NAME CALLBACK :active ACTIVE-P ]' and the form `[ NAME CALLBACK ACTIVE-P SUFFIX]' is accepted and is equivalent to `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]' However, these older forms are deprecated and should generally not be used. * If an element of a menu is a string, then that string will be presented in the menu as unselectable text. * If an element of a menu is a string consisting solely of hyphens, then that item will be presented as a solid horizontal line. * If an element of a menu is a string beginning with `--:', then a particular sort of horizontal line will be displayed, as follows: `"--:singleLine"' A solid horizontal line. This is equivalent to a string consisting solely of hyphens. `"--:doubleLine"' A solid double horizontal line. `"--:singleDashedLine"' A dashed horizontal line. `"--:doubleDashedLine"' A dashed double horizontal line. `"--:noLine"' No line (but a small space is left). `"--:shadowEtchedIn"' A solid horizontal line with a 3-d recessed appearance. `"--:shadowEtchedOut"' A solid horizontal line with a 3-d pushed-out appearance. `"--:shadowDoubleEtchedIn"' A solid double horizontal line with a 3-d recessed appearance. `"--:shadowDoubleEtchedOut"' A solid double horizontal line with a 3-d pushed-out appearance. `"--:shadowEtchedInDash"' A dashed horizontal line with a 3-d recessed appearance. `"--:shadowEtchedOutDash"' A dashed horizontal line with a 3-d pushed-out appearance. `"--:shadowDoubleEtchedInDash"' A dashed double horizontal line with a 3-d recessed appearance. `"--:shadowDoubleEtchedOutDash"' A dashed double horizontal line with a 3-d pushed-out appearance. * If an element of a menu is a list, it is treated as a submenu. The name of that submenu (the first element in the list) will be used as the name of the item representing this menu on the parent. The possible keywords are as follows: :active FORM FORM will be evaluated when the menu that this item is a part of is about to be displayed, and the item will be selectable only if the result is non-`nil'. If the item is unselectable, it will usually be displayed grayed-out to indicate this. :suffix FORM FORM will be evaluated when the menu that this item is a part of is about to be displayed, and the resulting string is appended to the displayed name. This provides a convenient way of adding the name of a command's "argument" to the menu, like `Kill Buffer NAME'. :keys STRING Normally, the keyboard equivalents of commands in menus are displayed when the "callback" is a symbol. This can be used to specify keys for more complex menu items. It is passed through `substitute-command-keys' first. :style STYLE Specifies what kind of object this menu item is. STYLE be one of the symbols `nil' A normal menu item. `toggle' A toggle button. `radio' A radio button. `button' A menubar button. The only difference between toggle and radio buttons is how they are displayed. But for consistency, a toggle button should be used when there is one option whose value can be turned on or off, and radio buttons should be used when there is a set of mutually exclusive options. When using a group of radio buttons, you should arrange for no more than one to be marked as selected at a time. :selected FORM Meaningful only when STYLE is `toggle', `radio' or `button'. This specifies whether the button will be in the selected or unselected state. FORM is evaluated, as for `:active'. :included FORM This can be used to control the visibility of a menu item. The form is evaluated and the menu item is only displayed if the result is non-`nil'. Note that this is different from `:active': If `:active' evaluates to `nil', the item will be displayed grayed out, while if `:included' evaluates to `nil', the item will be omitted entirely. :config SYMBOL This is an efficient shorthand for `:included (memq SYMBOL menubar-configuration)'. See the variable `menubar-configuration'. :accelerator KEY A menu accelerator is a keystroke which can be pressed while the menu is visible which will immediately activate the item. KEY must be a char or the symbol name of a key. *Note Menu Accelerators::. - Variable: menubar-configuration This variable holds a list of symbols, against which the value of the `:config' tag for each menubar item will be compared. If a menubar item has a `:config' tag, then it is omitted from the menubar if that tag is not a member of the `menubar-configuration' list. For example: ("File" :filter file-menu-filter ; file-menu-filter is a function that takes ; one argument (a list of menu items) and ; returns a list of menu items [ "Save As..." write-file] [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ] [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ] )  File: lispref.info, Node: Menubar Format, Next: Menubar, Prev: Menu Format, Up: Menus Format of the Menubar ===================== A menubar is a list of menus, menu items, and strings. The format is similar to that of a menu, except: * The first item need not be a string, and is not treated specially. * A string consisting solely of hyphens is not treated specially. * If an element of a menubar is `nil', then it is used to represent the division between the set of menubar items which are flush-left and those which are flush-right. (Note: this isn't completely implemented yet.)  File: lispref.info, Node: Menubar, Next: Modifying Menus, Prev: Menubar Format, Up: Menus Menubar ======= - Variable: current-menubar This variable holds the description of the current menubar. This may be buffer-local. When the menubar is changed, the function `set-menubar-dirty-flag' has to be called in order for the menubar to be updated on the screen. - Constant: default-menubar This variable holds the menubar description of the menubar that is visible at startup. This is the value that `current-menubar' has at startup. - Function: set-menubar-dirty-flag This function tells XEmacs that the menubar widget has to be updated. Changes to the menubar will generally not be visible until this function is called. The following convenience functions are provided for setting the menubar. They are equivalent to doing the appropriate action to change `current-menubar', and then calling `set-menubar-dirty-flag'. Note that these functions copy their argument using `copy-sequence'. - Function: set-menubar menubar This function sets the default menubar to be MENUBAR (*note Menu Format::). This is the menubar that will be visible in buffers that have not defined their own, buffer-local menubar. - Function: set-buffer-menubar menubar This function sets the buffer-local menubar to be MENUBAR. This does not change the menubar in any buffers other than the current one. Miscellaneous: - Variable: menubar-show-keybindings If true, the menubar will display keyboard equivalents. If false, only the command names will be displayed. - Variable: activate-menubar-hook Function or functions called before a menubar menu is pulled down. These functions are called with no arguments, and should interrogate and modify the value of `current-menubar' as desired. The functions on this hook are invoked after the mouse goes down, but before the menu is mapped, and may be used to activate, deactivate, add, or delete items from the menus. However, using a filter (with the `:filter' keyword in a menu description) is generally a more efficient way of accomplishing the same thing, because the filter is invoked only when the actual menu goes down. With a complex menu, there can be a quite noticeable and sometimes aggravating delay if all menu modification is implemented using the `activate-menubar-hook'. See above. These functions may return the symbol `t' to assert that they have made no changes to the menubar. If any other value is returned, the menubar is recomputed. If `t' is returned but the menubar has been changed, then the changes may not show up right away. Returning `nil' when the menubar has not changed is not so bad; more computation will be done, but redisplay of the menubar will still be performed optimally. - Variable: menu-no-selection-hook Function or functions to call when a menu or dialog box is dismissed without a selection having been made.  File: lispref.info, Node: Modifying Menus, Next: Pop-Up Menus, Prev: Menubar, Up: Menus Modifying Menus =============== The following functions are provided to modify the menubar of one of its submenus. Note that these functions modify the menu in-place, rather than copying it and making a new menu. Some of these functions take a "menu path", which is a list of strings identifying the menu to be modified. For example, `("File")' names the top-level "File" menu. `("File" "Foo")' names a hypothetical submenu of "File". Others take a "menu item path", which is similar to a menu path but also specifies a particular item to be modified. For example, `("File" "Save")' means the menu item called "Save" under the top-level "File" menu. `("Menu" "Foo" "Item")' means the menu item called "Item" under the "Foo" submenu of "Menu". - Function: add-submenu menu-path submenu &optional before in-menu This function adds a menu to the menubar or one of its submenus. If the named menu exists already, it is changed. MENU-PATH identifies the menu under which the new menu should be inserted. If MENU-PATH is `nil', then the menu will be added to the menubar itself. SUBMENU is the new menu to add (*note Menu Format::). BEFORE, if provided, is the name of a menu before which this menu should be added, if this menu is not on its parent already. If the menu is already present, it will not be moved. If IN-MENU is present use that instead of `current-menubar' as the menu to change. - Function: add-menu-button menu-path menu-leaf &optional before in-menu This function adds a menu item to some menu, creating the menu first if necessary. If the named item exists already, it is changed. MENU-PATH identifies the menu under which the new menu item should be inserted. MENU-LEAF is a menubar leaf node (*note Menu Format::). BEFORE, if provided, is the name of a menu before which this item should be added, if this item is not on the menu already. If the item is already present, it will not be moved. If IN-MENU is present use that instead of `current-menubar' as the menu to change. - Function: delete-menu-item menu-item-path &optional from-menu This function removes the menu item specified by MENU-ITEM-PATH from the menu hierarchy. If FROM-MENU is present use that instead of `current-menubar' as the menu to change. - Function: enable-menu-item menu-item-path This function makes the menu item specified by MENU-ITEM-PATH be selectable. - Function: disable-menu-item menu-item-path This function makes the menu item specified by MENU-ITEM-PATH be unselectable. - Function: relabel-menu-item menu-item-path new-name This function changes the string of the menu item specified by MENU-ITEM-PATH. NEW-NAME is the string that the menu item will be printed as from now on. The following function can be used to search for a particular item in a menubar specification, given a path to the item. - Function: find-menu-item menubar menu-item-path &optional parent This function searches MENUBAR for the item given by MENU-ITEM-PATH starting from PARENT (`nil' means start at the top of MENUBAR). This function returns `(ITEM . PARENT)', where PARENT is the immediate parent of the item found (a menu description), and ITEM is either a vector, list, or string, depending on the nature of the menu item. This function signals an error if the item is not found. The following deprecated functions are also documented, so that existing code can be understood. You should not use these functions in new code. - Function: add-menu menu-path menu-name menu-items &optional before This function adds a menu to the menubar or one of its submenus. If the named menu exists already, it is changed. This is obsolete; use `add-submenu' instead. MENU-PATH identifies the menu under which the new menu should be inserted. If MENU-PATH is `nil', then the menu will be added to the menubar itself. MENU-NAME is the string naming the menu to be added; MENU-ITEMS is a list of menu items, strings, and submenus. These two arguments are the same as the first and following elements of a menu description (*note Menu Format::). BEFORE, if provided, is the name of a menu before which this menu should be added, if this menu is not on its parent already. If the menu is already present, it will not be moved. - Function: add-menu-item menu-path item-name function enabled-p &optional before This function adds a menu item to some menu, creating the menu first if necessary. If the named item exists already, it is changed. This is obsolete; use `add-menu-button' instead. MENU-PATH identifies the menu under which the new menu item should be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first, second, and third elements of a menu item vector (*note Menu Format::). BEFORE, if provided, is the name of a menu item before which this item should be added, if this item is not on the menu already. If the item is already present, it will not be moved.  File: lispref.info, Node: Menu Filters, Next: Menu Accelerators, Prev: Pop-Up Menus, Up: Menus Menu Filters ============ The following filter functions are provided for use in `default-menubar'. You may want to use them in your own menubar description. - Function: file-menu-filter menu-items This function changes the arguments and sensitivity of these File menu items: `Delete Buffer' Has the name of the current buffer appended to it. `Print Buffer' Has the name of the current buffer appended to it. `Pretty-Print Buffer' Has the name of the current buffer appended to it. `Save Buffer' Has the name of the current buffer appended to it, and is sensitive only when the current buffer is modified. `Revert Buffer' Has the name of the current buffer appended to it, and is sensitive only when the current buffer has a file. `Delete Frame' Sensitive only when there is more than one visible frame. - Function: edit-menu-filter menu-items This function changes the arguments and sensitivity of these Edit menu items: `Cut' Sensitive only when XEmacs owns the primary X Selection (if `zmacs-regions' is `t', this is equivalent to saying that there is a region selected). `Copy' Sensitive only when XEmacs owns the primary X Selection. `Clear' Sensitive only when XEmacs owns the primary X Selection. `Paste' Sensitive only when there is an owner for the X Clipboard Selection. `Undo' Sensitive only when there is undo information. While in the midst of an undo, this is changed to `Undo More'. - Function: buffers-menu-filter menu-items This function sets up the Buffers menu. *Note Buffers Menu::, for more information.  File: lispref.info, Node: Pop-Up Menus, Next: Menu Filters, Prev: Modifying Menus, Up: Menus Pop-Up Menus ============ - Function: popup-menu menu-description &optional event This function pops up a menu specified by MENU-DESCRIPTION, which is a menu description (*note Menu Format::). The menu is displayed at the current mouse position. - Function: popup-menu-up-p This function returns `t' if a pop-up menu is up, `nil' otherwise. - Variable: popup-menu-titles If true (the default), pop-up menus will have title bars at the top. Some machinery is provided that attempts to provide a higher-level mechanism onto pop-up menus. This only works if you do not redefine the binding for button3. - Command: popup-mode-menu This function pops up a menu of global and mode-specific commands. The menu is computed by combining `global-popup-menu' and `mode-popup-menu'. This is the default binding for button3. You should generally not change this binding. - Variable: global-popup-menu This holds the global popup menu. This is present in all modes. (This is `nil' by default.) - Variable: mode-popup-menu The mode-specific popup menu. Automatically buffer local. This is appended to the default items in `global-popup-menu'. - Constant: default-popup-menu This holds the default value of `mode-popup-menu'. - Variable: activate-popup-menu-hook Function or functions run before a mode-specific popup menu is made visible. These functions are called with no arguments, and should interrogate and modify the value of `global-popup-menu' or `mode-popup-menu' as desired. Note: this hook is only run if you use `popup-mode-menu' for activating the global and mode-specific commands; if you have your own binding for button3, this hook won't be run. The following convenience functions are provided for displaying pop-up menus. - Command: popup-buffer-menu event This function pops up a copy of the `Buffers' menu (from the menubar) where the mouse is clicked. It should be bound to a mouse button event. - Command: popup-menubar-menu event This function pops up a copy of menu that also appears in the menubar. It should be bound to a mouse button event.  File: lispref.info, Node: Menu Accelerators, Next: Buffers Menu, Prev: Menu Filters, Up: Menus Menu Accelerators ================= Menu accelerators are keyboard shortcuts for accessing the menubar. Accelerator keys can be specified for menus as well as for menu items. An accelerator key for a menu is used to activate that menu when it appears as a submenu of another menu. An accelerator key for a menu item is used to activate that item. * Menu: * Creating Menu Accelerators:: How to add accelerator keys to a menu. * Keyboard Menu Traversal:: How to use and modify the keys which are used to traverse the menu structure. * Menu Accelerator Functions:: Functions for working with menu accelerators.  File: lispref.info, Node: Creating Menu Accelerators, Next: Keyboard Menu Traversal, Up: Menu Accelerators Creating Menu Accelerators -------------------------- Menu accelerators are specified as part of the menubar format using the :accelerator tag to specify a key or by placing "%_" in the menu or menu item name prior to the letter which is to be used as the accelerator key. The advantage of the second method is that the menu rendering code then knows to draw an underline under that character, which is the canonical way of indicating an accelerator key to a user. For example, the command (add-submenu nil '("%_Test" ["One" (insert "1") :accelerator ?1 :active t] ["%_Two" (insert "2")] ["%_3" (insert "3")])) will add a new menu to the top level menubar. The new menu can be reached by pressing "t" while the top level menubar is active. When the menu is active, pressing "1" will activate the first item and insert the character "1" into the buffer. Pressing "2" will activate the second item and insert the character "2" into the buffer. Pressing "3" will activate the third item and insert the character "3" into the buffer. It is possible to activate the top level menubar itself using accelerator keys. *Note Menu Accelerator Functions::.  File: lispref.info, Node: Keyboard Menu Traversal, Next: Menu Accelerator Functions, Prev: Creating Menu Accelerators, Up: Menu Accelerators Keyboard Menu Traversal ----------------------- In addition to immediately activating a menu or menu item, the keyboard can be used to traverse the menus without activating items. The keyboard arrow keys, the return key and the escape key are defined to traverse the menus in a way that should be familiar to users of any of a certain family of popular PC operating systems. This behavior can be changed by modifying the bindings in menu-accelerator-map. At this point, the online help is your best bet for more information about how to modify the menu traversal keys.  File: lispref.info, Node: Menu Accelerator Functions, Prev: Keyboard Menu Traversal, Up: Menu Accelerators Menu Accelerator Functions -------------------------- - Command: accelerate-menu Make the menubar immediately active and place the cursor on the left most entry in the top level menu. Menu items can be selected as usual. - Variable: menu-accelerator-enabled Whether menu accelerator keys can cause the menubar to become active. If `menu-force' or `menu-fallback', then menu accelerator keys can be used to activate the top level menu. Once the menubar becomes active, the accelerator keys can be used regardless of the value of this variable. `menu-force' is used to indicate that the menu accelerator key takes precedence over bindings in the current keymap(s). `menu-fallback' means that bindings in the current keymap take precedence over menu accelerator keys. Thus a top level menu with an accelerator of "T" would be activated on a keypress of Meta-t if MENU-ACCELERATOR-ENABLED is `menu-force'. However, if MENU-ACCELERATOR-ENABLED is `menu-fallback', then Meta-t will not activate the menubar and will instead run the function transpose-words, to which it is normally bound. The default value is `nil'. See also MENU-ACCELERATOR-MODIFIERS and MENU-ACCELERATOR-PREFIX. - Variable: menu-accelerator-map Keymap consulted to determine the commands to run in response to keypresses occurring while the menubar is active. *Note Keyboard Menu Traversal::. - Variable: menu-accelerator-modifiers A list of modifier keys which must be pressed in addition to a valid menu accelerator in order for the top level menu to be activated in response to a keystroke. The default value of `(meta)' mirrors the usage of the alt key as a menu accelerator in popular PC operating systems. The modifier keys in MENU-ACCELERATOR-MODIFIERS must match exactly the modifiers present in the keypress. The only exception is that the shift modifier is accepted in conjunction with alphabetic keys even if it is not a menu accelerator modifier. See also MENU-ACCELERATOR-ENABLED and MENU-ACCELERATOR-PREFIX. - Variable: menu-accelerator-prefix Prefix key(s) that must be typed before menu accelerators will be activated. Must be a valid key descriptor. The default value is `nil'. (setq menu-accelerator-prefix ?\C-x) (setq menu-accelerator-modifiers '(meta control)) (setq menu-accelerator-enabled 'menu-force) (add-submenu nil '("%_Test" ["One" (insert "1") :accelerator ?1 :active t] ["%_Two" (insert "2")] ["%_3" (insert "3")])) will add the menu "Test" to the top level menubar. Pressing C-x followed by C-M-T will activate the menubar and display the "Test" menu. Pressing C-M-T by itself will not activate the menubar. Neither will pressing C-x followed by anything else.  File: lispref.info, Node: Buffers Menu, Prev: Menu Accelerators, Up: Menus Buffers Menu ============ The following options control how the `Buffers' menu is displayed. This is a list of all (or a subset of) the buffers currently in existence, and is updated dynamically. - User Option: buffers-menu-max-size This user option holds the maximum number of entries which may appear on the `Buffers' menu. If this is 10, then only the ten most-recently-selected buffers will be shown. If this is `nil', then all buffers will be shown. Setting this to a large number or `nil' will slow down menu responsiveness. - Function: format-buffers-menu-line buffer This function returns a string to represent BUFFER in the `Buffers' menu. `nil' means the buffer shouldn't be listed. You can redefine this. - User Option: complex-buffers-menu-p If true, the `Buffers' menu will contain several commands, as submenus of each buffer line. If this is false, then there will be only one command: select that buffer. - User Option: buffers-menu-switch-to-buffer-function This user option holds the function to call to select a buffer from the `Buffers' menu. `switch-to-buffer' is a good choice, as is `pop-to-buffer'.  File: lispref.info, Node: Dialog Boxes, Next: Toolbar, Prev: Menus, Up: Top Dialog Boxes ************ * Menu: * Dialog Box Format:: * Dialog Box Functions::  File: lispref.info, Node: Dialog Box Format, Next: Dialog Box Functions, Up: Dialog Boxes Dialog Box Format ================= A dialog box description is a list. * The first element of the list is a string to display in the dialog box. * The rest of the elements are descriptions of the dialog box's buttons. Each one is a vector of three elements: - The first element is the text of the button. - The second element is the "callback". - The third element is `t' or `nil', whether this button is selectable. If the callback of a button is a symbol, then it must name a command. It will be invoked with `call-interactively'. If it is a list, then it is evaluated with `eval'. One (and only one) of the buttons may be `nil'. This marker means that all following buttons should be flushright instead of flushleft. The syntax, more precisely: form := command := callback := command | form active-p := name := partition := 'nil' button := '[' name callback active-p ']' dialog := '(' name [ button ]+ [ partition [ button ]+ ] ')'  File: lispref.info, Node: Dialog Box Functions, Prev: Dialog Box Format, Up: Dialog Boxes Dialog Box Functions ==================== - Function: popup-dialog-box dbox-desc This function pops up a dialog box. DBOX-DESC describes how the dialog box will appear (*note Dialog Box Format::). *Note Yes-or-No Queries::, for functions to ask a yes/no question using a dialog box.  File: lispref.info, Node: Toolbar, Next: Gutter, Prev: Dialog Boxes, Up: Top Toolbar ******* * Menu: * Toolbar Intro:: An introduction. * Creating Toolbar:: How to create a toolbar. * Toolbar Descriptor Format:: Accessing and modifying a toolbar's properties. * Specifying the Toolbar:: Setting a toolbar's contents. * Other Toolbar Variables:: Controlling the size of toolbars.  File: lispref.info, Node: Toolbar Intro, Next: Creating Toolbar, Up: Toolbar Toolbar Intro ============= A "toolbar" is a bar of icons displayed along one edge of a frame. You can view a toolbar as a series of menu shortcuts--the most common menu options can be accessed with a single click rather than a series of clicks and/or drags to select the option from a menu. Consistent with this, a help string (called the "help-echo") describing what an icon in the toolbar (called a "toolbar button") does, is displayed in the minibuffer when the mouse is over the button. In XEmacs, a toolbar can be displayed along any of the four edges of the frame, and two or more different edges can be displaying toolbars simultaneously. The contents, thickness, and visibility of the toolbars can be controlled separately, and the values can be per-buffer, per-frame, etc., using specifiers (*note Specifiers::). Normally, there is one toolbar displayed in a frame. Usually, this is the standard toolbar, but certain modes will override this and substitute their own toolbar. In some cases (e.g. the VM package), a package will supply its own toolbar along a different edge from the standard toolbar, so that both can be visible at once. This standard toolbar is usually positioned along the top of the frame, but this can be changed using `set-default-toolbar-position'. Note that, for each of the toolbar properties (contents, thickness, and visibility), there is a separate specifier for each of the four toolbar positions (top, bottom, left, and right), and an additional specifier for the "default" toolbar, i.e. the toolbar whose position is controlled by `set-default-toolbar-position'. The way this works is that `set-default-toolbar-position' arranges things so that the appropriate position-specific specifiers for the default position inherit from the corresponding default specifiers. That way, if the position-specific specifier does not give a value (which it usually doesn't), then the value from the default specifier applies. If you want to control the default toolbar, you just change the default specifiers, and everything works. A package such as VM that wants to put its own toolbar in a different location from the default just sets the position-specific specifiers, and if the user sets the default toolbar to the same position, it will just not be visible.  File: lispref.info, Node: Creating Toolbar, Next: Toolbar Descriptor Format, Prev: Toolbar Intro, Up: Toolbar Creating Toolbar ================ - Function: make-toolbar-specifier spec-list Return a new `toolbar' specifier object with the given specification list. SPEC-LIST can be a list of specifications (each of which is a cons of a locale and a list of instantiators), a single instantiator, or a list of instantiators. *Note Specifiers::, for more information about specifiers. Toolbar specifiers are used to specify the format of a toolbar. The values of the variables `default-toolbar', `top-toolbar', `left-toolbar', `right-toolbar', and `bottom-toolbar' are always toolbar specifiers. Valid toolbar instantiators are called "toolbar descriptors" and are lists of vectors. See `default-toolbar' for a description of the exact format.  File: lispref.info, Node: Toolbar Descriptor Format, Next: Specifying the Toolbar, Prev: Creating Toolbar, Up: Toolbar Toolbar Descriptor Format ========================= The contents of a toolbar are specified using a "toolbar descriptor". The format of a toolbar descriptor is a list of "toolbar button descriptors". Each toolbar button descriptor is a vector in one of the following formats: * `[GLYPH-LIST FUNCTION ENABLED-P HELP]' * `[:style 2D-OR-3D]' * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]' * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]' Optionally, one of the toolbar button descriptors may be `nil' instead of a vector; this signifies the division between the toolbar buttons that are to be displayed flush-left, and the buttons to be displayed flush-right. The first vector format above specifies a normal toolbar button; the others specify blank areas in the toolbar. For the first vector format: * GLYPH-LIST should be a list of one to six glyphs (as created by `make-glyph') or a symbol whose value is such a list. The first glyph, which must be provided, is the glyph used to display the toolbar button when it is in the "up" (not pressed) state. The optional second glyph is for displaying the button when it is in the "down" (pressed) state. The optional third glyph is for when the button is disabled. The last three glyphs are for displaying the button in the "up", "down", and "disabled" states, respectively, but are used when the user has called for captioned toolbar buttons (using `toolbar-buttons-captioned-p'). The function `toolbar-make-button-list' is useful in creating these glyph lists. * Even if you do not provide separate down-state and disabled-state glyphs, the user will still get visual feedback to indicate which state the button is in. Buttons in the up-state are displayed with a shadowed border that gives a raised appearance to the button. Buttons in the down-state are displayed with shadows that give a recessed appearance. Buttons in the disabled state are displayed with no shadows, giving a 2-d effect. * If some of the toolbar glyphs are not provided, they inherit as follows: UP: up DOWN: down -> up DISABLED: disabled -> up CAP-UP: cap-up -> up CAP-DOWN: cap-down -> cap-up -> down -> up CAP-DISABLED: cap-disabled -> cap-up -> disabled -> up * The second element FUNCTION is a function to be called when the toolbar button is activated (i.e. when the mouse is released over the toolbar button, if the press occurred in the toolbar). It can be any form accepted by `call-interactively', since this is how it is invoked. * The third element ENABLED-P specifies whether the toolbar button is enabled (disabled buttons do nothing when they are activated, and are displayed differently; see above). It should be either a boolean or a form that evaluates to a boolean. * The fourth element HELP, if non-`nil', should be a string. This string is displayed in the echo area when the mouse passes over the toolbar button. For the other vector formats (specifying blank areas of the toolbar): * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating whether the area is displayed with shadows (giving it a raised, 3-d appearance) or without shadows (giving it a flat appearance). * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank area. If omitted, it defaults to a device-specific value (8 pixels for X devices). - Function: toolbar-make-button-list up &optional down disabled cap-up cap-down cap-disabled This function calls `make-glyph' on each arg and returns a list of the results. This is useful for setting the first argument of a toolbar button descriptor (typically, the result of this function is assigned to a symbol, which is specified as the first argument of the toolbar button descriptor). - Function: check-toolbar-button-syntax button &optional noerror Verify the syntax of entry BUTTON in a toolbar description list. If you want to verify the syntax of a toolbar description list as a whole, use `check-valid-instantiator' with a specifier type of `toolbar'.  File: lispref.info, Node: Specifying the Toolbar, Next: Other Toolbar Variables, Prev: Toolbar Descriptor Format, Up: Toolbar Specifying the Toolbar ====================== In order to specify the contents of a toolbar, set one of the specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar', `left-toolbar', or `right-toolbar'. These are specifiers, which means you set them with `set-specifier' and query them with `specifier-specs' or `specifier-instance'. You will get an error if you try to set them using `setq'. The valid instantiators for these specifiers are toolbar descriptors, as described above. *Note Specifiers::, for more information. Most of the time, you will set `default-toolbar', which allows the user to choose where the toolbar should go. - Specifier: default-toolbar The position of this toolbar is specified in the function `default-toolbar-position'. If the corresponding position-specific toolbar (e.g. `top-toolbar' if `default-toolbar-position' is `top') does not specify a toolbar in a particular domain, then the value of `default-toolbar' in that domain, of any, will be used instead. Note that the toolbar at any particular position will not be displayed unless its thickness (width or height, depending on orientation) is non-zero and its visibility status is true. The thickness is controlled by the specifiers `top-toolbar-height', `bottom-toolbar-height', `left-toolbar-width', and `right-toolbar-width', and the visibility status is controlled by the specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p', `left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other Toolbar Variables::). - Function: set-default-toolbar-position position This function sets the position that the `default-toolbar' will be displayed at. Valid positions are the symbols `top', `bottom', `left' and `right'. What this actually does is set the fallback specifier for the position-specific specifier corresponding to the given position to `default-toolbar', and set the fallbacks for the other position-specific specifiers to `nil'. It also does the same thing for the position-specific thickness and visibility specifiers, which inherit from one of `default-toolbar-height' or `default-toolbar-width', and from `default-toolbar-visible-p', respectively (*note Other Toolbar Variables::). - Function: default-toolbar-position This function returns the position that the `default-toolbar' will be displayed at. You can also explicitly set a toolbar at a particular position. When redisplay determines what to display at a particular position in a particular domain (i.e. window), it first consults the position-specific toolbar. If that does not yield a toolbar descriptor, the `default-toolbar' is consulted if `default-toolbar-position' indicates this position. - Specifier: top-toolbar Specifier for the toolbar at the top of the frame. - Specifier: bottom-toolbar Specifier for the toolbar at the bottom of the frame. - Specifier: left-toolbar Specifier for the toolbar at the left edge of the frame. - Specifier: right-toolbar Specifier for the toolbar at the right edge of the frame. - Function: toolbar-specifier-p object This function returns non-`nil' if OBJECT is a toolbar specifier. Toolbar specifiers are the actual objects contained in the toolbar variables described above, and their valid instantiators are toolbar descriptors (*note Toolbar Descriptor Format::).  File: lispref.info, Node: Other Toolbar Variables, Prev: Specifying the Toolbar, Up: Toolbar Other Toolbar Variables ======================= The variables to control the toolbar thickness, visibility status, and captioned status are all specifiers. *Note Specifiers::. - Specifier: default-toolbar-height This specifies the height of the default toolbar, if it's oriented horizontally. The position of the default toolbar is specified by the function `set-default-toolbar-position'. If the corresponding position-specific toolbar thickness specifier (e.g. `top-toolbar-height' if `default-toolbar-position' is `top') does not specify a thickness in a particular domain (a window or a frame), then the value of `default-toolbar-height' or `default-toolbar-width' (depending on the toolbar orientation) in that domain, if any, will be used instead. - Specifier: default-toolbar-width This specifies the width of the default toolbar, if it's oriented vertically. This behaves like `default-toolbar-height'. Note that `default-toolbar-height' is only used when `default-toolbar-position' is `top' or `bottom', and `default-toolbar-width' is only used when `default-toolbar-position' is `left' or `right'. - Specifier: top-toolbar-height This specifies the height of the top toolbar. - Specifier: bottom-toolbar-height This specifies the height of the bottom toolbar. - Specifier: left-toolbar-width This specifies the width of the left toolbar. - Specifier: right-toolbar-width This specifies the width of the right toolbar. Note that all of the position-specific toolbar thickness specifiers have a fallback value of zero when they do not correspond to the default toolbar. Therefore, you will have to set a non-zero thickness value if you want a position-specific toolbar to be displayed. - Specifier: default-toolbar-visible-p This specifies whether the default toolbar is visible. The position of the default toolbar is specified by the function `set-default-toolbar-position'. If the corresponding position-specific toolbar visibility specifier (e.g. `top-toolbar-visible-p' if `default-toolbar-position' is `top') does not specify a visible-p value in a particular domain (a window or a frame), then the value of `default-toolbar-visible-p' in that domain, if any, will be used instead. - Specifier: top-toolbar-visible-p This specifies whether the top toolbar is visible. - Specifier: bottom-toolbar-visible-p This specifies whether the bottom toolbar is visible. - Specifier: left-toolbar-visible-p This specifies whether the left toolbar is visible. - Specifier: right-toolbar-visible-p This specifies whether the right toolbar is visible. `default-toolbar-visible-p' and all of the position-specific toolbar visibility specifiers have a fallback value of true. Internally, toolbar thickness and visibility specifiers are instantiated in both window and frame domains, for different purposes. The value in the domain of a frame's selected window specifies the actual toolbar thickness or visibility that you will see in that frame. The value in the domain of a frame itself specifies the toolbar thickness or visibility that is used in frame geometry calculations. Thus, for example, if you set the frame width to 80 characters and the left toolbar width for that frame to 68 pixels, then the frame will be sized to fit 80 characters plus a 68-pixel left toolbar. If you then set the left toolbar width to 0 for a particular buffer (or if that buffer does not specify a left toolbar or has a `nil' value specified for `left-toolbar-visible-p'), you will find that, when that buffer is displayed in the selected window, the window will have a width of 86 or 87 characters--the frame is sized for a 68-pixel left toolbar but the selected window specifies that the left toolbar is not visible, so it is expanded to take up the slack. - Specifier: toolbar-buttons-captioned-p Whether toolbar buttons are captioned. This affects which glyphs from a toolbar button descriptor are chosen. *Note Toolbar Descriptor Format::. You can also reset the toolbar to what it was when XEmacs started up. - Constant: initial-toolbar-spec The toolbar descriptor used to initialize `default-toolbar' at startup.  File: lispref.info, Node: Gutter, Next: Scrollbars, Prev: Toolbar, Up: Top Gutter ****** A gutter is a rectangle displayed along one edge of a frame. It can contain arbitrary text or graphics. * Menu: * Gutter Intro:: An introduction. * Creating Gutter:: How to create a gutter. * Gutter Descriptor Format:: Accessing and modifying a gutter's properties. * Specifying a Gutter:: Setting a gutter's contents. * Other Gutter Variables:: Controlling the size of gutters. * Common Gutter Widgets:: Things to put in gutters.