Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Automation Element Property Identifiers

This topic describes the named constants that identify the properties of Microsoft UI Automation elements.

Constant/valueDescription
UIA_AcceleratorKeyPropertyId
30006

Identifies the AcceleratorKey property, which is a string containing the accelerator key (also called shortcut key) combinations for the automation element.

Shortcut key combinations invoke an action. For example, CTRL+O is often used to invoke the Open file common dialog box. An automation element that has the AcceleratorKey property can implement the Invoke control pattern for the action that is equivalent to the shortcut command.

Variant type: VT_BSTR

Default value: empty string

UIA_AccessKeyPropertyId
30007

Identifies the AccessKey property, which is a string containing the access key character for the automation element.

An access key (sometimes called a mnemonic) is a character in the text of a menu, menu item, or label of a control such as a button, that activates the associated menu function. For example, to open the File menu, for which the access key is typically F, the user would press ALT+F.

Variant type: VT_BSTR

Default value: empty string

UIA_AriaPropertiesPropertyId
30102

Identifies the AriaProperties property, which is a formatted string containing the Accessible Rich Internet Application (ARIA) property information for the automation element. For more information about mapping ARIA states and properties to UI Automation properties and functions, see UI Automation for W3C Accessible Rich Internet Applications Specification.

AriaProperties is a collection of Name/Value pairs with delimiters of = (equals) and ; (semicolon), for example, "checked=true;disabled=false". The \ (backslash) is used as an escape character when these delimiter characters or \ appear in the values. For security and other reasons, the provider implementation of this property can take steps to validate the original ARIA properties; however, it is not required.

Variant type: VT_BSTR

Default value: empty string

UIA_AriaRolePropertyId
30101

Identifies the AriaRole property, which is a string containing the Accessible Rich Internet Application (ARIA) role information for the automation element. For more information about mapping ARIA roles to UI Automation control types, see UI Automation for W3C Accessible Rich Internet Applications Specification.

Note  As an option, the user agent can also offer a localized description of the W3C ARIA role in the LocalizedControlType property. When the localized string is not specified, the system will provide the default LocalizedControlType string for the element.

Variant type: VT_BSTR

Default value: empty string

UIA_AutomationIdPropertyId
30011

Identifies the AutomationId property, which is a string containing the UI Automation identifier (ID) for the automation element.

When it is available, the AutomationId of an element must be the same in any instance of the application, regardless of the local language. The value should be unique among sibling elements, but not necessarily unique across the entire desktop. For example, multiple instances of an application, or multiple folder views in Microsoft Windows Explorer, can contain elements with the same AutomationId property, such as "SystemMenuBar".

Although support for AutomationId is always recommended for better automated testing support, this property is not mandatory. Where it is supported, AutomationId is useful for creating a test automation script that runs regardless of the UI language. Clients should make no assumptions regarding the AutomationId values exposed by other applications. AutomationId is not guaranteed to be stable across different releases or builds of an application.

Variant type: VT_BSTR

Default value: empty string

UIA_BoundingRectanglePropertyId
30001

Identifies the BoundingRectangle property, which specifies the coordinates of the rectangle that completely encloses the automation element. The rectangle is expressed in physical screen coordinates. It can contain points that are not clickable if the shape or clickable region of the UI item is irregular, or if the item is obscured by other UI elements.

Variant type: VT_R8 | VT_ARRAY

Default value: empty rectangle

Note  This property is NULL if the item is not currently displaying a UI.

UIA_ClassNamePropertyId
30012

Identifies the ClassName property, which is a string containing the class name for the automation element as assigned by the control developer.

The class name depends on the implementation of the UI Automation provider and therefore is not always in a standard format. However, if the class name is known, it can be used to verify that an application is working with the expected automation element.

Variant type: VT_BSTR

Default value: empty string

UIA_ClickablePointPropertyId
30014

Identifies the ClickablePoint property, which is a point on the automation element that can be clicked. An element cannot be clicked if it is completely or partially obscured by another window.

Variant type: VT_R8 | VT_ARRAY

Default value: NULL.

UIA_ControllerForPropertyId
30104

Identifies the ControllerFor property, which is an array of automation elements that are manipulated by the automation element that supports this property.

ControllerFor is used when an automation element affects one or more segments of the application UI or the desktop; otherwise, it is hard to associate the impact of the control operation with UI elements.

Variant type for providers: VT_UNKNOWN | VT_ARRAY

Variant type for clients: VT_UNKNOWN (IUIAutomationElementArray )

Default value: NULL

UIA_ControlTypePropertyId
30003

Identifies the ControlType property, which is a class that identifies the type of the automation element. ControlType defines characteristics of the UI elements by well known UI control primitives such as button or check box.

Variant type: VT_I4

Default value: UIA_CustomControlTypeId

Note  Use the default value only if the automation element represents a completely new type of control.

UIA_CulturePropertyId
30015

Identifies the Culture property, which contains a locale identifier for the automation element (for example, 0x0409 for "en-US" or English (United States)).

Each locale has a unique identifier, a 32-bit value that consists of a language identifier and a sort order identifier. The locale identifier is a standard international numeric abbreviation and has the components necessary to uniquely identify one of the installed operating system-defined locales. For more information, see Language Identifier Constants and Strings.

This property may exist on a per-control basis, but typically is only available on an application level.

Variant type: VT_I4

Default value: 0

UIA_DescribedByPropertyId
30105

Identifies the DescribedBy property, which is an array of elements that provide more information about the automation element.

DescribedBy is used when an automation element is explained by another segment of the application UI. For example, the property can point to a text element of "2,529 items in 85 groups, 10 items selected" from a complex custom list object. Instead of using the object model for clients to digest similar information, the DescribedBy property can offer quick access to the UI element that may already offer useful end-user information that describes the UI element.

Variant type for providers: VT_UNKNOWN | VT_ARRAY

Variant type for clients: VT_UNKNOWN (IUIAutomationElementArray)

Default value: NULL

UIA_FlowsFromPropertyId
30148

Identifies the FlowsFrom property, which is an array of automation elements that suggests the reading order before the current automation element. Supported starting with Windows 8.

The FlowsFrom property specifies the reading order when automation elements are not exposed or structured in the same reading order as perceived by the user. While the FlowsFrom property can specify multiple preceding elements, it typically contains only the prior element in the reading order.

Variant type for providers: VT_UNKNOWN | VT_ARRAY

Variant type for clients: VT_UNKNOWN (IUIAutomationElementArray)

Default value: NULL

UIA_FlowsToPropertyId
30106

Identifies the FlowsTo property, which is an array of automation elements that suggests the reading order after the current automation element.

The FlowsTo property specifies the reading order when automation elements are not exposed or structured in the same reading order as perceived by the user. While the FlowsTo property can specify multiple succeeding elements, it typically contains only the next element in the reading order.

Variant type for providers: VT_UNKNOWN | VT_ARRAY

Variant type for clients: VT_UNKNOWN (IUIAutomationElementArray)

Default value: NULL

UIA_FrameworkIdPropertyId
30024

Identifies the FrameworkId property, which is a string containing the name of the underlying UI framework that the automation element belongs to.

The FrameworkId enables client applications to process automation elements differently depending on the particular UI framework. Examples of property values include "Win32", "WinForm", and "DirectUI".

Variant type: VT_BSTR

Default value: empty string

UIA_HasKeyboardFocusPropertyId
30008

Identifies the HasKeyboardFocus property, which is a Boolean value that indicates whether the automation element has keyboard focus.

Variant type: VT_BOOL

Default value: FALSE

UIA_HelpTextPropertyId
30013

Identifies the HelpText property, which is a help text string associated with the automation element.

The HelpText property is typically obtained from tooltip text associated with the element. The property can also be supported with placeholder text appearing in edit or list controls. For example, "Type text here for search" is a good candidate the HelpText property for an edit control that places the text prior to the user's actual input. However, it is not adequate for the name property of the edit control.

When HelpText is supported, the string must match the application UI language or the operating system default UI language.

Variant type: VT_BSTR

Default value: NULL

UIA_IsContentElementPropertyId
30017

Identifies the IsContentElement property, which is a Boolean value that specifies whether the element appears in the content view of the automation element tree. For more information, see UI Automation Tree Overview.

Note  For an element to appear in the content view, both the IsContentElement property and the IsControlElement property must be TRUE.

Variant type: VT_BOOL

Default value: TRUE

UIA_IsControlElementPropertyId
30016

Identifies the IsControlElement property, which is a Boolean value that specifies whether the element appears in the control view of the automation element tree. For more information, see UI Automation Tree Overview.

Variant type: VT_BOOL

Default value: TRUE

UIA_IsDataValidForFormPropertyId
30103

Identifies the IsDataValidForForm property, which is a Boolean value that indicates whether the entered or selected value is valid for the form rule associated with the automation element. For example, if the user entered "425-555-5555" for a zip code field that requires 5 or 9 digits, the IsDataValidForForm property can be set to FALSE to indicate that the data is not valid.

Variant type: VT_BOOL

Default value: FALSE

UIA_IsEnabledPropertyId
30010

