31.3. Adding configuration specific tool bar buttons to the XXE GUI

31.3.1. How does it work?

Configuration specific tool bar buttons defined in a toolBar configuration element may be added either to a ribbon or to a tool bar of the XXE GUI. A ribbon is a kind of “structured” tool bar, generally having more than one row of buttons.

Figure 6.1. Ribbon of the XXE desktop application when no document is being edited
Ribbon of the XXE desktop application when no document is being edited
Figure 6.2. Ribbon of the XXE desktop application when a DITA map is being edited
Ribbon of the XXE desktop application when a DITA map is being edited

This feature is implemented by the means of GUI specification elements. Excerpts from DesktopApp.xxe_gui, the specification of the XXE desktop application:

<ribbonItems name="configSpecificRibbonItems">
  <class>com.xmlmind.xmleditapp.desktop.part.ConfigSpecificRibbonItems</class>
</ribbonItems>

<ribbon rows="2" name="ribbon" helpId="ribbon">
  <div name="file" label="File">
    <action name="newAction" />
    <action name="saveAction" />
    ...
  </div>
  ...
  <ribbonItems name="configSpecificRibbonItems" />
</ribbon>

GUI specification element ribbon in XMLmind XML Editor - Customizing the User Interface defines the ribbon of the XXE desktop application and ribbonItems in XMLmind XML Editor - Customizing the User Interface copies the buttons found in the toolBar configuration element to this ribbon.

Excerpts from SingleDocApp.xxe_gui, an alternate, simpler, GUI specification:

<toolBarItems name="configSpecificToolBarItems">
  <class>com.xmlmind.xmleditapp.desktop.part.ConfigSpecificToolBarItems</class>
</toolBarItems>

<toolBar name="configSpecificToolBar" helpId="configSpecificMenu">
  <action name="configSpecificAction" />
  <toolBarItems name="configSpecificToolBarItems" />
</toolBar>

GUI specification element toolBar in XMLmind XML Editor - Customizing the User Interface defines a tool bar of the XXE GUI and toolBarItems in XMLmind XML Editor - Customizing the User Interface copies the buttons found in the toolBar configuration element to this tool bar.

31.3.2. Why specify div and span elements in a toolBar configuration element?

Configuration elements div and span are used only when the configuration specific tool bar buttons are copied to the ribbon of the XXE GUI. More precisely, aside button and separator, the following elements are used to compose the ribbon:

div

A group of buttons generally having a label. More information in XMLmind XML Editor - Customizing the User Interface.

span

A horizontal group of buttons. More information in XMLmind XML Editor - Customizing the User Interface.

[Important]

Adjacent buttons having the same value for attribute group must be wrapped into a span.

<span>
  <button group="listGroup"
    icon="xxe-config:common/icons/promoteListItem.png"
    toolTip="Decrease nesting level">
    <command name="promoteListItem"/>
  </button>
  <button group="listGroup"
    icon="xxe-config:common/icons/demoteListItem.png"
    toolTip="Increase nesting level">
    <command name="demoteListItem"/>
  </button>
</span>
spacer

Occupies the same space as a button having a 16x16 icon and no label. More information in XMLmind XML Editor - Customizing the User Interface.

separator line="false"

Inside a span, a separator having attribute line="false" is rendered as a small space. Inside a div, a separator having attribute line="false" may be used as a “column break”. More information in XMLmind XML Editor - Customizing the User Interface.

Configuration elements div and span are ignored when the configuration specific tool bar buttons are copied to a tool bar of the XXE GUI. More precisely

  • elements span and div are transparent, except that a separator is automatically added before each div;

  • element spacer and element separator having attribute line="false" are ignored.