Users Guide
Working with Windows

You use two views to specify menu items that display in the menu bar and under menu bar items:

The Tree Menu view and the WYSIWYG Menu view are equivalent. You can use either view to insert new menu items on the menu bar or on drop-down or cascading menus, or to modify existing menu items. The menus in both views change when you make a change in either view.

You specify menu properties in two views:

Views for the top level menu object

This Menu painter layout is for the top level menu object, m_main. The Tree Menu view is in the top left and the WYSIWYG Menu view is in the top middle. The General and Appearance tab pages display in the Properties view on the right. For more information about these properties, see Setting menu style properties for contemporary menus.

Views for submenu items

This Menu painter layout is for a menu item under the top level, in this case the Exit menu item. The Tree Menu view is in the top left and the WYSIWYG Menu view is in the top middle. The General and Toolbar tab pages display in the Properties view on the right. For more information about these properties, see Setting General properties for menu items.

A menu can have a contemporary or traditional style.

Menus that you import or migrate from earlier versions of PowerBuilder have the traditional style, and new menus use the traditional menu style by default. The new contemporary menu style has a three-dimensional menu appearance that can include images and menu title bands. With a contemporary menu, you can set the MenuAnimation, MenuImage, and MenuTitleText at runtime using scripts.

You select a menu style on the Appearance tab of the Properties view for the top-level menu object in the Menu painter. You must select the top-level menu object in the Tree Menu view of the Menu painter to display its Properties view.

Images for menus and toolbars

Contemporary menus can include images. You can use icons, bitmaps, GIF files, and JPEG files for both contemporary menus and traditional and contemporary toolbars.

All stock icons have a transparent background. Other icon and GIF files with transparent backgrounds are always displayed with a transparent background. If you want a bitmap to display with a transparent background, the bitmap must use button face as its background color. This applies whatever the background color of the menu or toolbar is set to. There is currently no property that allows you to specify that an image has a transparent background.

When an icon file includes several images

With the contemporary menu style and toolbar style, when an icon file includes several images, PowerBuilder uses the following image selection rules:

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

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:

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.

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.

This section describes the properties you can set when you select a menu item and then select the General tab page in the Properties view.

Creating MicroHelp and tags

MicroHelp is a brief text description of the menu item that displays on the status bar at the bottom of a Multiple Document Interface (MDI) application window. Type the text you want to display in the MicroHelp box. For examples of MicroHelp text, select an item from a menu in PowerBuilder and look at the text that displays in the status bar.

A tag is a text string that you can associate with an object and use in any way you want.

For information about defining MicroHelp text and tag properties, see the section called “Building an MDI Application” in Application Techniques.

Setting the appearance of a menu item

On the General tab page in the Properties view, you can also specify how a menu item appears at runtime.

The settings you specify here determine how the menu items display by default. You can change the values of the properties in scripts at runtime.

Assigning accelerator and shortcut keys

Every menu item should have an accelerator key, also called a mnemonic access key, which allows users to select the item from the keyboard by pressing Alt+key when the menu is displayed. Accelerator keys display with an underline in the menu item text.

You can also define shortcut keys, which are combinations of keys that a user can press to select a menu item whether or not the menu is displayed.

For example, in the following menu all menu items have accelerator keys: the accelerator key is U for Undo, T for Cut, and so on. New, Undo, Cut, Copy, Paste, and Clear each have shortcut keys: the Ctrl key in combination with another key or keys.

You should adopt conventions for using accelerator and shortcut keys in your applications. All menu items should have accelerator keys, and commonly used menu items should have shortcut keys.

If you specify the same shortcut for more than one MenuItem, the command that occurs later in the menu hierarchy is executed.

Some shortcut key combinations, such as Ctrl+C, Ctrl+V, and Ctrl+X, are commonly used by many applications. Avoid using these combinations when you assign shortcut keys for your application.

Menus with a contemporary style have a three-dimensional menu appearance and can include bitmap and menu title bands. The following figure shows a contemporary style menu:

After you select the contemporary style, you can modify other menu style properties on the top-level menu object and on all lower-level menu items. Since it is important to maintain a consistent look across each menu and toolbar, very few style properties are modifiable at the menu item level.

You can modify menu style properties only at design time. After you select the contemporary menu style for a top-level menu object, you can select values for other style properties to manipulate a menu's visual appearance. The following properties are modifiable for the top-level menu object only; you cannot modify them for individual menu items:

Menu items have style properties that you set at design time. You cannot use these style properties with a traditional style menu. Unlike the style properties on the Menu object that display on the Appearance tab of the Properties view, the fields where you set these properties are located on the General tab of the Properties view for each menu item.

