docs/accessibility.md - Issue 2385683003: docs: add accessibility overview

Side by Side Diff: docs/accessibility.md

Issue 2385683003: docs: add accessibility overview (Closed)

Patch Set: Created 4 years, 2 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

OLD	NEW
(Empty)
	1 # Accessibility Overview
	dmazzoni 2016/09/30 19:34:46 Thanks for writing this. Can you please link to t Thanks for writing this. Can you please link to this from https://www.chromium.org/developers/design-documents/accessibility? It doesn't seem redundant with any existing docs but we should cross-link Elly Fong-Jones 2016/10/03 11:54:42 As soon as it's landed, I can update that site to Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > Thanks for writing this. > > Can you please link to this from > https://www.chromium.org/developers/design-documents/accessibility > > It doesn't seem redundant with any existing docs but we should cross-link As soon as it's landed, I can update that site to link to it.
	2

	3 This document describes how accessibility is implemented throughout Chromium at

	4 a high level.

	5

	6 ## Concepts

	7

	8 The three central concepts of accessibility are:

	9

	10 1. The tree, which models the entire interface as a tree of objects, exposed

	11 to screenreaders or other accessibility software;

	12 2. Events, which let accessibility software know that a part of the tree has

	13 changed somehow;

	14 3. Commands, which come from accessibility software and ask the interface to
	dmazzoni 2016/09/30 19:34:46 I think we call this "actions" most often in the c I think we call this "actions" most often in the code It might be good to give examples of each of these Elly Fong-Jones 2016/10/03 11:54:42 Done. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > I think we call this "actions" most often in the code Done. Show quoted text > It might be good to give examples of each of these I added some synthetic examples of these things.
	15 change.

	16

	17 All three concepts are handled at several layers in Chromium.

	18

	19 ## Blink

	20

	21 Blink constructs an accessibility tree (a heirarchy of [WebAXObject]s) from the
	dmazzoni 2016/09/30 19:34:46 heirarchy -> hierarchy heirarchy -> hierarchy Elly Fong-Jones 2016/10/03 11:54:42 I have been making this typo my entire life :( Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > heirarchy -> hierarchy I have been making this typo my entire life :(
	22 page it is rendering. WebAXObject is the public API wrapper around [AXObject],

	23 which is the core class of Blink's accessibility tree. AXObjects come in two

	24 kinds: [AXNodeObject], which represents a [Node] in the accessibility tree,
	dmazzoni 2016/09/30 19:34:46 Two things are unclear in this description: 1. AX Two things are unclear in this description: 1. AXLayoutObject is a subclass of AXNodeObject, so the vast majority of nodes will be AXLayoutObject 2. There are other subclasses, not just those two. I think this is the best high-level summary: 1. AXObject is the abstract interface, it has some common code but can't be instantiated 2. Most AXObjects are AXNodeObjects and wrap a node 3. Most AXNodeObjects are AXLayoutObjects that wrap a layout object AND a node 4. There are a few subclasses of AXLayoutObject for specific elements like tables 5. The remaining AXObjects are subclasses of AXMockObject for things like a slider thumb or a menu list popup that need to exist in the accessibility tree but don't correspond to an actual object elsewhere in Blink Elly Fong-Jones 2016/10/03 11:54:42 Done. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > Two things are unclear in this description: > > 1. AXLayoutObject is a subclass of AXNodeObject, so the vast majority of nodes > will be AXLayoutObject > > 2. There are other subclasses, not just those two. > > I think this is the best high-level summary: > > 1. AXObject is the abstract interface, it has some common code but can't be > instantiated > 2. Most AXObjects are AXNodeObjects and wrap a node > 3. Most AXNodeObjects are AXLayoutObjects that wrap a layout object AND a node > 4. There are a few subclasses of AXLayoutObject for specific elements like > tables > 5. The remaining AXObjects are subclasses of AXMockObject for things like a > slider thumb or a menu list popup that need to exist in the accessibility tree > but don't correspond to an actual object elsewhere in Blink > > Done.
	25 and [AXLayoutObject], which represents a [LayoutObject] in the accessibility tre e.

	26 LayoutObjects are more or less Nodes with CSS applied; AXLayoutObject exists
	dmazzoni 2016/09/30 19:34:46 LayoutObjects are a lot more than that. There are LayoutObjects are a lot more than that. There are a lot of passes that happen after a change to the DOM tree. One of the first is style resolution, but that's a prerequisite for Layout, but otherwise not related. You can get a DOM node's style without layout, so Nektarios is wrong about that. The layout pass takes the DOM and the style resolution and builds or updates the layout tree, which contains the complete tree of how to layout all of the page content on the page. It handles things like line wrapping, overflow, etc. Stages after that include building the layer tree, paint tree, and compositing tree, etc., which accessibility mostly ignores One thing to note is that there are some LayoutObjects that don't correspond to nodes, for example "anonymous blocks" that just wrap and group a bunch of related inline elements. They're super annoying to deal with Elly Fong-Jones 2016/10/03 11:54:42 Done. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > LayoutObjects are a lot more than that. There are a lot of passes that happen > after a change to the DOM tree. One of the first is style resolution, but that's > a prerequisite for Layout, but otherwise not related. You can get a DOM node's > style without layout, so Nektarios is wrong about that. > > The layout pass takes the DOM and the style resolution and builds or updates the > layout tree, which contains the complete tree of how to layout all of the page > content on the page. It handles things like line wrapping, overflow, etc. > > Stages after that include building the layer tree, paint tree, and compositing > tree, etc., which accessibility mostly ignores > > One thing to note is that there are some LayoutObjects that don't correspond to > nodes, for example "anonymous blocks" that just wrap and group a bunch of > related inline elements. They're super annoying to deal with Done.
	27 primarily because certain kinds of node should only appear in the AXObject tree

	28 depending on details of their geometry or visibility.

	29

	30 The central class responsible for dealing with accessibility events in Blink is

	31 [AXObjectCacheImpl], which is responsible for caching the corresponding

	32 AXObjects for Nodes or LayoutObjects. This class has many methods named

	33 `handleFoo`, which are called throughout Blink to notify the AXObjectCacheImpl

	34 that it may need to update its tree. Since this class is already aware of all

	35 accessibility events in Blink, it is also responsible for relaying accessibility

	36 events from Blink to the embedding content layer.

	37

	38 ## The content layer

	39

	40 The content layer lives on both sides of the renderer/browser split. The content

	41 layer translates WebAXObjects into [AXContentNodeData], which is a subclass of

	42 [ui::AXNodeData]. The ui::AXNodeData class and related classes are Chromium's

	43 cross-platform accessibility tree. The translation is implemented in

	44 [BlinkAXTreeSource]. This translation happens on the renderer side, so the

	45 ui::AXNodeData tree now needs to be sent to the browser, which is done by

	46 sending [AccessibilityHostMsg_EventParams] with the payload being serialized

	47 delta-updates to the tree, so that changes that happen on the renderer side can

	48 be reflected on the browser side.

	49

	50 On the browser side, these IPCs are received by [BrowserAccessibilityManager],
	dmazzoni 2016/09/30 19:34:46 They're actually received by RenderFrameHostImpl, They're actually received by RenderFrameHostImpl, which owns the BAM - this is important because on Chrome OS we forward the accessibility events directly to extension processes like ChromeVox, bypassing BAM entirely Elly Fong-Jones 2016/10/03 11:54:42 Done. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > They're actually received by RenderFrameHostImpl, which owns the BAM - > this is important because on Chrome OS we forward the accessibility > events directly to extension processes like ChromeVox, bypassing BAM > entirely Done.
	51 which is responsible for:

	52

	53 1. Combining AXNodeData trees into a tree of [BrowserAccessibility] objects.
	dmazzoni 2016/09/30 19:34:46 To clarify a bit, this is handled by AXTree, and B To clarify a bit, this is handled by AXTree, and BrowserAccessibility wraps each AXNode in the AXTree for the platform-specific implementation Elly Fong-Jones 2016/10/03 11:54:42 I think I rewrote this to make more sense. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > To clarify a bit, this is handled by AXTree, and BrowserAccessibility wraps each > AXNode in the AXTree for the platform-specific implementation I think I rewrote this to make more sense.
	54 This is important because each page has its own accessibility tree, but each

	55 Chromium window must have only one accessibility tree, so trees from

	56 multiple pages need to be combined (possibly also with trees from Views UI).

	57 This is done by [AXTreeCombiner].
	dmazzoni 2016/09/30 19:34:46 Actually AXTreeCombiner isn't used for this. Rathe Actually AXTreeCombiner isn't used for this. Rather, the BrowserAccessibilityManagers all link to each other and present one big composed tree. Elly Fong-Jones 2016/10/03 11:54:42 Done. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > Actually AXTreeCombiner isn't used for this. Rather, the > BrowserAccessibilityManagers all link to each other and present one big composed > tree. Done.
	58 2. Dispatching outgoing accessibility events to the platform's accessibility

	59 APIs. This is done in the platform-specific subclasses of

	60 BrowserAccessibilityManager, in a method named `NotifyAccessibilityEvent`.

	61 3. Dispatching incoming accessibility commands to the appropriate recipient, via

	62 [BrowserAccessibilityDelegate]. For messages destined for a renderer,

	63 [RenderFrameHostImpl], which is a BrowserAccessibilityDelegate, is

	64 responsible for sending appropriate `AccessibilityMsg_Foo` IPCs to the

	65 renderer, where they will be received by [RenderAccessibilityImpl].

	66

	67 ## Views

	68

	69 Views generates a tree of AXPlatformNodes corresponding to the tree of Views.
	dmazzoni 2016/09/30 19:34:46 Sort of the other way around, each View creates a Sort of the other way around, each View creates a NativeViewAccessibility, which is used as the delegate for a AXPlatformNode that represents a node in the accessibility tree Elly Fong-Jones 2016/10/03 11:54:42 Done. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > Sort of the other way around, each View creates a NativeViewAccessibility, which > is used as the delegate > for a AXPlatformNode that represents a node in the accessibility tree Done.
	70 This is implemented in [NativeViewAccessibility] and is mostly straightforward.
	dmazzoni 2016/09/30 19:34:46 The un-straightforward part is how the web tree is The un-straightforward part is how the web tree is grated onto the views tree Elly Fong-Jones 2016/10/03 11:54:42 Done. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > The un-straightforward part is how the web tree is grated onto > the views tree Done.
	71

	72 ## WebUI

	73

	74 Since WebUI surfaces have renderer processes as normal, WebUI accessibility goes

	75 through the blink-to-content-to-platform pipeline described above. Accessibility

	76 for WebUI is largely implemented in JavaScript in [webui-js]; these classes take

	77 care of adding ARIA attributes and so on to DOM nodes as needed.

	78

	79 ## The chrome layer
	dmazzoni 2016/09/30 19:34:46 I'd call this the "Chrome OS" layer, since that's I'd call this the "Chrome OS" layer, since that's the only place where we currently use the automation API. Elly Fong-Jones 2016/10/03 11:54:42 Done. Show quoted text On 2016/09/30 19:34:46, dmazzoni wrote: > I'd call this the "Chrome OS" layer, since that's the only place > where we currently use the automation API. Done.
	80

	81 The accessibility tree is also exposed via the [chrome.automation API], which

	82 gives extension JavaScript access to the accessibility tree, events, and

	83 commands. This API is implemented in C++ by [AutomationInternalCustomBindings],

	84 which is renderer-side code, and in JavaScript by the [automation API]. The API

	85 is defined by [automation.idl], which must be kept synchronized with

	86 [ax_enums.idl].

	87

	88 [AccessibilityHostMsg_EventParams]: https://cs.chromium.org/chromium/src/content /common/accessibility_messages.h?sq=package:chromium&l=75

	89 [AutomationInternalCustomBindings]: https://cs.chromium.org/chromium/src/chrome/ renderer/extensions/automation_internal_custom_bindings.h

	90 [AXContentNodeData]: https://cs.chromium.org/chromium/src/content/common/ax_cont ent_node_data.h

	91 [AXLayoutObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source /modules/accessibility/AXLayoutObject.h

	92 [AXNodeObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/m odules/accessibility/AXNodeObject.h

	93 [AXObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/modul es/accessibility/AXObject.h

	94 [AXObjectCacheImpl]: https://cs.chromium.org/chromium/src/third_party/WebKit/Sou rce/modules/accessibility/AXObjectCacheImpl.h

	95 [AXTreeCombiner]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_tree_ combiner.h

	96 [AXTreeSerializer]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_tre e_serializer.h

	97 [BlinkAXTreeSource]: https://cs.chromium.org/chromium/src/content/renderer/acces sibility/blink_ax_tree_source.h

	98 [BrowserAccessibility]: https://cs.chromium.org/chromium/src/content/browser/acc essibility/browser_accessibility.h

	99 [BrowserAccessibilityDelegate]: https://cs.chromium.org/chromium/src/content/bro wser/accessibility/browser_accessibility_manager.h?sq=package:chromium&l=64

	100 [BrowserAccessibilityManager]: https://cs.chromium.org/chromium/src/content/brow ser/accessibility/browser_accessibility_manager.h

	101 [LayoutObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/c ore/layout/LayoutObject.h

	102 [NativeViewAccessibility]: https://cs.chromium.org/chromium/src/ui/views/accessi bility/native_view_accessibility.h

	103 [Node]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/core/dom/ Node.h

	104 [RenderAccessibilityImpl]: https://cs.chromium.org/chromium/src/content/renderer /accessibility/render_accessibility_impl.h

	105 [RenderFrameHostImpl]: https://cs.chromium.org/chromium/src/content/browser/fram e_host/render_frame_host_impl.h

	106 [ui::AXNodeData]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_node_ data.h

	107 [WebAXObject]: https://cs.chromium.org/chromium/src/third_party/WebKit/public/we b/WebAXObject.h

	108 [automation API]: https://cs.chromium.org/chromium/src/chrome/renderer/resources /extensions/automation

	109 [automation.idl]: https://cs.chromium.org/chromium/src/chrome/common/extensions/ api/automation.idl

	110 [ax_enums.idl]: https://cs.chromium.org/chromium/src/ui/accessibility/ax_enums.i dl

	111 [chrome.automation API]: https://developer.chrome.com/extensions/automation

	112 [webui-js]: https://cs.chromium.org/chromium/src/ui/webui/resources/js/cr/ui/

OLD	NEW

« no previous file with comments | « no previous file | no next file » | no next file with comments »