UI Automation Properties Overview

UI Automation providers expose properties on Microsoft UI Automation elements. These properties enable UI Automation client applications to discover information about pieces of the user interface (UI), especially controls, including both static and dynamic data.

This topic contains the following sections.

• Property Identifiers
• Properties by Category
• Properties and Events
• Related Topics

This section gives a broad overview of Microsoft UI Automation properties. More specific information is given in the following topics:

• UI Automation Properties for Clients

• Server-Side UI Automation Provider Implementation

Property Identifiers

Every property is identified by a number and a name. The names of properties are used only for debugging and diagnosis. Providers use the numeric IDs to identify incoming property requests. Client applications, however, only use AutomationProperty, which encapsulates the number and name, to identify properties they wish to retrieve.

AutomationProperty objects representing particular properties are available as fields in various classes. For security reasons, UI Automation providers obtain these objects from a separate set of classes that are contained in Uiautomationtypes.dll.

The following table categorizes properties by the classes that contain the AutomationProperty IDs.

Kinds of properties	Clients get IDs from	Providers get IDs from
Properties common to all elements (see following tables)	AutomationElement	AutomationElementIdentifiers
Position of a docking window	DockPattern	DockPatternIdentifiers
State of an element that can expand and collapse	ExpandCollapsePattern	ExpandCollapsePatternIdentifiers
Properties of an item in a grid	GridItemPattern	GridItemPatternIdentifiers
Properties of a grid	GridPattern	GridPatternIdentifiers
Current and supported view of an element that has multiple views	MultipleViewPattern	MultipleViewPatternIdentifiers
Properties of an element that moves over a range of values, such as a slider	RangeValuePattern	RangeValuePatternIdentifiers
Properties of a scrolling window	ScrollPattern	ScrollPatternIdentifiers
Status and container of an item that can be selected, as in a list	SelectionItemPattern	SelectionItemPatternIdentifiers
Properties of a control that contains selection items	SelectionPattern	SelectionPatternIdentifiers
Column and row headers of an item in a table	TableItemPattern	TableItemPatternIdentifiers
Column and row headers, and orientation, of a table	TablePattern	TablePatternIdentifiers
State of a toggle control	TogglePattern	TogglePatternIdentifiers
Capabilities of an element that can be moved, rotated, or resized	TransformPattern	TransformPatternIdentifiers
Value and read/write capabilities of an element that has a value	ValuePattern	ValuePatternIdentifiers
Capabilities and state of a window	WindowPattern	WindowPatternIdentifiers

Properties by Category

The following tables categorize the properties whose IDs are found in AutomationElement and AutomationElementIdentifiers. These properties are common to all controls. All but a few of them are likely to be static over the lifetime of the provider application; most dynamic properties are associated with control patterns.

The Property Access column lists any other accessors for each property, in addition to GetCurrentPropertyValue and GetCachedPropertyValue. For more information on getting properties in a client application, see UI Automation Properties for Clients.

Note:
For specific information about each property, follow the link in the Property Access column.

Display Characteristics

Property identifier	Property access
BoundingRectangleProperty	BoundingRectangle
CultureProperty	n/a
HelpTextProperty	HelpText
IsOffscreenProperty	IsOffscreen
OrientationProperty	Orientation

Element Type

Property identifier	Property access
ControlTypeProperty	ControlType
IsContentElementProperty	IsContentElement
IsControlElementProperty	IsControlElement
ItemTypeProperty	ItemType
LocalizedControlTypeProperty	LocalizedControlType

Identification

Property identifier	Property access
AutomationIdProperty	AutomationId
ClassNameProperty	ClassName
FrameworkIdProperty	FrameworkId
LabeledByProperty	LabeledBy
NameProperty	Name
ProcessIdProperty	ProcessId
RuntimeIdProperty	GetRuntimeId
NativeWindowHandleProperty	NativeWindowHandle

Interaction

Property identifier	Property access
AcceleratorKeyProperty	AcceleratorKey
AccessKeyProperty	AccessKey
ClickablePointProperty	GetClickablePoint
HasKeyboardFocusProperty	HasKeyboardFocus
IsEnabledProperty	IsEnabled
IsKeyboardFocusableProperty	IsKeyboardFocusable

Support for Patterns

Property identifier	Property access
IsDockPatternAvailableProperty	GetSupportedPatterns
IsExpandCollapsePatternAvailableProperty	GetSupportedPatterns
IsGridItemPatternAvailableProperty	GetSupportedPatterns
IsGridPatternAvailableProperty	GetSupportedPatterns
IsInvokePatternAvailableProperty	GetSupportedPatterns
IsMultipleViewPatternAvailableProperty	GetSupportedPatterns
IsRangeValuePatternAvailableProperty	GetSupportedPatterns
IsScrollItemPatternAvailableProperty	GetSupportedPatterns
IsScrollPatternAvailableProperty	GetSupportedPatterns
IsSelectionItemPatternAvailableProperty	GetSupportedPatterns
IsSelectionPatternAvailableProperty	GetSupportedPatterns
IsTableItemPatternAvailableProperty	GetSupportedPatterns
IsTablePatternAvailableProperty	GetSupportedPatterns
IsTextPatternAvailableProperty	GetSupportedPatterns
IsTogglePatternAvailableProperty	GetSupportedPatterns
IsTransformPatternAvailableProperty	GetSupportedPatterns
IsValuePatternAvailableProperty	GetSupportedPatterns
IsWindowPatternAvailableProperty	GetSupportedPatterns

Miscellaneous

Property identifier	Property access
IsRequiredForFormProperty	IsRequiredForForm
IsPasswordProperty	IsPassword
ItemStatusProperty	ItemStatus

Properties and Events

Closely tied in 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 UI changes. For example, if a check box is selected or cleared, a property-changed event is raised by the provider's implementation of the Toggle 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 an event when the SelectionProperty changes. In this case, the application instead must listen for an ElementSelectedEvent.

Clients listen for events by subscribing to them. Subscribing to events means creating delegate methods that can handle the events, and then passing the methods to UI Automation along with the specific events that will be dealt with in those methods. For property-changed events in particular, clients must implement AutomationPropertyChangedEventHandler.

See Also

Tasks

Find a UI Automation Element Based on a Property Condition
Return Properties from a UI Automation Provider
Raise Events from a UI Automation Provider

Concepts

Caching in UI Automation Clients
UI Automation Properties for Clients
Server-Side UI Automation Provider Implementation