16. menu

<menu
  label = non empty token
  name = NMTOKEN
  insert = non empty token
>
  Content: [ menu | separator | item | insert ]*
</menu>

<separator />

<insert />

<item
  label = non empty token
  icon = anyURI
  command = NMTOKEN (optionally preceded by a command namespace)
  parameter = string
>
  Content: [ accelerator ]?
</item>

<accelerator
  code = key code
  modifiers = possibly empty list of (ctrl|shift|alt|meta|altGr|mod)
/>

Specifies the label and content of the XML (placeholder) menu.

Note that the mnemonic of a menu or of a menu item is specified by adding an underscore ('_') before the character used as a mnemonic. Currently, only a-zA-Z0-1 characters can be used as mnemonics. Moreover, Java™ does not make a difference between an uppercase letter and a lowercase letter.

Example:

  <menu label="_XHTML">
    ...
    <menu label="C_ell">
      <item label="_Increment Column Span"
            icon="../common/icons2/incrColumnSpan.gif"
            command="xhtml.tableEdit" parameter="incrColumnSpan"/>
      <item label="_Decrement Column Span"
            icon="../common/icons2/decrColumnSpan.gif"
            command="xhtml.tableEdit" parameter="decrColumnSpan"/>
      ...
    </menu>
    <separator />
    <item label="_Go to Opposite Link End"
          command="followLink" parameter="swap"/>
    ...
    <separator />
    <item label="Pre_view" icon="../common/icons/Refresh16.gif"
          command="xhtml.preview">
      <accelerator code="F5" />
    </item>
  </menu>

There are two ways to extend previously defined menu:

  1. By using the insert child element.

  2. By using the insert attribute.

Both methods cannot be used in the same menu element. Method 1 is faster and simpler to use than method 2.

  1. Using the insert child element. Example:

    <include location="../common/common.incl" />
    <!-- ==============================================
    Let's suppose this menu is defined in common.incl:
    
    <cfg:menu label="Insert">
      <cfg:item label="Insert..." command="insert" parameter="into" />
    </cfg:menu>
    =============================================== -->
    
    <cfg:menu label="Insert">
      <cfg:item label="Insert Before..." command="insert"
         parameter="before[implicitElement]" />
      <cfg:insert />
      <cfg:item label="Insert After..." command="insert" 
        parameter="after[implicitElement]" />
    </cfg:menu>

    The insert child element is a directive which means: insert all the items of the previous definition of the same menu here.

    About the label attribute

    When you extend a previously defined menu, the label attribute specifies the title of the extended menu. This means that you can change the title of a menu at the same time you extend it.

    If you don't want to do that, which is often the case, simply specify label="-" in the menu extension. This is simpler and safer than repeating the original label of the menu. In such case, the above example becomes:

    <cfg:menu label="-">
      <cfg:item label="Insert Before..." command="insert"
         parameter="before[implicitElement]" />
      <cfg:insert />
      <cfg:item label="Insert After..." command="insert" 
        parameter="after[implicitElement]" />
    </cfg:menu>
  2. Using the insert attribute. Example:

    <include location="../common/common.incl" />
    <!-- ==============================================
    Let's suppose this menu is defined in common.incl:
    
    <cfg:menu label="Insert">
      <cfg:item label="Insert Before..." command="insert"
         parameter="before[implicitElement]" />
      <cfg:item label="Insert After..." command="insert" 
        parameter="after[implicitElement]" />
    </cfg:menu>
    =============================================== -->
    
    <cfg:menu label="Insert" insert="Insert After...">
      <cfg:item label="Insert..." command="insert" parameter="into" />
    </cfg:menu>

    The insert attribute is a directive which means: insert all the items found in this menu into the previous definition of the same menu, and this, at specified position.

    The value of the insert attribute is the label of an item found in the previous definition of the same menu. This label may be preceded by modifier "before " or by modifier "after ". Modifier "before " is the implicit one.

    In the above example, extending menu "Insert" could have also been achieved by using:

    <cfg:menu label="Insert" insert="before Insert After...">
      <cfg:item label="Insert..." command="insert" parameter="into" />
    </cfg:menu>

    or by using:

    <cfg:menu label="Insert" insert="after Insert Before...">
      <cfg:item label="Insert..." command="insert" parameter="into" />
    </cfg:menu>

    Alternatively, the value of the insert attribute may be ##first or ##last. Value ##first specifies the first item of the previous definition of the same menu. Value ##last specifies the last item of the previous definition of the same menu. Example:

    <cfg:menu label="Insert" insert="before ##last">
      <cfg:item label="Insert..." command="insert" parameter="into" />
    </cfg:menu>

    The value of the insert attribute may start with ifDefined(system_property_name). In such case, the previously defined menu is extended if and only if a system property called system_property_name has been defined (no matter its value). Example:

    <menu label="_XHTML" 
          insert="ifDefined(HAS_CONVERT_SUBMENU)after ##last">
      <separator />
      <menu label="_Convert Document">
      ...
      </menu>
    </menu>