Open Accessibility (A11y) Working Group     The Linux Foundation

Implementing Accessible Document Interfaces using ATK
Recommendations for Application Developers

Authors and Contributors

Outline and recommendation requests: Catherine Laws, IBM
ATK recommendations: Bill Haneman

Change History

Table of Contents


Using AT-SPI/ATK interfaces, developers of assistive technologies may face difficulties trying to implement logical navigation of the accessible content and structures of complex documents for users with vision, learning, physical, and cognitive impairments. Some of the challenges include:

To show the hierarchy and structure of documents, application developers need to expose through ATK the document elements and their characteristics as they appear in the document hierarchy, not just as a stream of text and associated properties. Without this, contextual information is lost.

To help application developers provide better navigational user interfaces and hierarchical relationships for complex documents, this paper outlines recommendations for implementing ATK interfaces which expose accessible document content, structure, navigation, and element characteristics. Additional recommendations may be added at a later time to address searching for accessible content, mutation events, and new document events.

Implementing ATK Interface Classes

Recommendations for exposing document objects and containers using the ATK interface classes for the following document types:

  1. Web (containing HTML, XHTML and XForms, DHTML, JavaScript).
  2. PDF (Portable Document Format)
  3. Word processing
  4. Spreadsheet
  5. Slide presentations

Consult Desirable Roles for Document Objects and Navigation for a list of document objects and containter types.


Recommendations for exposing actions for any interactive element, including elements with event handlers. Interactive elements include text and image links, image map areas, form elements, elements with access keys, DHTML widgets, and elements with event handlers. Interactive elements may be temporarily disabled programmatically (i.e. no user input allowed).
An event handler is a script which is executed when an event (such as a mouse over, key press, mouse click, etc.) of a given type occurs. An event handler is associated with a document element through document markup.

Discuss how to expose access keys for interactive elements in a document.

Also, discuss how to expose both default actions (click) as well as additional actions (such as a mouseOver).
See also: AtkImage, AtkRelation, AtkHyperlink, AtkObject.
Also, how to expose how many controls are within a form and how many areas within a map.




Recommend how to bound document and children containers (scope), including forms, tables, and sections within a document. A document consists of one or more containers, which include grids, sections, trees, blocks (list of contiguous interactive or non-interactive elements), embedded objects or documents, and others. The document itself is a container. Examples of sections include page, frame, form, map, navigation bar, block (list of interactive or non-interactive elements), object, content between headings, group boxes, tabbed pages, division, span, document landmarks identified by a role attribute or namespace, slide, sheet, note section, header, footer, table of contents, index, and others.
See also: Desirable Roles for Document Objects and Navigation for the type of containers (and sections) you should bound.
Also, recommend how to expose document container characteristics, such as language, title, and long descriptions if they exist (such as for frames in Web documents).
Would discussions of how to expose sets of documents go here, such as frames in Web documents, slides in presentations, and sheets in spreadsheets? Also, would recommendations related to exposing embedded objects go here?


Some document types are read-only (PDF in Adobe Reader, Web) except for form controls and dynamic content controlled by scripting, while other documents have all content as read/write (word processing). Add recommendations for exposing edit controls and dynamic content which is editable.



AtkHyperlink and AtkHyperText

Recommend how to expose text and image links and image map areas and their characteristics, such as the text for a hypertext link, its URL, and any associated shortcut keys.

Client-side image maps are examples of Hyperlinks that have multiple "anchors"; each anchor has a URI and backing object, and in the case of client-side image maps, the backing objects should implement Image and Action.

Within an object implementing Hypertext there may be multiple links. These are addressable in index order, with 0 being the first hyperlink in a text block, etc.


