13.13 Popup Menus

Java 1.1 adds a long-awaited feature: popup menus. They are remarkably simple to use: allocate a PopupMenu, add some MenuItem's to it, then watch for the popup trigger in a Component by checking mouse events with isPopupTrigger. When the trigger is received, show the menu. This will trigger an action event in the selected menu item.

Constructors

public PopupMenu()

This creates an untitled popup menu.

public PopupMenu(String title)

This creates a popup menu with the specified title. However, most current Windows 95/NT implementations do not display the title.

Example

Listing 13.40 creates a popup menu in an applet. It then watches the mouse events until one occurs that is a "popup trigger" (whatever mouse action normally displays menus in the current operating system), in which case the menu is displayed. By implementing the ActionListener interface and adding itself as a listener on each item in the menu, the applet's own actionPerformed method is called when items are selected. Figure 13-41 shows the result on Windows 95.

import java.applet.Applet;
import java.awt.*;
import java.awt.event.*;

/** Simple demo of popup menus in Java 1.1 */

public class ColorPopupMenu extends Applet
                            implements ActionListener {
 private String[] colorNames =
   { "White", "Light Gray", "Gray",
     "Dark Gray", "Black" };
  private Color[] colors =
    { Color.white, Color.lightGray, Color.gray,
      Color.darkGray, Color.black };
  private PopupMenu menu;

  /** Create PopupMenu and add MenuItems */
                              
  public void init() {
    setBackground(Color.gray);
    menu = new PopupMenu("Background Color");
    enableEvents(AWTEvent.MOUSE_EVENT_MASK);
    MenuItem colorName;
    for(int i=0; i<colorNames.length; i++) {
      colorName = new MenuItem(colorNames[i]);
      menu.add(colorName);
      colorName.addActionListener(this);
      menu.addSeparator();
    }
    add(menu);
  }

  /** Don't use a MouseListener, since in Win95/NT
   *  you have to check isPopupTrigger in
   *  mouseReleased, but do it in mousePressed in
   *  Solaris (boo!).
   */
  public void processMouseEvent(MouseEvent event) {
    if (event.isPopupTrigger())
      menu.show(event.getComponent(),
                event.getX(), event.getY());
    super.processMouseEvent(event);
  }
  
  public void actionPerformed(ActionEvent event) {
    setBackground(colorNamed(event.getActionCommand()));
    repaint();
  }

  private Color colorNamed(String colorName) {
    for(int i=0; i<colorNames.length; i++)
      if(colorNames[i].equals(colorName))
        return(colors[i]);
    return(Color.white);
  }
}

Figure 13-41 Popup menus on Windows 95 appear without titles.

Other PopupMenu Methods

The only method directly in the PopupMenu class is show, which displays the menu. Selected methods from the ancestor classes Menu and MenuItem are listed here as well.

public void add(MenuItem item)
public void add(String label)

This adds an entry to the menu. Rather than adding a string directly, it is usually better to turn it into a MenuItem first via new MenuItem(label). This lets you add an ActionListener on the label.

public void addActionListener(ActionListener listener)

This method is normally applied to MenuItems within the popup menu, and lets you add a listener to take action when the item is selected. Note that the label is available in the ActionEvent class via getActionCommand().

public void addSeparator()

This adds a nonselectable horizontal line to the menu. In Figure 13-41, there is a separator after every entry.

public void setShortcut(MenuShortcut shortcut)
public MenuShortcut getShortcut()
public void deleteShortcut()

In Java 1.0, there was no portable way to associate keyboard shortcuts with menu items. However, most Windows 95/NT implementations let you preface labels with "&" to make the next character be a shortcut. This was not satisfactory, however, since the "&" appeared in the label on other operating systems, and you had to remember to include the ampersand when comparing to labels. Java 1.1 lets you create portable shortcuts. Simply create a MenuShortcut via

      MenuShortcut shortcut = new MenuShortcut(int key);

Next, add the shortcut to a MenuItem via setShortcut. The getShortcut and deleteShortcut methods retrieve and delete the shortcut associated with a menu item.

public void show(Component c, int x, int y)

This displays the popup menu at the specified location relative to the top-left corner of the component.

Strictly speaking, PopupMenu is a Component. However, you should not rely on custom colors or fonts being supported.

Handling PopupMenu Events

There are two types of events you need to worry about with popup menus. The first is the mouse click that brings up the menu in the first place. The second is the event that occurs when an entry is actually selected.

Rather than having to remember what types of mouse clicks are supposed to initiate popup menus on different platforms, Java provides a convenient method in the MouseEvent class: isPopupTrigger. However, since some operating systems invoke the menu when the mouse is first pressed (e.g., Solaris) but others when it is released (e.g., Windows 95 and Windows NT), you probably want to watch mouse events in processMouseEvent rather than in a MouseListener. If you do use a MouseListener, be sure to check both mousePressed and mouseReleased. So the process of popping up the menu would go something like this:

      PopupMenu menu = new PopupMenu("[Title]");
      ...
      enableEvents(AWTEvent.MOUSE_EVENT_MASK);
      ...
      public void processMouseEvent(MouseEvent event) {
        if (event.isPopupTrigger())
          menu.show(event.getComponent(),
                    event.getX(), event.getY());
        super.processMouseEvent(event);
      }

To process the selections, add an ActionListener to each as it is created, as follows:

      MenuItem item = new MenuItem("[Label]");
      menu.add(item);
      item.addActionListener(someListener);

Recall that an ActionListener needs to implement the actionPerformed method, which takes an ActionEvent as an argument. The getActionCommand method of ActionEvent returns the label of the MenuItem.