PowerBuilder 9.0 Index Page / PowerBuilder User's Guide / Working with Windows / Chapter 13 Working with Menus / Building a new menu


Building a new menu

This section describes how to build menus from scratch. You will use this technique to create menus that are not based on existing menus. For how to create a new menu using inheritance, see "Using inheritance to build a menu ".

You build a new menu by creating a new Menu object and then working on it in the Menu painter.

Creating a new menu

Steps To create a new menu:

  1. Click the New button in the PowerBar.

  2. On the PB Object tab page, select Menu.

  3. Click OK.

    The Menu painter opens. Because you are creating a new menu and have not added menu items yet, the only content in the WYSIWYG and Tree Menu views is an untitled top-level tree view item in the TreeMenu view.


Working with menu items

A menu consists of at least one menu item on the menu bar and menu items in a drop-down menu. You can add menu items in three places:

Note Using the pop-up menu The procedures in this section use the Insert and Edit menus on the PowerBuilder main menu to insert and edit menu items. You can also use the equivalent items on the selected object's pop-up menu.

Inserting menu items

There are three choices on the Insert menu: Menu Item, Menu Item At End, and Submenu Item. Use the first two to insert menu items in the same menu as the selected item, and use Insert>Submenu Item to create a new drop-down or cascading menu for the selected item.

For example, suppose you have created a File menu on the menu bar with two menu items: Open and Exit. Here are the results of some insert operations:

Getting the menu started

The first thing you do with a new menu is add the first item to the menu bar. After doing so, you can continue adding new items to the menu bar or to the menu bar item you just created. As you work, the changes you make display in both the WYSIWYG and Tree Menu views.

The first procedure in this section describes how to add a single first item to the menu bar. Use this procedure if you want to add the menu bar item and then work on its drop-down menu. Use the second procedure to quickly add multiple items to the menu bar.

Steps To insert the first menu bar item in a new menu:

  1. Select Insert>Submenu Item.

    PowerBuilder displays an empty box on the menu bar in the WYSIWYG Menu view and as a sub item in the Tree Menu view.

  2. Type the text you want for the menu item and press Enter.


Steps To insert multiple menu bar items in a new menu:

  1. Select Insert>Submenu Item.

    PowerBuilder displays an empty box on the menu bar in the WYSIWYG Menu view and as a submenu item in the Tree Menu view.

  2. Type the text you want for the menu item and press Tab.

    PowerBuilder displays a new empty box on the menu bar in the WYSIWYG Menu view and as a submenu item in the Tree Menu view.

  3. Repeat step 2 until you have added all the menu bar items you need.

  4. Press Enter to save the last menu bar item.


Adding additional menu items

After you have created the first menu bar item, you can add more items to the menu bar or start building drop-down and cascading menus.

Steps To insert additional menu items on the menu bar:

  1. Do one of the following:
    • With any menu bar item selected, select Insert>Menu Item At End to add an item to the end of the menu bar.
    • Select a menu bar item and select Insert>Menu Item to add a menu bar item before the selected menu bar item.


  2. Type the text you want for the menu bar item and then press Enter.


Steps To add a drop-down menu to an item on the menu bar:

  1. Select the item in the menu bar for which you want to create a drop-down menu.

  2. Select Insert>Submenu Item.

    PowerBuilder displays an empty box.

  3. Type the text you want for the menu item and then press Tab.

  4. Repeat Step 3 until you have added all the items you want on the drop-down menu.

  5. Press Enter to save the last drop-down menu item.


Steps To add a cascading menu to an item in a drop-down menu:

  1. Select the item in a drop-down menu for which you want to create a cascading menu.

  2. Select Insert>Submenu Item.

    PowerBuilder displays an empty box.

  3. Type the text you want for the menu item and then press Tab.

  4. Repeat step 3 until you have added all the items you want on the cascading menu.

  5. Press Enter to save the last cascading menu item.


Steps To add an item to the end of any menu:

  1. Select any item on the menu.

  2. Select Insert>Menu Item At End.

    PowerBuilder displays an empty box.

  3. Type the text you want for the second menu item in the box and press Enter.


Steps To insert an item in any existing menu:

  1. Select the item before which the new menu item will display.

  2. Select Insert>Menu Item.

    An empty box displays above the item you selected.

  3. Type the text you want for the menu item and press Enter.


Creating separation lines in menus

You should separate groups of related menu items with lines.

Steps To create a line between items on a menu:

  1. Insert a new menu item where you want the separation line.

  2. Type a single dash (-) as the menu item text and press Enter.

    A separation line displays.




Duplicating menu items

You may find that you save time creating new menu items if you duplicate existing menu items. A duplicate menu item has the same properties and script as the original menu item. You may be able to slightly modify a long script to make it work for your duplicate menu item.

