IAccessibleEx Implementation Guidelines
The Microsoft UI Automation core can retrieve all Microsoft Active Accessibility properties for any accessible object exposed by a server through the IAccessible interface. When implementing IAccessibleEx, you must expose only those aspects of UI functionality that cannot otherwise be exposed through existing Microsoft Active Accessibility properties. This topic identifies the UI Automation properties and control patterns that represent UI functionality that has no counterpart in Microsoft Active Accessibility—they are the properties and control patterns that you can expose in an IAccessibleEx implementation.
This topic contains the following sections:
Properties
The following UI Automation properties do not overlap with Microsoft Active Accessibility functionality. They can be used in an IAccessibleEx implementation:
- AriaProperties
- AriaRole
- AutomationId
- ClassName
- ClickablePoint
- ControllerFor
- Culture
- DescribedBy
- FlowsTo
- FrameworkId
- IsContentElement
- IsControlElement
- IsDataValidForForm
- IsRequiredForForm
- ItemStatus
- ItemType
- LabeledBy
- LocalizedControlType
- Orientation
Although the AcceleratorKey and AccessKey UI Automation properties do overlap with the accKeyboardShortcut Microsoft Active Accessibility property, you can still use them in an IAccessibleEx implementation for controls that have both an access key and an accelerator. Similarly, the ControlType UI Automation property overlaps with the Microsoft Active Accessibility accRole property, but you can still use it in an IAccessibleEx implementation to define a more specific role for a control.
Because the following UI Automation element properties are already covered by Microsoft Active Accessibility properties, there is no need to use them in an IAccessibleEx implementation.
| UI Automation Property | Microsoft Active Accessibility Equivalent |
|---|---|
| BoundingRectangle | accLocation |
| HasKeyboardFocus | accState, STATE_SYSTEM_FOCUSED |
| IsEnabled | accState, STATE_SYSTEM_UNAVAILABLE |
| IsKeyboardFocusable | accState, STATE_SYSTEM_FOCUSABLE |
| IsPassword | accState, STATE_SYSTEM_PROTECTED |
| HelpText | accHelp |
| Name | accName |
| NativeWindowHandle | WindowFromAccessibleObject |
| IsOffscreen | accState, STATE_SYSTEM_INVISIBLE/STATE_SYSTEM_OFFSCREEN |
| ProcessId | Provided by UI Automation core |
For any unsupported UI Automation property, your implementation of the IRawElementProviderSimple::GetPropertyValue method should set the pRetVal parameter to VT_EMPTY, and return S_OK. Returning UIA_E_NOTSUPPORTED may cause the MSAA-to-UIA Proxy to remove the default mapping for the corresponding property.
Control Patterns
The following UI Automation control patterns do not overlap with Microsoft Active Accessibility functionality. They can be used in an IAccessibleEx implementation:
- Dock
- ExpandCollapse
- Grid
- GridItem
- MultipleView
- RangeValue
- Scroll
- ScrollItem
- SynchronizedInput
- Table
- TableItem
- Transform
For the RangeValue and Transform control patterns, some methods overlap between the UI Automation control pattern and Microsoft Active Accessibility methods. In these cases, both must be implemented. For example, both Microsoft Active Accessibility's IAccessible::get_accValue and IAccessible::put_accValue methods must both be implemented, as must the UI AutomationIRangeValueProvider::Value and IRangeValueProvider::SetValue methods. Internally, an implementation can share code for these. This requirement to implement both sets avoids having a partial implementation of a pattern interface while keeping the IAccessible interface usable by existing Microsoft Active Accessibility clients.
The following UI Automation control patterns are not required when the control has one of the roles outlined below; otherwise, they should be explicitly supported if relevant.
| UI Automation Control Pattern | Microsoft Active Accessibility Role |
|---|---|
| InvokePattern | ROLE_SYSTEM_PUSHBUTTON, ROLE_SYSTEM_MENUITEM, ROLE_SYSTEM_BUTTONDROPDOWN, ROLE_SYSTEM_SPLITBUTTON, and any other role where the value of the accDefaultAction property is not NULL. |
| SelectionItemPattern | ROLE_SYSTEM_LISTITEM, ROLE_SYSTEM_RADIOBUTTON |
| SelectionPattern | ROLE_SYSTEM_LIST |
| TogglePattern | ROLE_SYSTEM_CHECKBUTTON |
| ValuePattern | ROLE_SYSTEM_TEXT (when it is not read-only), ROLE_SYSTEM_PROGRESSBAR, ROLE_SYSTEM_COMBOBOX, and any other role when the value of the accValue property is not NULL. |
| WindowPattern | Automatically supported on top-level Microsoft Win32 HWNDs. |
WinEvents for UI Automation Property Changed Events
In addition to the events defined for IAccessible, the following event identifiers are also defined and may be used with an IAccessibleEx implementation as property changed events for corresponding UI Automation properties. These use the same mechanism as the events defined for IAccessible. For more information, see WinEvents.
| WinEvent ID for IAccessibleEx Implementations | Related WinEvent Id from Microsoft Active Accessibility |
|---|---|
| UIA_AriaPropertiesPropertyId | None |
| UIA_AriaRolePropertyId | None |
| UIA_ControllerForPropertyId | None |
| UIA_DescribedByPropertyId | None |
| UIA_ExpandCollapseExpandCollapseStatePropertyId | EVENT_OBJECT_STATECHANGE |
| UIA_FlowsToPropertyId | None |
| UIA_InputDiscardedEventId | None |
| UIA_InputReachedOtherElementEventId | None |
| UIA_InputReachedTargetEventId | None |
| UIA_IsDataValidForFormPropertyId | None |
| UIA_IsEnabledPropertyId | EVENT_OBJECT_STATECHANGE |
| UIA_ItemStatusPropertyId | None |
| UIA_MultipleViewCurrentViewPropertyId | None |
| UIA_ScrollHorizontallyScrollablePropertyId | None |
| UIA_ScrollHorizontalScrollPercentPropertyId | EVENT_OBJECT_CONTENTSCROLLED |
| UIA_ScrollHorizontalViewSizePropertyId | None |
| UIA_ScrollVerticallyScrollablePropertyId | None |
| UIA_ScrollVerticalScrollPercentPropertyId | EVENT_OBJECT_CONTENTSCROLLED |
| UIA_ScrollVerticalViewSizePropertyId | None |
| UIA_ToggleToggleStatePropertyId | EVENT_OBJECT_STATECHANGE |
For the events above that have an EVENT_OBJECT_ value listed after them, and IAccessibleEx implementation should fire this event in addition to the listed changed event. This enables existing IAccessibleEx client code to continue working, while conveying more granular event information to interested clients.
Related topics