Object Model Reference for GUI Testing > Standard Windows > BuildMenuPath Method

WinMenu Object

Description

A Windows menu.

IMPORTANT

Operations

The sections below list the built-in methods and properties that you can use as operations for the WinMenu object.

Methods

Method BuildMenuPath Returns the path of the specified menu item.
Common Method CaptureBitmap Saves a screen capture of the object as a .png or .bmp image using the specified file name.
Common Method Check Checks whether the actual value of an item matches the expected value.
Method CheckItemProperty Checks whether the specified item property achieves the specified value within the specified timeout.
Common Method CheckProperty Checks whether the specified object property achieves the specified value within the specified timeout.
Common Method ChildObjects Returns the collection of child objects contained within the object.
Method GetItemProperty Returns the current value of the specified property for the specified menu item.
Common Method GetROProperty Returns the current value of the description properties from the object in the application.
Common Method GetTOProperties Returns the collection of properties and values used to identify the object.
Common Method GetTOProperty Returns the value of the specified description properties from the test object description.
Common Method Output Retrieves the current value of an item and stores it in a specified location.
Common Method RefreshObject Instructs UFT to re-identify the object in the application the next time a step refers to this object.
Method Select Selects the specified item in the menu.
Common Method SetTOProperty Sets the value of the specified description properties in the test object description.
Common Method ToString Returns a string that represents the test object.
Method WaitItemProperty Waits until the specified item property achieves the specified value or exceeds the specified timeout before continuing to the next step.
Common Method WaitProperty Waits until the specified object property achieves the specified value or exceeds the specified timeout before continuing to the next step.

Properties

Common Property Exist Checks whether the object currently exists in the open application.
Property ExpandMenu Indicates whether to expand the menu when retrieving menu item properties.

 

Back to top

BuildMenuPath Method

Description

Returns the path of the specified menu item.

Syntax

object.BuildMenuPath ()

Return Type

A String value.

Parameters

Args

The menu item. The item's logical name, full path, or numeric index can denote the item. Index values begin with 1. For a full path, separate items with commas.

IMPORTANT

Tip: You can use this method to help you to create the value for the Item argument for the Select, CheckItemProperty, GetItemProperty, and WaitItemProperty methods in the correct format.
 
For example, if you want to select the View->Toolbars->Formatting menu item and you are not sure how to pass it to the Select method, you can use
ItemPath = Window("Some Window").WinMenu("Menu").BuildMenuPath("View","Toolbars","Formatting")
Window("Some Window").WinMenu("Menu").Select ItemPath
You can also specify the index of a particular menu item instead of the label. For example:
ItemPath = Window("Some Window").WinMenu("Menu").BuildMenuPath(3, 2, 2)
or
ItemPath = Window("Some Window").WinMenu("Menu").BuildMenuPath(3, "Toolbars", "Formatting")

Example


 

Back to top

CheckItemProperty Method

Description

Checks whether the specified item property achieves the specified value within the specified timeout.

Syntax

object.CheckItemProperty (Item, PropertyName, PropertyValue, [TimeOut])

Arguments

Parameter Description
Item Required. A String value.
The item name (with quotes) can denote the item.
PropertyName Required. A String value.
The name of the item property whose value is checked. The following properties are supported:
Property Name
Description
Checked 
Returns a boolean value indicating whether the specified menu item has a check mark displayed next to it. 
Enabled
Returns a boolean value indicating whether the specified menu item is currently enabled.
Exists
Returns a boolean value indicating whether the specified menu item exists.
HasSubMenu  
Returns a boolean value indicating whether the specified menu item has a sub-menu.
Index
Returns the numeric index location of the specified menu item.  Index values begin with 0.               
Label
Returns the menu item label as a string. 
SubMenuCount
Returns the number of items contained in the specified menu item's sub-menu (if any).
PropertyValue Required. A Variant.
The expected value against which the actual item property value should be checked. You can either use a simple value or you can use a comparison object together with the value to perform more complex comparisons.
TimeOut Optional. An unsigned long integer value.
The time, in milliseconds, within which UFT should check whether the actual value of the item property matches the specified expected value. If no value is specified, UFT uses the time set in the Object Synchronization Timeout option in the Run pane of the Test Settings dialog box.

Return Type

A Boolean value.

Returns TRUE if the item property achieves the value, and FALSE if the timeout is reached before the item property achieves the value.

A TRUE return value reports a Passed step to the run results; a FALSE return value reports a Failed step to the run results.

IMPORTANT

If the expected and actual values do not match, an error is reported and the test or component status is changed to failed.

Note: For test run synchronization, or whenever you do not want to fail the test if the expected and actual values do not match, use the WaitItemProperty method.

You can also use comparison objects to perform more complex value comparisons. For example, you can instruct UFT to check whether a specific item property value is greater than the specified value.

An example of the syntax required when using a comparison object is: Object.CheckItemProperty 2, "text", micNotEqual("John")"

