Designing menus
This section explains how to use JBuilder's Menu Designer to visually design main menus (on a menu bar), and popup menus (local context menus). It covers the following topics:
- Overview of menu components and terminology
Illustrates the general menu terminology used in Borland JBuilder. Also discusses the two types of menu components used in Java programs: MenuBar and PopupMenu.
- About the Menu Designer
Gives you an overview of the Menu Designer, its interaction with the Component Inspector, and explains the toolbar and popup menus accessible by clicking the right mouse button.
- Creating a menu
Explains how to open the Menu Designer and create a new menu. Tells you how to add, insert, and delete items, enter separator bars and shortcuts, and disable (dim) a menu item or make it checkable.
- Moving menu items
Describes how to drag and drop menu items along the menu bar to a different place in the menu list, or into a different menu entirely.
- Creating submenus
Explains how to create submenus (nested menus) accessible from an arrow to the right of a menu item.
- Attaching code to menu events
Demonstrates how to hook up menu items to events.
- Implementing a PopupMenu
Steps you through adding a PopupMenu to your UI design.
Overview of menu terminology and menu components
Menu terminology
The basic parts of a menu are referred to using the following terms:
- The menu bar displays at the top of a frame and is composed of menus containing individual menu items.
- A menu item is an individual element on a menu. Menu items can have attributes such as being disabled (gray) when not allowed, or checkable so their selection state can be toggled.
- A menu is a list of 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 bar helps to visually group related items together.
The following diagram demonstrates the menu terminology used in Borland JBuilder:
Types of menu components
There are two types of menu components on the Component Palette: a MenuBar and a PopupMenu (local context menu).
- A MenuBar is attached to the main UI Frame, and appears at the top of the application.
- A PopupMenu appears when the user right-clicks in your UI. Popup menus do not have menu bars.
Both kinds of controls contain menu items which can be inspected by the Component Inspector.
The first MenuBar control dropped onto the UI container is considered the current MenuBar for your UI. However, you can create more than one MenuBar for an application, and they are displayed in the Inspector in the frame's MenuBar property. To change which menu is the current MenuBar, just select a menu from the MenuBar property drop-down list.
Note: Menu components are only visible at design time in the Menu Designer. However, you can always see them and select them in the Component Tree. To see how the menu looks in your UI, run your application.
You add a menu component to your UI container, or containers, for every menu you want to include in your application.
About the Menu Designer
The Menu Designer is hosted in the Content Pane of the AppBrowser, and is accessed by double-clicking on a menu component in the Component Tree. It has its own toolbar and recognizes keystrokes such as the navigation cursors and Insert and Delete keys.
Interaction with the AppBrowser and the Inspector
The JBuilder IDE maintains everything in sync as you work. As you edit menu items in the Menu Designer, all changes are forwarded immediately to the AppBrowser and the Inspector. And when you make changes to the menus in the source code or the Inspector, those changes are reflected in the Menu Designer.
For example, when you add a Menu to a MenuBar component, this Menu appears in the Component Tree as a child of the MenuBar. Also, when you change properties for Menu or MenuItem (like label or enable), those changes are reflected in the Inspector.
Since the IDE also maintains synchronization with the AppBrowser, there is no need to explicitly save your menu design. Code is generated in the AppBrowser by the Menu Designer as you type and is saved when you save your Java source file. The next time you open the Java file and click on a MenuBar component in the Component Tree, the Menu Designer will open and reload everything for that component.
Once you add a menu component to the UI design, you can use the Menu Designer alone to design the menu structure. But to activate the menus in the user interface, you must use the Component Inspector to attach the menu items to events, or else enter the code manually in the AppBrowser.
The Menu Designer tool bar
The Menu Designer toolbar contains the following tools:
| Tool | Action |
|  | Inserts a placeholder for a new menu item above or to the left of the cursor. |
|  | Inserts a separator bar 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 enabled and disabled and dims it when it is disabled. |
|  | Makes the menu item checkable. |
The Menu Designer popup menu
The Menu Designer popup menu provides quick access to the most common Menu Designer commands. To display the Menu Designer popup menu, right-click the Menu Designer window.
Commands on the context menu:
Menu Command | Action |
Insert (Menu or Menu Item) | Inserts a placeholder for a new menu or menu item entry above or to the left of the cursor |
Delete | Deletes the selected menu or menu item (and all its sub-items, if any). |
Insert submenu | Creates a placeholder for a new submenu entry at a nested level and adds an arrow to the right of the selected menu item. |
Disable/Enable | Toggles the Enabled property of the selected menu item between enabled and disabled, and dims it when it is disabled. |
Make it checkable | Makes the menu item checkable. |
Creating a Menu
Adding a menu component to the UI
Since a menu can only be attached to a Frame, you must first open or create a Frame file. Do this one of the following ways:
- Create a new application with the Application Wizard, and on Step 2, check Create a 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 a menu component on the Component Palette and drop it anywhere in the UI Designer. You can choose between two menu components, a main menu (MenuBar) or a popup menu (PopupMenu).
- A MenuBar is attached to the main UI Frame, and appears at the top of the application.
- A PopupMenu appears when the user right-clicks in your UI. Popup menus do not have menu bars.
(Alternatively, you can open a file that already contains a menu component.)
At this point, nothing will be visible on the UI. The menu component you added is displayed in the Component Tree.
Opening the Menu Designer
To open the Menu Designer,
- Click the Design tab to open the UI Designer, if it isn't already open.
- Double-click on a menu component (for example, menuBar1) in the Component Tree.
Note: After you add menus and menu items to the menu bar, you can double-click on any menu bar component in the Component Tree to open the Menu Designer again.
Adding Menu Items
When you first open the Menu Designer, it displays the first (blank) menu item indicated by a dotted rectangle.
- In the Menu Designer, select the position on the menu bar or in a menu where you want to enter a new menu item.
- Type the text for the menu item's label.
As you start to type, the highlighted dotted rectangle changes to a normal text edit field containing a cursor. This field is a default width if that menu list is empty, or it is as wide as the longest menu item in the menu. The text field will scroll as you type to accommodate labels longer than the edit field.
- When you're finished typing, press Enter.
The width of the list expands if necessary to display all the labels in the list, and a placeholder for the next menu item is automatically selected.
Borland JBuilder automatically changes the name of the menu item in the Component Tree to reflect the label.
- Enter a label for each new item you want to create in the list, or press Esc to return to the menu bar.
Use the arrow keys to move from the menu bar into a menu, and to then move between items in the list; press Enter to complete an action.
Inserting and deleting menus and menu items
To insert a new, blank menu or menu item, place the cursor on an existing menu item and do one of the following:
- Click the Insert button
on the toolbar.
- Press the Insert key.
- Right-click and choose Insert (Menu or Menu Item).
Menus are inserted to the left of the selected item on the menu bar, and menu items are inserted above the selected item in the menu list.
To delete a menu item, place the cursor on the menu item you want to delete and do one of the following,
- Click the Delete button
on the toolbar.
- Press the Delete 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 bar
Separator bars insert a line between menu items. You can use separator bars to indicate groupings within the menu list, or simply to provide a visual break in a list.
To insert a separator bar on a menu,
- Select the menu item before which you want a separator, or choose the blank item at the end of a menu.
- Click the Insert Separator button
on the toolbar.
The separator bar is inserted above the selected menu item.
Specifying keyboard shortcuts
Keyboard shortcuts enable the user to perform an action without accessing the menu directly 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 type in.
When you add a shortcut, it appears next to the menu item at runtime.
Disabling (dimming) menu items
You can prevent users from accessing certain menu commands based on a particular state of the current program conditions, 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.
Disabling a menu item is done with the Enabled property for the menu item. As with most properties, you can specify an initial value for Enabled using the Component Inspector. The default state of the menu item is True, and this changes when some event occurs, like the selection of text.
To disable a menu item, select the menu item in the Menu Designer or on the Component Tree and do one of the following:
Creating checkable menu items
To make a menu item checkable, first you need to change the menu item from a regular MenuItem component to a CheckboxMenuItem. A CheckboxMenuItem 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 CheckboxMenuItem, select the menu item and click the Check button
on the toolbar.
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 item into a different menu, no matter what its original position is.
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 new menu.This causes the menu to open, enabling you to drag the item to its new location.
Note: While you are dragging a menu or menu item, the cursor changes shape to indicate whether you can release it at the new location.
- Release the mouse button to drop the menu item at 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.
Organizing your menu structure this way can save vertical screen space. 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 submenu button
on the toolbar.
- Press Ctrl+Right arrow to create the first placeholder.
- Right-click the menu item and choose Create Submenu.
- Type a name for the nested menu item, or drag an existing menu item into this placeholder.
- Press Enter, or Down arrow, to create the next placeholder.
- Repeat steps 3 and 4 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 accelerator or shortcut keys.
To add code to a menu item's actionPerformed event,
- Open the UI Designer on your UI frame.
- Add a MenuBar or PopupMenu component to your UI Frame in the UI Designer. (Alternatively, you can open a file that already contains a menu.)
- Select a menu item in the Menu Designer or the Component Tree.
- In the Inspector, select the Events tab.
- Double-click the actionPerformed value field to create an event-handling method stub 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 browser comes to the top, displaying the source code in the Content pane. The cursor is positioned in the body of the newly created actionPerformed event-handling method, ready for your code entry.
- Inside the open and close braces, enter or edit 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 Borland's Filer file open dialog box when the user chooses File | Open, you would do the following:
- If you do not already have a UI Frame under development, use the Application or Frame Wizard to put one in your project.
- Select the Frame file in the Navigation pane and choose View | Design to open the visual design tools.
- If you don't already have a MenuBar component, click it on the AWT tab of the Component Palette and drop it on the Component Tree .
- On the Dialogs tab of the Component Palette, click the Filer component and drop it on the Component Tree. You should see it appear in the "Others" section of the Component Tree.
- In the Inspector, select the frame property of the Filer component and set it to this. (This is necessary because all the JBuilder dialog components must be attached to a parent frame before they can be shown.)
- In the Component Tree, double-click on the MenuBar to open the Menu Designer.
- Create a File menu with an Open menu item. The example code shown below in step 10 was generated with Open as menuItem1.
- In the Menu Designer, or on the Component Tree, select the Open menu item.
- In the Inspector, select the Events page.
- Double-click the actionPerformed event to generate the following event-handling method stub in the source code, and to automatically have your cursor location positioned in it:
void menuItem1_actionPerformed(java.awt.event.ActionEvent e) {
}
Note: JBuilder will take you to the existing event-handling method if there is one.
- Inside the body of the actionPerformed method, type the following:
filer1.show();
In a real program, you will typically need to add several lines of custom code in the event-handling methods. In this example, 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 in the User's Guide and Creating events in the Component Writers Guide.
To learn about what code JBuilder automatically generates when you add an event, see Code that JBuilder generates to connect events in the User's Guide.
Implementing a PopupMenu
- Click the Design tab in the AppBrowser to put your UI class into Design mode.
- Drop a PopupMenu from the AWT tab of the Component Palette into the Component Tree.
- Double-click on the PopupMenu in the Component Tree to open the Menu Designer.
- Add one or more menu items to the PopupMenu.
- Double click on "this" in the Component Tree to get back to the UI Designer.
- Select the panel or other component to whose event you want the PopupMenu attached so you can see that component in the Inspector. For the example below, bevelPanel1 was selected.
- Click on the Event Tab in the Inspector.
- Double-click on the event for which you want the PopupMenu to appear. For the example below, the MouseClicked event was selected.
- Edit your event-handler stub to resemble the following:
void bevelPanel1_mouseClicked(java.awt.event.MouseEvent e) {
bevelPanel1.add(popupMenu1); // PopupMenu 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) { // because e.isPopupTrigger() isn't working in 1.1.2 WinAWT
// Make the PopupMenu visible relative to the current mouse position in the container.
popupMenu1.show(bevelPanel1, e.getX(), e.getY());
}
}
- Add event handlers to the PopupMenu's menu items as needed for your app