May 9th, 2010

Toggle menu buttons in Flamingo 5.0

A few months ago Pedro Duque Vieira (@P_Duke) has asked me to provide support for menu buttons with checkboxes. This comes in handy when you have a number of options that affect the same visual aspect of the document / application element – such as font style, text alignment, grid borders etc. The relevant core Swing classes are JCheckBoxMenuItem and JRadioButtonMenuItem, but i have never been too happy with the way the API hierarchy of the classes themselves, their basic UI delegates and the UI delegates from core / third-party look-and-feels looked like.

Check box and radio button menu items aim to extend their “standalone” (outside of menus) counterparts. Radio button menu items represent a number of options with single selection – such as text alignment (left, right, center, fill). Check box menu items represent a number of options when multiple options can be selected – such as font style (bold, italic, underlined, strike-through). A good design calls for both types of selection controls to be visually grouped together, and be distinct from other selection groups and controls. This can be done by using extra white space, horizontal separators and group headers.

Placing selection controls in menus provides much less options for separating distinct groups – you can either place them in different menus, or use menu separators between the groups. Suppose you have two single-selection groups that need to go in the same menu. With core Swing, you will be using JRadioMenuButton controls, and you will need to use a menu separator to indicate where one group ends and another begins (unless you opt for much less attractive options such as different fonts, background or foreground colors). If you have a multi-selection group (of JCheckBoxMenuItems), you will also need to “delimit” it by menu separators to make it easier for the user to see that all the menu items belong to the same functional group. Finally, if you have a single JCheckBoxMenuItem, it may or may not require menu separators before and after it – but in most cases the design must make it apparent that this selection control is the only one in its group.

Given the need for extra separation of selection controls placed in menus, i took a few weeks to think about whether the distinction between the radio button and check box menu items – as far as the class hierarchy goes – is required. The only visual difference between these two control types is the check mark icon. The JRadioButtonMenuItem has a small round checkmark (just as JRadioButton), and JCheckBoxMenuItem has a small square checkmark (just as JCheckBox does). The shape of the checkmark thus conveys the selection mode in the group – single or multiple.

It is my current belief that the extra visual message conveyed by the checkmark shape is far outweighed by the resulting complexity of class hierarchy for both the controls and their UI delegates. The placement and grouping of selection controls, as well as the texts associated with the controls should be enough to make it clear whether the group is in single selection or multi selection mode. This decision is reflected in the latest Flamingo 5.0dev that provides support for placing toggle menu buttons in popup menus.

This is a sample popup menu with four toggle menu buttons that belong to the same toggle button group (single selection):

https://flamingo.dev.java.net/release-info/5.0/toggle-menu-button-single-selection.png

Note that the second option is selected and has a selection visual painted behind its icon. And here is a similar popup menu, but this time with multi-selection group (where toggle menu buttons are not associated with any toggle button group):

https://flamingo.dev.java.net/release-info/5.0/toggle-menu-button-multi-selection.png

We have two elements selected – and they show the matching visuals around the icons.

As usual, to create a popup menu when the user activates the popup area of a command button, use the JCommandButton.setPopupCallback API. The new JCommandPopupMenu.addMenuButton(JCommandToggleButtonMenu) and the new JCommandToggleButtonMenu class can be used to add a toggle button menu to the popup menu. Use CommandToggleButtonGroup to create a single selection group and add one or more of your JCommandToggleButtonMenus to it.

If you want to take the toggle menu buttons for a spin, you will need the following:

Note that the last two are required if you’re running your application under one of Substance skins.