Identifies the IsEnabled property, which is a Boolean value that indicates whether the UI item referenced by the automation element is enabled and can be interacted with.

When the enabled state of a control is FALSE, it is assumed that child controls are also not enabled. Clients should not expect property-changed events from child elements when the state of the parent control changes.

Variant type: VT_BOOL

Default value: FALSE

UIA_IsKeyboardFocusablePropertyId
30009

Identifies the IsKeyboardFocusable property, which is a Boolean value that indicates whether the automation element can accept keyboard focus.

Variant type: VT_BOOL

Default value: FALSE

UIA_IsOffscreenPropertyId
30022

Identifies the IsOffscreen property, which is a Boolean value that indicates whether the automation element is entirely scrolled out of view (for example, an item in a list box that is outside the viewport of the container object) or collapsed out of view (for example, an item in a tree view or menu, or in a minimized window). If the element has a clickable point that can cause it to receive the focus, the element is considered to be on-screen while a portion of the element is off-screen.

The value of the property is not affected by occlusion by other windows, or by whether the element is visible on a specific monitor.

If the IsOffscreen property is TRUE, the UI element is scrolled off-screen or collapsed. The element is temporarily hidden, yet it remains in the end-user's perception and continues to be included in the UI model. The object can be brought back into view by scrolling, clicking a drop-down, and so on.

Objects that the end-user does not perceive at all, or that are "programmatically hidden" (for example, a dialog box that has been dismissed, but the underlying object is still cached by the application) should not be in the automation element tree in the first place (instead of setting the state of IsOffscreen to TRUE).

Variant type: VT_BOOL

Default value: FALSE

UIA_IsPasswordPropertyId
30019

Identifies the IsPassword property, which is a Boolean value that indicates whether the automation element contains protected content or a password.

When the IsPassword property is TRUE and the element has the keyboard focus, a client application should disable keyboard echoing or keyboard input feedback that may expose the user's protected information. Attempting to access the Value property of the protected element (edit control) may cause an error to occur.

Variant type: VT_BOOL

Default value: FALSE

UIA_IsPeripheralPropertyId
30150

Identifies the IsPeripheral property, which is a Boolean value that indicates whether the automation element represents peripheral UI. Peripheral UI appears and supports user interaction, but does not take keyboard focus when it appears. Examples of peripheral UI includes popups, flyouts, context menus, or floating notifications. Supported starting with Windows 8.1.

When the IsPeripheral property is TRUE, a client application can't assume that focus was taken by the element even if it's currently keyboard-interactive.

This property is relevant for these control types:

  • UIA_GroupControlTypeId
  • UIA_MenuControlTypeId
  • UIA_PaneControlTypeId
  • UIA_ToolBarControlTypeId
  • UIA_ToolTipControlTypeId
  • UIA_WindowControlTypeId
  • UIA_CustomControlTypeId

Variant type: VT_BOOL

Default value: FALSE

UIA_IsRequiredForFormPropertyId
30025

Identifies the IsRequiredForForm property, which is a Boolean value that indicates whether the automation element is required to be filled out on a form.

Variant type: VT_BOOL

Default value: FALSE

UIA_ItemStatusPropertyId
30026

Identifies the ItemStatus property, which is a text string describing the status of an item of the automation element.

ItemStatus enables a client to ascertain whether an element is conveying status about an item as well as what the status is. For example, an item associated with a contact in a messaging application might be "Busy" or "Connected".

When ItemStatus is supported, the string must match the application UI language or the operating system default UI language.

Variant type: VT_BSTR

Default value: empty string

UIA_ItemTypePropertyId
300021

Identifies the ItemType property, which is a text string describing the type of the automation element.

ItemType is used to obtain information about items in a list, tree view, or data grid. For example, an item in a file directory view might be a "Document File" or a "Folder".

When ItemType is supported, the string must match the application UI language or the operating system default UI language.

Variant type: VT_BSTR

Default value: empty string

UIA_LabeledByPropertyId
30018

Identifies the LabeledBy property, which is an automation element that contains the text label for this element.

This property can be used to retrieve, for example, the static text label for a combo box.

Variant type: VT_UNKNOWN

Default value: NULL

UIA_LiveSettingPropertyId
30135

Identifies the LiveSetting property, which is supported by an automation element that represents a live region. The LiveSetting property indicates the "politeness" level that a client should use to notify the user of changes to the live region. This property can be one of the values from the LiveSetting enumeration. Supported starting with Windows 8.

Variant type: VT_I4

Default value: LiveSetting_Off

UIA_LocalizedControlTypePropertyId
30004

Identifies the LocalizedControlType property, which is a text string describing the type of control that the automation element represents. The string should contain only lowercase characters:

  • Correct: "button"
  • Incorrect: "Button"

