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
• Control Patterns
• WinEvents for UI Automation Property Changed Events
• Related topics

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

WinEvents

The IAccessibleEx Interface