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