Menu object

In PowerBuilder, you use the Menu painter to create menus and toolbars. Typically, menus are lists of items (usually commands or options) that a user can select in the currently active window. Menus can display in a menu bar, in a drop-down or cascading menu, or as pop-up menus. A toolbar is associated with a menu, and its toolbar buttons act as shortcuts for choosing items from the menu.

PowerBuilder provides a Menu system object used to develop menus. A Menu object can contain other Menu objects that appear, for example, as the items in a drop-down or cascading menu. When the user clicks a Menu object, a Clicked event is triggered. If there is a drop-down or cascading menu under the clicked object, the script for the Clicked event for the object is executed, and then the menu displays. If there is no menu under the object, the script for the Clicked event for the object is executed.

Menus that you import or migrate from earlier versions of PowerBuilder use the Traditional menu style by default. Menus with a Contemporary style have a three-dimensional menu appearance similar to those in Microsoft Office 2003 and Visual Studio 2005, and can include bitmap and menu title bands.

Properties

Menu property

Datatype

Description

BitmapBackColor

Long

Background color of the bitmap band of the menu. (Default is silver.)

BitmapGradient

Boolean

Background of the bitmap band to a gradient style.

Checked

Boolean

Specifies whether the Menu object is selected. The state of the checked property is reflected in the toolbar button. Values are:

TRUE -- Object is selected.

FALSE -- Object is not selected.

ClassDefinition

PowerObject

An object of type PowerObject containing information about the class definition of the object or control.

Default

Boolean

Specifies whether the menu item is the default and appears in a bold typeface. Only one item within a menu should be set to default.

In context menus, the Default property is used to indicate the action that would have been performed if the user had double-clicked on the object rather than right-clicked on it.

The property is also used to indicate which operation would have been performed if the item had been dragged with the left mouse button rather than the right mouse button.

Values are:

TRUE  -- Menu item is bolded.

FALSE -- Menu item is not bolded.

Enabled

Boolean

Specifies whether the Menu object is enabled (can be clicked). The state of the enabled property is reflected in the toolbar button. Values are:

TRUE -- Object is enabled.

FALSE -- Object is not enabled.

FaceName

String

Font face name.

Italic

Boolean

Italic font.

Item[ ]

Menu

Specifies the Menu objects under a Menu object.

MenuAnimation

Boolean

Visual sizing cue to the menu item bitmap when the associated menu item is selected. This property is ignored if the MenuImage property is not assigned.

MenuBackColor

Long

Background color of the menu.

MenuBitmaps

Boolean

Bitmap band for the menu.

MenuHighlightColor

Long

Menu highlight color. The default is the default Windows highlight color.

MenuImage

String

Bitmap image to be used with the menu item. This property is ignored if the MenuBitmaps property for the menu object is not selected or is set to false. If you change MenuImage at runtime, the height of the image does not change, therefore you should avoid assigning a larger or smaller bitmap dynamically.

MenuItemType

MenuItemType (enumerated)

Allows you to identify special Menu objects that are used differently on different platforms. Values are:

MenuItemTypeAbout!

MenuItemTypeExit!

MenuItemTypeHelp!

MenuItemTypeNormal!

MenuStyle

MenuStyle (enumerated)

Overall menu style. Values are: contemporarymenu! and traditionalmenu!

MenuTextColor

Long

Menu text color. (Default is the Windows menu text color.)

MenuTitles

Boolean

Menu title band.

MenuTitleText

String

Label for a menu item that has a cascading submenu. The label text is set vertically in a column to the left of the submenu items and the bitmaps for submenu items, if any. If the vertical label text is longer than the height of all the submenu items, the label text is cut from the end. This property is ignored if the MenuTitles property for the menu object is not selected.

MergeOption

MenuMergeOption (enumerated)

Specifies how the object is affected when an OLE object is activated. Values are:

EditMenu!

Exclude!

FileMenu!

HelpMenu!

Merge!

WindowMenu!

For more information about MergeOption, see Using OLE in an Application in Application Techniques.

MicroHelp

String

Specifies the text of the MicroHelp for the object.

ParentWindow

Window

