• UseApis

Guideline 6. Implement interoperable application programming interfaces

6.1 Programmatic access to HTML/XML infoset (P1)

1. Provide programmatic read access to XML content by making available all of the information items defined by the W3C XML Infoset [INFOSET].
2. Provide programmatic read access to HTML content by making available all of the following information items defined by the W3C XML Infoset [INFOSET]:
   • Document Information item: children, document element, base URI, charset
   • Element Information items: element-type name, children, attributes, parent
   • Attribute Information items: attribute-type name, normalized value, specified, attribute type, references, owner element
   • Character Information items: character code, parent element
   • Comment Information items: content, parent
3. If the user can modify the state or value of a piece of HTML or XML content through the user interface (e.g., by checking a box or editing a text area), allow programmatic read access to the current state or value, and allow the same degree of write access programmatically as is available through the user interface.

Normative inclusions and exclusions

UAAG2 ISSUES

• A major concern with these 2 guidelines (6.1 & 6.2) is that out-of-process DOM APIs (such as accessibility APIs and ISimpleDOMNode) are often readonly and not read/write, which can be a problem for users of these APIs, such as ATs.

• But in-process APIs, such as JavaScript and XUL, which are used by plugins, extensions, and DHTML/AJAX Web applications, are read-write so there isn't a problem for them.

*CL: The requirement to provide read/write access should exist at least in-process - unless we want to ensure read/write access by both in-process and out-of-process APIs, especially since a screen reader is usually out-of-process. But then there are security issues to address for out-of-process.

*CL: Add a definition of "programmatic access" and "programmatic read access" based on the WCAG definition of "programmatically determined", such as "exposed to an assistive technology through an accessibility API that is supported by commonly available assistive technology."

*CL: The ARIA specs state a requirement about mapping roles, states, and properties to an adaptive interface or accessibility API for an operating system. This requirement could be more explicit in these guidelines for both ARIA markup as well as HTML 4.01 elements and attributes. Ask PF to define "adaptive interface." Define "accessibility API" as a programming interface for an application to provide, and an assistive technology to obtain, information about documents, applications, objects (aka elements) and attributes, characters, and events.

6.2 DOM access to HTML/XML content (P1)

1. Provide access to the content required in checkpoint 6.1 by conforming to the following modules of the W3C Document Object Model (DOM) Level 2 Core Specification [DOM2CORE] and exporting bindings for the interfaces they define:
   • for HTML: the Core module
   • for XML: the Core and XML modules
2. As part of satisfying provision one of this checkpoint:
   • In the Java and ECMAScript operating environments, export the normative bindings specified in the DOM Level 2 Core Specification [DOM2CORE], or
   • In other operating environments, the exported bindings (e.g., C++) must be publicly documented.

Normative inclusions and exclusions

1. Refer to the "Document Object Model (DOM) Level 2 Core Specification" [DOM2CORE] for information about which versions of HTML, XML, Java, and ECMAScript are covered. Appendix D contains the Java bindings and Appendix E contains the ECMAScript bindings.
2. The user agent is not required to export the bindings outside of the user agent process (though doing so may be useful to assistive technology developers).

Notes

• This checkpoint stands apart from checkpoint 6.1 to emphasize the distinction between what information is required and how to provide access to that information. Furthermore, the DOM Level 2 Core Specification does not provide access to current states and values referred to in provision three of checkpoint 6.1. For HTML content, the interfaces defined in [DOM2HTML] do provide access to current states and values.

UAAG2 ISSUES

• A major concern with these 2 guidelines (6.1 & 6.2) is that out-of-process DOM APIs (such as accessibility APIs and ISimpleDOMNode) are often readonly and not read/write, which can be a problem for users of these APIs, such as ATs.

But in-process APIs, such as JavaScript and XUL, which are used by plugins, extensions, and DHTML/AJAX Web applications, are read-write so there isn't a problem for them.

6.3 Programmatic access to non-HTML/XML content (P1)

1. For content other than HTML and XML, provide structured programmatic read access to content.
2. If the user can modify the state or value of a piece of non-HTML/XML content through the user interface (e.g., by checking a box or editing a text area), allow programmatic read access to the current state or value, and allow the same degree of write access programmatically as is available through the user interface.
3. As part of satisfying provision one of this checkpoint, implement at least one API according to this API cascade:
   • The API is defined by a W3C Recommendation, or the API is publicly documented and designed to enable interoperability with assistive technologies.
   • If no such API is available, or if available APIs do not enable the user agent to satisfy the requirements,
     • implement at least one publicly documented API to satisfy the requirements, and
     • follow operating environment conventions for the use of input and output APIs.

