UI Automation Properties for Clients
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.
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.
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:
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.
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. 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. 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.
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. 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)
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.
A collection of child AutomationElement objects that are in the cache.
An AutomationElement parent object that is in the cache.
(Static property) The AutomationElement that has the input focus.
(Static property) The root AutomationElement.