Retrieving Properties from UI Automation Elements

Properties on IUIAutomationElement objects contain information about UI elements, usually controls. The properties of an element are generic; that is, not specific to a control type. Control-specific properties of an element are exposed by its control pattern interfaces.

Microsoft 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 IUIAutomationScrollPattern::Scroll to change the position values of a scrolling window.

To improve performance, property values of controls and control patterns can be cached when elements are retrieved. For more information, see Caching UI Automation Properties and Control Patterns.

This topic contains the following sections.

• Property IDs
• Property Conditions
• Retrieving Properties
• Default Property Values
• Related topics

Property IDs

Property identifiers are defined in Uiautomationclient.h. They are used to specify properties when you subscribe to property-changed events, retrieve property values, and construct property conditions. Property identifiers also identify the property that has changed when IUIAutomationPropertyChangedEventHandler::HandlePropertyChangedEvent is called.

For a list of UI Automation property identifiers, see Property Identifiers.

Property Conditions

The property IDs are used in constructing IUIAutomationPropertyCondition objects that are used to find UI Automation elements. For example, you might want to find an element that has a certain name, or all controls that are enabled. Each property condition specifies a property identifier and the value that the property must match.

For more information, see the following reference topics:

• IUIAutomation::CreatePropertyCondition
• IUIAutomation::CreatePropertyConditionEx
• IUIAutomationElement::FindFirst
• IUIAutomationElement::FindAll

Retrieving Properties

Some generic properties, and all control pattern properties, are available as properties on the IUIAutomationElement or control pattern interface and can be retrieved by using an accessor, such as IUIAutomationElement::CurrentName or CachedDockPosition.

In addition, any current or cached property (other than control pattern properties) can be retrieved by using one of the following methods:

• GetCurrentPropertyValue
• GetCurrentPropertyValueEx
• GetCachedPropertyValue
• GetCachedPropertyValueEx

These methods offer slightly better performance and access to the full range of properties. However, values are returned in VARIANT structures, whereas the individual property accessors cast the value to the appropriate type.

Default Property Values

If a UI Automation provider does not implement a property, UI Automation can supply a default value. For example, if the provider for a control does not support the property identified by UIA_HelpTextPropertyId, UI Automation returns an empty string. Similarly, if the provider does not support the property identified by UIA_IsDockPatternAvailablePropertyId, UI Automation returns FALSE.

The difference between IUIAutomationElement::GetCurrentPropertyValue and GetCurrentPropertyValueEx (and between similar pairs of methods) is that the "Ex" method can specify that no default value is to be returned. In this case, the return value is a special unique constant, indicating that the property is not supported. On receiving this value, the application can supply its own value or simply ignore the property.

Related topics

Conceptual

UI Automation Properties Overview

Property Identifiers