Normative inclusions and exclusions

1. "Structured programmatic access" means access through an API to recognized information items of the content (such as the information items of the XML Infoset [INFOSET]). Plain text has little structure, so an API that provides access to it will be correspondingly less complex than an API for XML content. For content more structured than plain text, an API that only provides access to a stream of characters does not satisfy the requirement of providing structured programmatic access. This document does not otherwise define what is sufficiently structured access.
2. An API is considered "available" if the specification of the API is published (e.g., as a W3C Recommendation) in time for integration into a user agent's development cycle.

Notes

• This checkpoint addresses content not covered by checkpoints 6.1 and 6.2.

UAAG2 ISSUES

6.4 Programmatic access to information about rendered content (P1)

1. For graphical user agents, make available bounding dimensions and coordinates of rendered graphical objects. Coordinates must be relative to the point of origin in the graphical environment (e.g., with respect to the desktop), not the viewport.
2. For graphical user agents, provide access to the following information about each piece of rendered text: font family, font size, and foreground and background colors.
3. As part of satisfying provisions one and two of this checkpoint, implement at least one API according to the API cascade described in provision two of checkpoint 6.3.

*CL: Should be provision three of checkpoint 6.3.

*CL: We should consider combining 6.1 - 6.4. The techniques sections describe why there are separate guidelines - separating what info from how to provide, and HTML vs DOM vs non-HTML vs graphical content. But there is a lot of duplication. Need to decide if UAAG should require both DOM and accessibility APIs, especially in light of the fact that ATs don't want to get ARIA info out of the DOM.

Normative inclusions and exclusions

Notes

• User agents should provide programmatic access to additional useful information about rendered content that is not available through the APIs required by checkpoints 6.2 and 6.3, including the correspondence (in both directions) between graphical objects and their source in the document object, and information about the role of each graphical object.

UAAG2 ISSUES

6.5 Programmatic operation of user agent user interface (P1)

1. Provide programmatic read access to user agent user interface controls, selection, content focus, and user interface focus.
2. If the user can modify the state or value of a user agent user interface control (e.g., by checking a box or editing a text area), allow programmatic read access to the current state or value, and allow the same degree of write access programmatically as is available through the user interface.
3. As part of satisfying provisions one and two of this checkpoint, implement at least one API according to the API cascade described in provision two of checkpoint 6.3.

*CL: Should be provision three of checkpoint 6.3.

Normative inclusions and exclusions

1. For security reasons, user agents are not required to allow instructions in content to modify user agent user interface controls. See more information on security considerations.
2. Conformance detail: For user agent features

Notes

• APIs used to satisfy the requirements of this checkpoint may vary. For instance, they may be independent of a particular operating environment (e.g., the W3C DOM), or the conventional APIs for a particular operating environment, or the conventional APIs for programming languages, plug-ins, or virtual machine environments. User agent developers are encouraged to implement APIs that allow assistive technologies to interoperate with multiple types of software in a given operating environment (e.g., user agents, word processors, and spreadsheet programs), as this reuse will benefit users and assistive technology developers. User agents should always follow operating environment conventions for the use of input and output APIs.

UAAG2 ISSUES

6.6 Programmatic notification of changes (P1)

1. Provide programmatic notification of changes to content, states and values of content, user agent user interface controls, selection, content focus, and user interface focus.
2. As part of satisfying provision one of this checkpoint, implement at least one API according to the API cascade of provision two of checkpoint 6.3.

*CL: Should be provision three of checkpoint 6.3.

Normative inclusions and exclusions

1. The user agent is not required to provide notification of changes in the rendering of content (e.g., due to an animation effect or an effect caused by a style sheet) unless the document object is modified as part of those changes.
2. Conformance profile labels: Selection
3. Conformance detail: For both content and user agent

Notes

• For instance, provide programmatic notification when user interaction in one frame causes automatic changes to content in another.

UAAG2 ISSUES

• not all events are referenced in the DOM

not just limit notifications to AT through the DOM should include notification through the accessibility API

