29. toolBar
Prev | Chapter 7. Configuration elements | Next

## 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>

Prev | Up | Next
28. template | Home | 29.1. Custom controls