Designing menus

This chapter 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 terminology and menu components

Menu terminology

The basic parts of a menu are referred to using the following terms:

The following diagram demonstrates the menu terminology used in Borland JBuilder:

Menu terminology

Types of menu components

There are two types of menu components on the Component Palette: a MenuBar and a PopupMenu (local context menu). Both kinds of controls contain menu items which can be inspected by the 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 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:
 
ToolAction
 
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 CommandAction
Insert (Menu or Menu Item)Inserts a placeholder for a new menu or menu item entry above or to the left of the cursor
DeleteDeletes the selected menu or menu item (and all its sub-items, if any).
Insert submenuCreates a placeholder for a new submenu entry at a nested level and adds an arrow to the right of the selected menu item.
Disable/EnableToggles the Enabled property of the selected menu item between enabled and disabled, and dims it when it is disabled.
Make it checkableMakes the menu item checkable.


Creating a new 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:

To add a menu component to the UI,

  1. Select the UI frame file in the Navigation Pane.
  2. Click the Design tab at the bottom of the AppBrowser.
  3. Select your main UI frame in the UI Designer or in the Component Tree.
  4. 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). (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,
  1. Click the Design tab to open the UI Designer, if it isn't already open.
  2. 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.
  1. In the Menu Designer, select the position on the menu bar or in a menu where you want to enter a new menu item.
  2. 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.
  3. 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.
  4. 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:

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,

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,

  1. Select the menu item before which you want a separator, or choose the blank item at the end of a menu.
  2. 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,

  1. Select the menu item in the Menu Designer or in the Component Tree.
  2. 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 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. 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:

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,

  1. 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.
  2. 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,
  1. Select the menu item for which you want to create a submenu and do one of the following:
  2. Type a name for the nested menu item, or drag an existing menu item into this placeholder.
  3. Press Enter, or Down arrow, to create the next placeholder.
  4. Repeat steps 3 and 4 for each item you want to create in the nested menu.
  5. 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,

  1. Open the UI Designer on your UI frame.
  2. 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.)
  3. Select a menu item in the Menu Designer or the Component Tree.
  4. In the Inspector, select the Events tab.
  5. 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.

  6. 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:
  1. If you do not already have a UI Frame under development, use the Application or Frame Wizard to put one in your project.
  2. Select the Frame file in the Navigation pane and choose View | Design to open the visual design tools.
  3. 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 .
  4. 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.
  5. 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.)
  6. In the Component Tree, double-click on the MenuBar to open the Menu Designer.
  7. Create a File menu with an Open menu item. The example code shown below in step 10 was generated with Open as menuItem1.
  8. In the Menu Designer, or on the Component Tree, select the Open menu item.
  9. In the Inspector, select the Events page.
  10. 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.

  11. 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 Attaching event-handling code to a component event in the "Working with events" chapter of this book and "Working with events" in the Component Writers Guide.

    To learn about what code JBuilder automatically generates when you add an event, see the section called Code that JBuilder generates to connect events.


Implementing a PopupMenu

  1. Click the Design tab in the AppBrowser to put your UI class into Design mode.
  2. Drop a PopupMenu from the AWT tab of the Component Palette into the Component Tree.
  3. Double-click on the PopupMenu in the Component Tree to open the Menu Designer.
  4. Add one or more menu items to the PopupMenu.
  5. Double click on "this" in the Component Tree to get back to the UI Designer.
  6. 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.
  7. Click on the Event Tab in the Inspector.
  8. Double-click on the event for which you want the PopupMenu to appear. For the example below, the MouseClicked event was selected.
  9. 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());
        }
      }
    
  10. Add event handlers to the PopupMenu's menu items as needed for your application.