Skip to content

05. Conditions

Jump to bottom
Descolada edited this page Jul 17, 2022 · 1 revision

In the last section we listed some ways of accessing elements from the UIA tree. To use any of those methods (like FindFirst, FindAll, or TreeWalkers), we also need to provide conditions used for filtering when searching for elements in the tree. This is done with conditions.

Built-in conditions

Some conditions are already available to us as UIA_Interface class properties.

TrueCondition

UIA_Interface.TrueCondition is always true and matches every element.

RawViewCondition

UIA_Interface.RawViewCondition includes all UIAutomation elements. Used by itself, this condition is functionally identical to TrueCondition.

ControlViewCondition

UIA_Interface.ControlViewCondition includes only elements that are controls.

ContentViewCondition

UIA_Interface.ContentViewCondition includes only elements that contain content.

Creating conditions

Conditions can be created from the UIA_Interface class with CreateTrueCondition, CreateFalseCondition, CreatePropertyCondition, CreatePropertyConditionEx and CreateCondition.

CreateTrueCondition

Creates a new TrueCondition. This isn't needed with the UIA_Interface.ahk library, because UIA_Interface.TrueCondition is automatically created with this during UIA_Interface() call.

CreateFalseCondition

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.

CreatePropertyCondition

CreatePropertyCondition(propertyId, value, type="Variant") creates a condition that filters for a property with a specific value. propertyId needs to be a number from the UIA_Enum class from UIA_PropertyIds. For example to create a condition to only filter for elements with the name of "test", use UIA.CreatePropertyCondition(30005, "test"). 30005 can be substituted for UIA_Enum.UIA_NamePropertyId. For advanced use cases, the variant type for the value can also be specified, by default it is automatically detected from the propertyId.

CreatePropertyConditionEx

CreatePropertyConditionEx(propertyId, value, type="Variant", flags=0x1) works the same as CreatePropertyCondition, but additionally some flags can be added. flags can be one of PropertyConditionFlags: PropertyConditionFlags_None := 0x0 PropertyConditionFlags_IgnoreCase := 0x1 PropertyConditionFlags_MatchSubstring = 0x2 The default flag is PropertyConditionFlags_IgnoreCase = 0x1.

CreateNotCondition

CreateNotCondition(c) returns the negative of the supplied condition (condition must not match).

CreateCondition

CreateCondition(propertyOrExpr, valueOrFlags="", flags=0) is the most flexible method of creating conditions. CreateCondition can create a condition from an expression, or a PropertyId and property value pair.

  1. If creating a single condition from a PropertyId and value pair:
  • propertyOrExpr: Property can be the PropertyId, or (partial) name (eg 30000 == "ControlType" == "ControlTypePropertyId").
  • valueOrFlags: the value corresponding to the PropertyId
  • flags: 0=no flags; 1=ignore case (case insensitive matching); 2=match substring; 3=ignore case and match substring Example: CreateCondition("Name", "Username", 1) would create a condition with NameProperty and value of "Username", with case sensitivity turned off.
  1. If creating a condition from an expression, propertyOrExpr takes the expression and valueOrFlags the default flags, and flags argument is ignored:
  • Similarly to FindFirstBy, the expression takes a value in the form of "PropertyId=propertyValue" to create a property condition for PropertyId with the value propertyValue. PropertyId can be most properties from UIA_Enum.UIA_PropertyId method (for example Name, ControlType, AutomationId etc).
  • If propertyValue contains any parentheses, then the value needs to be surrounded by single quotes. Escape ' with \, escape \ with \. UIA.CreateCondition("Name=Username:") would create a property condition with UIA_Enum.UIA_NamePropertyId and the value "Username:" "Name='MyTest''" creates a NameProperty condition for value "MyTest'"
  • Criteria can be combined with AND, OR, &&, || (not case sensitive): "Name=Username: AND ControlType=Button" would create a condition with the name property of "Username:" and control type of button. Parentheses are supported.
  • Negation can be specified with NOT or !: "NOT ControlType=Edit" would create a condition that selects everything but ControlType Edit
  • Different flags can be specified for each condition by specifying "FLAGS=n" after the condition value. "Name=Username: FLAGS=1" would create a case-insensitive condition only for that condition. By default the flags argument is used.

Flags: 0=no flags; 1=ignore case (case insensitive); 2=match substring; 3=ignore case and match substring

Combining conditions

Conditions can also be combined with CreateAndCondition and CreateOrCondition.

CreateAndCondition

CreateAndCondition(c1,c2) takes two conditions and returns a new condition, where both c1 and c2 need to match.

CreateOrCondition

CreateOrCondition(c1,c2) takes two conditions and returns a new condition, where either c1 or c2 needs to match.

Properties of conditions

UIA_BoolCondition

BooleanValue

UIA_PropertyCondition

PropertyId
PropertyValue
PropertyConditionFlags

UIA_AndCondition

ChildCount

UIA_OrCondition

ChildCount

Methods of conditions

UIA_AndCondition

GetChildren() returns an array of conditions that the AndCondition consists of. The type of the conditions can be determined with condition.__Class

UIA_OrCondition

GetChildren() returns an array of conditions that the OrCondition consists of. The type of the conditions can be determined with condition.__Class

UIA_NotCondition

GetChild() returns the condition which the NotCondition was created from. The type of the condition can be determined with condition.__Class

Clone this wiki locally