Toggle menu buttons were added to the Flamingo component library a few days ago, and their functionality has been enhanced following feedback from Pedro. In addition to tweaking the visual layout of the area between the icon and the text, the two improvements are:

  • Showing a checkmark when the selected toggle menu button does not have an icon
  • Popup menus that are not automatically dismissed when a child menu button is clicked

The second entry enhances the usability of popup menus that have multiple toggle menu buttons. Here is a screenshot to demonstrate such a scenario (note checkmarks on the selected buttons):

https://flamingo.dev.java.net/release-info/5.0/popup-menu-no-auto-dismiss.png

If this menu controls a set of boolean options / preferences, dismissing the menu after a single button has been clicked (selected toggled) is a bad user experience if the user wanted to change multiple settings. To prevent the auto-dismissal, call the new JCommandPopupMenu.setToDismissOnChildClick(false) API. This way the menu will stay up until the user clicks anywhere outside it or hits the Escape key.

If you want to take the new 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.

I was recently asked how to create multi-level menus with Flamingo command menu buttons. There is nothing preventing you from creating arbitrary hierarchies of menus – and you can do this even in the stable 4.2 release. The latest 5.0dev drop of the library brings small improvements for mixing menu buttons with and without icons, and here is a small code sample to create a two-level menu:

public class MultiLevelMenu extends JFrame {

   public MultiLevelMenu() {
      super("Multi level menu");

      JCommandButton main = new JCommandButton("click me");
      main.setCommandButtonKind(CommandButtonKind.POPUP_ONLY);
      main.setDisplayState(CommandButtonDisplayState.MEDIUM);
      main.setFlat(false);

      // first level menu
      main.setPopupCallback(new PopupPanelCallback() {
         @Override
         public JPopupPanel getPopupPanel(JCommandButton commandButton) {
            JCommandPopupMenu result = new JCommandPopupMenu();

            result.addMenuButton(new JCommandMenuButton("Copy",
                  new edit_copy()));
            result.addMenuButton(new JCommandMenuButton("Cut",
                  new edit_cut()));
            result.addMenuButton(new JCommandMenuButton("Paste",
                  new edit_paste()));

            result.addMenuSeparator();

            JCommandMenuButton second = new JCommandMenuButton("Find", null);
            second.setCommandButtonKind(CommandButtonKind.POPUP_ONLY);
            // second level
            second.setPopupCallback(new PopupPanelCallback() {
               @Override
               public JPopupPanel getPopupPanel(
                     JCommandButton commandButton) {
                  JCommandPopupMenu result = new JCommandPopupMenu();

                  result.addMenuButton(new JCommandMenuButton("Find",
                        new edit_find()));
                  result.addMenuButton(new JCommandMenuButton(
                        "Find replace", new edit_find_replace()));

                  return result;
               }
            });
            second.setPopupOrientationKind(CommandButtonPopupOrientationKind.SIDEWARD);
            result.addMenuButton(second);

            return result;
         }
      });

      this.setLayout(new FlowLayout(FlowLayout.LEADING));
      this.add(main);

      this.setSize(300, 200);
      this.setLocationRelativeTo(null);
      this.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
   }

   public static void main(String[] args) {
      SwingUtilities.invokeLater(new Runnable() {
         @Override
         public void run() {
            SubstanceLookAndFeel.setSkin(new GeminiSkin());
            JFrame.setDefaultLookAndFeelDecorated(true);

            new MultiLevelMenu().setVisible(true);
         }
      });
   }
}

And this is how it looks like:

https://flamingo.dev.java.net/release-info/5.0/multi-level-menus.png

Couple of things to note:

  • It’s the same JCommandButton.setPopupCallback API that is used to create all menu levels
  • By default the popups are displayed below the originator component (unlike the core Swing menus). Use JCommandButton.setPopupOrientationKind API passing the SIDEWARD enum value to it to recreate the core Swing behavior.

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.

While careful design will pay special attention to the number of UI controls shown at any given moment, some scenarios may result in showing more controls than can fit in the available space – either horizontally or vertically. In Swing, these situations are usually addressed by wrapping the controls in a JScrollPane, which can be configured to show the scrollbars only when they are necessary. While the scroll bars are pervasive and an easily recognized solution, sometimes they add too much visual noise and hurt the application usability.

Here is an example from the last post on the breadcrumb bar:

https://flamingo.dev.java.net/release-info/5.0/breadcrumbbar.png

Here, the application window is not wide enough to show the full selected path – and adding a horizontal scroll bar between the breadcrumb bar and the main file listing panel would be a very bad design decision. Instead, the scrolling is done using the two double-arrow buttons placed on both sides of the breadcrumb bar. Another example can be found in the post that talked about scrollable popup menus:

https://flamingo.dev.java.net/release-info/5.0/button-popup-scrollable-top.png https://flamingo.dev.java.net/release-info/5.0/button-popup-scrollable-middle.png

Additional examples can be found in the entry that talked about horizontal shrinking of the ribbon component.

Originally contributed as part of the breadcrumb bar component by Rick Jeliffe of Topologi, the scrolling functionality has since been extracted and reused across other parts of Flamingo. And now for the good news – the latest 5.0dev drop of Flamingo component library (code-named Imogene) exposes the scrollable panel as part of the published API.

The main class is org.pushingpixels.flamingo.common.JScrollablePanel. You construct it by passing the view and the ScrollType – either HORIZONTALLY or VERTICALLY (note that the scroll type cannot be changed once the component has been constructed). When needed, the component will show the scroller buttons – just the same way as JScrollPane shows the scroll bars. Moving the mouse over a scroller button (when it’s visible) starts auto-scrolling the view in the matching direction. To turn off the auto-scrolling and do the scrolling only on button press call JScrollerPanel.setScrollOnRollover(false) API.

To fully reveal a specific part of the view, call JScrollerPanel.scrollToIfNecessary(), passing the start position and span in pixels. The values are either in X or Y coordinates – depending on the scroll type of the scroller panel. You can also register a change listener on the component to be notified whenever the layout change occurs. This comes handy if you have custom drawing outside the scroller panel that depends on the position of the scroller panel view.

If you want to take the scroller panel 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. You will need the 6.1dev drop of Substance Flamingo plugin – the latest 5.0dev drop of Flamingo core is incompatible with the 6.0 release of Substance Flamingo plugin – as mentioned before.