An overview of key concepts and features of accessibility (AX) support for a //content browser.
AXMode is a bitfield that specifies how much AX data the browser needs from renderers. The browser's own UI becomes accessible when the kNativeAPIs bit is set (this is typically called “native accessibility”). The pages displayed in WebContents become accessible when the kWebContents bit is set (typically called “web accessibility”). Additional mode flags increase the information from pages that are made available to an AX tool (AT). Some mode flags may enable other features in web content (e.g., image labeling).
A renderer produces AX data according to the mode flags that it is given by its WebContents. This may contain flags not present in the process-wide mode (BrowserAccessibilityState::GetAccessibilityMode()) due to targeting (see Targeted accessibility).
Typically, AX processing is enabled for the browser when it detects the presence of an AT. This is done via platform-specific mechanisms, which may involve heuristics. A distinction is made between an AT that is definitively a screen reader vs. some other tool (e.g., a form filler). When a screen reader is detected, kExtendedProperties is added to the browser's AXMode. This may be used as a signal for other components of the browser that need special behavior when a screen reader is in use.
AX processing is enabled by creation of a ScopedAccessibilityMode (SAM) instance, and stays active throughout the lifetime of said instance. AX processing is enabled for the entire browser process via creation of a SAM with one or more mode flags; see BrowserAccessibilityState::CreateScopedModeForProcess. In this case, all WebContents in the process receive the new mode flags (see Progressive Accessibility for more details). A process-wide SAM is the only way to enable native accessibility, as native accessibility applies to all native UI components (i.e., Views) in the process.
A component that requires AX data from a specific WebContents uses BrowserAccessibilityState::CreateScopedModeForWebContents to create a SAM targeting that one WebContents (with at least the kWebContents mode flag).
A SAM can target all WebContents belonging to a particular BrowserContext (a “Profile” in Chrome terms) with BrowserAccessibilityState::CreateScopedModeForBrowserContext. This is most useful for enabling mode flags associated with a user preference (e.g., image labeling). Due to filtering performed by BrowserAccessibilityState, a component may speculatively enable mode flags that depend on more fundamental flags. For example, kLabelImages is filtered out if kExtendedProperties is not also present.
A WebContents tells its RenderFrames that it wants AX data (e.g., trees and updates) by sending a set of AXMode flags to its blink::mojom::RenderAccessibility interface. These mode flags tell the renderer how much AX data the browser needs. As explained above, the bare minimum mode for web AX data is kWebContents.
A RenderFrame sends AX data to its RenderFrameHost in the browser by way of RenderAccessibilityHost. The frame's WebContents and its observers are given an opportunity to view/modify the AX data before it is given to the BrowserAccessibilityManager for merging into the WebContents's existing tree.
Mode flag changes are not distributed immediately to WebContents that are hidden. Such changes are held by the WebContents and only sent to its renderers when it is unhidden (becomes visible or occluded). One implication of this is that WebContents::GetAccessibilityMode() on an instance that has never been drawn will return an empty set.