• no caret indicator in the DOM, AT must rely on accessibility api for caret informaton/location
• AJAX = html + css+ javascript, accessibility tools can access dom for js events and html, but css changes are difficult
• issue: this may be out of date. in past calls we have talked about UAs increasingly relying on API rather than the DOM. How do we update this exclusion?

6.7 Conventional keyboard APIs (P1)

1. Implement APIs for the keyboard as follows:
   • Follow operating environment conventions.
   • If no conventions exist, implement publicly documented APIs.

*ckl: 2. Establish and document how the user agent resolves key binding conflicts between the user agent user interface, user agent extensions (e.g plug-ins), HTML elements (i.e. accesskeys), and JavaScript functions (i.e. keypress events). If a keystroke is not defined by the user agent user interface,the user agent should pass it on to the user agent extensions, HTML elements, then JavaScript functions, in that order. Not sure we should be this prescriptive - just throwing it out there for discussion.

Normative inclusions and exclusions

Notes

• An operating environment may define more than one conventional API for the keyboard. For instance, for Japanese and Chinese, input may be processed in two stages, with an API for each stage.

UAAG2 ISSUES

• plug-in keybindings, more conflicts with UA, AT
• if plug-in does not need a key, it should pass it on to the UA, not swallow it.
• Plug-ins should have some pass through to the UA function
• chaining, if something higher up the api chain gets a key lower level api may not see the event

6.8 API character encodings (P1)

1. For an API implemented to satisfy requirements of this document, support the character encodings required for that API.

Normative inclusions and exclusions

1. Conformance detail: For both content and user agent

Notes

• Support for character encodings is an important part of ensuring that text is correctly communicated to assistive technologies. For example, the DOM Level 2 Core Specification [DOM2CORE], section 1.1.5 requires that the DOMString type be encoded using UTF-16.

UAAG2 ISSUES

6.9 DOM access to CSS style sheets (P2)

1. For user agents that implement Cascading Style Sheets (CSS), provide programmatic access to style sheets by conforming to the CSS module of the W3C Document Object Model (DOM) Level 2 Style Specification [DOM2STYLE] and exporting bindings for the interfaces it defines.
2. As part of satisfying provision one of this checkpoint:
3. In the Java and ECMAScript operating environments, export the normative bindings specified in the CSS module of the DOM Level 2 Style Specification [DOM2STYLE], or
4. In other operating environments, the exported bindings (e.g., C++) must be publicly documented.

Normative inclusions and exclusions

1. For the purposes of satisfying this checkpoint, Cascading Style Sheets (CSS) are defined by either CSS Level 1 [CSS1] or CSS Level 2 [CSS2].
2. Refer to the "Document Object Model (DOM) Level 2 Style Specification" [DOM2STYLE] for information about which versions of Java and ECMAScript are covered. Appendix B contains the Java bindings and Appendix C contains the ECMAScript bindings.
3. The user agent is not required to export the bindings outside of the user agent process.

UAAG2 ISSUES

6.10 Timely exchanges through APIs (P2)

1. For APIs implemented to satisfy the requirements of this document, ensure that programmatic exchanges proceed in a timely manner.

Normative inclusions and exclusions

1. Conformance detail: For both content and user agent

Notes

• For example, the programmatic exchange of information required by other checkpoints in this document should be efficient enough to prevent information loss, a risk when changes to content or user interface occur more quickly than the communication of those changes. Timely exchange is also important for the proper synchronization of alternative renderings. The techniques for this checkpoint explain how developers can reduce communication delays. This will help ensure that assistive technologies have timely access to the document object model and other information that is important for providing access.

UAAG2 ISSUES

• define 'timely'
• chaining, if something higher up the api chain gets a key lower level api may not see the event
• UA extensions keybinding conflicts, big conflicts. keybinding negotiation (extension, content access key, plugins)

perhaps assign keys to roles, or similar to fonts have a list of proposed keys with fallback options

• Situations in which an API exchange is too slow include, but are not limited to, the following:
  • The user agent updates the content in the active view but does not indicate the change through the API in a timely manner such that an AT can update its cached content before the next user query or command. As a result, the user ends up working with stale content.
  • The user agent processes user input but does not indicate confirmation through the API in a timely manner such that the user knows the input was received. As a result, the user is apt to think the input was lost and repeat the action.