-
Notifications
You must be signed in to change notification settings - Fork 32
05. Conditions
In the last section we listed some ways of accessing elements from the UIA tree. To use any of those methods (like FindElement, WaitElement), we also need to provide conditions used for filtering when searching for elements in the tree. This is done with conditions.
The condition object needs to be an Object or Array.
-
A single property condition consists of an object where the key is the property name, and value is the property value:
{Name:"Test"}=> Creates a condition where the Name property must match "Test" exactly -
Everything inside {} is an "and" condition
{Type:"Button", Name:"Something"}=> Name must match "Something" AND ControlType must be Button -
Everything inside [] is an "or" condition
[{Name:"Test"}, {Name:"Something"}]Name must match "Test" OR Name must match "Something" -
Object key "not" creates a not condition
-
matchmode key (short form: mm) can be one of UIA.MatchMode values and defines the MatchMode StartsWith=1, Substring=2, Exact=3, RegEx
-
casesense key (short form: cs) defines case sensitivity (default: case-sensitive/True): True=case sensitive; False=case insensitive
Examples:
-
{Name:"Test"}=> Name must match "Test" exactly, case-sensitive -
{Type:"Button", or:[{Name:"Something"}, {Name:"Else"}]}=> Name must match "Something" OR "Else", AND ControlType must be Button. Alternative is{Type:"Button", Name:["Something", "Else"]} -
{Name:"Test", cs:0, mm:2}=> Name must contain "Test" and is case-insensitive. Long form would be{Name:"Test", casesense:0, matchmode:"Substring"}
UIAViewer creates a short-hand notations for object conditions to keep the UIA path more compact. In the notation T stands for Type, A is AutomationId, N is Name, CN is ClassName. Type value is the enumeration value minus 50000 (since all Type enumerations are in the 50000's). {T:0} is equivalent to {Type:50000} is equivalent to {Type:"Button"}.
Because UIAutomation framework doesn't support matchmodes StartsWith and RegEx, these two are not available. Other than that the syntax for the objects is the same.
Some conditions are already available to us as UIA class properties.
UIA.TrueCondition is always true and matches every element. This is the same as supplying an empty object as a condition.
UIA.RawViewCondition includes all UIAutomation elements. Used by itself, this condition is functionally identical to TrueCondition.
UIA.ControlViewCondition includes only elements that are controls.
UIA.ContentViewCondition includes only elements that contain content.
Here are explained all the underlying methods which are used to create the conditions from afore-mentioned objects. Most likely you can skip reading this section.
Conditions can be created from the UIA class with CreateTrueCondition, CreateFalseCondition, CreatePropertyCondition, CreatePropertyConditionEx and CreateCondition.
Creates a new TrueCondition. This isn't needed with the UIA.ahk library, because UIA.TrueCondition uses this and stores the value.
Creates a condition that is always false. This method is useless, it exists only for symmetry with CreateTrueCondition. It cannot usefully be combined with any other condition.
This is the most flexible method to create UIA conditions.
CreateCondition(conditionObject) creates a condition from a condition object.
CreateCondition(property, value, flags?) creates a condition from a property and property value pair. If only property and value are provided, then CreatePropertyCondition is called. If flags is also provided, then CreatePropertyConditionEx is called.
Examples:
CreateCondition({Name:"SomeName"}) == CreatePropertyCondition(UIA.Property.Name, "SomeName") == CreatePropertyCondition(30005, "SomeName")
CreateCondition("Name", "SomeName", "CaseSensitive") == CreatePropertyConditionEx(30005, "SomeName", 1)
CreatePropertyCondition(propertyId, value) creates a condition that filters for a property with a specific value.
propertyId needs to be a number from the UIA.Property enumeration. For example to create a condition to only filter for elements with the name of "test", use UIA.CreatePropertyCondition(UIA.Property.Name, "test"). UIA.Property.Name can be substituted for the value 30005.
CreatePropertyConditionEx(propertyId, value, flags=0) works the same as CreatePropertyCondition, but additionally some flags can be added.
flags can be one of UIA.PropertyConditionFlags:
UIA.PropertyConditionFlags.None := 0x0
UIA.PropertyConditionFlags.IgnoreCase := 0x1
UIA.PropertyConditionFlags.MatchSubstring = 0x2
The default flag is None.
CreateNotCondition(c) returns the negative of the supplied condition (condition must not match).
Conditions can also be combined with CreateAndCondition and CreateOrCondition.
CreateAndCondition(c1,c2) takes two conditions and returns a new condition, where both c1 and c2 need to match.
CreateOrCondition(c1,c2) takes two conditions and returns a new condition, where either c1 or c2 needs to match.
BooleanValue
PropertyId
PropertyValue
PropertyConditionFlags
ChildCount
ChildCount
GetChildren() returns an array of conditions that the AndCondition consists of. The type of the conditions can be determined with Type(condition)
GetChildren() returns an array of conditions that the OrCondition consists of. The type of the conditions can be determined with Type(condition)
GetChild() returns the condition which the NotCondition was created from. The type of the condition can be determined with Type(condition)