Mercurial > hg > xemacs-beta
annotate man/lispref/menus.texi @ 5706:44b0b4ea5cae
Implement and document :active keyword for submenu specs.
| author | Stephen J. Turnbull <stephen@xemacs.org> |
|---|---|
| date | Fri, 28 Dec 2012 17:23:25 +0900 |
| parents | 6b027725e340 |
| children | 8ca881999349 |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1997 Free Software Foundation, Inc. |
| 428 | 4 @c Copyright (C) 1995 Sun Microsystems. |
| 5 @c See the file lispref.texi for copying conditions. | |
| 6 @setfilename ../../info/menu.info | |
| 7 @node Menus, Dialog Boxes, Keymaps, Top | |
| 8 @chapter Menus | |
| 9 @cindex menu | |
| 10 | |
| 11 @menu | |
| 440 | 12 * Menu Format:: Format of a menu description. |
| 13 * Menubar Format:: How to specify a menubar. | |
| 14 * Menubar:: Functions for controlling the menubar. | |
| 15 * Modifying Menus:: Modifying a menu description. | |
| 16 * Pop-Up Menus:: Functions for specifying pop-up menus. | |
| 17 * Menu Filters:: Filter functions for the default menubar. | |
| 18 * Menu Accelerators:: Using and controlling menu accelerator keys | |
| 19 * Buffers Menu:: The menu that displays the list of buffers. | |
| 428 | 20 @end menu |
| 21 | |
| 22 @node Menu Format | |
| 23 @section Format of Menus | |
| 24 @cindex menu format | |
| 25 @cindex format of menus | |
| 26 | |
| 27 A menu is described using a @dfn{menu description}, which is a list of | |
| 28 menu items, keyword-value pairs, strings, and submenus. The menu | |
| 29 description specifies which items are present in the menu, what function | |
| 30 each item invokes, and whether the item is selectable or not. Pop-up | |
| 31 menus are directly described with a menu description, while menubars are | |
| 32 described slightly differently (see below). | |
| 33 | |
| 34 The first element of a menu must be a string, which is the name of the | |
| 35 menu. This is the string that will be displayed in the parent menu or | |
| 36 menubar, if any. This string is not displayed in the menu itself, | |
| 37 except in the case of the top level pop-up menu, where there is no | |
| 38 parent. In this case, the string will be displayed at the top of the | |
| 39 menu if @code{popup-menu-titles} is non-@code{nil}. | |
| 40 | |
| 41 Immediately following the first element there may optionally be up | |
|
5706
44b0b4ea5cae
Implement and document :active keyword for submenu specs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
5703
diff
changeset
|
42 to five keyword-value pairs, as follows: |
| 428 | 43 |
| 44 @table @code | |
| 45 @item :included @var{form} | |
| 46 This can be used to control the visibility of a menu. The form is | |
| 47 evaluated and the menu will be omitted if the result is @code{nil}. | |
| 48 | |
| 49 @item :config @var{symbol} | |
| 50 This is an efficient shorthand for @code{:included (memq @var{symbol} | |
| 51 menubar-configuration)}. See the variable @code{menubar-configuration}. | |
| 52 | |
| 53 @item :filter @var{function} | |
| 54 A menu filter is used to sensitize or incrementally create a submenu | |
| 55 only when it is selected by the user and not every time the menubar is | |
| 56 activated. The filter function is passed the list of menu items in the | |
| 57 submenu and must return a list of menu items to be used for the menu. | |
| 58 It is called only when the menu is about to be displayed, so other menus | |
| 59 may already be displayed. Vile and terrible things will happen if a | |
| 60 menu filter function changes the current buffer, window, or frame. It | |
| 61 also should not raise, lower, or iconify any frames. Basically, the | |
| 62 filter function should have no side-effects. | |
| 63 | |
| 64 @item :accelerator @var{key} | |
| 65 A menu accelerator is a keystroke which can be pressed while the menu is | |
| 66 visible which will immediately activate the item. @var{key} must be a char | |
|
5706
44b0b4ea5cae
Implement and document :active keyword for submenu specs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
5703
diff
changeset
|
67 or the symbol name of a key. |
|
44b0b4ea5cae
Implement and document :active keyword for submenu specs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
5703
diff
changeset
|
68 |
|
44b0b4ea5cae
Implement and document :active keyword for submenu specs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
5703
diff
changeset
|
69 @item :active @var{form} |
|
44b0b4ea5cae
Implement and document :active keyword for submenu specs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
5703
diff
changeset
|
70 @var{form} will be evaluated when the submenu is about to be displayed, |
|
44b0b4ea5cae
Implement and document :active keyword for submenu specs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
5703
diff
changeset
|
71 and the menu contents will be displayed only if the result is non-@code{nil}. |
|
44b0b4ea5cae
Implement and document :active keyword for submenu specs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
5703
diff
changeset
|
72 If the submenu is inactive, it will display the word "Invalid", grayed-out. |
|
44b0b4ea5cae
Implement and document :active keyword for submenu specs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
5703
diff
changeset
|
73 @xref{Menu Accelerators}. |
| 428 | 74 @end table |
| 75 | |
| 76 The rest of the menu consists of elements as follows: | |
| 77 | |
| 78 @itemize @bullet | |
| 79 @item | |
| 80 A @dfn{menu item}, which is a vector in the following form: | |
| 81 | |
| 82 @example | |
| 83 @code{[ @var{name} @var{callback} @var{:keyword} @var{value} @var{:keyword} @var{value} ... ]} | |
| 84 @end example | |
| 85 | |
| 86 @var{name} is a string, the name of the menu item; it is the string to | |
| 87 display on the menu. It is filtered through the resource database, so | |
| 88 it is possible for resources to override what string is actually | |
| 89 displayed. | |
| 90 | |
| 91 @var{callback} is a form that will be invoked when the menu item is | |
| 92 selected. If the callback of a menu item is a symbol, then it must name | |
| 93 a command. It will be invoked with @code{call-interactively}. If it is | |
| 94 a list, then it is evaluated with @code{eval}. | |
| 95 | |
| 96 The valid keywords and their meanings are described below. | |
| 97 | |
| 98 Note that for compatibility purposes, the form | |
| 99 | |
| 100 @example | |
| 101 @code{[ @var{name} @var{callback} @var{active-p} ]} | |
| 102 @end example | |
| 103 | |
| 104 is also accepted and is equivalent to | |
| 105 | |
| 106 @example | |
| 107 @code{[ @var{name} @var{callback} :active @var{active-p} ]} | |
| 108 @end example | |
| 109 | |
| 110 and the form | |
| 111 | |
| 112 @example | |
| 113 @code{[ @var{name} @var{callback} @var{active-p} @var{suffix}]} | |
| 114 @end example | |
| 115 | |
| 116 is accepted and is equivalent to | |
| 117 | |
| 118 @example | |
| 119 @code{[ @var{name} @var{callback} :active @var{active-p} :suffix @var{suffix}]} | |
| 120 @end example | |
| 121 | |
| 122 However, these older forms are deprecated and should generally not be used. | |
| 123 | |
| 124 @item | |
| 125 If an element of a menu is a string, then that string will be presented | |
| 126 in the menu as unselectable text. | |
| 127 | |
| 128 @item | |
| 129 If an element of a menu is a string consisting solely of hyphens, then | |
| 130 that item will be presented as a solid horizontal line. | |
| 131 | |
| 132 @item | |
| 133 If an element of a menu is a string beginning with @samp{--:}, then | |
| 134 a particular sort of horizontal line will be displayed, as follows: | |
| 135 | |
| 136 @table @samp | |
| 137 @item "--:singleLine" | |
| 138 A solid horizontal line. This is equivalent to a string consisting | |
| 139 solely of hyphens. | |
| 140 @item "--:doubleLine" | |
| 141 A solid double horizontal line. | |
| 142 @item "--:singleDashedLine" | |
| 143 A dashed horizontal line. | |
| 144 @item "--:doubleDashedLine" | |
| 145 A dashed double horizontal line. | |
| 146 @item "--:noLine" | |
| 147 No line (but a small space is left). | |
| 148 @item "--:shadowEtchedIn" | |
| 149 A solid horizontal line with a 3-d recessed appearance. | |
| 150 @item "--:shadowEtchedOut" | |
| 151 A solid horizontal line with a 3-d pushed-out appearance. | |
| 152 @item "--:shadowDoubleEtchedIn" | |
| 153 A solid double horizontal line with a 3-d recessed appearance. | |
| 154 @item "--:shadowDoubleEtchedOut" | |
| 155 A solid double horizontal line with a 3-d pushed-out appearance. | |
| 156 @item "--:shadowEtchedInDash" | |
| 157 A dashed horizontal line with a 3-d recessed appearance. | |
| 158 @item "--:shadowEtchedOutDash" | |
| 159 A dashed horizontal line with a 3-d pushed-out appearance. | |
| 160 @item "--:shadowDoubleEtchedInDash" | |
| 161 A dashed double horizontal line with a 3-d recessed appearance. | |
| 162 @item "--:shadowDoubleEtchedOutDash" | |
| 163 A dashed double horizontal line with a 3-d pushed-out appearance. | |
| 164 @end table | |
| 165 | |
| 166 @item | |
| 167 If an element of a menu is a list, it is treated as a submenu. The name | |
| 168 of that submenu (the first element in the list) will be used as the name | |
| 169 of the item representing this menu on the parent. | |
| 170 @end itemize | |
| 171 | |
| 172 The possible keywords are as follows: | |
| 173 | |
| 174 @table @asis | |
| 175 @item :active @var{form} | |
| 176 @var{form} will be evaluated when the menu that this item is a part of | |
| 177 is about to be displayed, and the item will be selectable only if the | |
| 178 result is non-@code{nil}. If the item is unselectable, it will | |
| 179 usually be displayed grayed-out to indicate this. | |
| 180 | |
| 181 @item :suffix @var{form} | |
| 182 @var{form} will be evaluated when the menu that this item is a part of | |
| 183 is about to be displayed, and the resulting string is appended to the | |
| 184 displayed name. This provides a convenient way of adding the name of a | |
| 185 command's ``argument'' to the menu, like @samp{Kill Buffer NAME}. | |
| 186 | |
| 187 @item :keys @var{string} | |
| 188 Normally, the keyboard equivalents of commands in menus are displayed | |
| 189 when the ``callback'' is a symbol. This can be used to specify keys for | |
| 190 more complex menu items. It is passed through | |
| 191 @code{substitute-command-keys} first. | |
| 192 | |
| 193 @item :style @var{style} | |
| 194 Specifies what kind of object this menu item is. @var{style} be one | |
| 195 of the symbols | |
| 196 | |
| 197 @table @code | |
| 198 @item nil | |
| 199 A normal menu item. | |
| 200 @item toggle | |
| 201 A toggle button. | |
| 202 @item radio | |
| 203 A radio button. | |
| 204 @item button | |
| 205 A menubar button. | |
| 206 @end table | |
| 207 | |
| 208 The only difference between toggle and radio buttons is how they are | |
| 209 displayed. But for consistency, a toggle button should be used when | |
| 210 there is one option whose value can be turned on or off, and radio | |
| 211 buttons should be used when there is a set of mutually exclusive options. | |
| 212 When using a group of radio buttons, you should arrange for no more than | |
| 213 one to be marked as selected at a time. | |
| 214 | |
| 215 @item :selected @var{form} | |
| 216 Meaningful only when @var{style} is @code{toggle}, @code{radio} or | |
| 217 @code{button}. This specifies whether the button will be in the | |
| 218 selected or unselected state. @var{form} is evaluated, as for | |
| 219 @code{:active}. | |
| 220 | |
| 221 @item :included @var{form} | |
| 222 This can be used to control the visibility of a menu item. The form is | |
| 223 evaluated and the menu item is only displayed if the result is | |
| 224 non-@code{nil}. Note that this is different from @code{:active}: If | |
| 225 @code{:active} evaluates to @code{nil}, the item will be displayed | |
| 226 grayed out, while if @code{:included} evaluates to @code{nil}, the item | |
| 227 will be omitted entirely. | |
| 228 | |
| 229 @item :config @var{symbol} | |
| 230 This is an efficient shorthand for @code{:included (memq @var{symbol} | |
| 231 menubar-configuration)}. See the variable @code{menubar-configuration}. | |
| 232 | |
| 233 @item :accelerator @var{key} | |
| 234 A menu accelerator is a keystroke which can be pressed while the menu is | |
| 235 visible which will immediately activate the item. @var{key} must be a char | |
| 236 or the symbol name of a key. @xref{Menu Accelerators}. | |
| 237 @end table | |
| 238 | |
| 239 @defvar menubar-configuration | |
| 240 This variable holds a list of symbols, against which the value of the | |
| 241 @code{:config} tag for each menubar item will be compared. If a menubar | |
| 242 item has a @code{:config} tag, then it is omitted from the menubar if | |
| 243 that tag is not a member of the @code{menubar-configuration} list. | |
| 244 @end defvar | |
| 245 | |
| 246 For example: | |
| 247 | |
| 248 @example | |
| 249 ("File" | |
| 440 | 250 :filter file-menu-filter ; file-menu-filter is a function that takes |
| 251 ; one argument (a list of menu items) and | |
| 252 ; returns a list of menu items | |
| 428 | 253 [ "Save As..." write-file] |
| 254 [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ] | |
| 255 [ "Read Only" toggle-read-only :style toggle :selected buffer-read-only ] | |
| 256 ) | |
| 257 @end example | |
| 258 | |
| 259 @node Menubar Format | |
| 260 @section Format of the Menubar | |
| 261 @cindex menubar format | |
| 262 @cindex format of the menubar | |
| 263 | |
| 264 A menubar is a list of menus, menu items, and strings. The format is | |
| 265 similar to that of a menu, except: | |
| 266 | |
| 267 @itemize @bullet | |
| 268 @item | |
| 269 The first item need not be a string, and is not treated specially. | |
| 270 | |
| 271 @item | |
| 272 A string consisting solely of hyphens is not treated specially. | |
| 273 | |
| 274 @item | |
| 275 If an element of a menubar is @code{nil}, then it is used to represent | |
| 276 the division between the set of menubar items which are flush-left and | |
| 277 those which are flush-right. (Note: this isn't completely implemented | |
| 278 yet.) | |
| 279 @end itemize | |
| 280 | |
| 281 @node Menubar | |
| 282 @section Menubar | |
| 283 @cindex menubar | |
| 284 | |
| 285 @defvar current-menubar | |
| 286 This variable holds the description of the current menubar. This may be | |
| 287 buffer-local. When the menubar is changed, the function | |
| 288 @code{set-menubar-dirty-flag} has to be called in order for the menubar | |
| 289 to be updated on the screen. | |
| 290 @end defvar | |
| 291 | |
| 292 @defvr Constant default-menubar | |
| 293 This variable holds the menubar description of the menubar that is | |
| 294 visible at startup. This is the value that @code{current-menubar} | |
| 295 has at startup. | |
| 296 @end defvr | |
| 297 | |
| 298 @defun set-menubar-dirty-flag | |
| 299 This function tells XEmacs that the menubar widget has to be updated. | |
| 300 Changes to the menubar will generally not be visible until this function | |
| 301 is called. | |
| 302 @end defun | |
| 303 | |
| 304 The following convenience functions are provided for setting the | |
| 305 menubar. They are equivalent to doing the appropriate action to change | |
| 306 @code{current-menubar}, and then calling @code{set-menubar-dirty-flag}. | |
| 307 Note that these functions copy their argument using | |
| 308 @code{copy-sequence}. | |
| 309 | |
| 310 @defun set-menubar menubar | |
| 311 This function sets the default menubar to be @var{menubar} (@pxref{Menu | |
| 312 Format}). This is the menubar that will be visible in buffers that | |
| 313 have not defined their own, buffer-local menubar. | |
| 314 @end defun | |
| 315 | |
| 316 @defun set-buffer-menubar menubar | |
| 317 This function sets the buffer-local menubar to be @var{menubar}. This | |
| 318 does not change the menubar in any buffers other than the current one. | |
| 319 @end defun | |
| 320 | |
| 321 Miscellaneous: | |
| 322 | |
| 323 @defvar menubar-show-keybindings | |
| 324 If true, the menubar will display keyboard equivalents. If false, only | |
| 325 the command names will be displayed. | |
| 326 @end defvar | |
| 327 | |
| 328 @defvar activate-menubar-hook | |
| 329 Function or functions called before a menubar menu is pulled down. | |
| 330 These functions are called with no arguments, and should interrogate and | |
| 331 modify the value of @code{current-menubar} as desired. | |
| 332 | |
| 333 The functions on this hook are invoked after the mouse goes down, but | |
| 334 before the menu is mapped, and may be used to activate, deactivate, add, | |
| 335 or delete items from the menus. However, using a filter (with the | |
| 336 @code{:filter} keyword in a menu description) is generally a more | |
| 337 efficient way of accomplishing the same thing, because the filter is | |
| 338 invoked only when the actual menu goes down. With a complex menu, | |
| 339 there can be a quite noticeable and sometimes aggravating delay if | |
| 340 all menu modification is implemented using the @code{activate-menubar-hook}. | |
| 341 See above. | |
| 342 | |
| 343 These functions may return the symbol @code{t} to assert that they have | |
| 344 made no changes to the menubar. If any other value is returned, the | |
| 345 menubar is recomputed. If @code{t} is returned but the menubar has been | |
| 346 changed, then the changes may not show up right away. Returning | |
| 347 @code{nil} when the menubar has not changed is not so bad; more | |
| 348 computation will be done, but redisplay of the menubar will still be | |
| 349 performed optimally. | |
| 350 @end defvar | |
| 351 | |
| 352 @defvar menu-no-selection-hook | |
| 353 Function or functions to call when a menu or dialog box is dismissed | |
| 354 without a selection having been made. | |
| 355 @end defvar | |
| 356 | |
| 357 @node Modifying Menus | |
| 358 @section Modifying Menus | |
| 359 | |
| 360 The following functions are provided to modify the menubar of one of its | |
| 361 submenus. Note that these functions modify the menu in-place, rather | |
| 362 than copying it and making a new menu. | |
| 363 | |
| 364 Some of these functions take a @dfn{menu path}, which is a list of | |
| 365 strings identifying the menu to be modified. For example, | |
| 366 @code{("File")} names the top-level ``File'' menu. @code{("File" | |
| 367 "Foo")} names a hypothetical submenu of ``File''. | |
| 368 | |
| 369 Others take a @dfn{menu item path}, which is similar to a menu path but | |
| 370 also specifies a particular item to be modified. For example, | |
| 371 @code{("File" "Save")} means the menu item called ``Save'' under the | |
| 372 top-level ``File'' menu. @code{("Menu" "Foo" "Item")} means the menu | |
| 373 item called ``Item'' under the ``Foo'' submenu of ``Menu''. | |
| 374 | |
| 444 | 375 @defun add-submenu menu-path submenu &optional before in-menu |
| 428 | 376 This function adds a menu to the menubar or one of its submenus. If the |
| 377 named menu exists already, it is changed. | |
| 378 | |
| 379 @var{menu-path} identifies the menu under which the new menu should be | |
| 380 inserted. If @var{menu-path} is @code{nil}, then the menu will be added | |
| 381 to the menubar itself. | |
| 382 | |
| 383 @var{submenu} is the new menu to add (@pxref{Menu Format}). | |
| 384 | |
| 385 @var{before}, if provided, is the name of a menu before which this menu | |
| 386 should be added, if this menu is not on its parent already. If the menu | |
| 387 is already present, it will not be moved. | |
| 444 | 388 |
| 389 If @var{in-menu} is present use that instead of @code{current-menubar} | |
| 390 as the menu to change. | |
| 428 | 391 @end defun |
| 392 | |
| 444 | 393 @defun add-menu-button menu-path menu-leaf &optional before in-menu |
| 428 | 394 This function adds a menu item to some menu, creating the menu first if |
| 395 necessary. If the named item exists already, it is changed. | |
| 396 | |
| 397 @var{menu-path} identifies the menu under which the new menu item should | |
| 398 be inserted. | |
| 399 | |
| 400 @var{menu-leaf} is a menubar leaf node (@pxref{Menu Format}). | |
| 401 | |
| 402 @var{before}, if provided, is the name of a menu before which this item | |
| 403 should be added, if this item is not on the menu already. If the item | |
| 404 is already present, it will not be moved. | |
| 444 | 405 |
| 406 If @var{in-menu} is present use that instead of @code{current-menubar} | |
| 407 as the menu to change. | |
| 428 | 408 @end defun |
| 409 | |
| 444 | 410 @defun delete-menu-item menu-item-path &optional from-menu |
| 428 | 411 This function removes the menu item specified by @var{menu-item-path} |
| 412 from the menu hierarchy. | |
| 444 | 413 |
| 414 If @var{from-menu} is present use that instead of @code{current-menubar} | |
| 415 as the menu to change. | |
| 428 | 416 @end defun |
| 417 | |
| 418 @defun enable-menu-item menu-item-path | |
| 419 This function makes the menu item specified by @var{menu-item-path} be | |
| 420 selectable. | |
| 421 @end defun | |
| 422 | |
| 423 @defun disable-menu-item menu-item-path | |
| 424 This function makes the menu item specified by @var{menu-item-path} be | |
| 425 unselectable. | |
| 426 @end defun | |
| 427 | |
| 428 @defun relabel-menu-item menu-item-path new-name | |
| 429 This function changes the string of the menu item specified by | |
| 430 @var{menu-item-path}. @var{new-name} is the string that the menu item | |
| 431 will be printed as from now on. | |
| 432 @end defun | |
| 433 | |
| 434 The following function can be used to search for a particular item in | |
| 435 a menubar specification, given a path to the item. | |
| 436 | |
| 437 @defun find-menu-item menubar menu-item-path &optional parent | |
| 438 This function searches @var{menubar} for the item given by | |
| 439 @var{menu-item-path} starting from @var{parent} (@code{nil} means start | |
| 440 at the top of @var{menubar}). This function returns @code{(@var{item} | |
| 441 . @var{parent})}, where @var{parent} is the immediate parent of the item | |
| 442 found (a menu description), and @var{item} is either a vector, list, or | |
| 443 string, depending on the nature of the menu item. | |
| 444 | |
| 445 This function signals an error if the item is not found. | |
| 446 @end defun | |
| 447 | |
| 448 The following deprecated functions are also documented, so that | |
| 449 existing code can be understood. You should not use these functions | |
| 450 in new code. | |
| 451 | |
| 452 @defun add-menu menu-path menu-name menu-items &optional before | |
| 453 This function adds a menu to the menubar or one of its submenus. If the | |
| 454 named menu exists already, it is changed. This is obsolete; use | |
| 455 @code{add-submenu} instead. | |
| 456 | |
| 457 @var{menu-path} identifies the menu under which the new menu should be | |
| 458 inserted. If @var{menu-path} is @code{nil}, then the menu will be added | |
| 459 to the menubar itself. | |
| 460 | |
| 461 @var{menu-name} is the string naming the menu to be added; | |
| 462 @var{menu-items} is a list of menu items, strings, and submenus. These | |
| 463 two arguments are the same as the first and following elements of a menu | |
| 464 description (@pxref{Menu Format}). | |
| 465 | |
| 466 @var{before}, if provided, is the name of a menu before which this | |
| 467 menu should be added, if this menu is not on its parent already. If the | |
| 468 menu is already present, it will not be moved. | |
| 469 @end defun | |
| 470 | |
| 471 @defun add-menu-item menu-path item-name function enabled-p &optional before | |
| 472 This function adds a menu item to some menu, creating the menu first if | |
| 473 necessary. If the named item exists already, it is changed. This is | |
| 474 obsolete; use @code{add-menu-button} instead. | |
| 475 | |
| 476 @var{menu-path} identifies the menu under which the new menu item should | |
| 477 be inserted. @var{item-name}, @var{function}, and @var{enabled-p} are | |
| 478 the first, second, and third elements of a menu item vector (@pxref{Menu | |
| 479 Format}). | |
| 480 | |
| 481 @var{before}, if provided, is the name of a menu item before which this | |
| 482 item should be added, if this item is not on the menu already. If the | |
| 483 item is already present, it will not be moved. | |
| 484 @end defun | |
| 485 | |
| 486 @node Menu Filters | |
| 487 @section Menu Filters | |
| 488 @cindex menu filters | |
| 489 | |
| 490 The following filter functions are provided for use in | |
| 491 @code{default-menubar}. You may want to use them in your own menubar | |
| 492 description. | |
| 493 | |
| 494 @defun file-menu-filter menu-items | |
| 495 This function changes the arguments and sensitivity of these File menu items: | |
| 496 | |
| 497 @table @samp | |
| 498 @item Delete Buffer | |
| 499 Has the name of the current buffer appended to it. | |
| 500 @item Print Buffer | |
| 501 Has the name of the current buffer appended to it. | |
| 502 @item Pretty-Print Buffer | |
| 503 Has the name of the current buffer appended to it. | |
| 504 @item Save Buffer | |
| 505 Has the name of the current buffer appended to it, and is sensitive only | |
| 506 when the current buffer is modified. | |
| 507 @item Revert Buffer | |
| 508 Has the name of the current buffer appended to it, and is sensitive only | |
| 509 when the current buffer has a file. | |
| 510 @item Delete Frame | |
| 511 Sensitive only when there is more than one visible frame. | |
| 512 @end table | |
| 513 @end defun | |
| 514 | |
| 515 @defun edit-menu-filter menu-items | |
| 516 This function changes the arguments and sensitivity of these Edit menu items: | |
| 517 | |
| 518 @table @samp | |
| 519 @item Cut | |
| 520 Sensitive only when XEmacs owns the primary X Selection (if | |
| 521 @code{zmacs-regions} is @code{t}, this is equivalent to saying that | |
| 522 there is a region selected). | |
| 523 @item Copy | |
| 524 Sensitive only when XEmacs owns the primary X Selection. | |
| 525 @item Clear | |
| 526 Sensitive only when XEmacs owns the primary X Selection. | |
| 527 @item Paste | |
| 528 Sensitive only when there is an owner for the X Clipboard Selection. | |
| 529 @item Undo | |
| 530 Sensitive only when there is undo information. While in the midst of an | |
| 531 undo, this is changed to @samp{Undo More}. | |
| 532 @end table | |
| 533 @end defun | |
| 534 | |
| 535 @defun buffers-menu-filter menu-items | |
| 536 This function sets up the Buffers menu. @xref{Buffers Menu}, for | |
| 537 more information. | |
| 538 @end defun | |
| 539 | |
| 540 @node Pop-Up Menus | |
| 541 @section Pop-Up Menus | |
| 542 @cindex pop-up menu | |
| 543 | |
| 444 | 544 @defun popup-menu menu-description &optional event |
| 545 This function pops up a menu specified by @var{menu-description}, which | |
| 546 is a menu description (@pxref{Menu Format}). The menu is displayed at | |
| 547 the current mouse position. | |
| 428 | 548 @end defun |
| 549 | |
| 550 @defun popup-menu-up-p | |
| 551 This function returns @code{t} if a pop-up menu is up, @code{nil} | |
| 552 otherwise. | |
| 553 @end defun | |
| 554 | |
| 555 @defvar popup-menu-titles | |
| 556 If true (the default), pop-up menus will have title bars at the top. | |
| 557 @end defvar | |
| 558 | |
| 559 Some machinery is provided that attempts to provide a higher-level | |
| 560 mechanism onto pop-up menus. This only works if you do not redefine | |
| 561 the binding for button3. | |
| 562 | |
| 563 @deffn Command popup-mode-menu | |
| 564 This function pops up a menu of global and mode-specific commands. The | |
| 565 menu is computed by combining @code{global-popup-menu} and | |
| 566 @code{mode-popup-menu}. This is the default binding for button3. | |
| 567 You should generally not change this binding. | |
| 568 @end deffn | |
| 569 | |
| 570 @defvar global-popup-menu | |
| 571 This holds the global popup menu. This is present in all modes. | |
| 572 (This is @code{nil} by default.) | |
| 573 @end defvar | |
| 574 | |
| 575 @defvar mode-popup-menu | |
| 576 The mode-specific popup menu. Automatically buffer local. | |
| 577 This is appended to the default items in @code{global-popup-menu}. | |
| 578 @end defvar | |
| 579 | |
| 580 @defvr Constant default-popup-menu | |
| 581 This holds the default value of @code{mode-popup-menu}. | |
| 582 @end defvr | |
| 583 | |
| 584 @defvar activate-popup-menu-hook | |
| 585 Function or functions run before a mode-specific popup menu is made | |
| 586 visible. These functions are called with no arguments, and should | |
| 587 interrogate and modify the value of @code{global-popup-menu} or | |
| 588 @code{mode-popup-menu} as desired. Note: this hook is only run if you | |
| 589 use @code{popup-mode-menu} for activating the global and mode-specific | |
| 590 commands; if you have your own binding for button3, this hook won't be | |
| 591 run. | |
| 592 @end defvar | |
| 593 | |
| 594 The following convenience functions are provided for displaying | |
| 595 pop-up menus. | |
| 596 | |
| 444 | 597 @deffn Command popup-buffer-menu event |
| 428 | 598 This function pops up a copy of the @samp{Buffers} menu (from the menubar) |
| 444 | 599 where the mouse is clicked. It should be bound to a mouse button event. |
| 600 @end deffn | |
| 428 | 601 |
| 444 | 602 @deffn Command popup-menubar-menu event |
| 428 | 603 This function pops up a copy of menu that also appears in the menubar. |
| 444 | 604 It should be bound to a mouse button event. |
| 605 @end deffn | |
| 428 | 606 |
| 607 @node Menu Accelerators | |
| 608 @section Menu Accelerators | |
| 609 @cindex menu accelerators | |
| 610 @cindex keyboard menu accelerators | |
| 611 | |
| 612 Menu accelerators are keyboard shortcuts for accessing the menubar. | |
| 613 Accelerator keys can be specified for menus as well as for menu items. An | |
| 614 accelerator key for a menu is used to activate that menu when it appears as a | |
| 615 submenu of another menu. An accelerator key for a menu item is used to | |
| 616 activate that item. | |
| 617 | |
| 618 @menu | |
| 440 | 619 * Creating Menu Accelerators:: How to add accelerator keys to a menu. |
| 620 * Keyboard Menu Traversal:: How to use and modify the keys which are used | |
| 621 to traverse the menu structure. | |
| 622 * Menu Accelerator Functions:: Functions for working with menu accelerators. | |
| 428 | 623 @end menu |
| 624 | |
| 625 @node Creating Menu Accelerators | |
| 626 @subsection Creating Menu Accelerators | |
| 627 | |
| 628 Menu accelerators are specified as part of the menubar format using the | |
| 629 :accelerator tag to specify a key or by placing "%_" in the menu or menu item | |
| 630 name prior to the letter which is to be used as the accelerator key. The | |
| 631 advantage of the second method is that the menu rendering code then knows to | |
| 632 draw an underline under that character, which is the canonical way of | |
| 633 indicating an accelerator key to a user. | |
| 634 | |
| 635 For example, the command | |
| 636 | |
| 637 @example | |
| 638 (add-submenu nil '("%_Test" | |
| 440 | 639 ["One" (insert "1") :accelerator ?1 :active t] |
| 640 ["%_Two" (insert "2")] | |
| 641 ["%_3" (insert "3")])) | |
| 428 | 642 @end example |
| 643 | |
| 644 will add a new menu to the top level menubar. The new menu can be reached | |
| 645 by pressing "t" while the top level menubar is active. When the menu is | |
| 646 active, pressing "1" will activate the first item and insert the character | |
| 5703 | 647 "1" into the buffer. Pressing "T" will activate the second item and insert |
| 428 | 648 the character "2" into the buffer. Pressing "3" will activate the third item |
| 649 and insert the character "3" into the buffer. | |
| 650 | |
| 651 It is possible to activate the top level menubar itself using accelerator keys. | |
| 652 @xref{Menu Accelerator Functions}. | |
| 653 | |
| 654 @node Keyboard Menu Traversal | |
| 655 @subsection Keyboard Menu Traversal | |
| 656 | |
| 657 In addition to immediately activating a menu or menu item, the keyboard can | |
| 658 be used to traverse the menus without activating items. The keyboard arrow | |
| 659 keys, the return key and the escape key are defined to traverse the menus in a | |
| 660 way that should be familiar to users of any of a certain family of popular PC | |
| 661 operating systems. | |
| 662 | |
| 663 This behavior can be changed by modifying the bindings in | |
| 664 menu-accelerator-map. At this point, the online help is your best bet | |
| 665 for more information about how to modify the menu traversal keys. | |
| 666 | |
| 667 @node Menu Accelerator Functions | |
| 668 @subsection Menu Accelerator Functions | |
| 669 | |
| 444 | 670 @deffn Command accelerate-menu |
| 428 | 671 Make the menubar immediately active and place the cursor on the left most entry |
| 672 in the top level menu. Menu items can be selected as usual. | |
| 444 | 673 @end deffn |
| 428 | 674 |
| 675 @defvar menu-accelerator-enabled | |
| 676 Whether menu accelerator keys can cause the menubar to become active. | |
| 677 | |
| 678 If @code{menu-force} or @code{menu-fallback}, then menu accelerator keys can | |
| 679 be used to activate the top level menu. Once the menubar becomes active, the | |
| 680 accelerator keys can be used regardless of the value of this variable. | |
| 681 | |
| 682 @code{menu-force} is used to indicate that the menu accelerator key takes | |
| 683 precedence over bindings in the current keymap(s). @code{menu-fallback} means | |
| 684 that bindings in the current keymap take precedence over menu accelerator keys. | |
| 685 Thus a top level menu with an accelerator of "T" would be activated on a | |
| 1738 | 686 keypress of Meta-t if @code{menu-accelerator-enabled} is @code{menu-force}. |
| 687 However, if @code{menu-accelerator-enabled} is @code{menu-fallback}, then | |
| 428 | 688 Meta-t will not activate the menubar and will instead run the function |
| 689 transpose-words, to which it is normally bound. | |
| 690 | |
| 691 The default value is @code{nil}. | |
| 692 | |
| 1738 | 693 See also @code{menu-accelerator-modifiers} and @code{menu-accelerator-prefix}. |
| 428 | 694 @end defvar |
| 695 | |
| 696 @defvar menu-accelerator-map | |
| 697 Keymap consulted to determine the commands to run in response to keypresses | |
| 698 occurring while the menubar is active. @xref{Keyboard Menu Traversal}. | |
| 699 @end defvar | |
| 700 | |
| 701 @defvar menu-accelerator-modifiers | |
| 702 A list of modifier keys which must be pressed in addition to a valid menu | |
| 703 accelerator in order for the top level menu to be activated in response to | |
| 704 a keystroke. The default value of @code{(meta)} mirrors the usage of the alt key | |
| 705 as a menu accelerator in popular PC operating systems. | |
| 706 | |
| 1738 | 707 The modifier keys in @code{menu-accelerator-modifiers} must match exactly the |
| 428 | 708 modifiers present in the keypress. The only exception is that the shift |
| 1738 | 709 modifier is accepted in conjunction with alphabetic keys even if it is not a |
| 710 menu accelerator modifier. | |
| 428 | 711 |
| 1738 | 712 See also @code{menu-accelerator-enabled} and @code{menu-accelerator-prefix}. |
| 428 | 713 @end defvar |
| 714 | |
| 715 @defvar menu-accelerator-prefix | |
| 716 Prefix key(s) that must be typed before menu accelerators will be activated. | |
| 717 Must be a valid key descriptor. | |
| 718 | |
| 719 The default value is @code{nil}. | |
| 720 @end defvar | |
| 721 | |
| 722 @example | |
| 723 (setq menu-accelerator-prefix ?\C-x) | |
| 724 (setq menu-accelerator-modifiers '(meta control)) | |
| 725 (setq menu-accelerator-enabled 'menu-force) | |
| 726 (add-submenu nil '("%_Test" | |
| 440 | 727 ["One" (insert "1") :accelerator ?1 :active t] |
| 728 ["%_Two" (insert "2")] | |
| 729 ["%_3" (insert "3")])) | |
| 428 | 730 @end example |
| 731 | |
| 732 will add the menu "Test" to the top level menubar. Pressing C-x followed by | |
| 733 C-M-T will activate the menubar and display the "Test" menu. Pressing | |
| 734 C-M-T by itself will not activate the menubar. Neither will pressing C-x | |
| 735 followed by anything else. | |
| 736 | |
| 737 @node Buffers Menu | |
| 738 @section Buffers Menu | |
| 739 @cindex buffers menu | |
| 740 | |
| 741 The following options control how the @samp{Buffers} menu is displayed. | |
| 742 This is a list of all (or a subset of) the buffers currently in existence, | |
| 743 and is updated dynamically. | |
| 744 | |
| 745 @defopt buffers-menu-max-size | |
| 746 This user option holds the maximum number of entries which may appear on | |
| 747 the @samp{Buffers} menu. If this is 10, then only the ten | |
| 748 most-recently-selected buffers will be shown. If this is @code{nil}, | |
| 749 then all buffers will be shown. Setting this to a large number or | |
| 750 @code{nil} will slow down menu responsiveness. | |
| 751 @end defopt | |
| 752 | |
| 753 @defun format-buffers-menu-line buffer | |
| 754 This function returns a string to represent @var{buffer} in the | |
| 755 @samp{Buffers} menu. @code{nil} means the buffer shouldn't be listed. | |
| 756 You can redefine this. | |
| 757 @end defun | |
| 758 | |
| 759 @defopt complex-buffers-menu-p | |
| 760 If true, the @samp{Buffers} menu will contain several commands, as submenus | |
| 761 of each buffer line. If this is false, then there will be only one command: | |
| 762 select that buffer. | |
| 763 @end defopt | |
| 764 | |
| 765 @defopt buffers-menu-switch-to-buffer-function | |
| 766 This user option holds the function to call to select a buffer from the | |
| 767 @samp{Buffers} menu. @code{switch-to-buffer} is a good choice, as is | |
| 768 @code{pop-to-buffer}. | |
| 769 @end defopt | |
| 770 |