5. menu

5. menu
	Chapter 4. Reference

<menu
  name = NMTOKEN
  label = non empty token
  icon = anyURI
  helpId = NMTOKEN
  insert = non empty token
  replace = non empty token
  replaceEnd = non empty token
>
  Content: [ insert | action | menu | separator | menuItems ]*
</menu>

<insert />

<action 
  name = NMTOKEN
/>

<menu 
  name = NMTOKEN
/>

<separator />

<menuItems 
  name = NMTOKEN
/>

Specifies a menu. A menu contains references to action, menu and menuItems elements declared elsewhere in the GUI specification.

Unless the referenced menuItems element has a count attribute, the reference to the menuItems element, if any, must be the last reference contained in the menu element.

The insert child element, the insert, replace, replaceEnd attributes may be used to customize to the previous definition of a menu. More information in Customizing a composite part without redefining it from scratch.

Attributes:

name

Required. Unique name identifying the menu in this GUI specification.

label

Required unless this declaration is an extension of the previous one (that is, <insert/> is used). Label of the menu.

icon

Icon used for the menu entry when this menu is added to a parent menu. Also used for the tool bar button when this menu is added to a toolBar.

This URI may be resolved using XML catalogs.

helpId

Online help ID of the menu.

Example, an ordinary menu:

<menu name="helpMenu" label="_Help"
      helpId="helpMenu">
  <action name="helpAction" />
  <action name="contextualHelpAction" />
  <separator />
  <action name="showContentModelAction" />
  <separator />
  <action name="listBindingsAction" />
  <action name="listPluginsAction" />
  <separator />
  <action name="aboutAction" />
</menu>

Example, a menu where all items are dynamic:

<menu name="configSpecificMenu" label="XML"
      helpId="configSpecificMenu">
  <menuItems name="configSpecificMenuItems" />
</menu>

Example, a menu which has two static items followed by dynamic items:

<menu name="viewMenu" label="_View"
      helpId="viewMenu">
  <action name="redrawAction" />
  <separator />
  <action name="addViewsAction" />
  <!-- Automatic separator here -->
  <menuItems name="setStyleSheetMenuItems" />
</menu>

The insert child element, the insert, replace, replaceEnd attributes may be used to customize to the previous definition of composite parts such as menu, menuBar, statusBar, toolBar, preferencesSheets, or layout groups such as topToolBars, bottomToolBars, leftToolBars, rightToolBars, leftPanes, rightPanes, hidden.

Extending a composite part

There are two ways to extend a composite part :

by using an insert child element;
by using an insert attribute.

Both methods cannot be used in the same element. The insert attribute is silently ignored when an insert child element has been specified.

Using the insert child element. Example:

<!-- ====================================================
Let's suppose this tool bar is initially defined as follows:

<toolBar name="toolBar1">
  <action name="openAction" />
</toolBar>
===================================================== -->

<toolBar name="toolBar1">
  <action name="newAction" />
  <insert />
  <action name="saveAction" />
</toolBar>

The insert child element is a directive which means: insert all the buttons of the previous definition of the same tool bar here.

Using the insert attribute. Example:
```


<toolBar name="toolBar1" insert="saveAction">
  <action name="openAction" />
</toolBar>
```
The insert attribute is a directive which means: insert all the buttons found in this tool bar into the previous definition of the same tool bar, and this, at specified position.
The value of the insert attribute is the name of a part found in the previous definition of the same composite part. In the case of the above example, saveAction is the value of the name attribute of an action contained in the previous definition of the tool bar.
This name may be preceded by modifier "before " or by modifier "after ". Modifier "before " is the implicit one.
In the above example, extending the tool bar could have also been achieved by using:
```
<toolBar name="toolBar1" insert="before saveAction">
  <action name="openAction" />
</toolBar>
```
or by using:
```
<toolBar name="toolBar1" insert="after newAction">
  <action name="openAction" />
</toolBar>
```
Instead of using the name of a part, it is also possible to use ##first or ##last. ##first specifies the first part referenced in the previous definition of the part container. ##last specifies the last part referenced in the previous definition of the part container.
Example:
```
<toolBar name="toolBar1" insert="after ##last">
  <action name="printAction" />
</toolBar>
```

Removing or replacing some parts inside a composite part

Removing or replacing some parts inside a composite part is done by the means of the replace attribute and, optionally, also the replaceEnd attribute. The replaceEnd attribute is needed to specify a range of sibling parts.

Note that the replace and replaceEnd attributes are silently ignored when an insert child element or an insert attribute has been specified.

Remove parts example:

<!-- ====================================================
Let's suppose this tool bar is initially defined as follows:

<toolBar name="toolBar1">
  <action name="newAction" />
  <action name="saveAction" />
</toolBar>
===================================================== -->

<toolBar name="toolBar1" replace="newAction" />

results in the following toolBar:

<toolBar name="toolBar1">
  <action name="saveAction" />
</toolBar>

This could have been specified as follows:

<toolBar name="toolBar1" replace="before saveAction" />

or as follows:

<toolBar name="toolBar1" replace="##first" />

In fact, the replace and replaceEnd attributes support exactly the same values as the insert attribute. See above. However, there is a pitfall. While attributes insert="before saveAction" and insert="saveAction" are equivalent, attributes replace="before saveAction" and replace="saveAction" are not equivalent.

Replace parts example:

<!-- ====================================================
Let's suppose this tool bar is initially defined as follows:

<toolBar name="toolBar1">
  <action name="newAction" />
  <action name="saveAction" />
  <action name="saveAsAction" />
</toolBar>
===================================================== -->

<toolBar name="toolBar1"
         replace="newAction" replaceEnd="saveAction">
  <action name="openAction" />
</toolBar>

results in the following toolBar:

<toolBar name="toolBar1">
  <action name="openAction" />
  <action name="saveAsAction" />
</toolBar>


4.8. The `insert` descendant element of `layout`		6. menuBar