29. toolBar

<toolBar
  name = NMTOKEN
  insert = non empty token
>
  Content: [ separator | button | insert ]*
</toolBar>

<separator />

<insert />

<button
  icon = anyURI
  toolTip = non empty token
>
  Content: [ class [ property ]* ]? command | menu
</button>

<class>
  Content: Java class name
</class>

<property
  name = NMTOKEN matching [_a-zA-Z][_a-zA-Z0-9]*
  type = (boolean|byte|char|short|int|long|float|double|
          String|URL)
  value = string
/>

<command
  name = NMTOKEN (optionally preceded by a command namespace)
  parameter = string
/>

<menu>
  Content: [ item | separator ]+
</menu>

<item
  label = non empty token
  icon = anyURI
  command = NMTOKEN (optionally preceded by a command namespace)
  parameter = string
/>

Add buttons specified in this element to the tool bar.

Example:

<toolBar>
  <button toolTip="Convert to emphasis" 
          icon="../icons2/emphasis_menu.gif">
    <menu>
      <item label="emphasis" command="convert"
            parameter="[implicitElement] emphasis" />
      <separator />
      <item label="literal" command="convert"
            parameter="[implicitElement] literal" />
    </menu>
  </button>

   <button toolTip="Convert to plain text" icon="../icons2/plain.gif">
    <command name="convert" parameter="[implicitElement] #text" />
  </button>

  <separator />

  <button toolTip="Add para" icon="../icons2/para.gif">
    <command name="add" parameter="after[implicitElement] para" />
  </button>
</toolBar>

Extending a previously defined tool bar

There are two ways to extend previously defined tool bar:

  1. By using the insert child element.

  2. By using the insert attribute.

Both methods cannot be used in the same toolBar 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 tool bar is defined in common.incl:
    
    <toolBar>
      <button toolTip="Convert to b" icon="../common/icons2/b.gif">
        <command name="convert" parameter="[implicitElement] b" />
      </button>
    </toolBar>
    ===================================================== -->
    
    <toolBar>
      <button toolTip="Convert to i" icon="../common/icons2/i.gif">
        <command name="convert" parameter="[implicitElement] i" />
      </button>
      <insert />
      <button toolTip="Convert to tt" icon="../common/icons2/tt.gif">
        <command name="convert" parameter="[implicitElement] tt" />
      </button>
    </toolBar>

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

  2. Using the insert attribute. Example:

    <include location="../common/common.incl" />
    <!-- ====================================================
    Let's suppose this tool bar is defined in common.incl:
    
    <toolBar>
      <button toolTip="Convert to i" icon="../common/icons2/i.gif">
        <command name="convert" parameter="[implicitElement] i" />
      </button>
      <button toolTip="Convert to tt" icon="../common/icons2/tt.gif">
        <command name="convert" parameter="[implicitElement] tt" />
      </button>
    </toolBar>
    ===================================================== -->
    
    <toolBar insert="Convert to tt">
      <button toolTip="Convert to b" icon="../common/icons2/b.gif">
        <command name="convert" parameter="[implicitElement] b" />
      </button>
    </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 toolTip of a button found in the previous definition of the same tool bar. If desired position is a button having no toolTip attribute, it is possible to use the basename of its icon (e.g. "para.gif" for icon="../icons2/para.gif").

    This tool tip (or icon basename) 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 insert="before Convert to tt">
      <button toolTip="Convert to b" icon="../common/icons2/b.gif">
        <command name="convert" parameter="[implicitElement] b" />
      </button>
    </toolBar>

    or by using:

    <toolBar insert="after Convert to i">
      <button toolTip="Convert to b" icon="../common/icons2/b.gif">
        <command name="convert" parameter="[implicitElement] b" />
      </button>
    </toolBar>

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

    <toolBar insert="before ##last">
      <button toolTip="Convert to b" icon="../common/icons2/b.gif">
        <command name="convert" parameter="[implicitElement] b" />
      </button>
    </toolBar>

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

    <toolBar insert="ifDefined(XXE.Feature.Spreadsheet) before ##last">
      ...
    </toolBar>