We started this chapter by introducing the most common components that you might want to place into a window, such as various kinds of buttons, text fields, and combo boxes. Swing also supports another type of user interface element, the pull-down menus that are familiar from GUI applications. A menu bar on top of the window contains the names of the pull-down menus. Clicking on a name opens the menu containing menu items and submenus. When the user clicks on a menu item, all menus are closed and a message is sent to the program. Figure 9-21 shows a typical menu with a submenu. Figure 9-21. A menu with a submenuMenu BuildingBuilding menus is straightforward. You create a menu bar: JMenuBar menuBar = new JMenuBar(); A menu bar is just a component that you can add anywhere you like. Normally, you want it to appear at the top of a frame. You can add it there with the setJMenuBar method: frame.setJMenuBar(menuBar); For each menu, you create a menu object: JMenu editMenu = new JMenu("Edit"); You add the top-level menus to the menu bar: menuBar.add(editMenu); You add menu items, separators, and submenus to the menu object: JMenuItem pasteItem = new JMenuItem("Paste"); editMenu.add(pasteItem); editMenu.addSeparator(); JMenu optionsMenu = . . .; // a submenu editMenu.add(optionsMenu); You can see separators in Figure 9-21 below the "Paste" and "Read-only" menu items. When the user selects a menu, an action event is triggered. You need to install an action listener for each menu item. ActionListener listener = . . .; pasteItem.addActionListener(listener); The method JMenu.add(String s) conveniently adds a menu item to the end of a menu, for example: editMenu.add("Paste"); The add method returns the created menu item, so you can capture it and then add the listener, as follows: JMenuItem pasteItem = editMenu.add("Paste"); pasteItem.addActionListener(listener); It often happens that menu items trigger commands that can also be activated through other user interface elements such as toolbar buttons. In Chapter 8, you saw how to specify commands through Action objects. You define a class that implements the Action interface, usually by extending the AbstractAction convenience class. You specify the menu item label in the constructor of the AbstractAction object, and you override the actionPerformed method to hold the menu action handler. For example, Action exitAction = new AbstractAction("Exit") // menu item text goes here { public void actionPerformed(ActionEvent event) { // action code goes here System.exit(0); } }; You can then add the action to the menu: JMenuItem exitItem = fileMenu.add(exitAction); This command adds a menu item to the menu, using the action name. The action object becomes its listener. This is just a convenient shortcut for JMenuItem exitItem = new JMenuItem(exitAction); fileMenu.add(exitItem); NOTE
javax.swing.JMenu 1.2
javax.swing.JMenuItem 1.2
javax.swing.AbstractButton 1.2
javax.swing.JFrame 1.2
Icons in Menu ItemsMenu items are very similar to buttons. In fact, the JMenuItem class extends the AbstractButton class. Just like buttons, menus can have just a text label, just an icon, or both. You can specify the icon with the JMenuItem(String, Icon) or JMenuItem(Icon) constructor, or you can set it with the setIcon method that the JMenuItem class inherits from the AbstractButton class. Here is an example: JMenuItem cutItem = new JMenuItem("Cut", new ImageIcon("cut.gif")); Figure 9-22 shows a menu with icons next to several menu items. As you can see, by default, the menu item text is placed to the right of the icon. If you prefer the text to be placed on the left, call the setHorizontalTextPosition method that the JMenuItem class inherits from the AbstractButton class. For example, the call cutItem.setHorizontalTextPosition(SwingConstants.LEFT); Figure 9-22. Icons in menu itemsmoves the menu item text to the left of the icon. You can also add an icon to an action: cutAction.putValue(Action.SMALL_ICON, new ImageIcon("cut.gif")); Whenever you construct a menu item out of an action, the Action.NAME value becomes the text of the menu item and the Action.SMALL_ICON value becomes the icon. Alternatively, you can set the icon in the AbstractAction constructor: cutAction = new AbstractAction("Cut", new ImageIcon("cut.gif")) { public void actionPerformed(ActionEvent event) { // action code goes here } }; javax.swing.JMenuItem 1.2
javax.swing.AbstractButton 1.2
javax.swing.AbstractAction 1.2
Checkbox and Radio Button Menu ItemsCheckbox and radio button menu items display a checkbox or radio button next to the name (see Figure 9-23). When the user selects the menu item, the item automatically toggles between checked and unchecked. Figure 9-23. A checked menu item and menu items with radio buttonsApart from the button decoration, you treat these menu items just as you would any others. For example, here is how you create a checkbox menu item. JCheckBoxMenuItem readonlyItem = new JCheckBoxMenuItem("Read-only"); optionsMenu.add(readonlyItem); The radio button menu items work just like regular radio buttons. You must add them to a button group. When one of the buttons in a group is selected, all others are automatically deselected. ButtonGroup group = new ButtonGroup(); JRadioButtonMenuItem insertItem = new JRadioButtonMenuItem("Insert"); insertItem.setSelected(true); JRadioButtonMenuItem overtypeItem = new JRadioButtonMenuItem("Overtype"); group.add(insertItem); group.add(overtypeItem); optionsMenu.add(insertItem); optionsMenu.add(overtypeItem); With these menu items, you don't necessarily want to be notified at the exact moment the user selects the item. Instead, you can simply use the isSelected method to test the current state of the menu item. (Of course, that means that you should keep a reference to the menu item stored in an instance field.) Use the setSelected method to set the state. javax.swing.JCheckBoxMenuItem 1.2
javax.swing.JRadioButtonMenuItem 1.2
javax.swing.AbstractButton 1.2
Pop-Up MenusA pop-up menu is a menu that is not attached to a menu bar but that floats somewhere (see Figure 9-24). Figure 9-24. A pop-up menuYou create a pop-up menu similarly to the way you create a regular menu, but a pop-up menu has no title. JPopupMenu popup = new JPopupMenu(); You then add menu items in the usual way: JMenuItem item = new JMenuItem("Cut"); item.addActionListener(listener); popup.add(item); Unlike the regular menu bar that is always shown at the top of the frame, you must explicitly display a pop-up menu by using the show method. You specify the parent component and the location of the pop-up, using the coordinate system of the parent. For example: popup.show(panel, x, y); Usually you write code to pop up a menu when the user clicks a particular mouse button, the so-called pop-up trigger. In Windows and Linux, the pop-up trigger is the nonprimary (usually, the right) mouse button. To pop up a menu when the user clicks on a component, using the pop-up trigger, simply call the method component.setComponentPopupMenu(popup); Very occasionally, you may place a component inside another component that has a pop-up menu. The child component can inherit the parent component's pop-up menu by calling child.setInheritsPopupMenu(true); These methods were added in JDK 5.0 to insulate programmers from system dependencies with pop-up menus. Before JDK 5.0, you had to install a mouse listener and add the following code to both the mousePressed and the mouseReleased listener methods: if (popup.isPopupTrigger(event)) popup.show(event.getComponent(), event.getX(), event.getY()); Some systems trigger pop-ups when the mouse button goes down, others when the mouse button goes up. javax.swing.JPopupMenu 1.2
java.awt.event.MouseEvent 1.1
javax.swing.JComponent 1.2
Keyboard Mnemonics and AcceleratorsIt is a real convenience for the experienced user to select menu items by keyboard mnemonics. You can specify keyboard mnemonics for menu items by specifying a mnemonic letter in the menu item constructor: JMenuItem cutItem = new JMenuItem("Cut", 'T'); The keyboard mnemonic is displayed automatically in the menu, with the mnemonic letter underlined (see Figure 9-25). For example, in the item defined in the last example, the label will be displayed as "Cut" with an underlined letter 't'. When the menu is displayed, the user just needs to press the T key, and the menu item is selected. (If the mnemonic letter is not part of the menu string, then typing it still selects the item, but the mnemonic is not displayed in the menu. Naturally, such invisible mnemonics are of dubious utility.) Figure 9-25. Keyboard mnemonicsSometimes, you don't want to underline the first letter of the menu item that matches the mnemonic. For example, if you have a mnemonic "A" for the menu item "Save As," then it makes more sense to underline the second "A" (Save As). As of JDK 1.4, you can specify which character you want to have underlined; call the setDisplayedMnemonicIndex method. If you have an Action object, you can add the mnemonic as the value of the Action.MNEMONIC_KEY key, as follows: cutAction.putValue(Action.MNEMONIC_KEY, new Integer('T')); You can supply a mnemonic letter only in the constructor of a menu item, not in the constructor for a menu. Instead, to attach a mnemonic to a menu, you call the setMnemonic method: JMenu helpMenu = new JMenu("Help"); helpMenu.setMnemonic('H'); To select a top-level menu from the menu bar, you press the ALT key together with the mnemonic letter. For example, you press ALT+H to select the Help menu from the menu bar. Keyboard mnemonics let you select a submenu or menu item from the currently open menu. In contrast, accelerators are keyboard shortcuts that let you select menu items without ever opening a menu. For example, many programs attach the accelerators CTRL+O and CTRL+S to the Open and Save items in the File menu. You use the setAccelerator method to attach an accelerator key to a menu item. The setAccelerator method takes an object of type Keystroke. For example, the following call attaches the accelerator CTRL+O to the openItem menu item. openItem.setAccelerator(KeyStroke.getKeyStroke(KeyEvent.VK_O, InputEvent.CTRL_MASK)); When the user presses the accelerator key combination, this automatically selects the menu option and fires an action event, as if the user had selected the menu option manually. You can attach accelerators only to menu items, not to menus. Accelerator keys don't actually open the menu. Instead, they directly fire the action event that is associated with a menu. Conceptually, adding an accelerator to a menu item is similar to the technique of adding an accelerator to a Swing component. (We discussed that technique in Chapter 8.) However, when the accelerator is added to a menu item, the key combination is automatically displayed in the menu (see Figure 9-26). Figure 9-26. AcceleratorsNOTE
javax.swing.JMenuItem 1.2
javax.swing.AbstractButton 1.2
Enabling and Disabling Menu ItemsOccasionally, a particular menu item should be selected only in certain contexts. For example, when a document is opened for reading only, then the Save menu item is not meaningful. Of course, we could remove the item from the menu with the JMenu.remove method, but users would react with some surprise to menus whose content keeps changing. Instead, it is better to deactivate the menu items that lead to temporarily inappropriate commands. A deactivated menu item is shown in gray, and it cannot be selected (see Figure 9-27). Figure 9-27. Disabled menu itemsTo enable or disable a menu item, use the setEnabled method: saveItem.setEnabled(false); There are two strategies for enabling and disabling menu items. Each time circumstances change, you can call setEnabled on the relevant menu items or actions. For example, as soon as a document has been set to read-only mode, you can locate the Save and Save As menu items and disable them. Alternatively, you can disable items just before displaying the menu. To do this, you must register a listener for the "menu selected" event. The javax.swing.event package defines a MenuListener interface with three methods: void menuSelected(MenuEvent event) void menuDeselected(MenuEvent event) void menuCanceled(MenuEvent event) The menuSelected method is called before the menu is displayed. It can therefore be used to disable or enable menu items. The following code shows how to disable the Save and Save As actions whenever the Read Only checkbox menu item is selected: public void menuSelected(MenuEvent event) { saveAction.setEnabled(!readonlyItem.isSelected()); saveAsAction.setEnabled(!readonlyItem.isSelected()); } CAUTION
javax.swing.JMenuItem 1.2
javax.swing.event.MenuListener 1.2
Example 9-11 is a sample program that generates a set of menus. It shows all the features that you saw in this section: nested menus, disabled menu items, checkbox and radio button menu items, a pop-up menu, and keyboard mnemonics and accelerators. Example 9-11. MenuTest.java1. import java.awt.*; 2. import java.awt.event.*; 3. import javax.swing.*; 4. import javax.swing.event.*; 5. 6. public class MenuTest 7. { 8. public static void main(String[] args) 9. { 10. MenuFrame frame = new MenuFrame(); 11. frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); 12. frame.setVisible(true); 13. } 14. } 15. 16. /** 17. A frame with a sample menu bar. 18. */ 19. class MenuFrame extends JFrame 20. { 21. public MenuFrame() 22. { 23. setTitle("MenuTest"); 24. setSize(DEFAULT_WIDTH, DEFAULT_HEIGHT); 25. 26. JMenu fileMenu = new JMenu("File"); 27. JMenuItem newItem = fileMenu.add(new TestAction("New")); 28. 29. // demonstrate accelerators 30. 31. JMenuItem openItem = fileMenu.add(new TestAction("Open")); 32. openItem.setAccelerator(KeyStroke.getKeyStroke(KeyEvent.VK_O, InputEvent .CTRL_MASK)); 33. 34. fileMenu.addSeparator(); 35. 36. saveAction = new TestAction("Save"); 37. JMenuItem saveItem = fileMenu.add(saveAction); 38. saveItem.setAccelerator(KeyStroke.getKeyStroke(KeyEvent.VK_S, InputEvent .CTRL_MASK)); 39. 40. saveAsAction = new TestAction("Save As"); 41. JMenuItem saveAsItem = fileMenu.add(saveAsAction); 42. fileMenu.addSeparator(); 43. 44. fileMenu.add(new 45. AbstractAction("Exit") 46. { 47. public void actionPerformed(ActionEvent event) 48. { 49. System.exit(0); 50. } 51. }); 52. 53. // demonstrate checkbox and radio button menus 54. 55. readonlyItem = new JCheckBoxMenuItem("Read-only"); 56. readonlyItem.addActionListener(new 57. ActionListener() 58. { 59. public void actionPerformed(ActionEvent event) 60. { 61. boolean saveOk = !readonlyItem.isSelected(); 62. saveAction.setEnabled(saveOk); 63. saveAsAction.setEnabled(saveOk); 64. } 65. }); 66. 67. ButtonGroup group = new ButtonGroup(); 68. 69. JRadioButtonMenuItem insertItem = new JRadioButtonMenuItem("Insert"); 70. insertItem.setSelected(true); 71. JRadioButtonMenuItem overtypeItem = new JRadioButtonMenuItem("Overtype"); 72. 73. group.add(insertItem); 74. group.add(overtypeItem); 75. 76. // demonstrate icons 77. 78. Action cutAction = new TestAction("Cut"); 79. cutAction.putValue(Action.SMALL_ICON, new ImageIcon("cut.gif")); 80. Action copyAction = new TestAction("Copy"); 81. copyAction.putValue(Action.SMALL_ICON, new ImageIcon("copy.gif")); 82. Action pasteAction = new TestAction("Paste"); 83. pasteAction.putValue(Action.SMALL_ICON, new ImageIcon("paste.gif")); 84. 85. JMenu editMenu = new JMenu("Edit"); 86. editMenu.add(cutAction); 87. editMenu.add(copyAction); 88. editMenu.add(pasteAction); 89. 90. // demonstrate nested menus 91. 92. JMenu optionMenu = new JMenu("Options"); 93. 94. optionMenu.add(readonlyItem); 95. optionMenu.addSeparator(); 96. optionMenu.add(insertItem); 97. optionMenu.add(overtypeItem); 98. 99. editMenu.addSeparator(); 100. editMenu.add(optionMenu); 101. 102. // demonstrate mnemonics 103. 104. JMenu helpMenu = new JMenu("Help"); 105. helpMenu.setMnemonic('H'); 106. 107. JMenuItem indexItem = new JMenuItem("Index"); 108. indexItem.setMnemonic('I'); 109. helpMenu.add(indexItem); 110. 111. // you can also add the mnemonic key to an action 112. Action aboutAction = new TestAction("About"); 113. aboutAction.putValue(Action.MNEMONIC_KEY, new Integer('A')); 114. helpMenu.add(aboutAction); 115. 116. // add all top-level menus to menu bar 117. 118. JMenuBar menuBar = new JMenuBar(); 119. setJMenuBar(menuBar); 120. 121. menuBar.add(fileMenu); 122. menuBar.add(editMenu); 123. menuBar.add(helpMenu); 124. 125. // demonstrate pop-ups 126. 127. popup = new JPopupMenu(); 128. popup.add(cutAction); 129. popup.add(copyAction); 130. popup.add(pasteAction); 131. 132. JPanel panel = new JPanel(); 133. panel.setComponentPopupMenu(popup); 134. add(panel); 135. 136. // the following line is a workaround for bug 4966109 137. panel.addMouseListener(new MouseAdapter() {}); 138. } 139. 140. public static final int DEFAULT_WIDTH = 300; 141. public static final int DEFAULT_HEIGHT = 200; 142. 143. private Action saveAction; 144. private Action saveAsAction; 145. private JCheckBoxMenuItem readonlyItem; 146. private JPopupMenu popup; 147. } 148. 149. /** 150. A sample action that prints the action name to System.out 151. */ 152. class TestAction extends AbstractAction 153. { 154. public TestAction(String name) { super(name); } 155. 156. public void actionPerformed(ActionEvent event) 157. { 158. System.out.println(getValue(Action.NAME) + " selected."); 159. } 160. } ToolbarsA toolbar is a button bar that gives quick access to the most commonly used commands in a program (see Figure 9-28). Figure 9-28. A toolbarWhat makes toolbars special is that you can move them elsewhere. You can drag the toolbar to one of the four borders of the frame (see Figure 9-29). When you release the mouse button, the toolbar is dropped into the new location (see Figure 9-30). Figure 9-29. Dragging the toolbarFigure 9-30. Dragging the toolbar to another borderNOTE
The toolbar can even be completely detached from the frame. A detached toolbar is contained in its own frame (see Figure 9-31). When you close the frame containing a detached toolbar, the toolbar jumps back into the original frame. Figure 9-31. Detaching the toolbarToolbars are straightforward to program. You add components into the toolbar: JToolBar bar = new JToolBar(); bar.add(blueButton); The JToolBar class also has a method to add an Action object. Simply populate the toolbar with Action objects, like this: bar.add(blueAction); The small icon of the action is displayed in the toolbar. You can separate groups of buttons with a separator: bar.addSeparator(); For example, the toolbar in Figure 9-28 has a separator between the third and fourth button. Then, you add the toolbar to the frame. add(bar, BorderLayout.NORTH); You can also specify a title for the toolbar that appears when the toolbar is undocked: bar = new JToolBar(titleString); By default, toolbars are initially horizontal. To have a toolbar start out as vertical, use bar = new JToolBar(SwingConstants.VERTICAL) or bar = new JToolBar(titleString, SwingConstants.VERTICAL) Buttons are the most common components inside toolbars. But there is no restriction on the components that you can add to a toolbar. For example, you can add a combo box to a toolbar. TIP
TooltipsA disadvantage of toolbars is that users are often mystified by the meanings of the tiny icons in toolbars. To solve this problem, user interface designers invented tooltips. A tooltip is activated when the cursor rests for a moment over a button. The tooltip text is displayed inside a colored rectangle. When the user moves the mouse away, the tooltip is removed. (See Figure 9-32.) Figure 9-32. A tooltipIn Swing, you can add tooltips to any JComponent simply by calling the setToolTipText method: exitButton.setToolTipText("Exit"); Alternatively, if you use Action objects, you associate the tooltip with the SHORT_DESCRIPTION key: exitAction.putValue(Action.SHORT_DESCRIPTION, "Exit"); Example 9-12 shows how the same Action objects can be added to a menu and a toolbar. Note that the action names show up as the menu item names in the menu, and the short descriptions as the tooltips in the toolbar. Example 9-12. ToolBarTest.java1. import java.awt.*; 2. import java.awt.event.*; 3. import java.beans.*; 4. import javax.swing.*; 5. 6. public class ToolBarTest 7. { 8. public static void main(String[] args) 9. { 10. ToolBarFrame frame = new ToolBarFrame(); 11. frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE); 12. frame.setVisible(true); 13. } 14. } 15. 16. /** 17. A frame with a toolbar and menu for color changes. 18. */ 19. class ToolBarFrame extends JFrame 20. { 21. public ToolBarFrame() 22. { 23. setTitle("ToolBarTest"); 24. setSize(DEFAULT_WIDTH, DEFAULT_HEIGHT); 25. 26. // add a panel for color change 27. 28. panel = new JPanel(); 29. 30. // set up actions 31. 32. Action blueAction = new ColorAction("Blue", 33. new ImageIcon("blue-ball.gif"), Color.BLUE); 34. Action yellowAction = new ColorAction("Yellow", 35. new ImageIcon("yellow-ball.gif"), Color.YELLOW); 36. Action redAction = new ColorAction("Red", 37. new ImageIcon("red-ball.gif"), Color.RED); 38. 39. Action exitAction = new 40. AbstractAction("Exit", new ImageIcon("exit.gif")) 41. { 42. public void actionPerformed(ActionEvent event) 43. { 44. System.exit(0); 45. } 46. }; 47. exitAction.putValue(Action.SHORT_DESCRIPTION, "Exit"); 48. 49. // populate toolbar 50. 51. JToolBar bar = new JToolBar(); 52. bar.add(blueAction); 53. bar.add(yellowAction); 54. bar.add(redAction); 55. bar.addSeparator(); 56. bar.add(exitAction); 57. add(bar, BorderLayout.NORTH); 58. 59. // populate menu 60. 61. JMenu menu = new JMenu("Color"); 62. menu.add(yellowAction); 63. menu.add(blueAction); 64. menu.add(redAction); 65. menu.add(exitAction); 66. JMenuBar menuBar = new JMenuBar(); 67. menuBar.add(menu); 68. setJMenuBar(menuBar); 69. } 70. 71. public static final int DEFAULT_WIDTH = 300; 72. public static final int DEFAULT_HEIGHT = 200; 73. 74. private JPanel panel; 75. 76. /** 77. The color action sets the background of the frame to a 78. given color. 79. */ 80. class ColorAction extends AbstractAction 81. { 82. public ColorAction(String name, Icon icon, Color c) 83. { 84. putValue(Action.NAME, name); 85. putValue(Action.SMALL_ICON, icon); 86. putValue(Action.SHORT_DESCRIPTION, name + " background"); 87. putValue("Color", c); 88. } 89. 90. public void actionPerformed(ActionEvent event) 91. { 92. Color c = (Color) getValue("Color"); 93. panel.setBackground(c); 94. } 95. } 96. } javax.swing.JToolBar 1.2
javax.swing.JComponent 1.2
|