27.4 Modifying Menus

The following functions are provided to modify the menubar of one of its submenus. Note that these functions modify the menu in-place, rather than copying it and making a new menu.

Some of these functions take a menu path, which is a list of strings identifying the menu to be modified. For example, ("File") names the top-level “File” menu. ("File" "Foo") names a hypothetical submenu of “File”.

Others take a menu item path, which is similar to a menu path but also specifies a particular item to be modified. For example, ("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”.

Function: add-submenu menu-path submenu &optional before in-menu

This function adds a menu to the menubar or one of its submenus. If the named menu exists already, it is changed.

menu-path identifies the menu under which the new menu should be inserted. If menu-path is nil, then the menu will be added to the menubar itself.

submenu is the new menu to add (see Menu Format).

before, if provided, is the name of a menu before which this menu should be added, if this menu is not on its parent already. If the menu is already present, it will not be moved.

If in-menu is present use that instead of current-menubar as the menu to change.

Function: add-menu-button menu-path menu-leaf &optional before in-menu

This function adds a menu item to some menu, creating the menu first if necessary. If the named item exists already, it is changed.

menu-path identifies the menu under which the new menu item should be inserted.

menu-leaf is a menubar leaf node (see Menu Format).

before, if provided, is the name of a menu before which this item should be added, if this item is not on the menu already. If the item is already present, it will not be moved.

If in-menu is present use that instead of current-menubar as the menu to change.

Function: delete-menu-item menu-item-path &optional from-menu

This function removes the menu item specified by menu-item-path from the menu hierarchy.

If from-menu is present use that instead of current-menubar as the menu to change.

Function: enable-menu-item menu-item-path

This function makes the menu item specified by menu-item-path be selectable.

Function: disable-menu-item menu-item-path

This function makes the menu item specified by menu-item-path be unselectable.

Function: relabel-menu-item menu-item-path new-name

This function changes the string of the menu item specified by menu-item-path. new-name is the string that the menu item will be printed as from now on.

The following function can be used to search for a particular item in a menubar specification, given a path to the item.

Function: find-menu-item menubar menu-item-path &optional parent

This function searches menubar for the item given by menu-item-path starting from parent (nil means start at the top of menubar). This function returns (item . parent), where parent is the immediate parent of the item found (a menu description), and item is either a vector, list, or string, depending on the nature of the menu item.

This function signals an error if the item is not found.

The following deprecated functions are also documented, so that existing code can be understood. You should not use these functions in new code.

Function: add-menu menu-path menu-name menu-items &optional before

This function adds a menu to the menubar or one of its submenus. If the named menu exists already, it is changed. This is obsolete; use add-submenu instead.

menu-path identifies the menu under which the new menu should be inserted. If menu-path is nil, then the menu will be added to the menubar itself.

menu-name is the string naming the menu to be added; menu-items is a list of menu items, strings, and submenus. These two arguments are the same as the first and following elements of a menu description (see Menu Format).

before, if provided, is the name of a menu before which this menu should be added, if this menu is not on its parent already. If the menu is already present, it will not be moved.

Function: add-menu-item menu-path item-name function enabled-p &optional before

This function adds a menu item to some menu, creating the menu first if necessary. If the named item exists already, it is changed. This is obsolete; use add-menu-button instead.

menu-path identifies the menu under which the new menu item should be inserted. item-name, function, and enabled-p are the first, second, and third elements of a menu item vector (see Menu Format).

before, if provided, is the name of a menu item before which this item should be added, if this item is not on the menu already. If the item is already present, it will not be moved.