Where supported by the platformAccessibilityAPI,user agents exposeWAI-ARIAsemantics through the standard mechanisms of the desktop accessibilityAPI. For example, forWAI-ARIAwidgets, compare how the widget is exposed in a similar desktop widget. In general mostWAI-ARIA widget capabilities are exposed through therole, value, Booleanstates, and relations of the accessibilityAPI.
With respect toWAI-ARIA 1.0 and 1.1, accessibilityAPIs operate in one direction only. User agents publishWAI-ARIA information (roles, states, and properties) via an accessibilityAPI, and anAT can acquire that information using the sameAPI. However, the other direction is not supported.WAI-ARIA 1.0 and 1.1 do not define mechanisms for assistive technologies to directly modifyWAI-ARIA information.
The terms "exposing", "mapping", and "including" refer to the creation ofaccessible objectnodes within theaccessibility tree, and populating these objects withAccessibilityAPI specificstates andproperties.
3.6Special Processing Requiring Additional Computation
Often in aGUI, there arerelationships between thewidgets that can be exposed programmatically toassistive technology.WAI-ARIA provides several relationshipproperties which are globally applicable to anyelement:aria-controls,aria-describedby,aria-flowto,aria-labelledby,aria-owns,aria-posinset, andaria-setsize. Therefore, it is not important to check therole before computing them.User agents can simply map these relations toaccessibilityAPIs as defined in the section titledState and Property Mapping.
3.6.2.2Implied reverse relations
In addition to the explicit relations defined byWAI-ARIAproperties, reverse relations are implied in two other situations:elements withrole="treeitem" where the ancestor does not have anaria-owns property and descendants of elements witharia-atomic property.
In the case ofrole="treeitem", whenaria-owns is not used,user agentsSHOULD do the following where reverse relations are supported by theAPI:
- If the current
treeitem usesaria-level, then walk backwards in the tree until atreeitem is found with a loweraria-level, then setRELATION_NODE_CHILD_OF to that element. If the top of the tree is reached, then setRELATION_NODE_CHILD_OF to the tree element itself. - If the parent of the
treeitem has arole ofgroup, then walk backwards from thegroup until an element with a role oftreeitem is found, then setRELATION_NODE_CHILD_OF to that element.
In the case ofaria-atomic, where reverse relations are supported by theAPI:
- User agentsSHOULD check the chain of ancestor elements for
aria-atomic="true". If found, user agentsSHOULD set theRELATION_MEMBER_OF relation to point to the ancestor that setsaria-atomic="true".
aria-level,aria-posinset, andaria-setsize are all 1-based. When theproperty is not present or is "0", it indicates the property is not computed or not supported. If any of these properties are specified by the author as either "0" or a negative number,user agentsSHOULD use "1" instead.
Ifaria-level is not provided or inherited for an element ofroletreeitem orcomment, user agents implementing IAccessible2 orATK/AT-SPIMUST compute it by following the explicit or computedRELATION_NODE_CHILD_OF relations.
Ifaria-posinset andaria-setsize are not provided, user agentsMUST compute them as follows:
- for
role="treeitem" androle="comment", walk the tree backward and forward until the explicit or computed level becomes less than the current item's level. Count items only if they are at the same level as the current item. - Otherwise, if the role supports
aria-posinset andaria-setsize, process the parent (DOM parent or parent defined byaria-owns), counting items that have the same role. - Because these value are 1-based, include the current item in the computation. For
aria-posinset, include the current item and other group items if they are before the current item in theDOM. Foraria-setsize, add to that the number of items in the same group after the current item in theDOM.
If the author provides one or more ofaria-setsize andaria-posinset, it is the author's responsibility to supply them for all elements in the set.User agent correction of missing values in this case is not defined.
MSAA/IAccessible2API mappings involve an additional function,groupPosition() [IAccessible2], whenaria-level,aria-posinset, and/oraria-setsize are present on an element, or are computed by the user agent. When this occurs:
aria-level is exposed in thegroupLevel parameter ofgroupPosition(),aria-setsize is exposed in thesimilarItemsInGroup parameter, andaria-posinset is exposed in thepositionInGroup parameter.
User agents fireevents for user actions,WAI-ARIAstate changes, changes to document content or node visibility, changes in selection and operation of menus as defined in the following sections.
3.8.2Changes to document content or node visibility
Processing document changes is important regardless ofWAI-ARIA. The events described in the table below are used by user agents to informAT of changes to theDOM via the accessibility tree. For the purposes of conformance with this standard,user agentsMUST implement the behavior described in this section wheneverWAI-ARIA attributes are applied to dynamic content on a Web page.
Table of document change scenarios and events to be fired in eachAPI| Scenario | MSAA + IAccessible2 event | UIA event | ATK/AT-SPI event | AX API Notification |
|---|
| When text is removed | IA2_EVENT_TEXT_REMOVED | EVENT_OBJECT_LIVEREGIONCHANGED | text_changed::delete | If in alive region,AXLiveRegionChanged.
If inaria-errormessage,AXValidationErrorChanged. |
|---|
| When text is inserted | IA2_EVENT_TEXT_INSERTED | EVENT_OBJECT_LIVEREGIONCHANGED | text_changed::insert | If in alive region,AXLiveRegionChanged.
If inaria-errormessage,AXValidationErrorChanged. |
|---|
| When text is changed | IA2_EVENT_TEXT_REMOVE andIA2_EVENT_TEXT_INSERTED | EVENT_OBJECT_LIVEREGIONCHANGED | text_changed::delete andtext_changed::insert | If in alive region,AXLiveRegionChanged.
If inaria-errormessage,AXValidationErrorChanged. |
|---|
Fire the following events for node changes where the node in question is an element and has anaccessible object. Theaccessibility subtree of a node is itsaccessible object in theaccessibility tree and all of it'saccessibility descendants. It does not include objects which have relationships other than parent-child in that tree. For example, it does not include objects linked viaaria-flowto unless those objects are also descendants in theaccessibility tree.
Table of document change scenarios and events to be fired in eachAPI| Scenario | MSAA | MicrosoftUIA event | ATK/AT-SPI event | AX API Notification |
|---|
| When anaccessibility subtree ishidden | EVENT_OBJECT_HIDE
TheMSAA event calledEVENT_OBJECT_DESTROY is not used because this has a history of stability issues and assistive technology avoids it. In any case, from the user's point of view, there is no difference between something that is hidden or destroyed. | AutomationElement..::.StructureChangedEvent | children_changed::remove | AXUIElementDestroyed
If in a live region,AXLiveRegionChanged |
|---|
| When an accessibility subtree is removed | EVENT_OBJECT_REORDER
TheMSAA event calledEVENT_OBJECT_DESTROY is not used because this has a history of stability issues and assistive technology avoids it. In any case, from the user's point of view, there is no difference between something that is hidden or destroyed. | AutomationElement..::.StructureChangedEvent | children_changed::remove | AXUIElementDestroyed
If in a live region,AXLiveRegionChanged |
|---|
| When an accessibility subtree is shown | EVENT_OBJECT_SHOW | | children_changed::add | AXUIElementCreated
If in a live region,AXLiveRegionChanged |
|---|
| When an accessibility subtree is inserted | EVENT_OBJECT_REORDER | | children_changed::add | AXUIElementCreated
If in a live region,AXLiveRegionChanged |
|---|
| When an accessibility subtree is moved | Treat it as a removal from one place and insertion in another | Treat it as a removal from one place and insertion in another | Treat it as a removal from one place and insertion in another | AXUIElementDestroyed/AXUIElementCreated
If in a live region,AXLiveRegionChanged |
|---|
| When an accessibility subtree is changed (e.g. replaceNode) | Treat it as a removal and insertion | Treat it as a removal and insertion | Treat it as a removal and insertion | AXUIElementDestroyed/AXUIElementCreated
If in a live region,AXLiveRegionChanged |
|---|
In some cases, node changes may occur where the node is not an element or has no accessible object. For example, a numbered list bullet ("12.") may have a node in the accessibility tree but not in theDOM tree. For text within a paragraph marked inHTML as<strong>, the<strong> element has a node in theDOM tree but may not have one in the accessibility tree. The text itself will of course be in the accessibility tree along with the identification of the range of text that is formatted as strong. If any of the changes described in the table above occur on such a node, user agentsSHOULD compute and fire relevant text change events as described above.
User agentsSHOULD ensure that an assistive technology, running in process can receive notification of a node being removed prior to removal. This allows an assistive technology, such as a screen reader, to refer back to the correspondingDOM node being deleted. This is important forlive regions where removals are important. For example, a screen reader would want to notify a user that another user has left a chat room. The event inMSAA would be EVENT_OBJECT_HIDE. ForATK/AT-SPI this would bechildren_changed::remove. And in macOS, the event isAXLiveRegionChanged. This also requires the user agent to provide a unique ID in theaccessibilityAPI notification identifying the unique node being removed.
When firing any of the above-mentioned change events, it is very useful to provide information about whether the change was caused by user input (as opposed to a timeout initiated from the page load, etc.). This allows the assistive technology to have different rules for presenting changes from the real world as opposed to from user action. Mouse hovers are not considered explicit user input because they can occur from accidental bumps of the mouse.
To expose whether a change occurred from user input:
Exposing additional useful information about the context of the change:
AdditionalMSAA events may be necessary:
The following table defines the accessibilityAPI keyboard focus states and events.
Table ofaccessibilityAPIs for focus states andevents| | MSAA | MicrosoftUIA | ATK/AT-SPI | AX API |
|---|
| Focusable state | STATE_SYSTEM_FOCUSABLE | Current state reflected inIUIAutomationElement::CurrentIsKeyboardFocusable, can be retrieved withIUIAutomationElement::GetCurrentPropertyValue method usingUIA_IsKeyboardFocusablePropertyId property identifier. | STATE_FOCUSABLE | boolean AXFocused: theAXUIElementIsAttributeSettable method returnsYES. |
|---|
| Focused state | STATE_SYSTEM_FOCUSED | Current state reflected inIUIAutomationElement::CurrentHasKeyboardFocus, can be retrieved withIUIAutomationElement::GetCurrentPropertyValue method usingUIA_HasKeyboardFocusPropertyId property identifier. | STATE_FOCUSED | boolean AXFocused |
|---|
| Focus event | EVENT_OBJECT_FOCUS | Clients can subscribe withIUIAutomation::AddFocusChangedEventHandler using callback interface isIUIAutomationFocusChangedEventHandler | object:state-changed:focused and: | AXFocusedUIElementChanged |
|---|
There are two cases for selection:
- Single selection
- Multiple selection
In the single selection case, selection follows focus (see the section "Focus States and Events Table" for information about focus events). User agentsMUST fire the following events whenaria-selected changes:
Single selection events| Scenario | MSAA | MicrosoftUIA | ATK/AT-SPI | AX API |
|---|
| Focus change | EVENT_OBJECT_SELECTION andEVENT_OBJECT_STATECHANGE on newly focused item. | UIA_SelectionItem_ElementSelectedEventId on the newly focused element.If on agridcell,row,option, ortab, fireUIA_SelectionItem_ElementSelectedEventId. | object:selection-changed on the current container,object:state-changed:selected on the descendantaccessible object whose selection has changed:detail1 = 1 for the descendant which just became selected.detail1 = 0 for the descendant which just became unselected.
| AXSelectedChildrenChanged |
|---|
The multiple selection case occurs whenaria-multiselectable="true" on anelement with arole that supports thatproperty. User agentsMUST fire the following events whenaria-selected changes on a descendant, as follows:
The multiple selection case occurs whenaria-multiselectable="true" on anelement with arole that supports thatproperty. There are several important aspects:
- In MicrosoftUIA, the
Selection andSelectionItem Control Patterns expose the selection availability, state, and methods. - User agentsMUST fire the following events when
aria-selected changes on a descendant, as follows:
Multiple selection events| Scenario | MSAA | MicrosoftUIA | ATK/AT-SPI | AX API |
|---|
Togglearia-selected | EVENT_OBJECT_SELECTIONADD/EVENT_OBJECT_SELECTIONREMOVE on the item. | SelectionItem Control Pattern:UIA_SelectionItem_ElementAddedToSelectionEventId orUIA_SelectionItem_ElementRemovedFromSelectionEventId on the item. | object:selection-changed on the current container,object:state-changed:selected on any descendantaccessible object whose selection has changed:detail1 = 1 for any descendant which just became selected.detail1 = 0 for any descendant which just became unselected.
| AXSelectedChildrenChanged |
|---|
| Selection follows focus | EVENT_OBJECT_SELECTION andEVENT_OBJECT_STATECHANGE on newly focused item. | FocusChangedEvent should be fired but individual selection event may not happen, to avoid redundancy. | object:selection-changed on the current container,object:state-changed:selected on any descendantaccessible object whose selection has changed:
| AXSelectedChildrenChanged |
|---|
| Select or deselect many items at once | User agentMAY fire anEVENT_OBJECT_SELECTIONWITHIN. If this event is fired the other events noted aboveMAY be trimmed out for performance. | For each element selected or deselected, fireSelectionItem Control Pattern:UIA_SelectionItem_ElementAddedToSelectionEventId orUIA_SelectionItem_ElementRemovedFromSelectionEventId on the current container. User agentsMAY choose to fire the Selection Control Pattern Invalidated event, which indicates that the selection in a container has changed significantly and requires sending more addition and removal events than theInvalidateLimit constant permits. | - the user agentMAY fire a single
object:selection-changed event on the container, vs. multiple events, for performance, object:state-changed:selected on any descendantaccessible object whose selection has changed:
| AXSelectedChildrenChanged |
|---|
3.8.5Special Events for Menus
SomeAPIs, provide specialevents whenever a menu is opened or closed.User agentsSHOULD provide the events as described in the table below. If provided, because menus can be made visible orhidden using a variety of techniques, auser agentMUST ensure that the events are nested and symmetrical.
Frequently, amenubar is used to organize a hierarchy of menus. In those cases, the menubarMUST be aDOM parent of the associatedmenuitems, or one defined byaria-owns. In other cases, no menubar is involved; for example, when themenu is associated with a toolbar button, or is a context menu. Nonetheless the relevant menu events are provided as described in the following table.
Menu events| Scenario | MSAA | MicrosoftUIA | AX API |
|---|
Menubar is currently not active, and user moves focus to the menubar from elsewhere thereby activating it. As a result, a menuitem in the menubar is focused. | Activate the menubar and fireEVENT_SYSTEM_MENUSTART on the accessible object for the menubar. | MenuModeStartEvent on the accessible object for the menu. | AXMenuOpenedNotification |
Focus a menuitem while menubar is activated, or focus a menuitem in a menu. | EVENT_OBJECT_FOCUS | AutomationFocusChangedEvent | AXMenuItemSelectedNotification |
Menu popup made visible (menu is opened). Should only be fired once until the menu is closed and opened again. | EVENT_SYSTEM_MENUPOPUPSTART | MenuOpenedEvent, then afocus event on a menuitem. | AXMenuOpenedNotification |
| Menu popup hidden (menu is closed). | EVENT_SYSTEM_MENUPOPUPEND once only for accessible menu object and only ifEVENT_SYSTEM_MENUPOPUPSTART was fired for it. | MenuClosedEvent | AXMenuClosedNotification |
| Any open menus are closed including sub-menus, and user moves focus away from the menubar; menubar is deactivated. | EVENT_SYSTEM_MENUEND on the menubar and deactivate the menubar. | MenuClosedEvent, thenMenuModeEndEvent | AXMenuClosedNotification |