When LocalizedControlType is not specified by the element provider, the default localized string is supplied by the framework, according to the control type of the element (for example, "button" for the Button control type). An automation element with the Custom control type must support a localized control type string that represents the role of the element (for example, "color picker" for a custom control that enables users to choose and specify colors).

When a custom value is supplied, the string must match the application UI language or the operating system default UI language.

Variant type: VT_BSTR

Default value: empty string

UIA_NamePropertyId
30005

Identifies the Name property, which is a string that holds the name of the automation element.

The Name property should be the same as the label text on screen. For example, Name should be "Browse" for a button element with the label "Browse". The Name property must not include the mnemonic character for the access keys (that is, "&"), which is underlined in the UI text presentation. Also, the Name property should not be an extended or modified version of the on-screen label because the inconsistency between the name and the label can cause confusion among client applications and users.

When the corresponding label text is not visible on screen, or when it is replaced by graphics, alternative text should be chosen. The alternative text should be concise, intuitive, and localized to the application UI language, or to the operating system default UI language. The alternative text should not be a detailed description of the visual details, but a concise description of the UI function or feature as if it were labeled by simple text. For example, the Windows Start menu button is named "Start" (button) instead of "Windows Logo on blue round sphere graphics" (button). For more information, see Creating Text Equivalents for Images.

When a UI label uses text graphics (for example, using ">>" for a button that adds an item from left to right), the Name property should be overridden by an appropriate text alternative (for example, "Add"). However the practice of using text graphics as a UI label is discouraged due to both localization and accessibility concerns.

The Name property must not include the control role or type information, such as "button" or "list"; otherwise, it will conflict with the text from the LocalizedControlType property when these two properties are appended (many existing assistive technologies do this).

The Name property cannot be used as a unique identifier among siblings. However, as long as it is consistent with the UI presentation, the same Name value can be supported among peers. For test automation, the clients should consider using the AutomationId or RuntimeId property.

Text controls do not always have to have the Name property be identical to the text that is displayed within the control, so long as the Text pattern is also supported.

Variant type: VT_BSTR

Default value: empty string

UIA_NativeWindowHandlePropertyId
30020

Identifies the NativeWindowHandle property, which is an integer that represents the handle (HWND) of the automation element window, if it exists; otherwise, this property is 0.

Variant type: VT_I4

Default value: 0

UIA_OptimizeForVisualContentPropertyId
30111

Identifies the OptimizeForVisualContent property, which is a Boolean value that indicates whether the provider exposes only elements that are visible. A provider can use this property to optimize performance when working with very large pieces of content. For example, as the user pages through a large piece of content, the provider can destroy content elements that are no longer visible. When a content element is destroyed, the provider should return the UIA_E_ELEMENTNOTAVAILABLE error code. Supported starting with Windows 8.

Variant type: VT_BOOL

Default value: FALSE

UIA_OrientationPropertyId
300023

Identifies the Orientation property, which indicates the orientation of the control represented by the automation element. The property is expressed as a value from the OrientationType enumerated type.

The Orientation property is supported by controls, such as scroll bars and sliders, that can have either a vertical or a horizontal orientation. Otherwise, it can always be OrientationType_None, which means that the control has no orientation.

Variant type: VT_I4

Default value: 0 (OrientationType_None)

UIA_ProcessIdPropertyId
30002

Identifies the ProcessId property, which is an integer representing the process identifier (ID) of the automation element.

The process identifier (ID) is assigned by the operating system. It can be seen in the PID column of the Processes tab in Task Manager.

Variant type: VT_I4

Default value: 0

UIA_ProviderDescriptionPropertyId
30107

Identifies the ProviderDescription property, which is a formatted string containing the source information of the UI Automation provider for the automation element, including proxy information.

Variant type: VT_BSTR

Default value: empty string

UIA_RuntimeIdPropertyId
30000

Identifies the RuntimeId property, which is an array of integers representing the identifier for an automation element.

The identifier is unique on the desktop, but it is guaranteed to be unique only within the UI of the desktop on which it was generated. Identifiers can be reused over time.

The format of RuntimeId can change. The returned identifier should be treated as an opaque value and used only for comparison; for example, to determine whether an automation element is in the cache.

Variant type: VT_I4 | VT_ARRAY

Default value: none

Requirements

Minimum supported client

Windows XP [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2003 [desktop apps | Windows Store apps]

Header

UIAutomationClient.h

See also

Conceptual
UI Automation Properties Overview
Retrieving Properties from UI Automation Elements

 

 

Community Additions

Show:
© 2014 Microsoft