You select or enter values for the menu item style properties on the General tab of the Properties view for each menu item. You can make selections for the MenuAnimation and MenuImage properties only if the MenuBitmaps check box for the current menu object is selected. The MenuBitmaps check box is selected by default for the contemporary menu style.

You can enter text for the MenuTitleText property only if the MenuTitles check box for the current menu object is selected.

Toolbars you add to a window behave like the toolbars provided in the PowerBuilder development environment:

Menus with multiple toolbars

A single menu can have more than one toolbar. When you associate a menu that has multiple toolbars with a window, PowerBuilder displays all the toolbars when you open the window. This screen shows a sheet open in an MDI frame, with one FrameBar and two SheetBars:

You can work with the toolbars independently. For example, you can float any of the toolbars, move them around the window, and dock them at different locations within the window.

The button associated with a menu item can appear on only one toolbar at a time. To indicate which toolbar a menu item's button belongs to, you set the ToolbarItemBarIndex property for the menu item. All items that have the same index number appear on the same toolbar.

PowerBuilder provides an easy way to add toolbars to a window: when you are defining an item in the Menu painter for a menu that will be associated with an MDI frame window, an MDI sheet, or a main window, you simply specify that you want the menu item to display in the toolbar with a specific picture. At runtime, PowerBuilder automatically generates a toolbar for the window containing the menu.

You select a toolbar style on the Appearance tab of the Properties view for the top-level menu object in the Menu painter.

A toolbar can have a contemporary or traditional style.

Toolbars that you import or migrate from earlier versions of PowerBuilder have the traditional style, and new toolbars use the traditional toolbar style by default.

Selecting the toolbar button style property. Unless you are using the traditional toolbar style for the current menu object, you can select the ToolbarAnimation check box on the Toolbar tab or the Properties view for each menu item. If you do not select an image for the ToolbarItemName property of a menu item, the selection you make for the ToolbarAnimation property is ignored.

You can customize the display of toolbars in applications that you create with PowerBuilder by setting toolbar properties.

Toolbar style properties

In addition to customizing the style of a menu, you can customize the style of a toolbar associated with the menu. For example, the following picture shows a contemporary style toolbar with an expanded toolbar cascade and a highlighted Exit button:

Toolbar style properties. Toolbars have style properties that you can change at design time on the top-level menu object. You can modify these properties only if you select contemporarytoolbar! as the toolbar style for the top-level menu object.

Property	Datatype	Use to assign
ToolbarBackColor	Long	Background color of the menu toolbar.
ToolbarGradient	Boolean	Gradient of the menu toolbar background.
ToolbarHighlightColor	Long	Highlight color for the toolbar buttons when they are selected.
ToolbarStyle	Enumerated	Overall style of the menu toolbar. Values are: contemporarytoolbar! and traditionaltoolbar!
ToolbarTextColor	Long	Color of the text in the menu toolbar.

Toolbar item style property. You can select the ToolbarAnimation property for a menu item toolbar button. This property offsets the button image by two pixels to the upper left when a user positions the cursor over the button. You cannot assign this property at the menu object or toolbar level. You must assign it to individual toolbar items (buttons) at design time. This property has a Boolean datatype. You can select it on the Toolbar tab for each menu item below the top-level menu object. With a contemporary menu, you can set the ToolbarAnimation property at runtime at runtime using scripts.

The customizable menu and toolbar styles can be used for MDI and main windows. Pop-up menus can also use menu style properties. The styles do not affect existing PowerBuilder applications that use a traditional style. You can, however, update an existing PowerBuilder application to use the new styleproperties.

Text in button, PowerTip

In the Window painter, you associate the menu with the window on the window's General property page. The window displays the toolbar by default. If you do not want the toolbar to display, clear the ToolbarVisible check box on the window's Toolbar property page. You can also specify the toolbar's alignment and position on this property page.

You can specify global properties for all toolbars in your application on the Toolbar property page in the Application painter or by setting properties of the Application object in a script. Typically you set these in the application's Open event, but you can set them anywhere.

Specifying the text in the toolbar's pop-up menu

By default, PowerBuilder provides a pop-up menu for the toolbar, which users can use to manipulate the toolbar. It is similar to the pop-up menu you use to manipulate the PowerBar and PainterBar.

You can change the text that displays in this menu, but you cannot change the functionality of the menu items in the menu. Typically, you do this when you are building an application in a language other than English.

You change the text as follows:

Menu items have the following events:

About the Clicked event

The Clicked event is triggered whenever:

About the Help event

The Help event is triggered when the user presses F1 or clicks the context Help button [?] on a window's title bar and then points and clicks on a menu item.

About the Selected event

The Selected event is triggered when the user selects a menu item.

You can use functions and variables in your scripts.

Using functions

PowerBuilder provides built-in functions that act on menu items. You can use these functions in scripts to manipulate menu items at runtime. For example, to hide a menu, you can use the built-in Hide function.

