VisualRelation Object

Description

An object that defines the details of a single visual relationship between a related object and the test object.

Important Information

If you need to specify more than one relative position for the same related object (for example, the related object is both left and above the test object to identify), include a separate VisualRelation object in the VisualRelationsCollection Object for each relationship.

Methods and Properties

Method GetArgumentReturns the value of a visual relation argument.
SetTOPropertySets the specified value of an description properties for an object.
RelatedObjectPathThe full object hierarchy path of the related object
RelativePositionThe position of the related object relative to the test object.
SetArgumentSets the value of a visual relation argument.

Back to top

GetArgument Method

Description

Returns the value of a visual relation argument.

Syntax

ArgVal = VisualRel.GetArgument(Argument)

Argument

Type

Description

Argument

String or Pre-defined constant

The name of the argument you want to retrieve

Possible values:

  • Inline (string) or micrelinline (constant)--A boolean argument that indicates whether the related object is (horizontally or vertically) in-line with the test object

ArgVal

Variant

A variable that will store the retrieved argument value.

Return Value

Variant. The value of the argument.

IMPORTANT

  • Use the GetArgument method to retrieve the value of the Inline argument. This argument indicates whether a related object is in line with the test object.

    • If the value is True for a VisualRelation object whose RelativePosition Property is left or right, then the related object is horizontally in line with the test object.

    • If the value is True for a VisualRelation object whose RelativePosition Property is above or below, then the related object is vertically in line with the test object.

  • The GetArgument method returns the value of a specified item from a VisualRelation.Arguments collection object. The Arguments collection is comprised of property-value pairs, similar to the Properties Object (Collection).

    Therefore, the statement:

    ArgVal = VisualRel.Arguments(Argument).Value

    is equivalent to:

    ArgVal = VisualRel.GetArgument(Argument)

    Example

The following example demonstrates the use of a VisualRelations collection with a test object that has an ambiguous programmatic description. The same test object is used to represent different buttons in the calculator application based on the relative position of the buttons to the left and right of that button. Using these settings, the example below clicks on buttons 2, 5, and 8 in the calculator. (The example assumes that all objects from the calculator application have been added to the object repository.)