Recommend how to expose images and their alternative or descriptive text and their source filename. For example, how to expose the alt and title attributes for HTML images, image links, maps and map areas, and image buttons, and the long description link (longdesc for an image or image link (URL).

Also, how to expose the number of areas in a map.

And how to expose the caption for a figure.

If possible, discuss how to implement empty descriptive (alt) text from no description available (no alt attribute) from a document author.

Discuss how to expose the language of the descriptive image text.

AtkNoOpObject and AtkNoOpObjectFactory



Recommendations on how to implement the name, role, description, relationships, states, locale, etc. for each object in a document. Consult Desirable Roles for Document Objects and Navigation for a list of document objects and containter types.

Discuss focus and change signals as they relate to document navigation.





AtkRelation and AtkRelationSet

Recommendations for exposing labels (label elements, title attributes, etc.) for single controls as well as compound controls (like combo boxes, select menus, etc.).

Recommendations for exposing groups of objects and controls (like group boxes, groupings of objects, FIELDSET and LEGEND in HTML, OPTGROUP in HTML select menus).

Recommendations using ATK_RELATION_CONTROLLER_FOR, such as describing the result of an event handler in addition to its action.

Discuss how to expose embedded objects in a document, such as images, pictures, diagrams, Flash content, Java applets, graphs, spreadsheets, and other document content imported from a different source file and/or document types.

Discuss how to indicate that interaction with a document object can result in a pop-up window.


Recommendations related to implementing single and multiple selection within a document using the keyboard and providing the selected content to the AT. Also, address selection across text, form controls, and embedded objects including images.

AtkState and AtkStateSet

Recommendations for how to expose states for all interactive elements, whether controls are enabled or not, whether elements are visible or hidden, whether elements are in the visual area or not, and whether the state of a control is affected by other controls in a group or container.




Discuss how to expose row and column headers, table summary, table caption, number of rows and columns, current row and column number, type of table (data or layout). Data tables in HTML documents should be distinguished from layout tables by the presence of a CAPTION, TH cells, header attributes, a role=”presentation”, and/or a summary attribute.


Recommendations related to how to expose a description for a text object, such as a title attribute for an abbreviation or any other text element.

Discuss how to expose style and font attributes.

Discuss implementing text attributes using name-value pairs to expose structure element types such as headings and their level, and lists and their indexes and nesting, versus the use of role attributes. Consult also Desirable Roles for Document Objects and Navigation for a list of document objects and container types.

Also, how to expose the number of list items within a list, the start index for an ordered list, and the type of list (ordered, unordered, simple, definition).

Discuss how to expose the locale for any element in a document.

Discuss how to define characters, words, lines, and sentences in a document, including internationalization considerations and how document structure can impact line definitions. A line definition may be based on a specified number of characters, which may be the visual width of the application’s edit/container control or the visual width of a column within a single element.




Recommend how to expose values for controls in documents and whether the values are read-only or not.

Collections of Containers and Objects

Recommendations on how to implement the Document and Collection interfaces to allow the AT to navigate objects and containers, including all items, interactive elements, hyperlinks, forms and form controls, headings, table tops and within tables, images and embedded objects, elements with access keys, frames, sections identified by a document landmark, within tree-style widgets. Consult Desirable Roles for Document Objects and Navigation for a more extensive list of document objects and containter types.

Discuss how to expose document versus tab order for interactive elements within a document using the sort parameter of the Collection interface.

Performance Considerations

Discuss ATK implementations in the application which can help to improve AT performance in response to user requests, such as how to implement the bounds for documents and containers so that the AT can limit the scope of its requests. To improve AT performance during navigation and collection of objects and their attributes, discuss any kind of streaming techniques or ways to reduce the number of API calls that the application can implement.

Notification of Document Events

Mutation events

Recommendations on how to notify an AT when part of a document changes and where it changed.

New document events

Recommendations on notification of new documents opening, including how to handle when multiple documents like frame documents are opened almost simultaneously.

Recommendations on how to send event notifications for alerts that are not top level windows and not focusable (from Aaron Leventhal regarding FireFox).

Keyboard Navigation Considerations

In the absence of the following keyboard navigation, an assistive technology may provide this navigation.

  1. The application should implement keyboard access to non-default and mouse-only actions from a context menu or through some other UI.
  2. The application should provide support for access keys assigned to elements in a document.
  3. The application should provide keyboard navigation and selection of text by word, character, and line.
  4. The application should provide keyboard navigation to all interactive elements in a document. Optionally, the application could provide keyboard navigation to just hyperlinks or just form controls in addition to the set of all interactive elements.

User Preferences Related to Accessibility

The application should maintain end user preferences and features related to visual presentation and events that can benefit everyone, such as a zoom feature, meta refresh rates, style sheets and fonts, the display of images, etc.

Point of Regard Considerations

Within a document, the point of regard (POR) is a position that references an object or element, plus a character offset to reference a more specific character or word within the object. The current POR refers to the position in a document where an AT is currently retrieving element characteristics or location information which it intends to use to create an output rendering for the end user. The input focus position in a document does not necessarily match the current POR. An application's accessibility interface and the assistive technology must share a common definition for the POR.

Recommendations on how the application should implement and maintain its point of regard, and how it communicates with the AT about the current POR.


Desirable Roles for Document Objects and Navigation

To support the identification, interaction, and navigation of custom widgets and objects in documents, such as DHTML widgets and document landmarks on Web pages, the application needs to expose meaningful roles, values, and states for every object in a document through the accessibility API (ATK). In XHTML 2.0, Web authors will be able to identify new widgets and document landmarks using the role attribute. Document landmarks include main content, secondary content like a portlet, navigation bars, content information like footnotes and copyright statements, advertisement and logo banners, and notes. However, even in today's Web, word processing, PDF, spreadsheet, and presentation documents, there are custom widgets, document landmarks, and text objects which the application developers need to identify for an AT using an extensible role value.

Below is an initial list of document object and landmark roles that application developers should be able to implement for AT identification and navigation. In addition to implementing these objects and landmarks as roles, application developers need to implement characteristics for each, such as a name, description, state, URL, index or level, number of contained elements, relationships, etc. Some are already standard roles, others would be new extensible roles.

Please address any technical difficulties experienced with this page to Please send any comments upon this document to

Valid XHTML 1.0! (check for yourself) Web-Content Accessibility Guidelines, Level Triple-A Compliant W3C Validated Cascading Style Sheets!