UI Automation Properties for Clients
Note
This documentation is intended for .NET Framework developers who want to use the managed UI Automation classes defined in the System.Windows.Automation namespace. For the latest information about UI Automation, see Windows Automation API: UI Automation.
This overview introduces you to UI Automation properties as they are exposed to UI Automation client applications.
Properties on AutomationElement objects contain information about user interface (UI) elements, usually controls. The properties of an AutomationElement are generic; that is, not specific to a control type. Many of these properties are exposed in the AutomationElement.AutomationElementInformation structure.
Control patterns also have properties. The properties of control patterns are specific to the pattern. For example, ScrollPattern has properties that enable a client application to discover whether a window is vertically or horizontally scrollable, and what the current view sizes and scroll positions are. Control patterns expose all their properties through a structure; for example, ScrollPattern.ScrollPatternInformation.
UI Automation properties are read-only. To set properties of a control, you must use the methods of the appropriate control pattern. For example, use Scroll to change the position values of a scrolling window.
To improve performance, property values of controls and control patterns can be cached when AutomationElement objects are retrieved. For more information, see Caching in UI Automation Clients.
Property IDs
Property identifiers (IDs) are unique, constant values that are encapsulated in AutomationProperty objects. UI Automation client applications get these IDs from the AutomationElement class or from the appropriate control pattern class, such as ScrollPattern. UI Automation providers get them from AutomationElementIdentifiers or from one of the control pattern identifiers classes, such as ScrollPatternIdentifiers.
The numeric Id of an AutomationProperty is used by providers to identify properties that are being queried for in the IRawElementProviderSimple.GetPropertyValue method. In general, client applications do not need to examine the Id. The ProgrammaticName is used only for debugging and diagnostic purposes.
Property Conditions
The property IDs are used in constructing PropertyCondition objects used to find AutomationElement objects. For example, you might wish to find an AutomationElement that has a certain name, or all controls that are enabled. Each PropertyCondition specifies an AutomationProperty identifier and the value that the property must match.
For more information, see the following reference topics:
Retrieving Properties
Some properties of AutomationElement and all properties of a control pattern class are exposed as nested properties of the Current or Cached property of the AutomationElement or control pattern object.
In addition, any AutomationElement or control pattern property, including a property that is not available in the Cached or Current structure, can be retrieved by using one of the following methods:
These methods offer slightly better performance as well as access to the full range of properties.
The following code example shows the two ways of retrieving a property on an AutomationElement.
// elementList is an AutomationElement.
// The following two calls are equivalent.
string name = elementList.Current.Name;
name = elementList.GetCurrentPropertyValue(AutomationElement.NameProperty) as string;
' elementList is an AutomationElement.
' The following two calls are equivalent.
Dim name As String = elementList.Current.Name
name = CStr(elementList.GetCurrentPropertyValue(AutomationElement.NameProperty))
To retrieve properties of control patterns supported by the AutomationElement, you do not need to retrieve the control pattern object. Simply pass one of the pattern property identifiers to the method.
The following code example shows the two ways of retrieving a property on a control pattern.
// elementList is an AutomationElement representing a list box.
// Error-checking is omitted. Assume that elementList is known to support SelectionPattern.
SelectionPattern selectPattern =
elementList.GetCurrentPattern(SelectionPattern.Pattern) as SelectionPattern;
bool isMultipleSelect = selectPattern.Current.CanSelectMultiple;
// The following call is equivalent to the one above.
isMultipleSelect = (bool)
elementList.GetCurrentPropertyValue(SelectionPattern.CanSelectMultipleProperty);
' elementList is an AutomationElement representing a list box.
' Error-checking is omitted. Assume that elementList is known to support SelectionPattern.
Dim selectPattern As SelectionPattern = _
DirectCast(elementList.GetCurrentPattern(SelectionPattern.Pattern), SelectionPattern)
Dim isMultipleSelect As Boolean = selectPattern.Current.CanSelectMultiple
' The following call is equivalent to the one above.
isMultipleSelect = CBool(elementList.GetCurrentPropertyValue(SelectionPattern.CanSelectMultipleProperty))
The Get methods return an Object. The application must cast the returned object to the proper type before using the value.
Default Property Values
If a UI Automation provider does not implement a property, the UI Automation system is able to supply a default value. For example, if the provider for a control does not support the property identified by HelpTextProperty, UI Automation returns an empty string. Similarly, if the provider does not support the property identified by IsDockPatternAvailableProperty, UI Automation returns false.
You can change this behavior by using the AutomationElement.GetCachedPropertyValue and AutomationElement.GetCurrentPropertyValue method overloads. When you specify true as the second parameter, UI Automation does not return a default value, but instead returns the special value NotSupported.
The following example code attempts to retrieve a property from an element, and if the property is not supported, an application-defined value is used instead.
// elementList is an AutomationElement.
object help = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, true);
if (help == AutomationElement.NotSupported)
{
help = "No help available";
}
string helpText = (string)help;
' elementList is an AutomationElement.
Dim help As Object = elementList.GetCurrentPropertyValue(AutomationElement.HelpTextProperty, True)
If help Is AutomationElement.NotSupported Then
help = "No help available"
End If
Dim helpText As String = CStr(help)
To discover what properties are supported by an element, use GetSupportedProperties. This returns an array of AutomationProperty identifiers.
Property-changed Events
When a property value on an AutomationElement or control pattern changes, an event is raised. An application can subscribe to such events by calling AddAutomationPropertyChangedEventHandler, supplying an array of AutomationProperty identifiers as the last parameter in order to specify the properties of interest.
In the AutomationPropertyChangedEventHandler, you can identify the property that has changed by checking the Property member of the event arguments. The arguments also contain the old and new values of the UI Automation property that has changed. These values are of type Object and must be cast to the correct type before being used.
Additional AutomationElement Properties
In addition to the Current and Cached property structures, AutomationElement has the following properties, which are retrieved through simple property accessors.
| Property | Description |
|---|---|
| CachedChildren | A collection of child AutomationElement objects that are in the cache. |
| CachedParent | An AutomationElement parent object that is in the cache. |
| FocusedElement | (Static property) The AutomationElement that has the input focus. |
| RootElement | (Static property) The root AutomationElement. |