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