The following comparison objects can be used:

When the types of the expected value and actual value do not match, the comparisons are performed as follows (in this order):

Example


 

Back to top

GetItemProperty Method

Description

Returns the current value of the specified property for the specified menu item.

Syntax

object.GetItemProperty (Item, Property)

Arguments

Parameter Description
Item Required. A String value.
The full path of the menu item to select from the list. The path is composed of the menu item names separated by a semicolon. 

Note: You can use the BuildMenuPath method to build the item path string that can then be used as the Item argument for this method.
Property Required. A String value.

Property to retrieve from the item. The following properties are supported:

Property Name
Description
Checked 
Returns a boolean value indicating whether the specified menu item has a check mark displayed next to it. 
Enabled
Returns a boolean value indicating whether the specified menu item is currently enabled.
Exists
Returns a boolean value indicating whether the specified menu item exists.
HasSubMenu  
Returns a boolean value indicating whether the specified menu item has a sub-menu.
Index
Returns the numeric index location of the specified menu item.  Index values begin with 0.                
Label
Returns the menu item label as a string. 
SubMenuCount
Returns the number of items contained in the specified menu item's sub-menu (if any).

Return Type

A Variant.

IMPORTANT

Use this method to retrieve property values of WinMenu items.

Example


 

Back to top

Select Method

Description

Selects the specified item in the menu.

Syntax

object.Select Item

Arguments

Parameter Description
Item Required. A Variant.
The full path of the menu item to select from the list. The path is composed of the menu item names or a numeric index separated by a semicolon. To specify the index of the item to select, use <Item #>. Index values begin with 1.

Note: You can use the BuildMenuPath method to build the item path string that can then be used as the Item argument for this method.

Return Type

None

Example


 

Back to top

WaitItemProperty Method

Description

Waits until the specified item property achieves the specified value or exceeds the specified timeout before continuing to the next step.

Syntax

object.WaitItemProperty (Item, PropertyName, PropertyValue, [TimeOut])

Arguments

Parameter Description
Item Required. A String value.
The item name (with quotes) can denote the item.
PropertyName Required. A String value.
The name of the item property whose value to wait for. The following properties are supported:
Property Name
Description
Checked 
Returns a boolean value indicating whether the specified menu item has a check mark displayed next to it. 
Enabled
Returns a boolean value indicating whether the specified menu item is currently enabled.
Exists
Returns a boolean value indicating whether the specified menu item exists.
HasSubMenu  
Returns a boolean value indicating whether the specified menu item has a sub-menu.
Index
Returns the numeric index location of the specified menu item.  Index values begin with 0.                         
Label
Returns the menu item label as a string. 
SubMenuCount
Returns the number of items contained in the specified menu item's sub-menu (if any).
PropertyValue Required. A Variant.
The expected value against which the actual item property value should be checked. You can either use a simple value or you can use a comparison object together with the value to perform more complex comparisons.
TimeOut Optional. A long integer value.
The time, in milliseconds, after which UFT continues to the next step if the specified item value is not achieved. If no value is specified, UFT uses the time set in the Object Synchronization Timeout option in the Run pane of the Test Settings dialog box.
Default value = -1

Return Type

A Boolean value.

Returns TRUE if the item property achieves the value, and FALSE if the timeout is reached before the item property achieves the value. A FALSE return value does not indicate a failed step.

IMPORTANT

Tip: This method is useful for test run synchronization. Unlike the Exist method and the WaitProperty method, the WaitItemProperty method enables you to synchronize the test run based on a specific object item property. For example, you can instruct UFT to wait for a particular string to appear in the second panel of the "StatusBar" control:
' Wait up to 30 seconds for the string "Ready" to appear in the second panel of the "StatusBar" control.
Window("Test").WinStatusBar("StatusBar").WaitItemProperty 2, "text", "Ready", 30000

You can also use comparison objects to perform more complex value comparisons. For example, you can instruct UFT to wait until a specific item property value is greater than the specified value.

An example of the syntax required when using a comparison object is: Object.WaitItemProperty 2, "text", micNotEqual("John")"

The following comparison objects can be used:

When the types of the expected value and actual value do not match, the comparisons are performed as follows (in this order):

Example


 

Back to top

ExpandMenu Property

Description

Indicates whether to expand the menu when retrieving menu item properties.

Syntax

object.ExpandMenu

Value Type

A Variant.

Property type

Read-write property

IMPORTANT

The open menu to retrieve item properties option (Tools > Options > Windows Applications pane) sets the default behavior for all menu objects (selected by default).  Use the ExpandMenu property to modify the behavior for a specified menu object.

Note: For better performance when running your test, you may want to set the ExpandMenu property to False (or to clear the open menu to retrieve item properties check box). (You may need to set the property to True when retrieving properties for menus that change dynamically.)   


Back to top

See also: