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
.