menu_add [ -before] destinationlabel [ -separator | [ -cmd {cmds}] [ -keykeyname | -keytext "text"] [ -toggle 'togexpr'] [ -radio] [ -active "actexpr"]]

This command adds an item to an existing menu where label is the name for the new menu item and destination is a menu path indicating the existing item that the new item should follow.

If destination or label contains spaces or special characters, it must be enclosed in quotes. Please note that underscores, spaces, and periods are not allowed for menu bar labels.

If -before is specified, the new item will appear before the destination item rather than after it.

label specifies the label displayed for the item. If label contains any variable references, for example, "Modify $tagname", the variable's value is substituted into the label string each time the menu containing the item is posted. Note that the label string label must be enclosed in single quotes to prevent the command parser from expanding the variable reference when the command is parsed.

A mnemonic access key may be specified for the menu item by preceding the desired letter in label with &. To use a literal & in label, use two ampersands, for example, "Save && Exit".

-cmd{ cmds } indicates the commands to be executed when the new menu item is selected. If an item is mapped to more than one command, the commands must be enclosed in curly braces and separated by semicolons.

-keykeyname specifies the accelerator key (used for keyboard shortcuts) displayed in the right-hand field of the menu item. To take effect, the accelerator key must be mapped to the command function using the map command; see the map command for a list of valid values for keyname. The keyname is abbreviated to reduce the size of the menu. For example, -key control+Z is displayed as Ctrl+Z.

If no commands are assigned to the menu item with the -cmd option, then the menu item executes whatever is mapped to keyname.

-keytext “text” adds the accelerator key text displayed in the right-hand field of the menu item. If “text” is none, then no accelerator is shown. The -keytext option is similar to the -key option except that the accelerator text is specified directly by text instead of by a keyname. Since the -keytext option requires more memory, the -key option is preferred. However, -keytext is useful for turning off accelerator text (using none) and also for menu items mapped to multiple keys, for example, using prefix keymaps, since -key only allows a single key to be specified.

-toggle 'togexpr' specifies that the menu item is a toggle item (that is, it displays a check mark if set). The string argument togexpr specifies an ACL expression to be evaluated when the menu is posted. If it evaluates to non-zero the menu item will be displayed with a check mark, otherwise, the check mark will be removed.

togexpr can also be surrounded with double quotes.

-radio specifies that the toggle menu item is part of a radio group, that is, it is one a set of mutually exclusive items. All adjacent toggle-type items with the -radio option are considered part of the group. Depending on the window system, a different icon is displayed for radio group items.

-active "actexpr" specifies an expression to be evaluated when the menu is posted that determines whether the menu item is enabled or disabled (grayed-out). If the expression evaluates to non-zero the menu item is selectable, otherwise, the menu item is grayed-out.

-separator specifies that this menu item is a separator line. In this case label should be a null string and no additional options are allowed.

To save menu additions across sessions, you must either write out your changes with the menu_save command (this creates a menu.cf file in the document directory which can be loaded automatically when the document is opened), or you can put your mappings in the docname.acl file for the document.

mad is a synonym for menu_add.

Examples