For i = 2 to 8 step 3
    print "Now selecting the object that matches button " & i & " via the related buttons " & (i-1) & " and " & (i+1)

    'Define an ambiguous button object on the calculator.
    Set obj = Window("text:=Calculator").WinButton("text:=.*")

    'Define two visual relations for the current button.
    Set rc = VisualRelations.Create
    Set relation = rc.Add
    relation.relatedobjectpath = "Window(""Calculator"").WinButton(""" & (i-1) & """)"
    relation.relativeposition = micRelLeft
    relation.setargument micrelinline, True
    Set relation = Nothing
    set relation = rc.Add
    relation.relatedobjectpath = "Window(""Calculator"").WinButton(""" & (i+1) & """)"
    relation.relativeposition = micRelRight
    relation.setargument micrelinline, True
    Set relation = Nothing

    'Update the defined test object with the new visual relation identifier.
    obj.SetTOProperty "visual relations", rc
    obj.Click
	
    'Release the objects
    Set rc = Nothing
    Set obj = Nothing
Next

Back to top

RelatedObjectPath Property

Description

The full object hierarchy path of the related object. For example: "Browser("Welcome: Mercury Tours").Page("Book a Flight: Mercury").WebEdit("passFirst1")"

Syntax

VRIColl.RelatedObjectPath

Return Value

Read-write. String.

IMPORTANT

The specified object must be an object from the test object repository. It cannot be a test object specified by a programmatic description.

The following example demonstrates the use of a VisualRelations collection with a test object that has an ambiguous programmatic description. The same test object is used to represent different buttons in the calculator application based on the relative position of the buttons to the left and right of that button. Using these settings, the example below clicks on buttons 2, 5, and 8 in the calculator. (The example assumes that all objects from the calculator application have been added to the object repository.)

For i = 2 to 8 step 3
    print "Now selecting the object that matches button " & i & " via the related buttons " & (i-1) & " and " & (i+1)

    'Define an ambiguous button object on the calculator.
    Set obj = Window("text:=Calculator").WinButton("text:=.*")

    'Define two visual relations for the current button.
    Set rc = VisualRelations.Create
    Set relation = rc.Add
    relation.relatedobjectpath = "Window(""Calculator"").WinButton(""" & (i-1) & """)"
    relation.relativeposition = micRelLeft
    relation.setargument micrelinline, True
    Set relation = Nothing
    set relation = rc.Add
    relation.relatedobjectpath = "Window(""Calculator"").WinButton(""" & (i+1) & """)"
    relation.relativeposition = micRelRight
    relation.setargument micrelinline, True

Back to top

RelativePosition Property

Description

The position of the related object relative to the test object.

Syntax

VRIColl.RelativePosition

Return Value

Read-write. String (or Pre-defined constant).

Possible values:

Constant

String

Description

micRelLeft

left

The related object is to the left of the test object.

micRelRight

right

The related object is to the right of the test object.

micRelAbove

above

The related object is above the test object.

micRelBelow

below

The related object is below the test object.

micRelContains

contains

The related object contains the test object.

micRelClosestX

closest-x

The related object is the closest object on the X-axis to the test object.

micRelClosestY

closest-y

The related object is the closest object on the Y-axis to the test object.

micRelClosest

closest

The related object is the closest object to the test object.

The following example demonstrates the use of a VisualRelations collection with a test object that has an ambiguous programmatic description. The same test object is used to represent different buttons in the calculator application based on the relative position of the buttons to the left and right of that button. Using these settings, the example below clicks on buttons 2, 5, and 8 in the calculator. (The example assumes that all objects from the calculator application have been added to the object repository.)

For i = 2 to 8 step 3
    print "Now selecting the object that matches button " & i & " via the related buttons " & (i-1) & " and " & (i+1)
    'Define an ambiguous button object on the calculator.
    Set obj = Window("text:=Calculator").WinButton("text:=.*")

    'Define two visual relations for the current button.
    Set rc = VisualRelations.Create
    Set relation = rc.Add
    relation.relatedobjectpath = "Window(""Calculator"").WinButton(""" & (i-1) & """)"
    relation.relativeposition = micRelLeft
    relation.setargument micrelinline, True
    Set relation = Nothing
    set relation = rc.Add
    relation.relatedobjectpath = "Window(""Calculator"").WinButton(""" & (i+1) & """)"
    relation.relativeposition = micRelRight
    relation.setargument micrelinline, True
    Set relation = Nothing

    'Update the defined test object with the new visual relation identifier.
    obj.SetTOProperty "visual relations", rc
    obj.Click

    'Release the objects
    Set rc = Nothing
    Set obj = Nothing
Next

Back to top

SetArgument Method

Description

Sets the value of a visual relation argument.

Syntax

VisualRel.SetArgument Argument, Value

Argument

Type

Description

Argument

String or Pre-defined constant

The name of the argument you want to set.

Possible values:

  • Inline (string) or micrelinline (constant))--A boolean argument that indicates whether the related object is (horizontally or vertically) in-line with the test object

Value

Variant

The value to assign to the argument.

IMPORTANT

  • Use the SetArgument method to set the value of the Inline (or micrelinline) argument. This argument indicates whether a related object is in line with the test object.

    • To indicate that an object is horizontally in line with the test object, set the value to True for a VisualRelation object whose RelativePosition Property is left or right.

    • To indicate that an object is vertically in line with the test object, set the value to True for a VisualRelation object whose RelativePosition Property is above or below.

  • The SetArgument method sets the value of a specified item in a VisualRelation Arguments collection object. The Arguments collection is comprised of property-value pairs, similar to the Properties Object (Collection).

    Therefore, the statement:

    VisualRel.Arguments(Argument).Value = ArgVal

    is equivalent to:

    VisualRel.SetArgument(Argument) = ArgVal

The following example demonstrates the use of a VisualRelations collection with a test object that has an ambiguous programmatic description. The same test object is used to represent different buttons in the calculator application based on the relative position of the buttons to the left and right of that button. Using these settings, the example below clicks on buttons 2, 5, and 8 in the calculator. (The example assumes that all objects from the calculator application have been added to the object repository.)

For i = 2 to 8 step 3
    print "Now selecting the object that matches button " & i & " via the related buttons " & (i-1) & " and " & (i+1)

    'Define an ambiguous button object on the calculator
    Set obj = Window("text:=Calculator").WinButton("text:=.*")

    'Define two visual relations for the current button.
    Set rc = VisualRelations.Create
    Set relation = rc.Add
    relation.relatedobjectpath = "Window(""Calculator"").WinButton(""" & (i-1) & """)"
    relation.relativeposition = micRelLeft
    relation.setargument micrelinline, True
    Set relation = Nothing
    set relation = rc.Add
    relation.relatedobjectpath = "Window(""Calculator"").WinButton(""" & (i+1) & """)"
    relation.relativeposition = micRelRight
    relation.setargument micrelinline, True
    Set relation = Nothing

    'Update the defined test object with the new visual relation identifier.
    obj.SetTOProperty "visual relations", rc
    obj.Click

    'Release the objects
    Set rc = Nothing
    Set obj = Nothing
Next

Back to top

See also: