Menu object

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 a pop-up menu.

PocketBuilder provides a Menu system object that is 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.

Smartphone platforms On Smartphone devices, the main menu bar must contain exactly two menu bar items. Although you can add as many cascading menu items as you want, typically nine menu items is the maximum you can fit on a Smartphone platform screen at one time. Shortcut keys and tool tips are not supported.

Many of the properties and functions do not work on a Smartphone platform for a menu while it is loaded, however, you can use these same properties and functions to modify the menu when it is not the current menu or you can use the window object ChangeMenu function to replace the current window’s menu.

Properties

Menu property	Datatype	Description
Checked	Boolean	Specifies whether the Menu object is selected. The state of the checked property will be 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	Not supported in PocketBuilder. 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 will be reflected in the toolbar button. Values are: TRUE – Object is enabled FALSE – Object is not enabled
Item[ ]	Menu	Specifies the Menu objects under a Menu object.
MenuItemType	MenuItemType (enumerated)	Not supported in PocketBuilder. Allows you to identify special Menu objects that are used differently on different platforms. Values are: MenuItemTypeAbout! MenuItemTypeExit! MenuItemTypeHelp! MenuItemTypeNormal!
MergeOption	MenuMerge Option (enumerated)	Not supported in PocketBuilder. 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 the chapter on using OLE in Application Techniques in the PowerBuilder documentation set.
MicroHelp	String	Not supported in PocketBuilder. Specifies the text of the MicroHelp for the object.
ParentWindow	Window	Specifies the window that owns the Menu object.
ShiftToRight	Boolean	Not supported on Smartphone platforms. Specifies whether the Menu object shifts down or to the right when other Menu objects are added in a descendent menu. Values are: TRUE – Object shifts to right FALSE – Object shifts down
Shortcut	Integer	Not supported in PocketBuilder. Specifies the shortcut key for the Menu object. This property should only be set 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.
ToolbarItemDown	Boolean	Not supported in PocketBuilder. 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.
ToolbarItemDown Name	String	Not supported in PocketBuilder. Specifies the name of the toolbar icon associated with the Menu object when it is down.
ToolbarItemBar Index	Integer	Not supported in PocketBuilder. 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.
ToolbarItemName	String	Not supported in PocketBuilder. Specifies the name of a stock toolbar picture that you want to represent an item in the toolbar or a string containing the name of a bitmap file.
ToolbarItemOrder	Integer	Not supported in PocketBuilder. Specifies the order of the item in the toolbar.
ToolbarItemSpace	Integer	Not supported in PocketBuilder. Specifies the amount of empty space before the item in the toolbar.
ToolbarItemText	String	Not supported in PocketBuilder. Specifies the text that displays in the toolbar item when the display text option is on for toolbars.
ToolbarItemVisible	Boolean	Not supported in PocketBuilder. Specifies whether the toolbar item displays. Values are: TRUE – The toolbar item is visible FALSE – The toolbar item is not visible
Visible	Boolean	Specifies whether the Menu object is visible. Values are: TRUE – Object is visible FALSE – Object is not visible

Menu property

Datatype

Description

Checked

Boolean

Specifies whether the Menu object is selected. The state of the checked property will be 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

Not supported in PocketBuilder.

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 will be reflected in the toolbar button. Values are:

TRUE – Object is enabled
FALSE – Object is not enabled

Item[ ]

Specifies the Menu objects under a Menu object.

MenuItemType

MenuItemType (enumerated)

Not supported in PocketBuilder.

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

MenuItemTypeAbout!
MenuItemTypeExit!
MenuItemTypeHelp!
MenuItemTypeNormal!

MergeOption

MenuMerge Option (enumerated)

Not supported in PocketBuilder.

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 the chapter on using OLE in Application Techniques in the PowerBuilder documentation set.

MicroHelp

String

Not supported in PocketBuilder.

Specifies the text of the MicroHelp for the object.

ParentWindow

Window

Specifies the window that owns the Menu object.

ShiftToRight

Boolean

Not supported on Smartphone platforms.

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

TRUE – Object shifts to right
FALSE – Object shifts down

Shortcut

Integer

Not supported in PocketBuilder.

Specifies the shortcut key for the Menu object. This property should only be set 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.

ToolbarItemDown

Boolean

Not supported in PocketBuilder.

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.

ToolbarItemDown Name

String

Not supported in PocketBuilder.

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

ToolbarItemBar Index

Integer

Not supported in PocketBuilder.

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.

ToolbarItemName

String

Not supported in PocketBuilder.

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

ToolbarItemOrder

Integer

Not supported in PocketBuilder.

Specifies the order of the item in the toolbar.

ToolbarItemSpace

Integer

Not supported in PocketBuilder.

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

ToolbarItemText

String

Not supported in PocketBuilder.

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

ToolbarItemVisible

Boolean

Not supported in PocketBuilder.

Specifies whether the toolbar item displays. Values are:

TRUE – The toolbar item is visible
FALSE – The toolbar item is not visible

Visible

Boolean

Specifies whether the Menu object is visible. Values are:

TRUE – Object is visible
FALSE – Object is not visible

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.

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.

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.