The configuration files

A MenuBuilder uses at least one XML file (the configuration file proper) and a resource bundle for configuration. The XML file does not contain any text but instead refers to captions, tool tips and the like by means of a key. This key is then searched for in the resource bundle to retrieve the corresponding localised text. The structure of the XML file is specified in this DTD which we shall try to explain below in a less formal way.

The following is a simple example configuration file for a menu bar containing a file menu with a single 'exit' action:

<!DOCTYPE configuration
  PUBLIC "-//SWIRL//MenuBuilder configuration 1.0//EN" "configuration.dtd"
>
<configuration>
  <root id="main.menu">
    <menu i18n="menu.file.text">
      <action id="exit">
        <caption i18n="exit.text"/>
      </action>
    </menu>
  </root>
</configuration>
            

(In the examples that follow we shall leave out the DOCTYPE declaration. You should however always include it in your configuration files, as it allows the menu builder - and your IDE - to check whether it has the correct format.)

The resource bundle that goes with this configuration will contain entries like the following:

menu.file.text = File
exit.text      = Exit program
            

(and others like them for the different languages that are supported by your application).

Let us use this example to give you a preliminary overview of the various XML elements you may encounter in a typical configuration file.

• A configuration file always consists of a single <configuration> element.

• A <root> element is always the base of a menu hierarchy. A MenuBuilder can convert a root element to a menu bar, a popup menu or a tool bar for your application. Every root element has an associated identifier (main.menu) which is used in your Java code to refer to that root element. More than one root element may be defined in the same configuration file.

• A <menu> element represents a (sub)menu of the menu bar.

• An <action> element will make the menu builder add a menu item for the Exit action to menu which encloses it

• The <caption> element determines the caption of the enclosing action.

Both the <caption> and the <menu> have an i18n-attribute that refers to a key in the resource bundle. In our example the English version of the application will therefore have a menu called File which contains a menu item called Exit program.

The Java side

The configuration file alone is not sufficient for the menu builder to be able to do its work. To create the actual menu bar we need a few lines of code:

MenuBuilder menuBuilder = new MenuBuilder ();
menuBuilder.load ("/myapplication/resources/menus.xml", 
                  "myapplication.resources.menus");
menuBuilder.registerAction ("exit", new ExitAction());
JMenuBar menuBar = menuBuilder.createJMenuBar ("main.menu");
            

Some remarks:

• The load method takes the name of a configuration file and a resource bundle name as parameters. Both are searched for in the class path. We assume that the configuration file and resource bundles above are stored as files menus.xml and menus.properties in a package myapplication.resources in the class path.

• Before we can build a menu bar, we need to register all Action classes for the action objects that occur in the constituent menus. We use the action identifier to associate both objects. In this case we use an object of class ExitAction (some class that implements the Action interface) and associate it with the Exit action.

• The parameter of createJMenuBar indicates the root element which must be converted to a menu bar. Our simple example only has one root element, and it uses the identifier main.menu.