Use cases: Catherine Laws, IBM
ATK and AT-SPI recommendations: Bill Haneman
July 19, 2005: Initial draft - Cathy Laws.
July 26, August 3, 2005: Initial AT-SPI recommendations for AT developers
- Bill Haneman..
August 11, 2005: Moved rendering of element characteristics to new section,
integration of Bill's AT-SPI recommendations, addition of Table of Contents,
new section about roles- Cathy Laws.
Loretta Guarino Reid (Adobe) contributed to the list of desirable document
object and landmark roles.
August 18, 2005: CKL: Deleted ATK implementation sections and changed perspective
of document to be just for AT developers. ATK ADOC recommendations to be
moved to a new document for application developers. Removed the list of
scenarios column in the element characteristics table. Other minor related
updates.
Introduction
Terminology
Common Assumptions
Use case: Navigate or Collect All Accessible Content by Unit
Scenario 1: Navigate to the next, previous, current, first, or last item
in the document
Scenario 2: Navigate to the next, previous, current, first, or last interactive
and enabled element in the document
Scenario 3: Navigate to the next, previous, current, first, or last hyperlink
in the document
Scenario 4: Navigate to the next, previous, current, first, or last enabled
form control in the document
Scenario 5: Collect all elements with a shortcut key in the document
Scenario 6: Navigate to the next, previous, current, first, or last frame in the document
Scenario 7: Navigate to the next, previous, current, first, or last section
identified by a heading in the document
Scenario 8: Navigate to the next, previous, current, first, or last data table in the document
Scenario 9: Navigate to the next, previous, current, first, or last embedded object or graphic in the document
Scenario 10: Navigate table cells by moving across rows and up and down columns within a grid or table
Scenario 11: Navigate to next, previous, current, first, last, up or down in a tree-style set of items or controls
Use case: Where am I
Use case: Document Summary
AT-SPI Interfaces to Obtain Element Characteristics for AT Renderings
Desirable Roles for Document Objects and Navigation
Using AT-SPI 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, the application devloper
must use the accessibility API to expose to the AT 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 assistive technology developers provide better navigational user
interfaces and hierarchical relationships for complex documents, this paper
outlines document navigation use cases with descriptions of recommended
AT-SPI interface usage by assistive technology developers. The use cases
include navigation and collection of selected document containers and elements,
Where am I, and document summary. Additional use cases may be added at
a later time to address searching for accessible content, mutation events,
and new document events.
This section describes terminology used in this document. The terms described in this section are desirable from an accessible document navigation perspective, but there is not yet consensus that all the concepts and components described in the terms are necessary in the AT-SPI interfaces.
Accessible content: All of a document�s elements and their characteristics (descriptions, roles, states, shortcut keys, language, etc) that should be made available by the application through AT-SPI/ATK to the assistive technology. Then the AT can make any of these characteristics available to an end user based on user preferences.
Container: 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.
Direction: When navigating to an item, element, the top of a container, or within a section, the direction parameter for an accessible document navigation request includes first, last, previous, next, or current. When navigating cells within a grid or table container, the directions include first in table, last in table, right in row, left in row, up one in column, down one in column, rightmost in row, leftmost in row, top in column, bottom in column, span right, span left, span up, span down, header right, header left, header up, header down. When navigating tree elements, the directions include first, last, next, previous, up, or down. Next and previous directions allow navigate to the same level items (like headings), and up and down directions allow the user to change levels. Navigation to the first and last tree items causes the POR to move to the first and last items within the same level.
Document landmark: A position in a document identified by a specific element attribute. In XHTML 2.0, the role attribute will identify document landmarks, such as main content, secondary content like a portlet, navigation bars, content information like footnotes and copyright statements, advertisement and logo banners, and notes.
Document summary: The document title, language, and number of tables, links, headings, frames, forms, controls, items, pages, and images.
Element: An information unit in a document for which each character in the unit has the same set of characteristics.
Element characteristics: Text and semantic characteristics of an element in a document that are derived from attributes usually specified by the document author or inherent in the object selected by the author, such as an element�s alternative description, access or shortcut key, role, table summary value, a heading level, a link (URL) value, an image source filename, language, text styles, or an accessibility API defined state.
Element location: Type of parent container(s), location of element within a container(s), container title(s) and position(s) relative to the whole document, section heading, element position relative to the whole document, and document title.
Enabled elements: An enabled element is a piece of content, usually an interactive element, with associated behaviors that can be activated through the user interface or through a programming interface. Enabled elements may be temporarily disabled programmatically (i.e. no user input allowed).
Event handler: 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.
Frame: A container in a document which allow authors to present the document in multiple views, offering a way to keep certain information visible, while scrolling or replacing other information in the views.
Grid: A container that has rows and columns, such as a table, spreadsheet, or calendar.
Information unit: A navigation unit for the accessible document interface. It can be a container
type, an item, heading levels, an interactive element, or a block of interactive
or non-interactive elements. Container types for navigation and collection
include well defined sections (frames, divisions, spans, pages, slides,
tabbed page or sheet), sections identified by document landmarks (such
as headings, chapters, a role attribute in XHTML), and specialized sections
or containers (forms, embedded objects, lists, header, footer, footnotes,
table of contents, notes, annotations, index, bibliography). The subset
of interactive elements for navigation includes form controls, bookmarks,
elements with event handlers, and elements with access keys.
Interactive elements: Has associated behaviors to be executed or carried out as a result of user
or programmatic interaction. For example, the interactive elements of HTML 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).
Item: Content in a document between each hard line break. Each character in the
document is contained within one and only one item. For example, paragraphs,
list items, table cells, images, map areas, and headings are items. Links
and controls are usually not an item on their own but a part of an item
unless a line break is forced.
Line: A specified number of characters,
which may be the visual width of the application�s edit/container control, an
AT text view, the number of characters on a Braille display, or something else.
Listener interface: A programming interface, implemented by the assistive technology, to which
the application accessibility interface asynchronously passes sets of information
in response to accessible document events or requests from the assistive
technology. The assistive technology monitors the listener interface. When
the AT sees information waiting to be processed, it requests to receive that
information from the listener interface.
Order: The navigation sequence of information units. If the information unit type is an interactive element or has a taborder characteristic like a tabindex, the order could be tab order versus document order.
Point of regard (POR): Within a document, 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. The assistive technology should manage the POR through a POR controller and may provide the application accessibility interface access to the POR controller for updating the POR. However, the accessibility interface may choose to communicate with the AT about POR values using interface parameters and return values.
POR Controller: A programming interface, implemented by the assistive technology, in which the current point of regard is updated and maintained. The assistive technology should expose the POR controller interface to the application, which could update the POR in response to accessible document requests and events. The assistive technology should update the POR based on output progress.
Scope: A range of accessible content within a document which can limit accessible document navigation or searching. The scope is either the whole document or a specified container within the document.
Section: A container in a document that clearly separates its content from other content in the document. Examples 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.
Streaming: When a navigation or search request will result in the return of multiple sets of information (like element characteristics and location information for the whole document or a collection of one type of element in the document), the AT receives and processes one set of information at a time by formatting and sending text output to the output devices before receiving all the sets of information from the application accessibility API listener interface. This technique provides the perception of a faster response time for the end user.
Tree: Container or set of elements that consists of a more than one level of lists, such as folders plus files, menus, heading levels, and lists with embedded lists.
Some assumptions are common to all accessible document use cases. Unique assumptions are stated in the individual use case descriptions.
Description:
Navigate or collect all accessible content of the whole document or a container
in a document (scope) by a specified information unit type (container, item, interactive or non-interactive element, or block of
interactive or non-interactive elements), in a specified direction
and order, starting from the current point of regard (POR). If collecting all of an information type in the whole document or container,
the collection starts from the beginning of either the whole document or
the specified container (scope), with or without updating the current POR
to the beginning of the document or container. The AT should receive through a listener interface a specified subset of element characteristics for each element in the requested information units. A listener interface
and streaming techniques implemented in the application ATK interfaces
will help the AT address more easily performance issues when trying to
obtain collections from large documents instead of trying to make multiple
and different types of AT-SPI calls or limiting collections to the visible
area of the document to manage performance.
Pre-conditions:
If requested scope is not the whole document, the point of regard must
be within the type of container you want to navigate.
Failed end conditions:
Main scenario description:
An item is content in a document between each hard line break. Each character
in the document is contained within one and only one item. For example,
paragraphs, list items, table cells, images, map areas, and headings are
items. Links and controls are usually not an item on their own but a part
of an item unless a line break is forced.This scenario allows an end user
to navigate sequentially through all the different elements in a document
in document order and "see, hear, or feel" their content and
element characteristics, regardless of the element type. This navigation
includes form controls which are read-only or disabled.
Alternate scenarios:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each element in each item.
General use of AT-SPI interfaces by ATs:
Using AT-SPI version 1.6:
Using AT-SPI with the proposed Collection, Document, etc. enhancements:
Main scenario: Navigate by item
Using AT-SPI 1.6:
Using AT-SPI with Collection/Doc enhancements:
Alternate scenario 1: Collect all items
AT-SPI version 1.6:
Using AT-SPI with the Collection and Document enhancements:
Alternate scenario 2: Navigate to or collect all items within a limited scope
Using AT-SPI version 1.6:
The method is the same as for the entire document, except that a different
boundary condition is used for the traversal.
Using AT-SPI with the Collection and Document enhancements:
This can be trivially done if the relevant containers implement Collection.
If they do not, Collection::getNextChildren() may be called using the bounding
container as the POR, and a traversal of the returned list may be truncated
when the list items no longer fall within the bounding container. This
must be established via calls to Accessible::getParent at present.
Main scenario description:
Interactive elements include text and image links, image map areas, form
elements, elements with access or shortcut keys, DHTML widgets like menus
and calendars and spreadsheets, and elements with event handlers. This
scenario allows an end user to navigate sequentially through all the interactive
elements and their characteristics in a document in document order. This
navigation does not include form controls which are read-only or disabled.
Note: User agents (such as a browser) usually provide navigation (i.e. the Tab
key) in tab order to the combined collection of form controls and hyperlinks,
but not usually to just hyperlinks, just form controls, or just elements
with access keys. Also, the user agent may not provide keyboard navigation
to elements that are not normally interactive but are made interactive
programmatically, such as elements in a Web page with JavaScript event
handlers. An AT may want to provide navigation to or lists for the individual
types of interactive elements (text links, image links, form controls,
elements with access keys, elements with event handlers, etc) as well as
for the combined collection in both document order and tab order. See other
scenarios below for navigation to individual types of interactive elements.
Alternate scenarios:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each interactive element.
Use of AT-SPI interfaces by ATs:
Using AT-SPI 1.6:
Using AT-SPI with Collection and Document enhancements:
For additional navigation techniques and recommendations, see the section on Desirable Roles for Document Objects and Navigation.
Main and Alternate 1 scenario: Navigate to all interactive and enabled
elements (controls, links, elements with event handlers, etc) in document
order
Using AT-SPI 1.6:
The main scenario is achievable without AT intervention if the user agent
provides basic keyboard navigation of the interactive elements.
The AT can achieve brute-force 'navigation' of the controls as follows: iterate through the document, possibly pruning nodes that are invisible. Collect the list of objects implementing 'Action' (Accessible::isAction()), whose StateSet includes SENSITIVE, i.e Accessible::getStateSet()::compare(sensitive_state) doesn't return an empty StateSet.
Using AT-SPI with enhancements:
From POR, find Document via Accessible::getDocument. Call Collection::getChildren
(), requesting SENSITIVE implementors of "Accessibility/Action".
This list can be the basis of end-user-visible iteration. To navigate with
respect to some already-determined POR, the Collection::getNextChildren
api can be used instead. The length of the returned list of actionable
items may be controlled by the AT, i.e. it may be 1 or 1000. Making it
small on the initial call, when AT navigation begins, may reduce user-visible
latency.
Alternate scenario 2: Navigate to or collect all interactive and enabled
elements in tab order
Using AT-SPI 1.6:
Tab order is known only to the user agent.
Using AT-SPI with Collections enhancements:
Specify SORT_ORDER_TAB in place of SORT_ORDER_FLOW in the calls to Collection:: apis.
Main scenario description:
Hyperlink elements include text and image links and image map areas. This scenario allows an end user to navigate sequentially through all the hyperlink elements and their characteristics in a document in document order.
Alternate scenarios:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each hyperlink.
Use of AT-SPI interfaces by ATs:
Main scenario: Navigate to all hyperlinks in document order
Using AT-SPI 1.6:
From the current POR, or start of document, iterate through content until the first/next object implementing the Hypertext interface is found. It should then present the hyperlink object as above, or, in some situations, may present other information such as the URI of one or more of the link's "anchors".
Using AT-SPI enhancements:
As above, but Collection::getNextChildren (... "IDL:Accessibility/Hypertext:1.0",
..., SORT_ORDER_FLOW ) may be used to avoid iteration through the document.
When querying Image hyperlinks, the Image::getLocale api should be used
to determine the language to be used when presenting the image description.
Alternate scenario 1: Collect a list of all hyperlinks in document order
Trivially the same as the main scenario. If the AT-SPI Collection enhancements
are not present, streaming and preloading may be used to reduce end-user-visible
latency in compiling the list, i.e. the first element of the list should
be obtained and presented before traversing the entire document.
Alternate scenario 2: Navigate to or collect a list of all hyperlinks in tab order
Using AT-SPI 1.6
Tab order is unknown (However if the user agent implements keyboard navigation,
it is unnecessary to compile the list in order to traverse the links in
tab order).
Using AT-SPI Collection interface
SORT_ORDER_TAB may be substituted for SORT_ORDER_FLOW.
Main scenario description:
Form controls include radio buttons, check boxes, text fields and areas,
password fields, buttons, select menu and options, combo boxes, sliders,
and other custom controls, such as DHTML widgets (menus, calendars, spreadsheets,
etc).. This scenario allows an end user to navigate sequentially through
all the form control elements and their characteristics in a document in
document order. This navigation does not include form controls which are
read-only or disabled.
Alternate scenarios:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each form control.
Use of AT-SPI interfaces by ATs:
Main and Alternate 1 scenario: Navigate to or collect all enabled form
controls in document order
Using AT-SPI 1.6:
Iterate through the document, possibly pruning nodes that are invisible. Collect the list of objects implementing 'Action' (Accessible::isAction()), whose StateSet includes SENSITIVE, i.e Accessible::getStateSet()::compare(sensitive_state) doesn't return an empty StateSet.
Using AT-SPI with enhancements:
From POR, find Document via Accessible::getDocument. Call Collection::getChildren
(), requesting SENSITIVE implementors of "Accessibility/Action".
This list can be the basis of end-user-visible iteration. To navigate with
respect to some already-determined POR, the Collection::getNextChildren
api can be used instead. The length of the returned list of actionable
items may be controlled by the AT, i.e. it may be 1 or 1000. Making it
small on the initial call, when AT navigation begins, may reduce user-visible
latency.
For additional navigation techniques and recommendations, see the section
on Desirable Roles for Document Objects and Navigation.
Alternate scenario 2: Navigate to and collect a list of all enabled form
controls in tab order
Using AT-SPI 1.6:
Tab order is known only to the user agent.
Using AT-SPI with Collections enhancements:
Specify SORT_ORDER_TAB in place of SORT_ORDER_FLOW in the calls to Collection:: apis.
Main scenario description:
In HTML documents, elements with a shortcut key have an accesskey attribute.
For this scenario, the AT may create a list of all elements (usually interactive elements) in a document with a shortcut or access key and
display the list in alphanumeric order with the key listed as the first character in each list item.
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each element with a shortcut key.
Use of AT-SPI interfaces by ATs:
Elements with shortcut keys are by definition actionable (i.e. the Action
interface is implemented). Proceed as in Scenario #2, then prune objects
whose keyboard shortcuts are empty (Action::getKeybinding()).
Main scenario description:
This scenario allows an end user to navigate through all the frames in an HTML frameset.
Alternate scenarios:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each frame.
Use of AT-SPI interfaces by ATs:
Recommend interfaces for navigation and collection of frame elements in
a frameset, plus interfaces for getting the required element characteristics
for the current one or a collection of frame elements. Recommend how to handle point of regard (POR) and performance (by limiting scope to the visible area, streaming, etc).
Main scenario: Navigate by frame
Alternate scenario 1: Collect a list of frames in a frameset
Main scenario description:
A heading in an HTML document is identified by an h1, h2, ..., h6 element. In office documents,
different heading levels are identified by a certain
set of style attributes. For this scenario, the AT may provide sequential
navigation to all the sections in a document with a heading.
Alternate scenarios:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each heading.
Use of AT-SPI interfaces by ATs:
Main scenario: Navigate to all sections in a document identified by a heading
Using AT-SPI 1.6:
Traverse next/previous/first/last as in Scenario 1 (navigate by item),
but test for the presence of the Text interface and an appropriate text
attribute via Text::getAttributes at offset 0. Traversals should be careful
of FLOWS_FROM and FLOWS_TO relations.
Using AT-SPI Collection and Document enhancements:
From the POR, determine the containing Document via Accessible::getDocument. Retrieve a list of headings by constructing a match set of text attributes, and calling Collection::getNextChildren(...) with the specified attribute set and match rule MATCH_ANY. The specified length of the returned list may be '1'. The sort order should be SORT_ORDER_FLOW.
Alternate scenario 1: Collect a list of all headings in a document
As above, but if Collection is available, the returned list length may be as long as the AT wishes, subject to latency considerations.
Alternate scenario 2: Navigate heading levels a a tree structure
'Level' should be determined by either the use of multiple queries, or by querying the heading attributes of the elements in the returned list (which need to be presented to the end-user in any case). Depending on how the AT wishes to manage its IPC transport, it may wish to construct a local hierarchy, tag the list of document landmarks, or maintain multiple lists in order to efficiently present such structured navigation. At the ATs discretion, the application-side POR may be programmatically moved via Component::grabFocus and Text::setCaretPosition (bearing in mind that applications have the right to return FALSE to indicate that the request could not be honored).
Alternate scenario 3: Navigate to or collect other document landmarks with
a role attribute
See the section on Desirable Roles for Document Objects and Navigation.
Main scenario description:
For this scenario, the AT may provide navigation to the tops of all the data tables in the
document.
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each table top.
Use of AT-SPI interfaces by ATs:
Recommend interfaces for navigation and collection of table elements, plus
interfaces for getting the required element characteristics for the current
one or a collection of table elements. Recommend how to handle point of regard (POR) and performance (by limiting scope to the visible area, streaming, etc).
Also, see the section on Desirable Roles for Document Objects and Navigation.
Main scenario description:
This scenario allows an end user to navigate sequentially to all the different
embedded objects in a document, including images, pictures, diagrams, Flash
content, Java applets, graphs, spreadsheets, and other document content
imported from a different source file and/or document types. This navigation
does not include navigation within the embedded objects.
Alternate scenarios:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each embedded object or graphic (image).
Use of AT-SPI interfaces by ATs:
Recommend interfaces for navigation, collection, and moving focus in and
out of embedded objects or graphics, plus interfaces for getting the required
element characteristics for the current one or a collection of embedded
objects or graphics. Recommend how to handle point of regard (POR) and performance (by limiting scope to the visible area, streaming, etc).
Also, see the section on Desirable Roles for Document Objects and Navigation.
Main scenario: Navigate to all types of embedded objects (and images) in
the document
Alternate scenario 1: Collect a list of all types of embedded objects
Alternate scenario 2: Navigate to or collect a list of one type of embedded
object
Alternate scenario 3: Move keyboard focus in and out of an embedded object
Main scenario description:
If the POR is within a data table or a grid like a spreadsheet or a calendar, the AT may provide navigation of table cells by allowing the user to move up or down one table cell in a column, or left or right one table cell in a row.
Alternate scenarios:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each element in each table cell.
Use of AT-SPI interfaces by ATs:
Using AT-SPI 1.6:
The AT should bound document traversal using the accessible Table interface.
Recommend interfaces for navigation of table cells within a table or grid,
plus interfaces for getting the required element characteristics for a
table cell. Recommend how to handle point of regard (POR) and performance (by limiting scope to the visible area, streaming, etc).
Also, see the section on Desirable Roles for Document Objects and Navigation.
Main scenario: Navigate table cells, up and down columns and across rows
Alternate scenario 1: Move to first or last cell in a table
Using AT-SPI 1.6:
If an object which implements Table is encountered, additional heuristics may be needed in order to identify a suitable "first presentation item" (typically the table cell at row 0, column 0). The last item in a container may similarly be identified by traversing down the containers using Accessible::getChildAtIndex (Accessible::getChildCount() - 1).
Alternate scenario 2: Move to first or last cell in a row, top or bottom cell in a column
Alternate scenario 3: Navigate by spanned cell across a row, or up and down a column
Alternate scenario 4: Read header or footer cells without moving (without losing current reading position)
Main scenario description:
For this scenario, the AT may provide tree-style navigation for a list
with embedded lists of items, menu widgets, or folder-file type lists.
Next and previous directions allow navigation to the same level items,
and up and down directions allow the user to change levels. First and last
causes the POR to move to the first and last items within the same level.
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for each item in a tree-style set of items or controls.
Use of AT-SPI interfaces by ATs:
Using AT-SPI 1.6:
The AT should bound document traversal using the accessible Table interface.
Recommend interfaces for navigation of tree-style items or controls, plus
interfaces for getting the required element characteristics for that item
or control. Recommend how to handle point of regard (POR) and performance (by limiting scope to the visible area, streaming, etc).
Also, see the section on Desirable Roles for Document Objects and Navigation.
Main scenario description:
For this scenario, the user wants to receive information about the current
element characteristics plus type of parent container(s), location of element
within a container(s), container title(s) and position(s) relative to the
whole document, section heading, element position relative to the whole
document, and document title. Where am I output varies based on the current POR, the type of element
at the current POR, and the parent container type. Example of possible output by AT:
Select menu 1 of
3.
Labeled Search
type.
Select menu item
2 of 5.
Form 1 of 5.
Heading level 3:
BluePages.
At 59% of page.
Alternate scenarios:
Failed end conditions:
Successful end conditions:
For each potential point of regard, the AT may require the following element
characteristics, if they exist, depending on the type of elements in the
item at the current POR:
Table information if in a table:
Section information if in a section:
Form control information if on a form control:
Map information if in a map:
List or menu information if within a menu or list:
Link information if on a link:
For all locations:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for how to obtain each type of information that should be rendered for Where am I.
Main scenario description:
For this scenario, the users wants to know the document title and language
as well as the number of tables, links, headings, frames, forms, controls,
items, images, and pages.
Alternate scenarios:
Failed end conditions:
Successful end conditions:
Refer to the section AT-SPI interfaces to obtain element characteristics for AT renderings for the desired statistics for the document summary.
The AT may require the following element characteristics, if they exist, depending on the type of elements required for the requested rendering:
Element characteristic | Recommended AT-SPI interface to obtain it |
Main text content for an element |
|
Alternative or descriptive text for an image or an image link or button (title, alt, name) | Accessible:getName to get alt or Accessible:getDescription to get title? |
Long description link for an image or image link (URL) | Image::getImageDescription |
Alternative content or descriptive text (title) for an embedded object | |
Label or alternative text (title) for a control | |
Group label for a control (such as LEGEND or OPTGROUP in HTML) | |
Alternative text (title attribute) for any element (such as an abbreviation or text link) or beginning of any container (such as a map, select menu, or frame) | |
Caption and table summary for the beginning of a table | |
Content for row and column headers if in a table cell | |
Relative number (n of total number) for the beginning of a form and for a table | |
Number of rows and columns for the beginning of a table | |
Number of controls within a form, areas within a map, or items in a list of links | |
Row and column number if in a table cell | |
Level number if item is a heading or in a section with a heading | |
Index or start + index for a list item which is a link | |
Shortcut key for an interactive element | |
Value for an interactive element | |
Role for any element | |
State for any interactive element | |
Actions for any interactive elements, including event handlers | |
Locale (language) for element | Image::getLocale Text object - result of cascade: Accessible::getApplication, then Application::getLocale, Document::getLocale, and text attributes named "lang" or "locale". |
URL if a link | |
Source filename if an image | |
Text attributes | |
Title for target (current) frame or document | |
Long description link for a frame (URL) | |
Number of frames in a frameset | |
Relative number of the current frame | |
Section type (page, frame, heading) | |
Relative number (n of total number) for a section with a heading | |
Relative page number in a document (n of total number) | |
Relative item number (n of total number) within a document | |
Relative link number (n of total) within the document | |
Document language | Accessible::getApplication, then Application::getLocale, Document::getLocale, |
Number of form controls in a document | |
Number of images and embedded objects in a document |
To identify, interact with, and navigate to custom widgets in documents,
such as DHTML widgets on Web pages, the assistive technology needs to be
able to locate and obtain element characteristics for extensible roles,
values, and states for any element. Extensible roles should also be used
to identify and navigate to new types of document landmarks and text objects.
In XHTML 2.0, Web authors will be able to identify new document landmarks
using the role attribute. However, even in today's Web, word processing,
PDF, spreadsheet, and presentation documents, there are custom widgets,
document landmarks, and text objects th AT cannot identify using an extensible
role value.
Below is an initial list of document object and landmark roles that ATs
should be able to identify, navigate to, and obtain element characteristics.
Some are already standard roles, others would be new roles.
Document
Preface
Appendix
Epilogue
Part
Article
Section
Division
BlockQuote
Caption
Table of contents
Table of figures
Table of tables
Index
Footnote
Endnote
Sidebar
Paragraph
Table, Table cell
List
Figure
Formula
Equation
Heading
Reference
Bibliography
Credits
Link
Example
Quotation
Instructions
Contact Information
Return Address
Salutation
Signature
Date
Form
Form Section or Subsection
Interactive field types
Form controls (radio button, check box, text field, text area, password
field, combo box, select list, multi-select)
Advertisement
Comments
Multi-media content (sound clips, movies, etc).
Abbreviation
Image, Graph, Chart, Diagram
Spreadsheet
Calendar
Menu
Tabbed section
Map, Map areas
Bookmark
XHTML 2.0 sections identified through role attribute