Automation Element Property Identifiers
This topic describes the named constants that identify the properties of Microsoft UI Automation elements.
| Constant/value | Description |
|---|---|
|
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 |
|
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 |
|
Identifies the AnnotationObjects property, which is a list of annotation objects in a document, such as comment, header, footer, and so on. Variant type: VT_I4 | VT_ARRAY Default value: empty array |
|
Identifies the AnnotationTypes property, which is a list of the types of annotations in a document, such as comment, header, footer, and so on. Variant type: VT_I4 | VT_ARRAY Default value: empty array |
|
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 |
|
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:
|
|
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 |
|
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: [0,0,0,0] Note:
|
|
Identifies the CenterPoint property, which specifies the center X and Y point coordinates of the automation element. The coordinate space is what the provider logically considers a page. Variant type: VT_R8 | VT_ARRAY Default value: VT_EMPTY |
|
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 |
|
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: VT_EMPTY |
|
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. This identifier is commonly used for Auto-suggest accessibility. Variant type for providers: VT_UNKNOWN | VT_ARRAY Variant type for clients: VT_UNKNOWN (IUIAutomationElementArray ) Default value: empty array |
|
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:
|
|
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 |
|
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: empty array |
|
Identifies the FillColor property, which specifies the color used to fill the automation element. This attribute is specified as a COLORREF, a 32-bit value used to specify an RGB or RGBA color. Variant type: VT_I4 Default value: 0 |
|
Identifies the FillType property, which specifies the pattern used to fill the automation element, such as none, color, gradient, picture, pattern, and so on. Variant type: VT_I4 Default value: 0 |
|
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: empty array |
|
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: empty array |
|
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 |
|
The FullDescription property exposes a localized string which can contain extended description text for an element. FullDescription can contain a more complete description of an element than may be appropriate for the element Name. Variant type: VT_BSTR Default value: empty string |
|
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 |
|
Identifies the HeadingLevel property, which indicates the heading level of a UI Automation element. Variant type: VT_I4 Default value: HeadingLevel_None |
|
Identifies the HelpText property, which is a help text string associated with the automation element. The HelpText property can 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: empty string |
|
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:
|
|
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 |
|
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 |
|
Identifies the IsDialog property, which is a Boolean value that indicates whether the automation element is a dialog window. For example, assistive technology such as screen readers typically speak the title of the dialog, the focused control in the dialog, and then the content of the dialog up to the focused control ("Do you want to save your changes before closing"). For standard windows, a screen reader typically speaks the window title followed by the focused control. The IsDialog property can be set to TRUE to indicate that the client application should treat the element as a dialog window. Variant type: VT_BOOL Default value: FALSE |
|
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 |
|
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 |
|
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 |
|
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 |
|
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:
Default value: FALSE |
|
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 |
|
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 |
|
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 |
|
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 |
|
Identifies the LandmarkType property, which is a Landmark Type Identifier associated with an element. The LandmarkType property describes an element that represents a group of elements. For example, a search landmark could represent a set of related controls for searching. If UIA_CustomLandmarkTypeId is used then UIA_LocalizedLandmarkTypePropertyId is required to describe the custom landmark. Variant Type: VT_I4 Default Value: 0 |
|
Identifies the Level property, which is a 1-based integer associated with an automation element. The Level property describes the location of an element inside a hierarchical or broken hierarchical structures. For example a bulleted/numbered list, headings, or other structured data items can have various parent/child relationships. Level describes where in the structure the item is located. It is recommended to use the CustomNavigation Control Pattern in tandem with Level. Variant type: VT_I4 Default value: 0 |
|
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: 0 |
|
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:
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 |
|
Identifies the LocalizedLandmarkType, which is a text string describing the type of landmark that the automation element represents. This should be used in tandem with UIA_CustomLandmarkTypeId however, LocalizedLandmarkType should always take precedence over LandmarkType and be used to describe the landmark before LandmarkType. The string must match the application UI language or the operating system default UI language. Variant type: VT_BSTR Default value: empty string |
|
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 |
|
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 |
|
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 |
|
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) |
|
Identifies the OutlineColor property, which specifies the color used for the outline of the automation element. This attribute is specified as a COLORREF, a 32-bit value used to specify an RGB or RGBA color. Variant type: VT_I4 | VT_ARRAY Default value: 0 |
|
Identifies the OutlineThickness property, which specifies the width for the outline of the automation element. Variant type: VT_R8 | VT_ARRAY Default value: VT_EMPTY |
|
Identifies the PositionInSet property, which is a 1-based integer associated with an automation element. PositionInSet describes the ordinal location of the element within a set of elements which are considered to be siblings. PositionInSet works in coordination with the SizeOfSet property to describe the ordinal location in the set. Variant type: VT_I4 Default value: 0 |
|
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 |
|
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 |
|
Identifies the Rotation property, which specifies the angle of rotation in unspecified units. Variant type: VT_R8 Default value: 0 |
|
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: VT_EMPTY |
|
Identifies the Size property, which specifies the width and height of the automation element. Variant type: VT_R8 | VT_ARRAY Default value: VT_EMPTY |
|
Identifies the SizeOfSet property, which is a 1-based integer associated with an automation element. SizeOfSet describes the count of automation elements in a group or set that are considered to be siblings. SizeOfSet works in coordination with the PositionInSet property to describe the count of items in the set. Variant type: VT_I4 Default value: 0 |
|
Identifies the VisualEffects property, which is a bit field that specifies effects on the automation element, such as shadow, reflection, glow, soft edges, or bevel. VisualEffects:
Default value: 0 |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows XP [desktop apps | UWP apps] |
| Minimum supported server |
Windows Server 2003 [desktop apps | UWP apps] |
| Header |
|
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for