UI Automation Properties Overview
Microsoft UI Automation providers expose properties on UI Automation elements. Properties enable client applications to retrieve information about controls.
UI Automation exposes two different kinds of properties: automation element properties, and control pattern properties. The automation element properties consist of a common set of properties, such as Name, AcceleratorKey, and ClassName, that are exposed by all UI Automation elements, regardless of the control type. Most automation element properties are static values.
Control pattern properties are those that are exposed by a control that supports a particular control pattern. Each control pattern has a corresponding set of control pattern properties that the control must expose. For example, a control that supports the Grid control pattern exposes the ColumnCount and RowCount properties. Most control pattern properties are dynamic values.
This topic contains the following sections.
Property Identifiers
Every property is identified by a PROPERTYID numeric value called a property identifier (ID). Providers and clients use the numeric IDs in method calls such as IRawElementProviderAdviseEvents::AdviseEventAdded and IUIAutomationElement::GetCachedPropertyValue to identify property requests. For a detailed description of each UI Automation property identifier, including the data type and default value of each property, see Property Identifiers.
Property Values
All properties are read-only, although some can be changed by using methods that act on the control, such as IDockProvider::SetDockPosition (provider) or IUIAutomationDockPattern::SetDockPosition (client).
For information about retrieving property values, see Retrieving Properties from UI Automation Elements.
Properties and Events
Closely associated with the properties in UI Automation is the concept of property-changed events. For dynamic properties, a client application needs a way to know that a property value has changed, so that it can update its cache of information or react to the new information in some other way. Clients can register to listen for property-changed events on any property.
Providers raise events when something in the UI changes. For example, if a check box is selected or cleared, a property-changed event is raised by the provider implementation of the Toggle control pattern. Providers can raise events selectively, depending on whether any clients are listening for events, or listening for specific events.
Not all property changes raise events; that is entirely up to the implementation of the UI Automation provider for the element. For example, the standard proxy providers for list boxes do not raise a property-changed event when the Selection property changes. In this case, the application must listen for the event raised when the selection changes (UIA_SelectionItem_ElementSelectedEventId).
Clients listen for events by subscribing to them, as described at Subscribing to UI Automation Events. For property-changed events in particular, clients must implement IUIAutomationPropertyChangedEventHandler and pass the interface to IUIAutomation::AddPropertyChangedEventHandler or IUIAutomation::AddPropertyChangedEventHandlerNativeArray.
Related topics
-
Reference
-
Conceptual