Steps To duplicate a menu item or a submenu item:

  1. Select the menu item or the submenu item to duplicate.

  2. Select Edit>Duplicate or press Ctrl+T.

    The duplicate item displays at the same level of the menu following the item you selected. The name of the duplicate menu item is unique.

  3. Change the text of the duplicate menu item.

  4. Modify the properties and script associated with the duplicate item as needed.


Changing menu item text

You often need to change the text of a menu item, and if you duplicate a menu item, you need to change the text of the duplicate item.

Steps To change the text of a menu item:

  1. Do one of the following:
    • Click the item to select it, then click it again.
    • Select the item and select Edit>Menu Item Text.
    • Select the item and open the general page in the Properties view.


  2. Type the new text for the menu item in the box in the WYSIWYG Menu or Tree Menu view or in the Text box in the Properties view.


Selecting menu items

You can select more than one menu item to move them, delete them, or change their common properties.

Steps To select individual menu items:

  1. Press Ctrl and select each item you want.


Steps To select a range of menu items at the same level in the menu:

  1. Select the first item, press Shift, and select the last item.


Navigating in the menu

As you work in a menu, you can move to another menu item by selecting it. You can also use the Right Arrow, Left Arrow, Up Arrow, and Down Arrow keys on the keyboard to navigate.

Moving menu items

The easiest way to change the order of items in the menu bar or in a drop-down or cascading menu is to drag the item you want to move and drop it where you want it to be. You can drag items at the same level in a menu structure or to another level. For example, you can drag an item in the menu bar to a drop-down menu or an item in a cascading menu to the menu bar.

Note WYSIWYG Menu and Tree Menu views You can use drag and drop within each view. You can also drag from one view and drop in another.

Steps To move a menu item or submenu item using drag and drop:

  1. Select the item.

  2. Press and hold the left mouse button and drag the item to a new location.

    A feedback line appears at the new location that indicates where to drop it.

  3. Release the mouse button to drop the menu item.

    The menu item displays in the new location.


Note Dragging to copy To copy a menu item by dragging it, press and hold the Ctrl key while you drag and drop the item. A copied menu item has the same properties and scripts as the original menu item.

You can also copy or move a menu item by selecting the item and using the Cut, Copy, and Paste items on the Edit menu or the pop-up menu.

Deleting menu items

Steps To delete a menu item:

  1. Select the menu item you want to delete.

  2. Click the Delete button in the PainterBar or select Edit>Delete from the menu bar.


How menu items are named

When you add a menu item, PowerBuilder gives it a default name, which displays in the Name box in the Properties view. This is the name by which you refer to a menu item in a script.

About the default menu item names

The default name is a concatenation of the default prefix for menus, m_, and the valid PowerBuilder characters and symbols in the text you typed for the menu item. If there are no valid characters or symbols in the text you typed for the menu item, PowerBuilder creates a unique name m_n, where n is the lowest number that can be combined with the prefix to create a unique name.

Note Prefix may be different The default prefix is different if it has been changed in the Options dialog box.

The complete menu item name (prefix and suffix) can be up to 40 characters. If the prefix and suffix exceed this size, PowerBuilder uses only the first 40 characters without displaying a warning message.

Duplicate menu item names

If you add a menu item that has the same name as an existing menu item, PowerBuilder displays a dialog box that suggests a unique name for the menu item. For example, you might already have an Options item on the Edit menu with the default name m_options. If you add an Options item to another menu, PowerBuilder cannot give it the name m_options.

Menu item names are locked by default

After you add a menu item, the name PowerBuilder assigns to the menu item is locked. Even if you later change the text that displays for the menu item, PowerBuilder will not rename the menu item. This is so you can change the text that displays in a menu without having to revise all your scripts that reference the menu item (remember, you reference a menu item through the name that PowerBuilder assigns to it).

If you want to rename a menu item after changing the text that displays for it, you can unlock the name.

Steps To have PowerBuilder rename a menu item:

  1. On the General property page in the Properties view, clear the Lock Name check box.

  2. Change the text that displays for the menu item.


Saving the menu

You can save the menu you are working on at any time. When you save a menu, PowerBuilder saves the compiled menu items and scripts in the library you specify.

Steps To save a menu:

  1. Select File>Save from the menu bar.

    If you have previously saved the menu, PowerBuilder saves the new version in the same library and returns you to the Menu painter.

    If you have not previously saved the menu, PowerBuilder displays the Save Menu dialog box.

  2. Name the menu in the Menus box (see "Naming the menu").

  3. Write comments to describe the menu.

    These comments display in the Select Menu dialog box and in the Library painter. It is a good idea to use comments so you and others can easily remember the purpose of the menu later.

  4. Specify the library in which to save the menu and click OK.


Naming the menu

The menu name can be any valid PowerBuilder identifier up to 40 characters. For information about PowerBuilder identifiers, see the PowerScript Reference .

A common convention is to use m_ as a standard prefix, and a suffix that helps you identify the particular menu. For example, you might name a menu used in a sales application m_sales.