WinMenu Object

Description

A Windows menu.

Note: When the Qt Add-in is loaded, this test object also represents QMenu controls.

Qt menu objects are comprised of a QMenu and a QMenuBar, each of these represented by separate test objects in UFT One: a parent Window object, and a child WinToolbar object.

IMPORTANT

The WinMenu test object does not have any description properties. To retrieve property values for WinMenu items, use the GetItemProperty method.

Operations

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

Methods

Method BuildMenuPathReturns the path of the specified menu item.
Common Method CaptureBitmapSaves a screen capture of the object as a .png or .bmp image using the specified file name.
Common Method CheckChecks whether the actual value of an item matches the expected value.
Method CheckItemPropertyChecks whether the specified item property achieves the specified value within the specified timeout.
Common Method CheckPropertyChecks whether the specified object property achieves the specified value within the specified timeout.
Common Method ChildObjectsReturns the collection of child objects contained within the object.
Common Method GetAllROProperties

Returns the collection of properties and current values from the object in the application.

Method GetItemPropertyReturns the current value of the specified property for the specified menu item.
Common Method GetROPropertyReturns the current value of the description property from the object in the application.
Common Method GetTOPropertiesReturns the collection of properties and values used to identify the object.
Common Method GetTOPropertyReturns the value of the specified description property from the test object description.
Common Method HighlightHighlights the object in the application.
Common Method OutputRetrieves the current value of an item and stores it in a specified location.
Common Method RefreshObjectInstructs UFT One to re-identify the object in the application the next time a step refers to this object.
Method SelectSelects the specified item in the menu.
Common Method SetTOPropertySets the value of the specified description property in the test object description.
Common Method ToStringReturns a string that represents the test object.
Method WaitItemPropertyWaits until the specified item property achieves the specified value or exceeds the specified timeout before continuing to the next step.
Common Method WaitPropertyWaits until the specified object property achieves the specified value or exceeds the specified timeout before continuing to the next step.

Properties

Common Property ExistChecks whether the object currently exists in the open application.
Property ExpandMenuIndicates 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

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

                    'The following example uses the BuildMenuPath method to open each
'menu item (including all sub-menus), and writes the menu item names
'to the test's report log. The BuildMenuPath method is used to
'recursively build the item path string, which is then used to
'retrieve the menu item's properties.

Window("Notepad").WinMenu("Menu").ExpandMenu = True
Window("Notepad").Activate
GetNamesRec "", Window("Notepad").WinMenu("Menu")
Function GetNamesRec(itemPath, menuObj)
     ret = 0
     lbl = menuObj.GetItemProperty(itemPath, "Label")
     Reporter.ReportEvent 0, itemPath & " label", lbl
     ret = menuObj.GetItemProperty(itemPath, "HasSubMenu")
     If ret Then
        cnt = menuObj.GetItemProperty(itemPath, "SubMenuCount")
        Reporter.ReportEvent 0, itemPath & " sub-menu items", cnt
        For n = 1 To cnt
           Path = menuObj.BuildMenuPath(itemPath, n)
           GetNamesRec Path, menuObj
        Next
    End If
End Function
                    'The following example uses the BuildMenuPath method to construct the
'menu item path string for selecting the second menu item under the
'File menu. This method returns the string File;<Item 2>:

Path = Window("Notepad").WinMenu("Menu").BuildMenuPath("File", 2)
Window("Notepad").WinMenu("Menu").Select Path

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

ParameterDescription
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 One should check whether the actual value of the item property matches the specified expected value. If no value is specified, UFT One 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 One 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:

  • micGreaterThan: Greater than; Specifies that UFT One checks whether the item property value is greater than the specified value.
  • micLessThan: Less than; Specifies that UFT One checks whether the item property value is less than the specified value.
  • micGreaterThanOrEqual: Greater than or equal to; Specifies that UFT One checks whether the item property value is greater than or equal to the specified value.
  • micLessThanOrEqual: Less than or equal to; Specifies that UFT One checks whether the item property value is less than or equal to the specified value.
  • micNotEqual: Not equal to; Specifies that UFT One checks whether the item property value is not equal to the specified value.
  • micRegExpMatch: Regular expression; Specifies that UFT One checks whether the item property value achieves a regular expression match with the specified value. Regular expressions are case-sensitive and must match exactly. For example, 'E.*h' matches 'Earth' but not 'The Earth' or 'earth'.

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

  • Empty values: Empty values may be an uninitialized variable or field (which returns TRUE for the IsNull function in VBscript) or initialized to an empty value (which returns TRUE for the IsEmpty function is VBscript). When trying to compare two arguments when at least one is an empty value, the comparison assumes equality for two uninitialized arguments and for two empty arguments. Any other combination is considered unequal.
    For example:
    dim vEmpty
    Object.CheckItemProperty 2, "text",micNotEqual    (vEmpty) 
    will not wait for the timeout (because the 'text' property value is an empty string and the argument passed to micNotEqual is an empty value, and so micNotEqual finds them not equal and returns TRUE).
  • String values: When trying to compare a string value with non-string value, the string value is converted to the non-string type and then compared. If the string value cannot be converted to the non-string type, the comparison assumes the values are not equal.
    For example:
    Object.CheckItemProperty 2, "text", micGreaterThan("8")"
    will not wait for the timeout if the 'text' property value is '16' (because micGreaterThan finds 16 to be greater than 8 and returns TRUE), but will wait if the 'text' property value is 'a' (because 'a' cannot be converted to a number).
  • Boolean values: When trying to compare a Boolean value with non-boolean value, the non-boolean value is converted to a boolean value and then compared. The conversion method assumes that any integer value other than '0' is TRUE, and that '0' alone is FALSE. If the conversion fails to produce a boolean value (for example, if the value is 'abc'), the comparison result will be FALSE (note that for the WaitProperty method this result would instruct UFT One to keep waiting). If the conversion succeeds, the method compares the two boolean values according to the comparison logic.
  • Other value types: When other value types do not match, they are compared under the assumption that different types are not equal (nor greater than or less than each other).

