Prevent popup menu dismissal

If you’ve ever written your own pop-down style button, then you’ve most certainly run into the following nasty little issue.

A pop-down button should show a menu below its associated button when pressed. When pressed a second time, the menu should be dismissed. You might initially think this is a straight forward issue, but I assure you, it’s not!

You’re inital pass would probably include a MouseListener on a JToggleButton so that you could show the menu if the button was about to be selected (usually, pop-down menus are shown when the associated button is pressed, rather than fully selected). Your listener might look like this:

    private MouseListener createButtonMouseListener() {
        return new MouseAdapter() {
            public void mousePressed(MouseEvent e) {
                // if the popup menu is currently showing, then hide it.
                // else if the popup menu is not showing, then show it.
                if (fPopupMenu.isShowing()) {
                    hidePopupMenu();
                } else {
                    showPopupMenu();
                }
            }
        };
    }

This actually works perfectly – when you press the button, the menu shows; when you press the button again, the menu hides. After thinking about the problem a little more, you might realize the user would like to dismiss the popup menu with an Escape key press, or a click away from the menu. Either of these events should change the button state back to unpressed.

OK – sounds straight forward enough. We need to add a PopupMenuListener to the JPopupMenu so that we can that we can set the button’s selected state to false when the popup menu is canceled. So you’d create a listener that looks something like this:

    private PopupMenuListener createPopupMenuListener() {
        return new PopupMenuListener() {
            public void popupMenuWillBecomeVisible(PopupMenuEvent e) {
                // no implementation.
            }
            public void popupMenuWillBecomeInvisible(PopupMenuEvent e) {
                // no implementation.
            }
            public void popupMenuCanceled(PopupMenuEvent e) {
                // the popup menu has been canceled externally (either by 
                // pressing escape or clicking off of the popup menu). update
                // the button's state to reflect the menu dismissal.
                fButton.setSelected(false);
            }
        };
    }

Everything seems to be going great! Until, that is, you go back and try to toggle the menu by selecting and deselecting the toggle button. When the button is pressed and the menu is showing, and you press the button a second time, the menu disappears for a fraction of a second and then reappears again.

What’s going on?

When the popup menu is showing, and the button is selected, pressing the button causes the popup menu to dismiss (remember that clicking outside a popup menu normally dismisses it). How, then, are we to indicate that clicking the button should not dismiss the popup menu?

Fortunately, this trail has already been blazed by the implementors of JComboBox. Installing the below client property on our button, allows the button to be clicked, without causing the popup menu to be dismissed:

// this is a trick to get hold of the client property which prevents
// closing of the popup when the down arrow is pressed.
JComboBox box = new JComboBox();
Object preventHide = box.getClientProperty("doNotCancelPopup");
putClientProperty("doNotCancelPopup", preventHide);

Here’s the full listing of the PopdownButton I wrote to demonstrate this issue. This isn’t a production ready implementation, but it’s enough to get you started.

Button at rest
Button pressed/selected

public class PopdownButton {
    
    private JToggleButton fButton = new JToggleButton();
    private JPopupMenu fPopupMenu = new JPopupMenu();    
    private boolean fShouldHandlePopupWillBecomeInvisible = true;

    public PopdownButton(Icon defaultIcon, Icon pressedAndSelectedIcon) {
        // setup the default button state.
        fButton.setIcon(defaultIcon);
        fButton.setPressedIcon(pressedAndSelectedIcon);
        fButton.setSelectedIcon(pressedAndSelectedIcon);
        fButton.setFocusable(false);
        fButton.putClientProperty("JButton.buttonType", "textured");
        
        // install a mouse listener on the button to hide and show the popup
        // menu as appropriate.
        fButton.addMouseListener(createButtonMouseListener());
        
        // add a popup menu listener to update the button's selection state
        // when the menu is being dismissed.
        fPopupMenu.addPopupMenuListener(createPopupMenuListener());

        // install a special client property on the button to prevent it from
        // closing of the popup when the down arrow is pressed.
        JComboBox box = new JComboBox();
        Object preventHide = box.getClientProperty("doNotCancelPopup");
        fButton.putClientProperty("doNotCancelPopup", preventHide);
    }
    
    private MouseListener createButtonMouseListener() {
        return new MouseAdapter() {
            public void mousePressed(MouseEvent e) {
                // if the popup menu is currently showing, then hide it.
                // else if the popup menu is not showing, then show it.
                if (fPopupMenu.isShowing()) {
                    hidePopupMenu();
                } else {
                    showPopupMenu();
                }
            }
        };
    }
    
    private PopupMenuListener createPopupMenuListener() {
        return new PopupMenuListener() {
            public void popupMenuWillBecomeVisible(PopupMenuEvent e) {
                // no implementation.
            }
            public void popupMenuWillBecomeInvisible(PopupMenuEvent e) {
                // handle this event if so indicated. the only time we don't handle 
                // this event is when the button itself is pressed, the press action
                // toggles the button selected state for us. this case handles when
                // the button has been toggled, but the user clicks outside the
                // button in order to dismiss the menu.
                if (fShouldHandlePopupWillBecomeInvisible) {
                    fButton.setSelected(false);
                }
            }
            public void popupMenuCanceled(PopupMenuEvent e) {
                // the popup menu has been canceled externally (either by 
                // pressing escape or clicking off of the popup menu). update
                // the button's state to reflect the menu dismissal.
                fButton.setSelected(false);
            }
        };
    }
    
    private void hidePopupMenu() {
        fShouldHandlePopupWillBecomeInvisible = false;
        fPopupMenu.setVisible(false);
        fShouldHandlePopupWillBecomeInvisible = true;
    }
    
    private void showPopupMenu() {
        // show the menu below the button, and slightly to the right.
        fPopupMenu.show(fButton, 5, fButton.getHeight());
    }
    
    public JComponent getComopnent() {
        return fButton;
    }
    
    public JPopupMenu getPopupMenu() {
        return fPopupMenu;
    }
}