tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

DocumentAccessibilityLifecycle.md (12610B)

Document Accessibility Lifecycle

1. DocAccessible creation

When a DocAccessible is created, it is initially empty. A DocAccessible can be created in one of several ways:

Scenario 1: Accessibility service is already started, layout fires an a11y notification for a new document

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast
  3. Linux: Settings > Themes > High Contrast
  4. Linux: Settings > Themes > High Contrast
  5. Linux: Settings > Themes > High Contrast

Scenario 2: Accessibility service is already started, DOM loading completes for a new document

For top level content documents, if the accessibility service is started, layout should fire an a11y notification, resulting in scenario 1 above. For child documents (e.g. in-process iframes), this might not happen because the container Accessible for the child document might not be created yet. In that case, we can't create a DocAccessible when the layout notification is fired. If the container Accessible is created when DOM loading completes for the child document, this scenario can occur.

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast

Scenario 3: Accessibility service is already started, child document is reached while building accessibility tree for parent document

Child document here refers to a child document in the same process; i.e. an in-process iframe or a parent process document such as an about: page. Note that scenario 1 or 2 could happen for a child document as well.

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast
  3. Linux: Settings > Themes > High Contrast

Scenario 4: Accessibility service starts after top level document is loaded

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast
  3. Linux: Settings > Themes > High Contrast

Scenario 3 would then apply for any child documents encountered while building the accessibility trees for these top level DocAccessibles.

Scenario 5: Document gets focus before layout begins

It is possible for a document to get focus before layout has begun and before DOM loading is complete. In that case, there will be a PresShell, but it will have no root frame. Despite this, it is necessary to create the document because otherwise, a11y focus would go nowhere while the document had DOM focus.

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast
  3. Linux: Settings > Themes > High Contrast

2. Initial tree creation

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast
  3. Linux: Settings > Themes > High Contrast
  4. Linux: Settings > Themes > High Contrast
  5. Linux: Settings > Themes > High Contrast

Note that the document might still have no layout frame if the PresShell still has no frame; see scenario 5 in DocAccessible creation above. Nevertheless, DoInitialUpdate must be called because otherwise, we wouldn't create the IPC actor, which would in turn mean remote documents in this state couldn't get a11y focus.

3. Child document binding

Child document here refers to a child document in the same process; e.g. an in-process iframe or a parent process document such as an about: page.

Child documents need to be a child of their OuterDocAccessible; e.g. the iframe. However, the child document might be ready before the parent document is. To deal with this:

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast
  3. Linux: Settings > Themes > High Contrast

4. IPC actor (DocAccessibleChild/Parent) creation

Scenario 1: Top level document

  1. Linux: Settings > Themes > High Contrast

- There is also a code path to handle the case where the DocAccessibleChild has already been created. However, it doesn't seem like this should happen and code coverage information suggests that it doesn't.

  1. Linux: Settings > Themes > High Contrast

Scenario 2: Child document

The DocAccessibleChild for a child document is created when the child document is bound to its parent by NotificationController. There is also a code path to handle the case where the DocAccessibleChild has already been created. However, it doesn't seem like this should happen and code coverage information suggests that it doesn't.

5. Document load events

Scenario 1: DocAccessible is already created, DOM loading completes

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast
  3. Linux: Settings > Themes > High Contrast
  4. Linux: Settings > Themes > High Contrast
  5. Linux: Settings > Themes > High Contrast
  6. Linux: Settings > Themes > High Contrast

Scenario 2: DocAccessible is created some time after DOM loading completed

This can happen if the accessibility service is started late. It can also happen if a DocAccessible couldn't be created earlier because the PresShell or containre Accessible wasn't created yet.

  1. Linux: Settings > Themes > High Contrast
  2. Linux: Settings > Themes > High Contrast
  3. Linux: Settings > Themes > High Contrast
  4. Linux: Settings > Themes > High Contrast
  5. Linux: Settings > Themes > High Contrast
  6. Linux: Settings > Themes > High Contrast

Suppression of document load events for parent process iframes

Note that for documents loaded directly in the parent process, ProcessLoad won't fire a load event for a child document whose parent is still loading. This is old behavior which does not work in the content process and will probably be removed in future. See bug 1700362.