Example

                    'The following example uses the CheckItemProperty method to check whether
'the "Format;Word Wrap" Notepad menu item is checked.
'If the expected value is not reached within two seconds, the step status
'is reported as Failed and the method returns False.

bSucceeded = Window("Notepad").WinMenu("Menu").WaitItemProperty("Format;Word Wrap", "checked", True, 2000)
                    'The following example uses the CheckItemProperty method to check whether
'first sub-item of the "Format" menu in Notepad is checked. If the expected value
'is not reached within five seconds, the step status is reported as Failed
'and the method returns False.

bSucceeded = Window("Notepad").WinMenu("Menu").WaitItemProperty("Format;<Item 1>", "checked", True, 2000)

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

ParameterDescription
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

                    'The following example uses the GetItemProperty method to retrieve the
'label property of a menu item.

itemLabel = Window("Notepad").WinMenu("Menu").GetItemProperty("<Item 2>;<Item 1>", "Label")
                    'The following example uses the GetItemProperty method to retrieve
'the number of items under the File menu item.

sub Count = Window("Notepad").WinMenu("Menu").GetItemProperty("File", "SubMenuCount")

Back to top

 

Select Method

Description

Selects the specified item in the menu.

Syntax

object.Select Item

Arguments

ParameterDescription
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

                    'The following example uses the Select method to open the Open File
'dialog box in Notepad.

Window("Notepad").WinMenu("Menu").Select "File;Open...  Ctrl+O"
'You can also open a menu item according to its indexed number.

Window("Notepad").WinMenu("Menu").Select "<Item 1>;<Item 2>"
                    'The following example uses the Select method to open the Open File
'dialog box in Notepad using the menu indexes.

Window("Notepad").WinMenu("Menu").Select "<Item 1>;<Item 2>"

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

ParameterDescription
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 One continues to the next step if the specified item value is not achieved. If no value is specified, UFT One 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 One 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 One 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:

  • micGreaterThan: Greater than; Specifies that UFT One waits until the item property value is greater than the specified value.
  • micLessThan: Less than; Specifies that UFT One waits until the item property value is less than the specified value.
  • micGreaterThanOrEqual: Greater than or equal to; Specifies that UFT One waits until the item property value is greater than or equal to the specified value.
  • micLessThanOrEqual: Less than or equal to; Specifies that UFT One waits until the item property value is less than or equal to the specified value.
  • micNotEqual: Not equal to; Specifies that UFT One waits until the item property value is not equal to the specified value.
  • micRegExpMatch: Regular expression; Specifies that UFT One waits until the item property value achieves a regular expression match with the specified value. Regular expressions are case-sensitive and must match exactly. For example, 'E.*h' matches 'Earth' but not 'The Earth' or 'earth'.

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

  • Empty values: Empty values may be an uninitialized variable or field (which returns TRUE for the IsNull function in VBscript) or initialized to an empty value (which returns TRUE for the IsEmpty function is VBscript). When trying to compare two arguments when at least one is an empty value, the comparison assumes equality for two uninitialized arguments and for two empty arguments. Any other combination is considered unequal.
    For example:
    dim vEmpty
    Object.WaitItemProperty 2, "text",micNotEqual    (vEmpty) 
    will not wait for the timeout (because the 'text' property value is an empty string and the argument passed to micNotEqual is an empty value, and so micNotEqual finds them not equal and returns TRUE).
  • String values: When trying to compare a string value with non-string value, the string value is converted to the non-string type and then compared. If the string value cannot be converted to the non-string type, the comparison assumes the values are not equal.
    For example:
    Object.WaitItemProperty 2, "text",micGreaterThan(8) will not wait for the timeout if the 'text' property value is '16' (because micGreaterThan finds 16 to be greater than 8 and returns TRUE), but will wait if the 'text' property value is 'a' (because 'a' cannot be converted to a number).
  • Boolean values: When trying to compare a Boolean value with non-boolean value, the non-boolean value is converted to a boolean value and then compared. The conversion method assumes that any integer value other than '0' is TRUE, and that '0' alone is FALSE. If the conversion fails to produce a boolean value (for example, if the value is 'abc'), the comparison result will be FALSE (note that for the WaitProperty method this result would instruct UFT One to keep waiting). If the conversion succeeds, the method compares the two boolean values according to the comparison logic.
  • Other value types: When other value types do not match, they are compared under the assumption that different types are not equal (nor greater than or less than each other).

Example

                    'The following example uses the WaitItemProperty method to wait
'up to two seconds until the "Format;Word Wrap" Notepad menu item
'is checked. If the expected value is not reached within two seconds,
'the method returns False and the step status is reported as Warning.

bSucceeded = Window("Notepad").WinMenu("Menu").WaitItemProperty("Format;Word Wrap", "checked", True, 2000)
                    'The following example uses the WaitItemProperty method to wait
'up to two seconds until the first sub-item of the "Format" menu in Notepad
'is checked. If the expected value is not reached within two seconds,
'the method returns False and the step status is reported as Warning.

bSucceeded = Window("Notepad").WinMenu("Menu").WaitItemProperty("Format;<Item 1>", "checked", True, 2000)

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: