info/lispref.info-20

   1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  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
  20
  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.
  24
  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.
  28
  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.
  33
  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.
  38
  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.
  45
  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.
  51
  52 \1f
  53 File: lispref.info,  Node: Menu Format,  Next: Menubar Format,  Up: Menus
  54
  55 Format of Menus
  56 ===============
  57
  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).
  64
  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'.
  71
  72    Immediately following the first element there may optionally be up
  73 to four keyword-value pairs, as follows:
  74
  75 `:included FORM'
  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'.
  78
  79 `:config SYMBOL'
  80      This is an efficient shorthand for `:included (memq SYMBOL
  81      menubar-configuration)'.  See the variable `menubar-configuration'.
  82
  83 `:filter FUNCTION'
  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.
  94
  95 `:accelerator KEY'
  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
  99      Accelerators::.
 100
 101    The rest of the menu consists of elements as follows:
 102
 103    * A "menu item", which is a vector in the following form:
 104
 105           `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]'
 106
 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.
 111
 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
 116      `eval'.
 117
 118      The valid keywords and their meanings are described below.
 119
 120      Note that for compatibility purposes, the form
 121
 122           `[ NAME CALLBACK ACTIVE-P ]'
 123
 124      is also accepted and is equivalent to
 125
 126           `[ NAME CALLBACK :active ACTIVE-P ]'
 127
 128      and the form
 129
 130           `[ NAME CALLBACK ACTIVE-P SUFFIX]'
 131
 132      is accepted and is equivalent to
 133
 134           `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]'
 135
 136      However, these older forms are deprecated and should generally not
 137      be used.
 138
 139    * If an element of a menu is a string, then that string will be
 140      presented in the menu as unselectable text.
 141
 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.
 144
 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:
 147
 148     `"--:singleLine"'
 149           A solid horizontal line.  This is equivalent to a string
 150           consisting solely of hyphens.
 151
 152     `"--:doubleLine"'
 153           A solid double horizontal line.
 154
 155     `"--:singleDashedLine"'
 156           A dashed horizontal line.
 157
 158     `"--:doubleDashedLine"'
 159           A dashed double horizontal line.
 160
 161     `"--:noLine"'
 162           No line (but a small space is left).
 163
 164     `"--:shadowEtchedIn"'
 165           A solid horizontal line with a 3-d recessed appearance.
 166
 167     `"--:shadowEtchedOut"'
 168           A solid horizontal line with a 3-d pushed-out appearance.
 169
 170     `"--:shadowDoubleEtchedIn"'
 171           A solid double horizontal line with a 3-d recessed appearance.
 172
 173     `"--:shadowDoubleEtchedOut"'
 174           A solid double horizontal line with a 3-d pushed-out
 175           appearance.
 176
 177     `"--:shadowEtchedInDash"'
 178           A dashed horizontal line with a 3-d recessed appearance.
 179
 180     `"--:shadowEtchedOutDash"'
 181           A dashed horizontal line with a 3-d pushed-out appearance.
 182
 183     `"--:shadowDoubleEtchedInDash"'
 184           A dashed double horizontal line with a 3-d recessed
 185           appearance.
 186
 187     `"--:shadowDoubleEtchedOutDash"'
 188           A dashed double horizontal line with a 3-d pushed-out
 189           appearance.
 190
 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.
 194
 195    The possible keywords are as follows:
 196
 197 :active FORM
 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.
 202
 203 :suffix FORM
 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
 208      NAME'.
 209
 210 :keys STRING
 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.
 215
 216 :style STYLE
 217      Specifies what kind of object this menu item is.  STYLE be one of
 218      the symbols
 219
 220     `nil'
 221           A normal menu item.
 222
 223     `toggle'
 224           A toggle button.
 225
 226     `radio'
 227           A radio button.
 228
 229     `button'
 230           A menubar button.
 231
 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
 238      time.
 239
 240 :selected FORM
 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'.
 244
 245 :included FORM
 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
 251      omitted entirely.
 252
 253 :config SYMBOL
 254      This is an efficient shorthand for `:included (memq SYMBOL
 255      menubar-configuration)'.  See the variable `menubar-configuration'.
 256
 257 :accelerator KEY
 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
 261      Accelerators::.
 262
 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'
 268      list.
 269
 270    For example:
 271
 272       ("File"
 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 ]
 279        )
 280
 281 \1f
 282 File: lispref.info,  Node: Menubar Format,  Next: Menubar,  Prev: Menu Format,  Up: Menus
 283
 284 Format of the Menubar
 285 =====================
 286
 287    A menubar is a list of menus, menu items, and strings.  The format is
 288 similar to that of a menu, except:
 289
 290    * The first item need not be a string, and is not treated specially.
 291
 292    * A string consisting solely of hyphens is not treated specially.
 293
 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
 297      implemented yet.)
 298
 299 \1f
 300 File: lispref.info,  Node: Menubar,  Next: Modifying Menus,  Prev: Menubar Format,  Up: Menus
 301
 302 Menubar
 303 =======
 304
 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.
 310
 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
 314      at startup.
 315
 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.
 320
 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'.
 325
 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.
 330
 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
 334      one.
 335
 336    Miscellaneous:
 337
 338  - Variable: menubar-show-keybindings
 339      If true, the menubar will display keyboard equivalents.  If false,
 340      only the command names will be displayed.
 341
 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.
 346
 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.
 356
 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.
 364
 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.
 368
 369 \1f
 370 File: lispref.info,  Node: Modifying Menus,  Next: Pop-Up Menus,  Prev: Menubar,  Up: Menus
 371
 372 Modifying Menus
 373 ===============
 374
 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.
 378
 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
 382 submenu of "File".
 383
 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".
 389
 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.
 393
 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
 396      the menubar itself.
 397
 398      SUBMENU is the new menu to add (*note Menu Format::).
 399
 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.
 403
 404      If IN-MENU is present use that instead of `current-menubar' as the
 405      menu to change.
 406
 407  - Function: add-menu-button menu-path menu-leaf &optional before
 408           in-menu
 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
 411      changed.
 412
 413      MENU-PATH identifies the menu under which the new menu item should
 414      be inserted.
 415
 416      MENU-LEAF is a menubar leaf node (*note Menu Format::).
 417
 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.
 421
 422      If IN-MENU is present use that instead of `current-menubar' as the
 423      menu to change.
 424
 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.
 428
 429      If FROM-MENU is present use that instead of `current-menubar' as
 430      the menu to change.
 431
 432  - Function: enable-menu-item menu-item-path
 433      This function makes the menu item specified by MENU-ITEM-PATH be
 434      selectable.
 435
 436  - Function: disable-menu-item menu-item-path
 437      This function makes the menu item specified by MENU-ITEM-PATH be
 438      unselectable.
 439
 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.
 444
 445    The following function can be used to search for a particular item in
 446 a menubar specification, given a path to the item.
 447
 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.
 455
 456      This function signals an error if the item is not found.
 457
 458    The following deprecated functions are also documented, so that
 459 existing code can be understood.  You should not use these functions in
 460 new code.
 461
 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.
 466
 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
 469      the menubar itself.
 470
 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::).
 475
 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.
 479
 480  - Function: add-menu-item menu-path item-name function enabled-p
 481           &optional before
 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.
 485
 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
 489      Format::).
 490
 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.
 494
 495 \1f
 496 File: lispref.info,  Node: Menu Filters,  Next: Menu Accelerators,  Prev: Pop-Up Menus,  Up: Menus
 497
 498 Menu Filters
 499 ============
 500
 501    The following filter functions are provided for use in
 502 `default-menubar'.  You may want to use them in your own menubar
 503 description.
 504
 505  - Function: file-menu-filter menu-items
 506      This function changes the arguments and sensitivity of these File
 507      menu items:
 508
 509     `Delete Buffer'
 510           Has the name of the current buffer appended to it.
 511
 512     `Print Buffer'
 513           Has the name of the current buffer appended to it.
 514
 515     `Pretty-Print Buffer'
 516           Has the name of the current buffer appended to it.
 517
 518     `Save Buffer'
 519           Has the name of the current buffer appended to it, and is
 520           sensitive only when the current buffer is modified.
 521
 522     `Revert Buffer'
 523           Has the name of the current buffer appended to it, and is
 524           sensitive only when the current buffer has a file.
 525
 526     `Delete Frame'
 527           Sensitive only when there is more than one visible frame.
 528
 529  - Function: edit-menu-filter menu-items
 530      This function changes the arguments and sensitivity of these Edit
 531      menu items:
 532
 533     `Cut'
 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).
 537
 538     `Copy'
 539           Sensitive only when XEmacs owns the primary X Selection.
 540
 541     `Clear'
 542           Sensitive only when XEmacs owns the primary X Selection.
 543
 544     `Paste'
 545           Sensitive only when there is an owner for the X Clipboard
 546           Selection.
 547
 548     `Undo'
 549           Sensitive only when there is undo information.  While in the
 550           midst of an undo, this is changed to `Undo More'.
 551
 552  - Function: buffers-menu-filter menu-items
 553      This function sets up the Buffers menu.  *Note Buffers Menu::, for
 554      more information.
 555
 556 \1f
 557 File: lispref.info,  Node: Pop-Up Menus,  Next: Menu Filters,  Prev: Modifying Menus,  Up: Menus
 558
 559 Pop-Up Menus
 560 ============
 561
 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.
 566
 567  - Function: popup-menu-up-p
 568      This function returns `t' if a pop-up menu is up, `nil' otherwise.
 569
 570  - Variable: popup-menu-titles
 571      If true (the default), pop-up menus will have title bars at the
 572      top.
 573
 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.
 577
 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.
 583
 584  - Variable: global-popup-menu
 585      This holds the global popup menu.  This is present in all modes.
 586      (This is `nil' by default.)
 587
 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'.
 591
 592  - Constant: default-popup-menu
 593      This holds the default value of `mode-popup-menu'.
 594
 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
 602      won't be run.
 603
 604    The following convenience functions are provided for displaying
 605 pop-up menus.
 606
 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
 610      mouse button event.
 611
 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.
 615
 616 \1f
 617 File: lispref.info,  Node: Menu Accelerators,  Next: Buffers Menu,  Prev: Menu Filters,  Up: Menus
 618
 619 Menu Accelerators
 620 =================
 621
 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.
 627
 628 * Menu:
 629
 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.
 634
 635 \1f
 636 File: lispref.info,  Node: Creating Menu Accelerators,  Next: Keyboard Menu Traversal,  Up: Menu Accelerators
 637
 638 Creating Menu Accelerators
 639 --------------------------
 640
 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.
 647
 648    For example, the command
 649
 650      (add-submenu nil '("%_Test"
 651                         ["One" (insert "1") :accelerator ?1 :active t]
 652                         ["%_Two" (insert "2")]
 653                         ["%_3" (insert "3")]))
 654
 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
 661 buffer.
 662
 663    It is possible to activate the top level menubar itself using
 664 accelerator keys.  *Note Menu Accelerator Functions::.
 665
 666 \1f
 667 File: lispref.info,  Node: Keyboard Menu Traversal,  Next: Menu Accelerator Functions,  Prev: Creating Menu Accelerators,  Up: Menu Accelerators
 668
 669 Keyboard Menu Traversal
 670 -----------------------
 671
 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.
 677
 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.
 681
 682 \1f
 683 File: lispref.info,  Node: Menu Accelerator Functions,  Prev: Keyboard Menu Traversal,  Up: Menu Accelerators
 684
 685 Menu Accelerator Functions
 686 --------------------------
 687
 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
 691      as usual.
 692
 693  - Variable: menu-accelerator-enabled
 694      Whether menu accelerator keys can cause the menubar to become
 695      active.
 696
 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
 700      of this variable.
 701
 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.
 711
 712      The default value is `nil'.
 713
 714      See also MENU-ACCELERATOR-MODIFIERS and MENU-ACCELERATOR-PREFIX.
 715
 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
 719      Menu Traversal::.
 720
 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.
 727
 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.
 732
 733      See also MENU-ACCELERATOR-ENABLED and MENU-ACCELERATOR-PREFIX.
 734
 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.
 738
 739      The default value is `nil'.
 740
 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")]))
 748
 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.
 753
 754 \1f
 755 File: lispref.info,  Node: Buffers Menu,  Prev: Menu Accelerators,  Up: Menus
 756
 757 Buffers Menu
 758 ============
 759
 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.
 763
 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.
 770
 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
 774      can redefine this.
 775
 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.
 780
 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
 784      is `pop-to-buffer'.
 785
 786 \1f
 787 File: lispref.info,  Node: Dialog Boxes,  Next: Toolbar,  Prev: Menus,  Up: Top
 788
 789 Dialog Boxes
 790 ************
 791
 792 * Menu:
 793
 794 * Dialog Box Format::
 795 * Dialog Box Functions::
 796
 797 \1f
 798 File: lispref.info,  Node: Dialog Box Format,  Next: Dialog Box Functions,  Up: Dialog Boxes
 799
 800 Dialog Box Format
 801 =================
 802
 803    A dialog box description is a list.
 804
 805    * The first element of the list is a string to display in the dialog
 806      box.
 807
 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.
 811
 812         - The second element is the "callback".
 813
 814         - The third element is `t' or `nil', whether this button is
 815           selectable.
 816
 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'.
 820
 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.
 823
 824    The syntax, more precisely:
 825
 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>
 831         name         :=  <string>
 832         partition    :=  'nil'
 833         button       :=  '['  name callback active-p ']'
 834         dialog       :=  '(' name [ button ]+ [ partition [ button ]+ ] ')'
 835
 836 \1f
 837 File: lispref.info,  Node: Dialog Box Functions,  Prev: Dialog Box Format,  Up: Dialog Boxes
 838
 839 Dialog Box Functions
 840 ====================
 841
 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::).
 845
 846    *Note Yes-or-No Queries::, for functions to ask a yes/no question
 847 using a dialog box.
 848
 849 \1f
 850 File: lispref.info,  Node: Toolbar,  Next: Gutter,  Prev: Dialog Boxes,  Up: Top
 851
 852 Toolbar
 853 *******
 854
 855 * Menu:
 856
 857 * Toolbar Intro::               An introduction.
 858 * Creating Toolbar::            How to create a toolbar.
 859 * Toolbar Descriptor Format::   Accessing and modifying a toolbar's
 860                                   properties.
 861 * Specifying the Toolbar::      Setting a toolbar's contents.
 862 * Other Toolbar Variables::     Controlling the size of toolbars.
 863
 864 \1f
 865 File: lispref.info,  Node: Toolbar Intro,  Next: Creating Toolbar,  Up: Toolbar
 866
 867 Toolbar Intro
 868 =============
 869
 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.
 877
 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::).
 883
 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'.
 891
 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.
 907
 908 \1f
 909 File: lispref.info,  Node: Creating Toolbar,  Next: Toolbar Descriptor Format,  Prev: Toolbar Intro,  Up: Toolbar
 910
 911 Creating Toolbar
 912 ================
 913
 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.
 920
 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
 924      toolbar specifiers.
 925
 926      Valid toolbar instantiators are called "toolbar descriptors" and
 927      are lists of vectors.  See `default-toolbar' for a description of
 928      the exact format.
 929
 930 \1f
 931 File: lispref.info,  Node: Toolbar Descriptor Format,  Next: Specifying the Toolbar,  Prev: Creating Toolbar,  Up: Toolbar
 932
 933 Toolbar Descriptor Format
 934 =========================
 935
 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
 939 following formats:
 940
 941    * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
 942
 943    * `[:style 2D-OR-3D]'
 944
 945    * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
 946
 947    * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
 948
 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.
 953
 954    The first vector format above specifies a normal toolbar button; the
 955 others specify blank areas in the toolbar.
 956
 957    For the first vector format:
 958
 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
 970      glyph lists.
 971
 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.
 979
 980    * If some of the toolbar glyphs are not provided, they inherit as
 981      follows:
 982
 983                UP:                up
 984                DOWN:              down -> up
 985                DISABLED:          disabled -> up
 986                CAP-UP:            cap-up -> up
 987                CAP-DOWN:          cap-down -> cap-up -> down -> up
 988                CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up
 989
 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
 994      is invoked.
 995
 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.
1000
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
1003      toolbar button.
1004
1005    For the other vector formats (specifying blank areas of the toolbar):
1006
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).
1010
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).
1014
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).
1022
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
1027      `toolbar'.
1028
1029 \1f
1030 File: lispref.info,  Node: Specifying the Toolbar,  Next: Other Toolbar Variables,  Prev: Toolbar Descriptor Format,  Up: Toolbar
1031
1032 Specifying the Toolbar
1033 ======================
1034
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
1042 information.
1043
1044    Most of the time, you will set `default-toolbar', which allows the
1045 user to choose where the toolbar should go.
1046
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.
1054
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::).
1064
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::).
1076
1077  - Function: default-toolbar-position
1078      This function returns the position that the `default-toolbar' will
1079      be displayed at.
1080
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
1086 this position.
1087
1088  - Specifier: top-toolbar
1089      Specifier for the toolbar at the top of the frame.
1090
1091  - Specifier: bottom-toolbar
1092      Specifier for the toolbar at the bottom of the frame.
1093
1094  - Specifier: left-toolbar
1095      Specifier for the toolbar at the left edge of the frame.
1096
1097  - Specifier: right-toolbar
1098      Specifier for the toolbar at the right edge of the frame.
1099
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::).
1105
1106 \1f
1107 File: lispref.info,  Node: Other Toolbar Variables,  Prev: Specifying the Toolbar,  Up: Toolbar
1108
1109 Other Toolbar Variables
1110 =======================
1111
1112    The variables to control the toolbar thickness, visibility status,
1113 and captioned status are all specifiers.  *Note Specifiers::.
1114
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.
1125
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'.
1129
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
1133 `left' or `right'.
1134
1135  - Specifier: top-toolbar-height
1136      This specifies the height of the top toolbar.
1137
1138  - Specifier: bottom-toolbar-height
1139      This specifies the height of the bottom toolbar.
1140
1141  - Specifier: left-toolbar-width
1142      This specifies the width of the left toolbar.
1143
1144  - Specifier: right-toolbar-width
1145      This specifies the width of the right toolbar.
1146
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.
1151
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.
1161
1162  - Specifier: top-toolbar-visible-p
1163      This specifies whether the top toolbar is visible.
1164
1165  - Specifier: bottom-toolbar-visible-p
1166      This specifies whether the bottom toolbar is visible.
1167
1168  - Specifier: left-toolbar-visible-p
1169      This specifies whether the left toolbar is visible.
1170
1171  - Specifier: right-toolbar-visible-p
1172      This specifies whether the right toolbar is visible.
1173
1174    `default-toolbar-visible-p' and all of the position-specific toolbar
1175 visibility specifiers have a fallback value of true.
1176
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.
1183
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.
1194
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::.
1199
1200    You can also reset the toolbar to what it was when XEmacs started up.
1201
1202  - Constant: initial-toolbar-spec
1203      The toolbar descriptor used to initialize `default-toolbar' at
1204      startup.
1205
1206 \1f
1207 File: lispref.info,  Node: Gutter,  Next: Scrollbars,  Prev: Toolbar,  Up: Top
1208
1209 Gutter
1210 ******
1211
1212    A gutter is a rectangle displayed along one edge of a frame.  It can
1213 contain arbitrary text or graphics.
1214
1215 * Menu:
1216
1217 * Gutter Intro::                An introduction.
1218 * Creating Gutter::             How to create a gutter.
1219 * Gutter Descriptor Format::    Accessing and modifying a gutter's
1220                                   properties.
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.
1224