XEmacs Pull-down Menus
======================

If you are running XEmacs under X, a menu bar on top of the Emacs frame provides access to pull-down menus of file, edit, and help-related commands. The menus provide convenient shortcuts and an easy interface for novice users.  They do not provide additions to the functionality available via key commands; you can still invoke commands from the keyboard as in previous versions of Emacs.

File
     Perform file and buffer-related operations, such as opening and closing files, saving and printing buffers, as well as exiting Emacs.

Edit
     Perform standard editing operations, such as cutting, copying, pasting, and killing selected text.

Apps
     Access to sub-applications implemented within XEmacs, such as the mail reader, the World Wide Web browser, the spell-checker, and the calendar program.

Options
     Control various options regarding the way XEmacs works, such as controlling which elements of the frame are visible, selecting the fonts to be used for text, specifying whether searches are case-sensitive, etc.

Buffers
     Present a menu of buffers for selection as well as the option to display a buffer list.

Tools
     Perform various actions designed to automate software development and similar technical work, such as searching through many files, compiling a program, and comparing or merging two or three files.

Help
     Access to Emacs Info.

There are two ways of selecting an item from a pull-down menu:

  * Select an item in the menu bar by moving the cursor over it and click the left mouse-button.  Then move the cursor over the menu item you want to choose and click left again.

  * Select an item in the menu bar by moving the cursor over it and click and hold the left mouse-button.  With the mouse-button depressed, move the cursor over the menu item you want, then release it to make your selection.

If a command in the pull-down menu is not applicable in a given situation, the command is disabled and its name appears faded.  You cannot invoke items that are faded.  For example, many commands on the Edit menu appear faded until you select text on which they are to operate; after you select a block of text, edit commands are enabled. See Mouse Selection, for information on using the mouse to select text.  See Using X Selections, for related information.

There are also M-x equivalents for each menu item.  To find the equivalent for any left-button menu item, do the following:

 1. Type C-h k to get the Describe Key prompt.

 2. Select the menu item and click.

Emacs displays the function associated with the menu item in a separate window, usually together with some documentation.

The File Menu
-------------

The File menu bar item contains the items New Frame, Open File..., Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete Frame, Kill Buffer and Exit Emacs on the pull-down menu.  If you select a menu item, Emacs executes the equivalent command.

Open File, New Frame...
     Prompts you for a filename and loads that file into a new buffer in a new Emacs frame, that is, a new X window running under the same Emacs process.  You can remove the frame using the Delete Frame menu item.  When you remove the last frame, you exit Emacs and are prompted for confirmation.

Open File...
     Prompts you for a filename and loads that file into a new buffer. Open File... is equivalent to the Emacs command find-file (C-x C-f).

Insert File...
     Prompts you for a filename and inserts the contents of that file into the current buffer.  The file associated with the current buffer is not changed by this command.  This is equivalent to the Emacs command insert-file (C-x i).

Save Buffer
     Writes and saves the current Emacs buffer as the latest version of the current visited file.  Save Buffer is equivalent to the Emacs command save-buffer (C-x C-s).

Save Buffer As...
     Writes and saves the current Emacs buffer to the filename you specify. Save Buffer As... is equivalent to the Emacs command write-file (C-x C-w).

Revert Buffer
     Restores the last saved version of the file to the current buffer.  When you edit a buffer containing a text file, you must save the buffer before your changes become effective.  Use Revert Buffer if you do not want to keep the changes you have made in the buffer.  Revert Buffer is equivalent to the Emacs command revert-file (M-x revert-buffer).

Kill Buffer
     Kills the current buffer, prompting you first if there are unsaved changes.  This is roughly equivalent to the Emacs command kill-buffer (C-x k), except that kill-buffer prompts for the name of a buffer to kill.

Print Buffer
     Prints a hardcopy of the current buffer.  Equivalent to the Emacs command print-buffer (M-x print-buffer).

New Frame
     Creates a new Emacs frame displaying the *scratch* buffer.  This is like the Open in New Frame... menu item, except that it does not prompt for nor load a file.

Delete Frame
     Allows you to close all but one of the frames created by New Frame. If you created several Emacs frames belonging to the same Emacs process, you can close all but one of them.  When you attempt to close the last frame, Emacs informs you that you are attempting to delete the last frame.  You have to choose Exit Emacs for that.

Split Frame
     Divides the current window on the current frame into two equal-sized windows, both displaying the same buffer.  Equivalent to the Emacs command split-window-vertically (C-x 2).

Un-split (Keep This)
     If the frame is divided into multiple windows, this removes all windows other than the selected one.  Equivalent to the Emacs command delete-other-windows (C-x 1).

Un-split (Keep Others)
     If the frame is divided into multiple windows, this removes the selected window from the frame, giving the space back to one of the other windows.  Equivalent to the Emacs command delete-window (C-x 0).

