16.5.5 Adding new menus

These commands can be associated with menus, tool bar buttons and keys. All of these use similar syntax.

Binding a menu to an action is done through the <menu> and <submenu> tags.

The <menu> tag takes the following attributes:

action (mandatory)

This attribute specifies which action to execute when the menu is selected by the user. If no action by this name was defined, no new menu is added. The action name can start with a '/', in which case it represents the absolute path to a menu to execute instead.

This attribute can be omitted only when no title is specified for the menu to make it a separator (see below).

If a filter is associated with the action through the <filter> tag, then the menu will be greyed out when the filter doesn't match. As a result, users will not be able to click on it.

before (optional)

It specifies the name of another menu item before which the new menu should be inserted. The reference menu must have been created before, otherwise the new menu is inserted at the end. This attribute can be used to control where precisely the new menu should be made visible.

after (optional)

This attribute is similar to before, but has a lower priority. If it is specified, and there is no before attribute, it specifies a reference menu after which the new menu should be inserted.

It should also have one XML child called <title> which specifies the label of the menu. This is really a path to a menu, and thus you can define submenus by specifying something like "/Parent1/Parent2/Menu" in the title to automatically create the parent menus if they don't exist yet.

You can define the accelerator keys for your menus, using underscores in the titles. Thus, if you want an accelerator on the first letter in a menu named File, set its title as _File.

The tag <submenu> accepts the following attributes:

before (optional)

See description above, same as for <menu>

after (optional)

See description above, same as for <menu>

It accepts several children, among <title> (which must be specified at most once), <submenu> (for nested menus), and <menu>.

Since <submenu> doesn't accept the action attribute, you should use <menu> for clickable items that should result in an action, and <submenu> if you want to define several menus with the same path.

You can specify which menu the new item is added to in one of two ways:

• Specify a path in the title attribute of <menu>
• Put the <menu> as a child of a <submenu> node This requires slightly more typing, but it allows you to specify the exact location, at each level, of the parent menu (before or after an existing menu).

For example, this adds an item named mymenu to the standard Edit menu.

     <?xml version="1.0" ?>
     <test>
       <submenu>
         <title>Edit</title>
         <menu action="current file uses">
            <title>mymenu</title>
         </menu>
       </submenu>
     </test>

The following has exactly the same effect:

     <?xml version="1.0" ?>
     <test>
       <menu action="current file uses">
         <title>Edit/mymenu</title>
       </menu>
     </test>

The following adds a new item "stats" to the "unit testing" submenu in "my_tools".

     <?xml version="1.0" ?>
     <test>
       <menu action="execute my stats">
          <title>/My_Tools/unit testing/stats</title>
       </menu>
     </test>

The previous syntax is shorter, but less flexible than the following, where we also force the My_Tools menu, if it doesn't exist yet, to appear after the File menu. This is not doable by using only <menu> tags. We also insert several items in that new menu

     <?xml version="1.0" ?>
     <test>
       <submenu after="File">
         <title>My_Tools</title>
         <menu action="execute my stats">
            <title>unit testing/stats</title>
         </menu>
         <menu action="execute my stats2">
            <title>unit testing/stats2</title>
         </menu>
       </submenu>
     </test>

Adding an item with an empty title or no title at all inserts a menu separator. For instance, the following example will insert a separator followed by a File/Custom menu:

     <?xml version="1.0" ?>
     <menus>
       <action name="execute my stats" />
       <submenu>
          <title>File</title>
          <menu><title/></menu>
          <menu action="execute my stats">
              <title>Custom</title>
          </menu>
       </submenu>
     </menus>