Designing menus
This chapter shows you how to visually design menus. Using the JBuilder menu designer, you can visually design both menu bar menus and pop-up menus.
Opening the menu designer
To open the menu designer, you must be in the UI designer. Select the AppBrowser's Design tab to open the UI designer. The Design tab is only available when a visually designable file, such as a Frame
file, is open and active in the content pane.
To use the menu designer, you must first select the menu component you want to work with and bring it into the UI designer:
- Click one of the following menu bar or pop-up menu components on the component palette:
- From the Swing containers palette:
JMenuBar
JPopUpMenu
- From the AWT palette:
MenuBar
PopUpMenu
- Drop the component anywhere onto the component tree or into the UI designer. It is automatically placed in the component tree's Menu folder.
To toggle the menu designer:
- Double-click any menu component in the component tree.
- Select the menu component in the component tree and press Enter.
- Right-click the menu component in the component tree and choose Activate Designer.
As you edit menu items in the menu designer, all changes are immediately reflected in the the inspector, the component tree, and the source code. Likewise, when you make changes in the source code, the changes are reflected in the IDE.
There is no need to save your menu design explicitly. Code is generated as you work in the menu designer and is saved when you save your .java
source file. The next time you open the .java
file and click a MenuBar
component in the component tree, the menu designer will open and reload everything for that component.
Menu terminology
The basic parts of a menu are referred to using the following terms:
- A menu is a list of menu items.
- A menu item is one choice on a menu. Menu items can have attributes such as being disabled (gray) when not available to the user, or checkable so their selection state can be toggled.
- The menu bar is located at the top of a frame and is composed of menus containing individual menu items.
- A submenu is a nested menu accessed by clicking on an arrow to the right of a menu item.
- A keyboard shortcut is displayed to the right of the menu item, and may be specific to a particular editor interface. For example, Ctrl+X is used to indicate Edit|Cut in many editors.
- The separator is a bar that visually separates different groups of menu items.
This demonstrates the menu terminology used in JBuilder:
Menu design tools
When you open the menu designer on a menu item, the design surface changes to look something like this:
This menu designer has its own toolbar and recognizes keystrokes such as the navigation arrows and Ins and Del keys.
The menu designer toolbar contains the following tools:
| Tool | Action |
|  | Inserts a placeholder for a new menu to the left of the selected menu or a new menu item above the selected menu item. |
|  | Inserts a separator immediately above the currently selected menu item. |
|  | Creates a placeholder for a nested submenu and adds an arrow to the right of the selected menu item. |
|  | Deletes the selected menu item (and all its submenu items, if any). |
|  | Toggles the enabled property of the selected menu item between true and false and dims it when it is false (disabled). (Applies to Swing menu components; the enabled property of AWT menu components must be changed by hand in your source code, since it is not surfaced in the inspector.) |
|  | Makes the menu item checkable. |
|  | Toggles the menu item between being a JMenuItem or a JRadioButtonMenuItem . |
Note: Right-click a menu item in the menu designer to display a pop-up menu containing many of the same commands.
Creating a new menu
A menu must be attached to a Frame
, so to create a menu in your application, first create a Frame
file. Do this in one of the following ways:
- Create a new application with the Application wizard. On Step 2 of the wizard, check Generate Menu Bar.
- Open an existing
Frame
file.
- Use the Frame wizard to add a
Frame
file to your project.
To add a menu component to the UI,
- Select the UI
Frame
file in the navigation pane.
- Click the Design tab at the bottom of the AppBrowser.
- Select your main UI frame in the UI designer or in the component tree.
- Click the menu component you want from either the AWT page or the Swing Containers page of the component palette, and drop it anywhere in the UI designer or in the component tree.
- A
MenuBar
or JMenuBar
is attached to the main UI Frame
, and appears at the top of the application at runtime.
- A
PopupMenu
or JPopupMenu
appears when the user right-clicks in your UI. Pop-up menus do not have menu bars.
The menu component you added shows up as a node in the component tree, and its properties are displayed in the inspector.
For every menu you want to include in your application, add a menu component to the target UI container. The first MenuBar
component dropped onto the UI container is considered the current MenuBar
for your UI. However, you can create more than one MenuBar
for an application. Each MenuBar
's name is displayed in the inspector in the frame's MenuBar
property. To change the current MenuBar
, select a menu from the MenuBar
property drop-down list.
Note: At design time, menu components are visible only in the menu designer (not in the UI designer). However, you can always see them and select them in the component tree. To see how the menu looks in your UI, you must run your application.
Adding menu items
When you first open the menu designer, it displays the first (blank) menu item indicated by a dotted rectangle.
- Type a label for the menu item. (You may have to double-click inside the rectangle to get a cursor.)
The field is a default width if that menu list is empty. When it's not empty, the field is as wide as the longest menu item in the menu. While you're typing, the text field will scroll to accommodate labels longer than the edit field.
- Press Enter, or press the down arrow key to add another menu item.
A placeholder for the next menu or menu item is automatically added.
The name of the menu item in the component tree changes to reflect the label.
- Type a label for each new item you want to create in the list, or press Esc to return to the menu bar.
You can use the arrow keys to move from the menu bar into a menu, and to move between items in the list.
Inserting and deleting menus and menu items
To insert a new menu or menu item into an existing menu, select the rectangle where you want the new menu item to be (a new menu is inserted to the left of the selected menu on the menu bar, and a new menu item is inserted above the selected item in the menu list). Then do one of the following:
- Click the Insert button
on the toolbar.
- Press the Ins key.
- Right-click and choose Insert Menu or Insert Menu Item.
To delete a menu item, select the menu item you want to delete, and do one of the following:
- Click the Delete Item button
on the toolbar.
- Press the Del key.
Note: A default placeholder (which you cannot delete) appears after the last menu on the menu bar and below the last item on a menu. This placeholder does not appear in your menu at runtime.
Inserting a separator
A separator inserts a horizontal line between menu items. You can use separators to group items within a menu list, or simply to provide a visual break in a list.
To insert a separator on a menu,
- Select the menu item before which you want a separator.
- Click the Insert Separator button
on the toolbar.
The separator is inserted above the selected menu item.
Specifying keyboard shortcuts
Keyboard shortcuts enable the user to perform a menu action by typing in a shortcut key combination. For example, a commonly used shortcut for File|Save is Ctrl+S.
To specify a keyboard shortcut for a menu item,
- Select the menu item in the menu designer or in the component tree.
- In the inspector, select the
shortcut
property and enter a value or choose a key combination from the drop-down list. This list is only a subset of the valid combinations you can use.
When you add a shortcut, it appears next to the menu item at runtime, but not otherwise.
Disabling (dimming) menu items
You can prevent users from accessing certain menu commands based on a particular state of the current program, without removing the command from the menu. For example, if no text is currently selected in a document, the Cut, Copy, and Delete items on the Edit menu appear dimmed.
To disable a menu item, set its enabled
property to false. The default state of a menu item is true.
To disable a Swing menu item
- Click the Disable button on the toolbar.
The Disable button toggles the enabled
property for the selected menu item between true (enabled) and false (disabled).
- In the inspector, set the
enabled
property for the menu item to false.
(In contrast to the visible
property, the enabled
property leaves the item visible. A value of false simply dims the menu item.)
To disable an AWT menu item
Because AWT menu items do not have an enabled
property surfaced in the inspector, you must change your source code to disable the item; for example, before the line that sets the text of the menu item, type
jMenuItem8.setEnabled(false);
Creating checkable menu items
To make a menu item checkable, you must change the menu item from a regular JMenuItem
component to a JCheckBoxMenuItem
. A JCheckBoxMenuItem
has a state
property (boolean) that determines if the associated event, or behavior, should be executed.
- A checked menu item has its
state
property set to true.
- An unchecked menu item has its
state
property set to false.
To change a regular menu item to a JCheckboxMenuItem
, select the menu item and click the Check button
on the toolbar, or right-click the menu item and choose Make it checkable.
Creating radio button menu items
The menu designer lets you create menu items that are part of a ButtonGroup
in which only one item in the group can be selected. The selected item displays its selected state, causing any other selected items to switch to the unselected state.
To create a group of radio button menu items,
- In the menu designer, create a menu or nested menu containing the menu items you want in the radio button group.
- Right-click each of these menu items in the designer and choose Convert to
JRadioButtonMenuItem
. (You could also select the menu item and click the RadioButton icon
on the menu designer toolbar.)
- Click the Bean Chooser
icon on the component palette to open the Package browser. (If you have already added packages to your Bean Chooser list, choose Select.
- Expand
javax.Swing
and double-click ButtonGroup
. The selection cursor is now holding ButtonGroup
.
- Click anywhere in the tree or the UI designer. This adds a
buttonGroup1
to the Other
folder in the tree, and adds the following line to the class variables:
ButtonGroup buttonGroup1 = new ButtonGroup();
- Click the Source tab, and in the constructor's try block after
jbInit()
, add each jRadioButtonMenuItem
to buttonGroup1
as follows:
//Construct the frame
public Frame1() {
enableEvents(AWTEvent.WINDOW_EVENT_MASK);
try {
jbInit();
buttonGroup1.add(jRadioButtonMenuItem1);
buttonGroup1.add(jRadioButtonMenuItem2);
buttonGroup1.add(jRadioButtonMenuItem3);
}
catch(Exception e) {
e.printStackTrace();
}
}
- Click the Design tab, and in the inspector, set the
selected
property for one of the radio button menu items to true (whichever one you want selected as the default). The following line of code is added to your source:
jRadioButtonMenuItem2.setSelected(true);
- Now, if you run your program, you'll see the menu item whose
selected
property you set as true has a radio button to the left of it. If you click one of the other menu items, the radio button moves to the newly selected item.
Moving menu items
In the menu designer, you can move menus and menu items simply by dragging and dropping them with the mouse. When you move a menu or a submenu, any items contained in it move as well.
You can move the following:
- Menus along the menu bar.
- Menu items within a menu.
- Menu items to other menus.
- Entire menus to a nest under a different menu item. (These become submenus.)
- Submenus up to the menu bar to create new menus.
- Submenu items to other menus.
The only exception to this is hierarchical: you cannot move a menu from the menu bar into itself; nor can you move a menu item into its own submenu. However, you can move any menu item into a different menu regardless of its original position.
To move a menu or menu item,
- Drag it with the mouse until the tip of the cursor points to the new location.
If you are dragging the menu or menu item to another menu, drag it along the menu bar until the cursor points to the target menu. This opens the target menu, letting you drag and drop the menu or menu item to its new location.
- Release the mouse button to drop the menu item into the new location.
Creating submenus
Many applications have menus containing drop-down lists that appear next to a menu item to provide additional, related commands. Such lists are indicated by an arrow to the right of the menu item. JBuilder supports as many levels of such nested menus, or submenus, as you want to build into your menu.
However, for optimal design purposes you probably want to use no more than two or three menu levels in your UI design.
When you move a menu off the menu bar into another menu, its items become a submenu. Similarly, if you move a menu item into an existing submenu, its sub-items then form another nested menu under the submenu.
You can move a menu item into an existing submenu, or you can create a placeholder at a nested level next to an existing item, and then drop the menu item into the placeholder to nest it.
Creating a new submenu
To create a submenu,
- Select the menu item for which you want to create a submenu and do one of the following:
- Click the Insert Nested Submenu button
on the toolbar.
- Right-click the menu item and choose Insert Submenu.
- Type a name for the nested menu item, or drag an existing menu item into this placeholder.
- Press Enter, or the Down arrow, to create the next placeholder.
- Repeat steps 2 and 3 for each item you want to create in the nested menu.
- Press Esc to return to the previous menu level.
Moving existing menus to submenus
You can also create a submenu by inserting a menu from the menu bar between menu items in another menu. When you move a menu into an existing menu structure, all its associated items move with it, creating a fully intact nested menu. This pertains to moving submenus as well; moving a submenu into another submenu just creates one more level of nesting.
Attaching code to menu events
A menu item has only one event: actionPerformed
. Code that you add to the actionPerformed
event for a menu item is executed whenever the user chooses that menu item or uses its keyboard shortcut.
To add code to a menu item's actionPerformed
event,
- In the menu designer, select a menu item.
- In the inspector, select the Events tab.
- Select the column beside
actionPerformed
and double-click to create an event-handling method skeleton in the source code with a default name.
Note: To override the default name for the actionPerformed
event-handling method, single click in the event's value field, type a new name for the event method and press Enter.
When you double-click the event value, the source code is displayed. The cursor is positioned in the body of the newly created actionPerformed
event-handling method, ready for you to type.
- Inside the open and close braces, type the code you want to have executed when the user clicks this menu command.
Example: Invoking a dialog box from a menu item
To display the Filer
file open dialog box when the user chooses File|Open, you would do the following:
- Create a File menu with an Open menu item.
- On the Swing Containers page of the component palette, click the
JFileChooser
component and drop it on UI
folder in the component tree.
- In the menu designer, or in the component tree, select the Open menu item.
- In the inspector, select the Events page.
- Select the
actionPerformed
event and double-click to generate the following event-handling method skeleton in the source code, with your cursor in the correct location, waiting for you to type:
void jMenuItem1_actionPerformed(ActionEvent e) {
}
Note: JBuilder takes you to the existing event-handling method if there is one.
- Inside the body of the
actionPerformed
method, type the following:
if (JFileChooser.APPROVE_OPTION==jFileChooser1.showOpenDialog(this));
- In a real program, you will typically need to add several lines of custom code in the event-handling methods. For example, here you might want to extract the file name the user entered from the
Filer
and use it to open or manipulate a file.
For information about events, see "Working with events".
To learn about what code JBuilder automatically generates when you add an event, see "Code that JBuilder generates to connect events" in the section "Working with events" in Building applications with JBuilder.
Creating a pop-up menu
To create a pop-up menu,
- In the UI designer, click a
PopupMenu
component from the AWT page of the component palette or a JPopupMenu
component from the Swing Containers page and drop it into the component tree. It will be the selected item in the tree.
- Press Enter on the selected
PopupMenu
or JPopupMenu
in the component tree to open the menu designer.
- Add one or more menu items to the menu.
- Select
this(BorderLayout)
in the component tree and press Enter to return to the UI designer.
- Select the panel or other component to whose event you want the pop-up menu attached, so you can see that component in the inspector. For the example below,
jPanel1
was selected.
- Click the Event tab in the inspector.
- Double-click the event for which you want the pop-up menu to appear. For the example below, the
MouseClicked
event was selected in the example below.
- Edit your event-handler skeleton code to resemble the following:
void jPanel1_mouseClicked(MouseEvent e) {
jPanel1.add(jPopupMenu1); // JPopupMenu must be added to the component whose event is chosen.
// For this example event, we are checking for right-mouse click.
if (e.getModifiers() == Event.META_MASK) {
// Make the jPopupMenu visible relative to the current mouse position in the container.
jPopupMenu1.show(jPanel1, e.getX(), e.getY());
}
}
- Add event handlers to the pop-up menu items as needed for your application.