Export (0) Print
Expand All

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 PropertyMicrosoft Active Accessibility Equivalent
BoundingRectangleaccLocation
HasKeyboardFocusaccState, STATE_SYSTEM_FOCUSED
IsEnabledaccState, STATE_SYSTEM_UNAVAILABLE
IsKeyboardFocusableaccState, STATE_SYSTEM_FOCUSABLE
IsPasswordaccState, STATE_SYSTEM_PROTECTED
HelpTextaccHelp
NameaccName
NativeWindowHandle WindowFromAccessibleObject
IsOffscreenaccState, STATE_SYSTEM_INVISIBLE/STATE_SYSTEM_OFFSCREEN
ProcessIdProvided 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 PatternMicrosoft Active Accessibility Role
InvokePatternROLE_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.
SelectionItemPatternROLE_SYSTEM_LISTITEM, ROLE_SYSTEM_RADIOBUTTON
SelectionPatternROLE_SYSTEM_LIST
TogglePatternROLE_SYSTEM_CHECKBUTTON
ValuePatternROLE_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.
WindowPatternAutomatically 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 ImplementationsRelated WinEvent Id from Microsoft Active Accessibility
UIA_AriaPropertiesPropertyIdNone
UIA_AriaRolePropertyIdNone
UIA_ControllerForPropertyIdNone
UIA_DescribedByPropertyIdNone
UIA_ExpandCollapseExpandCollapseStatePropertyIdEVENT_OBJECT_STATECHANGE
UIA_FlowsToPropertyIdNone
UIA_InputDiscardedEventIdNone
UIA_InputReachedOtherElementEventIdNone
UIA_InputReachedTargetEventIdNone
UIA_IsDataValidForFormPropertyIdNone
UIA_IsEnabledPropertyIdEVENT_OBJECT_STATECHANGE
UIA_ItemStatusPropertyIdNone
UIA_MultipleViewCurrentViewPropertyIdNone
UIA_ScrollHorizontallyScrollablePropertyIdNone
UIA_ScrollHorizontalScrollPercentPropertyIdEVENT_OBJECT_CONTENTSCROLLED
UIA_ScrollHorizontalViewSizePropertyIdNone
UIA_ScrollVerticallyScrollablePropertyIdNone
UIA_ScrollVerticalScrollPercentPropertyIdEVENT_OBJECT_CONTENTSCROLLED
UIA_ScrollVerticalViewSizePropertyIdNone
UIA_ToggleToggleStatePropertyIdEVENT_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

 

 

Community Additions

ADD
Show:
© 2014 Microsoft