2 @node Pull-down Menus, Entering Emacs, Keystrokes, Top
3 @comment node-name, next, previous, up
4 @section XEmacs Pull-down Menus
6 If you are running XEmacs under X, a menu bar on top of the
7 Emacs frame provides access to pull-down menus of file, edit, and
8 help-related commands. The menus provide convenient shortcuts and an
9 easy interface for novice users. They do not provide additions to the
10 functionality available via key commands; you can still invoke commands
11 from the keyboard as in previous versions of Emacs.
15 Perform file and buffer-related operations, such as opening and closing
16 files, saving and printing buffers, as well as exiting Emacs.
20 Perform standard editing operations, such as
21 cutting, copying, pasting, and killing selected text.
24 @c #### The Mule menu needs to be documented, but this is not the place
25 @c for it since Ben just moved it.
28 Access to sub-applications implemented within XEmacs, such as the mail
29 reader, the World Wide Web browser, the spell-checker, and the calendar
34 Control various options regarding the way XEmacs works, such as controlling
35 which elements of the frame are visible, selecting the fonts to be used for
36 text, specifying whether searches are case-sensitive, etc.
40 Present a menu of buffers for selection as well as the option to display
45 Perform various actions designed to automate software development and
46 similar technical work, such as searching through many files, compiling
47 a program, and comparing or merging two or three files.
54 @cindex Pull-down Menus
57 There are two ways of selecting an item from a pull-down menu:
61 Select an item in the menu bar by moving the cursor over it and click the
62 left mouse-button. Then move the cursor over the menu item you want to choose
65 Select an item in the menu bar by moving the cursor over it and click and
66 hold the left mouse-button. With the mouse-button depressed, move the
67 cursor over the menu item you want, then release it to make your selection.
70 If a command in the pull-down menu is not applicable in a given
71 situation, the command is disabled and its name appears faded. You
72 cannot invoke items that are faded. For example, many commands on the
73 @b{Edit} menu appear faded until you select text on which they are to
74 operate; after you select a block of text, edit commands are enabled.
75 @xref{Mouse Selection}, for information on using the mouse to select
76 text. @xref{Using X Selections}, for related information.
78 There are also @kbd{M-x} equivalents for each menu item. To find the
79 equivalent for any left-button menu item, do the following:
83 Type @kbd{C-h k} to get the @code{Describe Key} prompt.
85 Select the menu item and click.
88 Emacs displays the function associated with the menu item in a separate
89 window, usually together with some documentation.
92 * File Menu:: Items on the File menu.
93 * Edit Menu:: Items on the Edit menu.
94 * Apps Menu:: Items on the Apps menu.
95 * Options Menu:: Items on the Options menu.
96 * Buffers Menu:: Information about the Buffers menu.
97 * Tools Menu:: Items on the Tools menu.
98 * Help Menu:: Items on the Help menu.
99 * Menu Customization:: Adding and removing menu items and related
104 @subsection The File Menu
108 The @b{File} menu bar item contains the items @b{New Frame}, @b{Open
109 File...}, @b{Save Buffer}, @b{Save Buffer As...}, @b{Revert Buffer},
110 @b{Print Buffer}, @b{Delete Frame}, @b{Kill Buffer} and @b{Exit Emacs}
111 on the pull-down menu. If you select a menu item, Emacs executes the
114 @cindex Open File, New Frame... menu item
115 @cindex Open File... menu item
116 @cindex Insert File... menu item
117 @cindex Save Buffer menu item
118 @cindex Save Buffer As ... menu item
119 @cindex Revert Buffer menu item
120 @cindex Kill Buffer menu item
121 @cindex Print Buffer menu item
122 @cindex New Frame menu item
123 @cindex Delete Frame menu item
125 @cindex Un-split (Keep This)
126 @cindex Un-split (Keep Others)
127 @cindex Exit Emacs menu item
130 @item Open File, New Frame...
131 Prompts you for a filename and loads that file into a new buffer in a
132 new Emacs frame, that is, a new X window running under the same Emacs
133 process. You can remove the frame using the @b{Delete Frame} menu
134 item. When you remove the last frame, you exit Emacs and are prompted
135 for confirmation. @refill
138 Prompts you for a filename and loads that file into a new buffer.
139 @b{Open File...} is equivalent to the Emacs command @code{find-file} (@kbd{C-x
143 Prompts you for a filename and inserts the contents of that file into
144 the current buffer. The file associated with the current buffer is
145 not changed by this command. This is equivalent to the Emacs command
146 @code{insert-file} (@kbd{C-x i}).@refill
149 Writes and saves the current Emacs buffer as the latest
150 version of the current visited file. @b{Save Buffer} is equivalent to the
151 Emacs command @code{save-buffer} (@kbd{C-x C-s}).@refill
153 @item Save Buffer As...
154 Writes and saves the current Emacs buffer to the filename you specify.
155 @b{Save Buffer As...} is equivalent to the Emacs command
156 @code{write-file} (@kbd{C-x C-w}).@refill
159 Restores the last saved version of the file to the current buffer. When
160 you edit a buffer containing a text file, you must save the buffer
161 before your changes become effective. Use @b{Revert Buffer} if you do
162 not want to keep the changes you have made in the buffer. @b{Revert
163 Buffer} is equivalent to the Emacs command @code{revert-file} (@kbd{M-x
164 revert-buffer}).@refill
167 Kills the current buffer, prompting you first if there are unsaved
168 changes. This is roughly equivalent to the Emacs command
169 @code{kill-buffer} (@kbd{C-x k}), except that @code{kill-buffer}
170 prompts for the name of a buffer to kill. @refill
173 Prints a hardcopy of the current buffer. Equivalent
174 to the Emacs command @code{print-buffer} (@kbd{M-x print-buffer}).@refill
177 Creates a new Emacs frame displaying the @code{*scratch*} buffer. This
178 is like the @b{Open File, New Frame...} menu item, except that it does
179 not prompt for or load a file.@refill
182 Allows you to close all but one of the frames created by @b{New Frame}.
183 If you created several Emacs frames belonging to the same Emacs
184 process, you can close all but one of them. When you attempt to close the
185 last frame, Emacs informs you that you are attempting to delete the
186 last frame. You have to choose @b{Exit Emacs} for that.@refill
189 Divides the current window on the current frame into two equal-sized
190 windows, both displaying the same buffer. Equivalent to the Emacs
191 command @code{split-window-vertically} (@kbd{C-x 2}).@refill
193 @item Un-split (Keep This)
194 If the frame is divided into multiple windows, this removes all windows
195 other than the selected one. Equivalent to the Emacs command
196 @code{delete-other-windows} (@kbd{C-x 1}).@refill
198 @item Un-split (Keep Others)
199 If the frame is divided into multiple windows, this removes the
200 selected window from the frame, giving the space back to one of the
201 other windows. Equivalent to the Emacs command @code{delete-window}
202 (@kbd{C-x 0}).@refill
205 Shuts down (kills) the Emacs process. Equivalent to the Emacs command
206 @code{save-buffers-kill-emacs} (@kbd{C-x C-c}). Before killing the
207 Emacs process, the system asks which unsaved buffers to save by going through
208 the list of all buffers in that Emacs process.@refill
212 @subsection The Edit Menu
215 The @b{Edit} pull-down menu contains the @b{Undo}, @b{Cut}, @b{Copy},
216 @b{Paste}, and @b{Clear} menu items. When you select a menu item, Emacs
217 executes the equivalent command. Most commands on the @b{Edit} menu
218 work on a block of text, the X selection. They appear faded until you
219 select a block of text (activate a region) with the mouse. @xref{Using
220 X Selections}, @pxref{Killing}, and @pxref{Yanking} for more
223 @c **** zmacs-regions is on by default these days - jwz
225 @c Note: By default, you can use the @b{Edit} menu items on the region between
226 @c point and the mark as well as regions selected with the mouse. To change
227 @c this behavior, set the variable @code{zmacs-regions} to
228 @c @code{t}. @xref{Active Regions} for more information.
230 @cindex Undo menu item
231 @cindex Cut menu item
232 @cindex Copy menu item
233 @cindex Paste menu item
234 @cindex Clear menu item
235 @cindex Start Macro Recording menu item
236 @cindex End Macro Recording menu item
237 @cindex Execute Last Macro menu item
240 Undoes the previous command. @b{Undo} is equivalent to
241 the Emacs command @code{undo} (@kbd{C-x u}).@refill
244 Removes the selected text block from the current buffer, makes it the X
245 clipboard selection, and places it in the kill ring. Before executing
246 this command, you have to select a region using Emacs region selection
247 commands or with the mouse.@refill
250 Makes a selected text block the X clipboard selection, and places it in
251 the kill ring. You can select text using one of the Emacs region
252 selection commands or by selecting a text region with the mouse.@refill
255 Inserts the current value of the X clipboard selection in the current
256 buffer. Note that this is not necessarily the same as the Emacs
257 @code{yank} command, because the Emacs kill ring and the X clipboard
258 selection are not the same thing. You can paste in text you
259 have placed in the clipboard using @b{Copy} or @b{Cut}. You can also
260 use @b{Paste} to insert text that was pasted into the clipboard from other
264 Removes the selected text block from the current buffer but does not
265 place it in the kill ring or the X clipboard selection.
267 @item Start Macro Recording
268 After selecting this, Emacs will remember every keystroke you type until
269 @b{End Macro Recording} is selected. This is the same as the Emacs
270 command @code{start-kbd-macro} (@kbd{C-x (}).
272 @item End Macro Recording
273 Selecting this tells emacs to stop remembering your keystrokes. This is
274 the same as the Emacs command @code{end-kbd-macro} (@kbd{C-x )}).
276 @item Execute Last Macro
277 Selecting this item will cause emacs to re-interpret all of the
278 keystrokes which were saved between selections of the @b{Start Macro
279 Recording} and @b{End Macro Recording} menu items. This is the same
280 as the Emacs command @code{call-last-kbd-macro} (@kbd{C-x e}).
284 @subsection The Apps Menu
287 The @b{Apps} pull-down menu contains the @b{Read Mail (VM)...}, @b{Read
288 Mail (MH)...}, @b{Send Mail...}, @b{Usenet News}, @b{Browse the Web},
289 @b{Gopher}, @b{Spell-Check Buffer} and @b{Emulate VI} menu items,
290 and the @b{Calendar} and @b{Games} sub-menus. When you select a menu
291 item, Emacs executes the equivalent command. For some of the menu
292 items, there are sub-menus which you will need to select.
295 @subsection The Options Menu
298 The @b{Options} pull-down menu contains the @b{Read Only}, @b{Case
299 Sensitive Search}, @b{Overstrike}, @b{Auto Delete Selection},
300 @b{Teach Extended Commands}, @b{Syntax Highlighting}, @b{Paren
301 Highlighting}, @b{Font}, @b{Size}, @b{Weight}, @b{Buffers Menu
302 Length...}, @b{Buffers Sub-Menus} and @b{Save Options} menu items.
303 When you select a menu item, Emacs executes the equivalent command.
304 For some of the menu items, there are sub-menus which you will need
307 @cindex Read Only menu item
308 @cindex Case Sensitive Search menu item
309 @cindex Overstrike menu item
310 @cindex Auto Delete Selection menu item
311 @cindex Teach Extended Commands menu item
312 @cindex Syntax Highlighting menu item
313 @cindex Paren Highlighting menu item
314 @cindex Font menu item
315 @cindex Size menu item
316 @cindex Weight menu item
317 @cindex Buffers Menu Length... menu item
318 @cindex Buffers Sub-Menus menu item
322 Selecting this item will cause the buffer to visit the file in a
323 read-only mode. Changes to the file will not be allowed. This is
324 equivalent to the Emacs command @code{toggle-read-only}
327 @item Case Sensitive Search
328 Selecting this item will cause searches to be case-sensitive. If
329 its not selected then searches will ignore case. This option is
333 After selecting this item, when you type letters they will replace
334 existing text on a one-to-one basis, rather than pushing it to the
335 right. At the end of a line, such characters extend the line. Before
336 a tab, such characters insert until the tab is filled in. This is the
337 same as Emacs command @code{quoted-insert} (@kbd{C-q}).
339 @item Auto Delete Selection
340 Selecting this item will cause automatic deletion of the selected
341 region. The typed text will replace the selection if the selection
342 is active (i.e. if its highlighted). If the option is not selected
343 then the typed text is just inserted at the point.
345 @item Teach Extended Commands
346 After you select this item, any time you execute a command with
347 @kbd{M-x}which has a shorter keybinding, you will be shown the
348 alternate binding before the command executes.
350 @item Syntax Highlighting
351 You can customize your init file to include the font-lock mode so that
352 when you select this item, the comments will be displayed in one face,
353 strings in another, reserved words in another, and so on. @xref{Init
354 File}. When @b{Fonts} is selected, different parts of the program will
355 appear in different Fonts. When @b{Colors} is selected, then the program
356 will be displayed in different colors. Selecting @b{None} causes the
357 program to appear in just one Font and Color. Selecting @b{Less} resets
358 the Fonts and Colors to a fast, minimal set of decorations. Selecting
359 @b{More} resets the Fonts and Colors to a larger set of decorations. For
360 example, if @b{Less} is selected (which is the default setting) then you
361 might have all comments in green color. Whereas, if @b{More} is
362 selected then a function name in the comments themselves might appear in
363 a different Color or Font.@refill
365 @item Paren Highlighting
366 After selecting @b{Blink} from this item, if you place the cursor
367 on a parenthesis, the matching parenthesis will blink. If you select
368 @b{Highlight} and place the cursor on a parenthesis, the whole
369 expression of the parenthesis under the cursor will be highlighted.
370 Selecting @b{None} will turn off the options (regarding @b{Paren
371 Highlighting}) which you had selected earlier.@refill
374 You can select any Font for your program by choosing from one of the
378 You can select any size ranging from @b{2} to @b{24} by selecting the
379 appropriate option.@refill
382 You can choose either @b{Bold} or @b{Medium} for the weight.@refill
384 @item Buffers Menu Length...
385 Prompts you for the number of buffers to display. Then it will display
386 that number of most recently selected buffers.
388 @item Buffers Sub-Menus
389 After selection of this item the Buffers menu will contain several
390 commands, as submenus of each buffer line. If this item is unselected,
391 then there are no submenus for each buffer line, the only command
392 available will be selecting that buffer.
395 Selecting this item will save the current settings of your Options
396 menu to your init file. @xref{Init File}.
400 @subsection The Buffers Menu
402 The @b{Buffers} menu provides a selection of up to ten buffers and the
403 item @b{List All Buffers}, which provides a Buffer List. @xref{List
404 Buffers}, for more information.
407 @subsection The Tools Menu
410 The @b{Tools} pull-down menu contains the @b{Grep...}, @b{Compile...},
411 @b{Shell Command...}, @b{Shell Command on Region...}, @b{Debug(GDB)...}
412 and @b{Debug(DBX)...} menu items, and the @b{Compare}, @b{Merge},
413 @b{Apply Patch} and @b{Tags} sub-menus. When you select a menu item,
414 Emacs executes the equivalent command. For some of the menu items,
415 there are sub-menus which you will need to select.
418 @subsection The Help Menu
421 The Help Menu gives you access to Emacs Info and provides a menu
422 equivalent for each of the choices you have when using @kbd{C-h}.
423 @xref{Help}, for more information.
425 The Help menu also gives access to UNIX online manual pages via the
426 @b{UNIX Manual Page} option.
428 @node Menu Customization
429 @subsection Customizing XEmacs Menus
431 You can customize any of the pull-down menus by adding or removing menu
432 items and disabling or enabling existing menu items.
434 The following functions are available:
436 @item add-menu: (@var{menu-path} @var{menu-name} @var{menu-items} &optional @var{before})
437 Add a menu to the menu bar or one of its submenus.
438 @item add-menu-item: (@var{menu-path} @var{item-name} @var{function}
439 @var{enabled-p} &optional @var{before})
440 Add a menu item to a menu, creating the menu first if necessary.
441 @item delete-menu-item: (@var{path})
442 Remove the menu item defined by @var{path} from the menu hierarchy.
443 @item disable-menu-item: (@var{path})
444 Disable the specified menu item.
445 @item enable-menu-item: (@var{path})
446 Enable the specified previously disabled menu item.
447 @item relabel-menu-item: (@var{path} @var{new-name})
448 Change the string of the menu item specified by @var{path} to
455 Use the function @code{add-menu} to add a new menu or submenu.
456 If a menu or submenu of the given name exists already, it is changed.
458 @var{menu-path} identifies the menu under which the new menu should be
459 inserted. It is a list of strings; for example, @code{("File")} names
460 the top-level @b{File} menu. @code{("File" "Foo")} names a hypothetical
461 submenu of @b{File}. If @var{menu-path} is @code{nil}, the menu is
462 added to the menu bar itself.
464 @var{menu-name} is the string naming the menu to be added.
466 @var{menu-items} is a list of menu item descriptions. Each menu item
467 should be a vector of three elements:
471 A string, which is the name of the menu item
473 A symbol naming a command, or a form to evaluate
475 @code{t} or @code{nil} to indicate whether the item is selectable
478 The optional argument @var{before} is the name of the menu before which
479 the new menu or submenu should be added. If the menu is already
480 present, it is not moved.
482 @findex add-menu-item
483 @cindex adding menu items
484 The function @code{add-menu-item} adds a menu item to the specified
485 menu, creating the menu first if necessary. If the named item already
486 exists, the menu remains unchanged.
488 @var{menu-path} identifies the menu into which the new menu item should
489 be inserted. It is a list of strings; for example, @code{("File")}
490 names the top-level @b{File} menu. @code{("File" "Foo")} names a
491 hypothetical submenu of @b{File}.
493 @var{item-name} is the string naming the menu item to add.
495 @var{function} is the command to invoke when this menu item is selected.
496 If it is a symbol, it is invoked with @code{call-interactively}, in the
497 same way that functions bound to keys are invoked. If it is a list, the
498 list is simply evaluated.
500 @var{enabled-p} controls whether the item is selectable or not.
501 It should be @code{t}, @code{nil}, or a form to evaluate to decide.
502 This form will be evaluated just before the menu is displayed, and
503 the menu item will be selectable if that form returns non-@code{nil}.
505 For example, to make the @code{rename-file} command available from the
506 @b{File} menu, use the following code:
509 (add-menu-item '("File") "Rename File" 'rename-file t)
512 To add a submenu of file management commands using a @b{File Management}
513 item, use the following code:
516 (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
517 (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
518 (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)
521 The optional @var{before} argument is the name of a menu item before
522 which the new item should be added. If the item is already present, it
525 @findex delete-menu-item
526 @cindex deleting menu items
527 To remove a specified menu item from the menu hierarchy, use
528 @code{delete-menu-item}.
530 @var{path} is a list of strings that identify the position of the menu
531 item in the menu hierarchy. @code{("File" "Save")} means the menu item
532 called @b{Save} under the top level @b{File} menu. @code{("Menu" "Foo"
533 "Item")} means the menu item called @b{Item} under the @b{Foo} submenu
536 @findex disable-menu-item
537 @findex enable-menu-item
538 @cindex enabling menu items
539 @cindex disabling menu items
541 To disable a menu item, use @code{disable-menu-item}. The disabled
542 menu item is grayed and can no longer be selected. To make the
543 item selectable again, use @code{enable-menu-item}.
544 @code{disable-menu-item} and @code{enable-menu-item} both have the
547 @findex relabel-menu-item
548 @cindex changing menu items
549 To change the string of the specified menu item, use
550 @code{relabel-menu-item}. This function also takes the argument @var{path}.
552 @var{new-name} is the string to which the menu item will be changed.