29.1. Custom controls

Normally the above specification is used to create a normal button, either directly invoking a command or displaying a menu where each item invokes a different command. However, if the first child element of a button element is a class element, a custom control is created rather than a normal button.

Note that a custom control created this way interprets the attributes (icon, toolTip, etc) and the other child elements of its button parent (command, menu) in a specific way. These specificities must be documented separately for each type of custom control.

class

Must be a class which extends java.awt.Component and which implements the com.xmlmind.xmleditapp.kit.part.toolbar.ToolBarTool interface.

property

One or more property elements may be used to parametrize the newly created custom component. See bean properties.

DocBook 4 examples:

<button toolTip="emphasis" 
        icon="xxe-config:common/icons/italic.png">
  <class>com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleToggle</class>

  <command name="pass" parameter="emphasis" />
</button>

<button toolTip="link" 
        icon="xxe-config:common/icons/hyperText_menu.png">
  <class>com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleToggle</class>
  <property name="toggleShowsActiveTextStyle" type="boolean" value="true" />

  <menu>
    <item label="link" icon="xxe-config:common/icons/hyperText.png"
          command="pass" parameter="link[@linkend]" />
    <item label="ulink" icon="xxe-config:common/icons/link.png"
          command="pass" parameter="ulink[@url]" />
  </menu>
</button>

29.1.1. The TextStyleMenu custom control

This custom control consists in a button which displays a menu containing checkboxes. Each checkbox toggles a different text style. More information about text style toggles in About “text style” toggles in XMLmind XML Editor - Online Help.

Class name: com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleMenu

Table 7.1. TextStyleMenu properties

PropertyTypeDefault valueDescription
customizationIdString-

If set, a Customize item is added at the end of the menu. The Customize item displays a dialog box allowing to quickly customize the entries of the menu. More information in Section 14, “Dialog box allowing to edit “text style” menu items” in XMLmind XML Editor - Online Help.

The value of this property is a string which must be chosen in order to be unique within all the customizationId values of all the toolBar custom controls of all XXE configurations.


This custom control is specified similarly to a normal toolBar button element containing a menu child element (see Section 29, “toolBar”), except that:

  1. The first child of the button element must be a class element containing com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleMenu.

  2. The item/@command attributes are completely ignored. For example, you may specify pass or alert.

  3. The item/@parameter attributes must contain a specification of a text style. DocBook 4 examples: emphasis, link[@linkend], sgmltag[@class="element"]. Text style specification is documented in Section 98, “toggleTextStyle” in XMLmind XML Editor - Commands.

In the following DocBook 5 examples, the caret is found inside an email element. That's why the email checkbox is checked.

Example 7.2. Simplest TextStyleMenu custom control

<button toolTip="Miscellaneous text styles" 
        icon="xxe-config:common/icons/emphasisText_menu.png">
  <class>com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleMenu</class>

  <menu>
    <item label="quote" 
          icon="xxe-config:common/icons/quote.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}quote" />
    <item label="email" 
          icon="xxe-config:common/icons/email.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}email" />
  </menu>
</button>

Example 7.3. Customizable TextStyleMenu custom control

<button toolTip="Miscellaneous text styles" 
        icon="xxe-config:common/icons/emphasisText_menu.png">
  <class>com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleMenu</class>
  <property name="customizationId" type="String" 
            value="db5.miscTextStyles" />

  <menu>
    <item label="quote" 
          icon="xxe-config:common/icons/quote.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}quote" />
    <item label="email" 
          icon="xxe-config:common/icons/email.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}email" />
  </menu>
</button>

29.1.2. The TextStyleToggle custom control

This custom control is a variant of the TextStyleMenu custom control. This custom control combines a toggle button and a plain button having an arrow icon. The arrow button displays a menu containing checkboxes. Each checkbox toggles a different text style. More information about text style toggles in About “text style” toggles in XMLmind XML Editor - Online Help. By default, the toggle button toggles the first text style of the menu. Therefore, this toggle button may be considered to be a “quick access” to the first entry of the menu. Note that when the menu contains a single entry, the arrow button —which is not useful in this case— is automatically suppressed.

Class name: com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleToggle

Table 7.2. TextStyleToggle properties

PropertyTypeDefault valueDescription
customizationIdString-

If set, an arrow button displaying a menu is always created and a Customize item is added at the end of the menu. The Customize item displays a dialog box allowing to quickly customize the entries of the menu. More information in Section 14, “Dialog box allowing to edit “text style” menu items” in XMLmind XML Editor - Online Help.

The value of this property is a string which must be chosen in order to be unique within all the customizationId values of all the toolBar custom controls of all XXE configurations.

toggleShowsLabelbooleanfalse

If set to true, the toggle button shows a label, possibly in addition to an icon.

toggleShowsActiveTextStylebooleanfalse

By default, the toggle button is simply a “quick access” to the first entry of the menu. When this property is set to true, the toggle button becomes a quick access to the entry of the menu which is checked. If there is no checked checkbox in the menu, then the toggle button is a quick access to the first entry of the menu.

Important

Do not set this property to true unless each menu item has a different icon and/or you also set toggleShowsLabel to true.

If you don't follow this recommendation, the user of XXE will probably not understand the behavior of TextStyleToggle.


This custom control is specified similarly to a normal toolBar button element containing a command or a menu child element (see Section 29, “toolBar”), except that:

  1. The first child of the button element must be a class element containing com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleToggle.

  2. The command/@name and item/@command attributes are completely ignored. For example, you may specify pass or alert.

  3. The command/@parameter and item/@parameter attributes must contain a specification of a text style. DocBook 4 examples: emphasis, link[@linkend], sgmltag[@class="element"]. Text style specification is documented in Section 98, “toggleTextStyle” in XMLmind XML Editor - Commands.

In the following DocBook 5 examples, the caret is found inside an email element. That's why the email checkbox is checked and, for some examples, the toggle button is selected and shows an envelope icon.

Example 7.4. Simplest TextStyleToggle custom control

<button toolTip="Miscellaneous text styles" 
        icon="xxe-config:common/icons/emphasisText_menu.png">
  <class>com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleToggle</class>

  <menu>
    <item label="quote" 
          icon="xxe-config:common/icons/quote.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}quote" />
    <item label="email" 
          icon="xxe-config:common/icons/email.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}email" />
  </menu>
</button>

Example 7.5. “Active” TextStyleToggle custom control

<button toolTip="Miscellaneous text styles" 
        icon="xxe-config:common/icons/emphasisText_menu.png">
  <class>com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleToggle</class>
  <property name="toggleShowsActiveTextStyle" type="boolean" value="true" />

  <menu>
    <item label="quote" 
          icon="xxe-config:common/icons/quote.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}quote" />
    <item label="email" 
          icon="xxe-config:common/icons/email.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}email" />
  </menu>
</button>

Example 7.6. “Active” TextStyleToggle custom control showing a label in addition to an icon

<button toolTip="Miscellaneous text styles" 
        icon="xxe-config:common/icons/emphasisText_menu.png">
  <class>com.xmlmind.xmleditapp.kit.part.toolbar.TextStyleToggle</class>
  <property name="toggleShowsActiveTextStyle" type="boolean" value="true" />
  <property name="toggleShowsLabel" type="boolean" value="true" />

  <menu>
    <item label="quote" 
          icon="xxe-config:common/icons/quote.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}quote" />
    <item label="email" 
          icon="xxe-config:common/icons/email.png"
          command="pass"
          parameter="{http://docbook.org/ns/docbook}email" />
  </menu>
</button>