Toggles

We distinguish between two kinds of toggle buttons:

• Buttons that can be selected independently of other buttons in the application. In a menu we represent this kind of toggle button by a check box menu item, and in a tool bar by a standard toggle button. We refer to these as toggles.

• Buttons that belong to a group in which at most one button may be selected at a given time. In a menu this kind of toggle button is displayed as a radio button menu item, and in a tool bar as a standard toggle button. We call a button group of this kind a selection group, as its purpose is to select one possibility among several.

In this section we shall discuss the toggles, i.e., the first kind of toggle buttons. The next section discusses selection groups and their constituent buttons.

The look and feel of a toggle is defined in almost the same way as an action, except that we use the <toggle> element (and <toggle-ref> for references).

<toggle id="italic">
  <caption i18n="italic.text"/>
  <tooltip i18n="italic.tooltip"/>
  <icon url="classpath:/myapplication/resources/icon-italic.png"/>
</toggle>
            

When the same toggle is used twice (say once in a menu and once in a toolbar) then the resulting check box and toggle button will share their ButtonModel and hence their state will be synchronized: checking the box will automatically select the button, unchecking the box will automatically deselect the button - and conversely.

Before building a menu that contains a particular toggle, you must first register a corresponding ItemListener with the menu builder.

menuBuilder.registerAction ("italic", new ItalicItemListener());
            

(Although Swing allows check box items and toggle buttons to be built from Action objects, this is not very useful, as the action is only triggered when the toggle is selected and not when it is deselected.)

Selection groups

A selection group allows the user to select one of several alternatives by pushing the appropriate button or radio button menu item. As an example we shall build a color selection menu which allows the user to select one of 3 different colors: red, blue or green. A group like this might be configured in the following way:

<group id="select.color">
  <button id="red">
    <caption i18n="red.text"/>
    <tooltip i18n="red.tooltip"/>
    <icon url="classpath:/myapplication/resources/icon-red.png"/>
  </button>
  <button id="green">
    <caption i18n="green.text"/>
    <tooltip i18n="green.tooltip"/>
    <icon url="classpath:/myapplication/resources/icon-green.png"/>
  </button>
  <button id="blue">
    <caption i18n="blue.text"/>
    <tooltip i18n="blue.tooltip"/>
    <icon url="classpath:/myapplication/resources/icon-blue.png"/>
  </button>
</group>
            

The <group> element in the configuration file consists of one or more <button> elements describing its individual buttons (in a tool bar) or radio button items (in a menu). Each <button> element is configured in much the same way as an <action> or a <toggle>. Both groups and their constituent buttons need an identifier. Groups can be referred to elsewhere by means of an <group-ref> element, but references to individual buttons are not allowed.

The Java side of a selection group is slightly more complicated than for the other types of buttons: with each selection group you must associate an object of type GenericSelectionModel<E>. This is a generic type and the associated parameter E refers to the type of elements which can be selected by the group. In many cases this is an 'enum' type, but for our example we will take E to be the class Color: the objects which can be selected by our buttons are either Color.RED, Color.GREEN or Color.BLUE.

The menu builder requires you to register each selection group and to register the corresponding selected object for each button in that group. Luckily it is possible to do this with a single method call:

GenericSelectionModel<Color> selectionModel = new DefaultGenericSelectionModel<Color> ();
menuBuilder.registerGroup ("select.color", selectionModel,
    "red",   Color.RED,
    "green", Color.GREEN,
    "blue",  Color.BLUE );
            

The first parameter of registerGroup is the group identifier and the second is the selection model (note that Swirl provides a default implementation for the selection model which can be used here). After that parameters come in pairs: the identifier of a button within the group followed by the object of type T that is 'selected' by that button. (The method uses the 'varargs' mechanism of Java 5.0.)

You can ask a selection model for the currently selected object, and you can register a ChangeListener with a selection model to be notified of any changes. A standard selection group makes sure that always exactly one object is selected, but you can relax this to also allow that no object is selected (by setting clearable="true" in the <group> tag), in which case the selection object will be null.