For a complete list of the menu-level built-in functions, look at the Function List view or use the Browser.

Using variables

Scripts for menu items have access to all global variables declared for the application. You can also declare local variables, which are accessible only in the script where they are declared.

You can declare instance variables for the menu when you have data that needs to be accessible to scripts in several menu items in a menu. Instance variables are accessible to all menu items in the menu.

For a complete description of variables and how to declare them, see the the section called “Declaring variables” in PowerScript Reference.

Defining menu-level structures

If you need to manipulate a collection of related variables, you can define menu-level structures using the Structure view. You do this by displaying the Structure List view and then selecting Add from the pop-up menu. The Structure and Structure List views are not part of the default layout.

For more information, see Working with Structures.

You can refer to any object in the application in scripts for menu items. You must fully qualify the reference, using the object name, as follows.

Referring to windows

When referring to a window, you simply name the window. When referring to a property in a window, you must always qualify the property with the window's name:

window.property

For example, this statement moves the window w_cust from within a menu item script:

w_cust.Move(300, 300)

This statement minimizes w_cust:

w_cust.WindowState = Minimized!

You can use the reserved word ParentWindow to refer to the window that the menu is associated with at runtime. For example, the following statement closes the window the menu is associated with:

Close(ParentWindow)

You can also use ParentWindow to refer to properties of the window a menu is associated with, but not to refer to properties of controls or user objects in the window.

For example, the following statement is valid, because it refers to properties of the window itself:

ParentWindow.Height = ParentWindow.Height/2

But the following statement is invalid, because it refers to a control in the window:

ParentWindow.sle_result.Text = "Statement invalid"

Referring to controls and user objects in windows

When referring to a control or user object, you must always qualify the control or user object with the name of the window:

window.control.property

window.userobject.property

For example, this statement enables a CommandButton in window w_cust from a menu item script:

w_cust.cb_print.Enabled = TRUE

Referring to menu items

When referring to a menu item, use this syntax:

menu.menu item
menu.menu item.property

When referring to a menu item in a drop-down or cascading menu, you must specify each menu item on the path to the menu item you are referencing, separating the names with periods.

For example, to place a check mark next to the menu item m_bold, which is on a drop-down menu under m_text in the menu saved in the library as m_menu, use this statement:

m_menu.m_text.m_bold.Check( )

If the previous script is for a menu item in the same menu (m_menu), you do not need to qualify the menu item with the name of the menu:

m_text.m_bold.Check( )

When you build and save a menu, PowerBuilder treats the menu as a unit that includes:

What you can do

You can do the following in a descendant menu:

What you cannot do

You cannot do the following in a descendant menu:

About menu item names in a descendant

PowerBuilder uses the following syntax to show names of inherited menu items:

AncestorMenuName::MenuItemName

For example, in a menu inherited from m_update_file, you see m_update_file::m_file for the m_file menu item, which is defined in m_update_file.

The inherited menu item name is also locked, so you cannot change it.

Understanding inheritance

The issues concerning inheritance with menus are similar to the issues concerning inheritance with windows and user objects. For information, see Understanding Inheritance.

Modifying the ShiftToRight property

When defining a descendant menu, you might want to insert menu items in the middle of the menu bar or in the middle of a drop-down or cascading menu. To do this, you set the ShiftToRight property in a menu item's Properties view on the General property page.

If the ancestor menu has no menu items with ShiftToRight set, you can add a new menu item to the end of the descendant menu. To add new menu items elsewhere in the menu, set the ShiftToRight property for the descendant menu items that will follow the new menu item.

The ShiftToRight property is used for menu items on the menu bar (where items need to shift right if a new item is inserted) and for menu items in a drop-down or cascading menu (where items might need to shift down if a new item is inserted). The property name is ShiftToRight, but it means shift down in drop-down or cascading menus.

Where you set the ShiftToRight property

You set the ShiftToRight property in an ancestor menu only if you know that you will always want a group of menu items to shift right (or down) when you inherit from the menu and add a new menu item. For example, if you have File, Edit, Window, and Help menus on the menu bar, set the ShiftToRight property for the Window and Help menu items if you are going to inherit from this menu, because Window and Help are usually the last items on a menu bar.

Where you can insert menu items in a descendant menu

In a descendant menu, a group of menu items can be one of four types. Each type has an insertion rule.

The Example with no ShiftToRight in ancestor and the Example with ShiftToRight in ancestor demonstrate some of these rules.

How to insert menu items in a descendant menu

If you can insert a menu item in a descendant menu, the Insert Menu Item option on the Insert menu and the pop-up menu is enabled. The Insert Menu Item is enabled if ShiftToRight is set in the selected item that will follow the item you are inserting and all menu items following it.

To insert a menu item in a descendant, you use the same method you use to insert an item in a new menu, whether the menu item is on the menu bar or on a drop-down or cascading menu. For information about inserting menu items, see Working with menu items.

The following examples illustrate where you can insert menu items in a descendant menu and demonstrate the rules that govern where you can insert them.

Example with no ShiftToRight in ancestor

Suppose you have a menu with File, Edit, Window, and Help items on the menu bar. The menu is inherited from an ancestor frame menu with no items set as ShiftToRight in the ancestor.

Here is how you might add some new menu items. Since ShiftToRight is not set anywhere at first, you can add a menu item only to the end.

Select any item in the menu bar and select Insert>Menu Item At End.

Name the new menu item New1 and press Enter.

The New1 menu item is added to the right of the Help menu.

Now add a new Menu item before the New1 menu item. You can do this without setting ShiftToRight on New1, because New1 is a new menu item in the inherited menu.

Select Insert Menu Item from the pop-up menu for New1.

Name the new menu item New2 and press Enter.

Now add a new Menu item before the Help menu item. You cannot do this unless you set ShiftToRight on the Help menu item, the New2 Menu item, and the New1 menu item, because Help is an inherited menu item without ShiftToRight set in the ancestor menu. For Help to shift right, New2 and New1 must also be able to shift right.

Select the Help menu item and in the Properties view, select the ShiftToRight property, and then do the same for New1 and New2.

Now you can add a new menu item before the Help menu item.

Select the Help menu item, then select Insert New Item from the pop-up menu, name the new item New3, and then press Enter.

If you want to add a new Menu item before the New3 menu item, you can do it without setting ShiftToRight on New3, because New3 is a new menu item and ShiftToRight is set in all items that follow.

However, if you want to add a new menu item before the Window menu item, you cannot do this by working only in the descendant menu because the Window menu item is an ancestor menu item and ShiftToRight is not set in the ancestor. To be able to do this, you must set Window as ShiftToRight in the ancestor.

Example with ShiftToRight in ancestor

In this example, the inherited menu has the same four menu bar items, but ShiftToRight has been set in the Window and Help menu items in the ancestor menu. Suppose you want to insert a new menu item before the Help menu item and the Window menu item.

Select the Help menu item and display the pop-up menu.

The Insert Menu Item option is disabled because the Help item is not the first item in a group of ancestor menu items (Window and Help) with ShiftToRight set in the ancestor.

Select the Window menu item and display the pop-up menu.

The Insert Menu Item option is enabled because the Window item is the first item in a group of ancestor menu items with ShiftToRight set in the ancestor.

Select Insert Menu Item At End from the pop-up menu to insert a new menu item after Help, name it New1, and press Enter.

The New1 item's ShiftToRight property is set automatically.

Now the Window, Help, and New1 items are set ShiftToRight. You can insert a new item before Window and New1, but not before Help. This is because the Window and Help menu items are a group for which ShiftToRight is set in the ancestor.

You cannot insert a new item before the Edit menu item because Edit is in a group (File and Edit) that are inherited items with no ShiftToRight set in the ancestor.

Select the Edit menu item, select ShiftToRight in the Properties view, and then add a new menu item.

You could also have set the ShiftToRight property in the ancestor menu, but it is easier to work just in the descendant.

To have a menu bar display when a window is opened by a user, you associate a menu with the window in the Window painter.

Identifying menu items in window scripts

You reference menu items in scripts in windows and controls using the following syntax:

menu.menu item

You must always fully qualify the menu item with the name of the menu.

When referring to a menu item in a drop-down or cascading menu, you must specify each menu item on the path to the menu item you are referencing, separating the names with periods.

For example, to refer to the Enabled property of menu item m_open, which is under the menu bar item m_file in the menu saved in the library as m_menu, use:

m_menu.m_file.m_open.Enabled

Changing a window's menu at runtime

You can use the ChangeMenu function in a script to change the menu associated with a window at runtime.

To display a pop-up menu in a window, use the PopMenu function to identify the menu and the location at which you want to display the menu.

If the menu is associated with the window

If the menu is currently associated with the window, you can simply call the PopMenu function.

The following statement in a CommandButton script displays m_appl.m_help as a pop-up menu at the current pointer position, assuming menu m_appl is already associated with the window:

m_appl.m_help.PopMenu(PointerX(), PointerY())

If the menu is not associated with the window

If the menu is not already associated with the window, you must create an instance of the menu before you can display it as a pop-up menu.

The following statements create an instance of the menu m_new, then pop up the menu mymenu.m_file at the pointer location, assuming m_new is not associated with the window containing the script:

m_new mymenu
mymenu = create m_new
mymenu.m_file.PopMenu(PointerX(), PointerY())