Specifies the window that owns the Menu object.

ShiftToRight

Boolean

Specifies whether the Menu object shifts down or to the right when other Menu objects are added in a descendant menu. Values are:

TRUE -- Object shifts to right.

FALSE -- Object shifts down.

Shortcut

Integer

Specifies the shortcut key for the Menu object. This property should be set only in the Menu painter. It cannot be set at runtime.

Tag

String

Specifies the tag value assigned to the Menu object.

Text

String

Specifies the text in the Menu object.

TextSize

Integer

Font character size in points for menu items. This property does not apply to the Traditional menu style, and it does not apply to the main menu bar, which has a fixed height of 8 points.

TitleBackColor

Long

Background color of the title panel.

TitleGradient

Boolean

Background gradient style for the title panel.

ToolbarAnimation

Boolean

Specifies animation for the toolbar image. You can select the ToolbarAnimation check box on the Toolbar tab in the Properties view for each menu item unless you are using the traditional toolbar style for the current menu object. 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.

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.

ToolbarItemBarIndex

Integer

Specifies which toolbar the Menu object is on when multiple toolbars exist. If setting this index results in the object being the first item on a new toolbar, the toolbar is implicitly created. If setting this index results in emptying a toolbar, the toolbar is implicitly destroyed.

ToolbarItemDown

Boolean

Specifies how the toolbar button appears. Values are:

TRUE -- Toolbar button appears down.

FALSE -- Toolbar button appears up.

This property is automatically reset when any button is pressed using the mouse.

ToolbarItemDownName

String

Specifies the name of the toolbar icon associated with the Menu object when it is down.

ToolbarItemName

String

Specifies the name of a stock toolbar picture you want to use to represent an item in the toolbar or a string containing the name of a bitmap file.

ToolbarItemOrder

Integer

Specifies the order of the item in the toolbar.

ToolbarItemSpace

Integer

Specifies the amount of empty space before the item in the toolbar.

ToolbarItemText

String

Specifies the text that displays in the toolbar item when the display text option is on for toolbars.

ToolbarItemVisible

Boolean

Specifies whether the toolbar item displays. Values are:

TRUE -- The toolbar item is visible.

FALSE -- The toolbar item is not visible.

If any toolbar item has a ToolbarItemName assigned, an empty toolbar displays even if this property has been set to false for all toolbar items. To control display of the toolbar, use the ToolbarVisible property of the window.

ToolbarStyle

ToolbarStyle (enumerated)

Overall style of the menu toolbar. Values are: contemporarytoolbar! and traditionaltoolbar!

ToolbarTextColor

Long

Color of the text in menu toolbar.

Underline

Boolean

Underline font.

Visible

Boolean

Specifies whether the Menu object is visible. Values are:

TRUE -- Object is visible.

FALSE -- Object is not visible.

Weight

Integer

Font weight.


Events

Menu event

Occurs

Clicked

When the Menu object is clicked (selected or unselected)

Help

When the user presses the F1 key or drags the context help button (question mark) from the title bar to a menu item or control

Selected

When the user moves to the Menu object using the arrow keys or the mouse


Functions

Menu function

Datatype returned

Description

Check

Integer

Displays a check mark next to the Menu object and sets the Checked property.

ClassName

String

Returns the class of the Menu object.

Disable

Integer

Disables (and grays) the Menu object so that it cannot be selected and unsets the Enabled property.

Enable

Integer

Enables the Menu object so that it can be selected and displays it normally (not grayed) and sets the Enabled property.

GetContextService

Integer

Creates a reference to a context-specific instance of the specified service.

GetParent

PowerObject

Returns a reference to the name of the parent object.

Hide

Integer

Makes the Menu object invisible.

PopMenu

Integer

Displays the Menu object at the specified location.

PostEvent

Integer

Adds an event to the end of the message queue for the Menu object.

Show

Integer

Makes the Menu object visible.

TriggerEvent

Integer

Triggers a specified event in the Menu object and executes the script for the event.

TypeOf

Object

Returns the type of the control.

Uncheck

Integer

Removes the check mark next to the Menu object and sets the Checked property to FALSE.