Exit Emacs
     Shuts down (kills) the Emacs process.  Equivalent to the Emacs command save-buffers-kill-emacs (C-x C-c).  Before killing the Emacs process, the system asks which unsaved buffers to save by going through the list of all buffers in that Emacs process.

The Edit Menu
-------------

The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and Clear menu items.  When you select a menu item, Emacs executes the equivalent command.  Most commands on the Edit menu work on a block of text, the X selection.  They appear faded until you select a block of text (activate a region) with the mouse.  See Using X Selections, see Killing, and see Yanking for more information.

Undo
     Undoes the previous command.  Undo is equivalent to the Emacs command undo (C-x u).

Cut
     Removes the selected text block from the current buffer, makes it the X clipboard selection, and places it in the kill ring.  Before executing this command, you have to select a region using Emacs region selection commands or with the mouse.

Copy
     Makes a selected text block the X clipboard selection, and places it in the kill ring.  You can select text using one of the Emacs region selection commands or by selecting a text region with the mouse.

Paste
     Inserts the current value of the X clipboard selection in the current buffer.  Note that this is not necessarily the same as the Emacs yank command, because the Emacs kill ring and the X clipboard selection are not the same thing.  You can paste in text you have placed in the clipboard using Copy or Cut.  You can also use Paste to insert text that was pasted into the clipboard from other applications.

Clear
     Removes the selected text block from the current buffer but does not place it in the kill ring or the X clipboard selection.

Start Macro Recording
     After selecting this, Emacs will remember every keystroke you type until End Macro Recording is selected.  This is the same as the Emacs command start-kbd-macro (C-x ().

End Macro Recording
     Selecting this tells emacs to stop remembering your keystrokes.  This is the same as the Emacs command end-kbd-macro (C-x )).

Execute Last Macro
     Selecting this item will cause emacs to re-interpret all of the keystrokes which were saved between selections of the Start Macro Recording and End Macro Recording menu items.  This is the same as the Emacs command call-last-kbd-macro (C-x e).

The Apps Menu
-------------

