Automation Element Property Identifiers
This section lists the constant values used to identify the properties that pertain to Microsoft UI Automation elements.
Constants
- UIA_AcceleratorKeyPropertyId (30006)
Identifies the AcceleratorKey property, which is a string containing the accelerator key combinations for the automation element.
Accelerator key (also called 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 accelerator key property may implement the Invoke control pattern for the action that is equivalent to the accelerator command.
The AcceleratorKey property has a variant type of VT_BSTR; the default value is an 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 keyboard shortcut or 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.
The AccessKey property has a variant type of VT_BSTR; the default value is an 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.
The AriaProperties property has a variant type of VT_BSTR; the default value is an 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. The AriaRole property has a variant type of VT_BSTR; the default value is an 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, may contain elements with the same AutomationId property, such as "SystemMenuBar".
While support for AutomationId is always recommended for better testability, 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 AutomationIds exposed by other applications. AutomationId is not guaranteed to be stable across different releases or builds of an application.
The AutomationId property has a variant type of VT_BSTR; the default value is an 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.
The BoundingRectangle property has a variant type of VT_R8|VT_ARRAY; the default value is an empty rectangle. This property is NULL if the item is not currently displaying a user interface (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 cannot be counted on to be 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.
The ClassName property has a variant type of VT_BSTR; the default value is an 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.
The ClickablePoint property has a variant type of VT_R8|VT_ARRAY; the default value is 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.
The ControllerFor property has a variant type of VT_UNKNOWN|VT_ARRAY; the default value is 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.
The ControlType property has a variant type of VT_I4. The default value is UIA_CustomControlTypeId, which should be avoided unless the automation element is representing 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.
The Culture property has a variant type of VT_I4; the default value is 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.
The DescribedBy property has a variant type of VT_UNKNOWN|VT_ARRAY; the default value is 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.
The FlowsTo property has a variant type of VT_UNKNOWN|VT_ARRAY; the default value is 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".
The FrameworkId property has a variant type of VT_BSTR; the default value is an empty string.- UIA_HasKeyboardFocusPropertyId (30008)
Identifies the HasKeyboardFocus property, which is a Boolean value that indicates whether the automation element has keyboard focus.
The HasKeyboardFocus property has a variant type of VT_BOOL; the default value is 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.
The HelpText property has a variant type of VT_BSTR; the default value is 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. The IsContentElement property has a variant type of VT_BOOL; the default value is 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. The IsControlElement property has a variant type of VT_BOOL; the default value is 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.
The IsDataValidForForm property has a variant type of VT_BOOL; the default value is FALSE.- UIA_IsEnabledPropertyId (30010)
Identifies the IsEnabled property, which is a Boolean value that indicates whether the user interface (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.
The IsEnabled property has a variant type of VT_BOOL; the default value is FALSE.- UIA_IsKeyboardFocusablePropertyId (30009)
Identifies the IsKeyboardFocusable property, which is a Boolean value that indicates whether the automation element can accept keyboard focus.
The IsKeyboardFocusable property has a variant type of VT_BOOL; the default value is 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 underlining 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).
The IsOffscreen property has a variant type of VT_BOOL; the default value is 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.
The IsPassword property has a variant type of VT_BOOL; the default value is 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.
The IsRequiredForForm property has a variant type of VT_BOOL; the default value is 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.
The ItemStatus property has a variant type of VT_BSTR; the default value is an 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.
The ItemType property has a variant type of VT_BSTR; the default value is an 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.
The LabeledBy property has a variant type of VT_UNKNOWN; the default value is NULL.- 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.
The LocalizedControlType property has a variant type of VT_BSTR; the default value is an empty string.- UIA_NamePropertyId (30005)
Identifies the Name property, which is a string for the text representation of the automation element.
The Name property should always be the same as the label text on screen. For example, Name must be "Browse…" for the 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 right to left), 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.
The Name property may not 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.
The Name property has a variant type of VT_BSTR; the default value is an 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.
The NativeWindowHandle property has a variant type of VT_I4; the default value is 0.- 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.
The Orientation property has a variant type of VT_I4; the default value is 0.- 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.
The ProcessId property has a variant type of VT_I4; the default value is 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.
The ProviderDescription property has a variant type of VT_BSTR; the default value is an 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 only guaranteed to be unique within the UI of the desktop on which it was generated. Identifiers can be reused over time.
The format of RuntimeId may 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.
The RuntimeId property has a variant type of VT_I4|VT_ARRAY; it has no default value.
See Also
UI Automation Properties Overview, UI Automation Properties for Clients