29.1. Custom controls
Prev | 29. toolBar | Next

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

Property | Type | Default value | Description
--- | --- | --- | ---
customizationId | String | - | 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

Property | Type | Default value | Description
--- | --- | --- | ---
customizationId | String | - | 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.
toggleShowsLabel | boolean | false | If set to true, the toggle button shows a label, possibly in addition to an icon.
toggleShowsActiveTextStyle | boolean | false | 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>

Prev | Up | Next
29. toolBar | Home | 29.2. Multiple toolBars