The Apps pull-down menu contains the Read Mail (VM)..., Read Mail (MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.  When you select a menu item, Emacs executes the equivalent command.  For some of the menu items, there are sub-menus which you will need to select.

The Options Menu
----------------

The Options pull-down menu contains the Read Only, Case Sensitive Search, Overstrike, Auto Delete Selection, Teach Extended Commands, Syntax Highlighting, Paren Highlighting, Font, Size, Weight, Buffers Menu Length..., Buffers Sub-Menus and Save Options menu items. When you select a menu item, Emacs executes the equivalent command. For some of the menu items, there are sub-menus which you will need to select.

Read Only
     Selecting this item will cause the buffer to visit the file in a read-only mode. Changes to the file will not be allowed. This is equivalent to the Emacs command toggle-read-only (C-x C-q).

Case Sensitive Search
     Selecting this item will cause searches to be case-sensitive. If its not selected then searches will ignore case. This option is local to the buffer.

Overstrike
     After selecting this item, when you type letters they will replace existing text on a one-to-one basis, rather than pushing it to the right. At the end of a line, such characters extend the line. Before a tab, such characters insert until the tab is filled in. This is the same as Emacs command quoted-insert (C-q).

Auto Delete Selection
     Selecting this item will cause automatic deletion of the selected region. The typed text will replace the selection if the selection is active (i.e. if its highlighted). If the option is not selected then the typed text is just inserted at the point.

Teach Extended Commands
     After you  select this item, any time you execute a command with M-xwhich has a shorter keybinding, you will be shown the alternate binding before the command executes.

Syntax Highlighting
     You can customize your init file to include the font-lock mode so that when you select this item, the comments will be displayed in one face, strings in another, reserved words in another, and so on. See Init File.  When Fonts is selected, different parts of the program will appear in different Fonts. When Colors is selected, then the program will be displayed in different colors. Selecting None causes the program to appear in just one Font and Color. Selecting Less resets the Fonts and Colors to a fast, minimal set of decorations. Selecting More resets the Fonts and Colors to a larger set of decorations. For example, if Less is selected (which is the default setting) then you might have all comments in green color.  Whereas, if More is selected then a function name in the comments themselves might appear in a different Color or Font.

Paren Highlighting
     After selecting Blink from this item, if you place the cursor on a parenthesis, the matching parenthesis will blink. If you select Highlight and place the cursor on a parenthesis, the whole expression of the parenthesis under the cursor will be highlighted. Selecting None will turn off the options (regarding Paren Highlighting) which you had selected earlier.

Font
     You can select any Font for your program by choosing from one of the available Fonts.

Size
     You can select any size ranging from 2 to 24 by selecting the appropriate option.

Weight
     You can choose either Bold or Medium for the weight.

Buffers Menu Length...
     Prompts you for the number of buffers to display. Then it will display that number of most recently selected buffers.

Buffers Sub-Menus
     After selection of this item the Buffers menu will contain several commands, as submenus of each buffer line. If this item is unselected, then there are no submenus for each buffer line, the only command available will be selecting that buffer.

Save Options
     Selecting this item will save the current settings of your Options menu to your init file.  See Init File.

The Buffers Menu
----------------

The Buffers menu provides a selection of up to ten buffers and the item List All Buffers, which provides a Buffer List. See List Buffers, for more information.

The Tools Menu
--------------

The Tools pull-down menu contains the Grep..., Compile..., Shell Command..., Shell Command on Region..., Debug(GDB)... and Debug(DBX)... menu items, and the Compare, Merge, Apply Patch and Tags sub-menus.  When you select a menu item, Emacs executes the equivalent command.  For some of the menu items, there are sub-menus which you will need to select.

The Help Menu
-------------

The Help Menu gives you access to Emacs Info and provides a menu equivalent for each of the choices you have when using C-h. See Help, for more information.

The Help menu also gives access to UNIX online manual pages via the UNIX Manual Page option.

Customizing XEmacs Menus
------------------------

You can customize any of the pull-down menus by adding or removing menu items and disabling or enabling existing menu items.

The following functions are available:

add-menu: (MENU-PATH MENU-NAME MENU-ITEMS &optional BEFORE)
     Add a menu to the menu bar or one of its submenus.

add-menu-item: (MENU-PATH ITEM-NAME FUNCTION
     ENABLED-P &optional BEFORE) Add a menu item to a menu, creating the menu first if necessary.

delete-menu-item: (PATH)
     Remove the menu item defined by PATH from the menu hierarchy.

disable-menu-item: (PATH)
     Disable the specified menu item.

enable-menu-item: (PATH)
     Enable the specified previously disabled menu item.

relabel-menu-item: (PATH NEW-NAME)
     Change the string of the menu item specified by PATH to NEW-NAME.

Use the function add-menu to add a new menu or submenu. If a menu or submenu of the given name exists already, it is changed.

MENU-PATH identifies the menu under which the new menu should be inserted.  It is a list of strings; for example, ("File") names the top-level File menu.  ("File" "Foo") names a hypothetical submenu of File.  If MENU-PATH is nil, the menu is added to the menu bar itself.

MENU-NAME is the string naming the menu to be added.

MENU-ITEMS is a list of menu item descriptions.  Each menu item should be a vector of three elements:

  * A string, which is the name of the menu item

  * A symbol naming a command, or a form to evaluate

  * t or nil to indicate whether the item is selectable

The optional argument BEFORE is the name of the menu before which the new menu or submenu should be added.  If the menu is already present, it is not moved.

The function add-menu-item adds a menu item to the specified menu, creating the menu first if necessary.  If the named item already exists, the menu remains unchanged.

MENU-PATH identifies the menu into which the new menu item should be inserted.  It is a list of strings; for example, ("File") names the top-level File menu.  ("File" "Foo") names a hypothetical submenu of File.

ITEM-NAME is the string naming the menu item to add.

FUNCTION is the command to invoke when this menu item is selected. If it is a symbol, it is invoked with call-interactively, in the same way that functions bound to keys are invoked.  If it is a list, the list is simply evaluated.

ENABLED-P controls whether the item is selectable or not. It should be t, nil, or a form to evaluate to decide. This form will be evaluated just before the menu is displayed, and the menu item will be selectable if that form returns non-nil.

For example, to make the rename-file command available from the File menu, use the following code:

     (add-menu-item '("File") "Rename File" 'rename-file t)

To add a submenu of file management commands using a File Management item, use the following code:

     (add-menu-item '("File" "File Management") "Copy File" 'copy-file t)
     (add-menu-item '("File" "File Management") "Delete File" 'delete-file t)
     (add-menu-item '("File" "File Management") "Rename File" 'rename-file t)

The optional BEFORE argument is the name of a menu item before which the new item should be added.  If the item is already present, it is not moved.

To remove a specified menu item from the menu hierarchy, use delete-menu-item.

PATH is a list of strings that identify the position of the menu item in the menu hierarchy.  ("File" "Save") means the menu item called Save under the top level File menu.  ("Menu" "Foo" "Item") means the menu item called Item under the Foo submenu of Menu.

To disable a menu item, use disable-menu-item.  The disabled menu item is grayed and can no longer be selected.  To make the item selectable again, use enable-menu-item. disable-menu-item and enable-menu-item both have the argument PATH.

To change the string of the specified menu item, use relabel-menu-item. This function also takes the argument PATH.

NEW-NAME is the string to which the menu item will be changed.