References

A configuration file really serves two different purposes:

• It defines the various strings and icons that must be used for each action, toggle or button and it describes the composition of selection groups.

• It groups these items into menus and submenus.

Both of these tasks are largely independent, and if you prefer you can also separate them in the configuration file. You can define the look and feel of all actions, toggles and buttons in a first part and then refer to these definitions in a second part while describing the hierarchical structure of your menus or the contents of your tool bars. An alternative to our example configuration file would be the following:

<configuration>
  <action id="exit">
    <caption i18n="exit.text"/>
  </action>
                
  <root id="main.menu">
    <menu i18n="menu.file.text">
      <action-ref id="exit"/>
    </menu>
  </root>
</configuration>
            

(Do not forget to include the DOCTYPE declaration at the top.)

The <action-ref> refers to an action with the same identifier, which was already declared before. It can also be useful when we want to include the same action in different root elements. If in our example we would like a tool bar that contains a button with the same functionality as the exit menu item, we could extend the configuration as follows:

<configuration>
   ...
   <root id="toolbar">
     <action-ref id="exit"/>
   </root>
</configuration>
            

(This works with both versions of the configuration file given so far.)

Accelerators, mnemonics, tool tips and icons

In these simple examples we have only specified the caption text of the exit button. A more realistic example would include various other properties:

<action id="exit">
  <caption i18n="exit.text"/>
  <tooltip i18n="exit.tooltip"/>
  <menu-icon url="file:/tmp/icons/icon-M.png"/>
  <menu-icon-disabled url="file:/tmp/icons/icon-MD.png"/>
  <icon url="file:/tmp/icons/icon-B.png"/>
  <icon-disabled url="file:/tmp/icons/icon-BD.png"/>       
</action>
            

(None of these elements is required, but they must always occur in the order given.)

The <menu-icon> and <menu-icon-disabled> elements (when present) specify the icons to be used when the action is rendered as part of a menu. The <icon> and <icon-disabled> elements are used when the action is rendered as a button in a tool bar. Tool bar buttons are rendered without caption (with an icon only) but can have an (internationalized) tool tip.

Icons are referred to by URL. In the example a file: URL is used, which is impractical in most cases because it requires you to deploy your application in a fixed location on the hard disk. As an alternative SWIRL provides a classpath: URL handler (see Handler) for referring to icons in the class path:

<action id="exit">
  <caption i18n="exit.text"/>
  <tooltip i18n="exit.tooltip"/>
  <menu-icon url="classpath:/myapplication/resources/icon-M.png"/>
  <menu-icon-disabled url="classpath:/myapplication/resources/icon-MD.png"/>
  <icon url="classpath:/myapplication/resources/icon-B.png"/>
  <icon-disabled url="classpath:/myapplication/resources/icon-BD.png"/>       
</action>
            

This allows us to store the icons in the same place as the configuration files.

Mnemonics and accelerator keys are not configured in the XML configuration file, but in the resource bundle, as part of the caption text. (They also need to be localized.) For this we use the 'description string' format of the SWIRL Description class:

menu.file.text = &File
exit.text      = E&xit program [alt F4]
            

As you can see, mnemonics for menus are specified in the same way.