Edit

Share via

IAccessibleEx Implementation Guidelines

  • Article

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.

WinEvents

The IAccessibleEx Interface