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 propertes. 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 pattern exposes the ColumnCount and RowCount properties. Most control pattern properties are dynamic values.
This topic contains the following sections.
- Property Identifiers
- Property Values
- Properties and Events
- Related Topics
Property Identifiers
Every property is identified by a PROPERTYID numeric value. Providers and clients use the numeric IDs to identify property requests. For a description of properties, including the data types and default values, 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 IUIAutomationDockPattern::SetDockPosition.
For information about retrieving property values, see UI Automation Properties for Clients.
Properties and Events
Closely associated with the properties in UI Automation is the concept of property-changed events. For dynamic properties, the 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.
Providers raise events when something in the user interface (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 UI Automation Events for Clients. For property-changed events in particular, clients must implement IUIAutomationPropertyChangedEventHandler and pass the interface to IUIAutomation::AddPropertyChangedEventHandler or IUIAutomation::AddPropertyChangedEventHandlerNativeArray.