Building a new menu

This section describes how to build menus that are not based on existing menus. To create a new menu using inheritance, see Using inheritance to build a menu.

Creating a new menu

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

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 and displays the Tree Menu view and the WYSIWYG view for defining the menu, and the General and Appearance tab pages for setting menu and toolbar properties. For information about menu and toolbar properties, see Defining the appearance and behavior of menu items.

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

Font size of the menu bar and menu text

You can change the value of the TextSize property for submenu items, but not for the main menu bar. The main menu bar has a fixed height that you cannot change.

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:

  • To the menu bar

  • To a drop-down menu

  • To a cascading menu

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.

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.

Prefix might be different

The default prefix is different if it has been changed in the Design>Options dialog box.

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

Duplicate menu item names

Menu items in the Tree Menu view and WYSIWYG Menu view can have the same names, but they cannot have the same name in the Properties view. If you try to add a menu item using 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 that PowerBuilder assigns to the menu item is locked.Even if you later change the text that displays for the menu item, PowerBuilder does not rename the menu item. This allows you to 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.)

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

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.

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:

  • Select File and select Insert>Menu Item At End

    A new item is added to the menu bar after the File menu.

  • Select Open and select Insert>Menu Item

    A new item is added to the File menu above Open.

  • Select Open and select Insert>Menu Item At End

    A new item is added to the File menu after Exit.

  • Select Open and select Insert>Submenu Item

    A new cascading menu is added to the Open menu item.

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 add multiple items to the menu bar quickly.

To insert the first menu bar item in a new menu

  1. Select the first menu item, and then select Insert>Submenu Item from the PowerBuilder menu bar.

    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.

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.

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.

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.

  3. PowerBuilder displays an empty box.

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

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

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

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.

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.

To insert an item in any existing menu

  1. Select the item that should follow the new menu item.

  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.

To create a line between items on a menu

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

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

    A separation line displays.


Duplicating menu items

You might 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 might be able to modify a long script slightly to make it work for your duplicate menu item.

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

It is often necessary 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.

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.

  2. Select the item and open the general page in the Properties view.

  3. 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 multiple menu items to move them, delete them, or change their common properties.

To select multiple individual menu items

  • Press Ctrl and select each item you want.

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

  • 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.

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.

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 to indicate where to drop the item.

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

    The menu item displays in the new location.

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

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.

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.

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 of up to 40 characters. For information about PowerBuilder identifiers, see the the section called “Identifier names” in 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.