Please note, this is a STATIC archive of website from 03 Nov 2016, does not collect or store any user information, there is no "phishing" involved.

Mozilla AT-SPI Support for Linux/UNIX Assistive Technology Developers

Note: The documentation is out of date. You may want use instead new all-in-one documentation.

This FAQ explains how makers of Linux- or UNIX- based screen readers, voice dictation packages, onscreen keyboards, magnification software and other assitive technologies can support Gecko-based software. The base of our support for these products is AT-SPI (Assistive Technology Service Provider Interface) and the keyboard API/user interface.

For Firefox and all other Gecko-based products: this documentation only applies to up-to-date builds of Firefox -- currently not available on official releases. Grab the current build of Firefox which supports these features.

To Do

  • Document dynamic content, such as how to track mutations
  • Document text selection
  • Update list of supported features for each role
  • Go through XXX notes and file bugs or deal with questions
  • Add DHTML examples
  • Go through Bill's notes in HTML examples and remove or integrate
  • Explain embedded object characters and other new things in
  • Describe how to know where forced and soft line breaks are
  • Fix HTML Examples table, the wiki format is messed up


Here are some basic definitions that you'll need for this document to make sense:

The rendering engine for Firefox, Thunderbird, Nvu, Mozilla Seamonkey and other applications. Gecko is the internal engine that Mozilla uses to render any kind of web content. It supports HTML, XHTML, Cascading Style Sheets (CSS) and the Document Object Model (DOM).
Assistive Technology Service Provider Interface (AT-SPI)
an API devised by Sun Microsystems so that accessibility aids can track what's going on inside the user interface of any software package that supports it. If you seriously need to understand AT-SPI, you'll need to read the docs on and play with the available sample apps and code, such as at-poke. Please note that the web docs are sometimes out of date, and the latest AT-SPI is available on CVS.
DOM: Document Object Model
This is the W3C's specification for how web content is exposed to Javascript and other languages. It covers content, style and events. Inside the Gecko process, code has full access to DOM APIs. However, exposing the entire DOM to external software packages is quite involved, partially because changes to the DOM in Firefox must occur on the main thread. We have chosen a subset of readonly methods in the DOM needed for assistive technology vendors. Events such as focus changes must be tracked through AT-SPI events, rather than DOM events.
XUL: eXtensible User-interface Language
The XML-based language used by Firefox and Mozilla to develop the UI. Similar to HTML in that it can be combined with CSS and Javascript to make powerful applications. Contains more desktop-style widgets than HTML and follows a box layout model, rather than being text-flow based.
AJAX: Asynchronous JavaScript And XML
AJAX is a method of building interactive web applications that process user requests, user actions immediately in real time, unlike an HTTP request, during which users must wait for a whole page to reload or for a new page to load. Data is therefore stored and retrieved dynamically much faster.
Roles, states and events
please read the AT-SPI documentation if you are unfamiliar with these.


AT-SPI tree vs. DOM tree - what's the relation?

The AT-SPI tree and the DOM tree are parallel structures, although the AT-SPI tree is a subset of the DOM tree. QueryInterface() can be used to switch between the interfaces (Accessible, AccessibleText, AccessibleValue, etc.).

What is exposed? Any DOM node that ...

  • Is focusable
  • Is formatted with a blank line before and after (display:block in web jargon)
  • Conveys important information about the structure of the document, such as a heading
  • Contains a value that can change
  • Uses a dynamic content role attribute that is not equal to "presentation"
  • Uses one of the universal dynamic content property attributes, which are currently aaa:describedby, aaa:labelledby, aaa:required or aaa:invalid
  • Uses an onclick handler
  • Is in list of accessible elements in the role table

Linux/UNIX Applications Based on the Gecko Layout Engine

Gecko is a rendering engine that Firefox, SeaMonkey, Netscape and yelp use. Gecko can render a variety of content, not just HTML and supports key web standards such as Cascading Style Sheets, Javascript and the W3C DOM. Gecko also handles the users keystrokes and mouse clicks. Gecko is the core architecture that we are adding accessibility to, in order to support basic accessibility in all applications that are based on it.

The Mozilla Gecko engine must be version 1.9 or later to have high quality AT-SPI support, as documented here.

Embedded Clients

Embedded clients use Gecko only in the content window, at the moment for HTML and generic XML only. They typically use standard Windows controls for their user interface -- the area outside of the client content window, plus the context menu.

  • Yelp help viewer. No version is yet known to be available that uses a recent enough version of the Mozilla Gecko engine, for quality AT-SPI support.
  • Evolution email: no version is yet known to be available that uses a recent enough version of the Mozilla Gecko engine, for quality AT-SPI support.
  • Many more applications exist and are expected to be released

XUL-Based Clients

XUL-based clients make full use of the Gecko architecture, not only for HTML content, as well as for menus, dialogs and the entire user interface via an XML language called XUL (eXtensible User-interface Language). None of the user interface contains standard Windows controls -- not even the menus! This is done to ensure a common look and feel across all supported platforms, and to allow for different skins (appearances).

Determining if Accessibility is Enabled in a Firefox Installation

See the about:accessibilityenabled Firefox extension.

How to Find the Content Window and Load the Document

In XUL-based clients, screen readers may need to find the content window so that they know where to start grabbing the AT-SPI tree, in order to load the current document into a buffer in their own process.

Use RELATION_EMBEDS on the ROLE_FRAME, which is at the root of each top level window. This will point to the root content accessible(s) for that XUL window.

When you see the content window receive focus, first check the role. If it is a ROLE_DOCUMENT_FRAME then this should be treated as a document for the default modality of the screen reader. If it is a ROLE_EMBEDDED, ROLE_DIALOG or ROLE_ALERT then stay in focus tracking mode -- there is no need to parse the document. In addition, if it is a ROLE_ALERT, a screen reader should treat it as a message box -- that is, to read the entire contents. These roles can occur on content because of the new Accessible DHTML technology which allows the author to specify the type of document or container.

Gecko also helps determine when to load a new window by firing the following document events: document:load-complete, document:reload and document:load-stopped

Supported AT-SPI Interfaces

Interface Supported Notes
Accessible Yes

See supported object attributes below

Action Yes All methods
Application Yes All methods
Component Yes All methods
Desktop No
Document Yes All methods?
EditableText Yes All methods
Event Yes

See supported events below

Hyperlink Yes Any object embedded in text is considered a hyperlink!
Hypertext Yes Any text with objects embedded in it is considered a hypertext!
Image No ROLE_IMAGE is supported, and is enough
LoginHelper No
Registry No?
Relation Yes

See supported relations below

Role Yes

See supported roles below

Selection Yes Not yet supported for text
Selector No
State Yes

See supported states below

StreamableContent No Could apply to plugins, but probably not objects rendered by Gecko
Table Yes In addition, the object attribute layout-guess=true when Gecko thinks the table is for layout, not for data
Text Yes

See supported text attributes below

Value Yes

Supported AT-SPI Roles

The following roles are currently supported:

  • XXX Needs updating -- this list is copied from MSAA document
Role Supported? Special features
ROLE_INVALID Not a role that can be supported  
ROLE_ALERT XUL: <browsermessage><br /> DHTML: xhtml2:role="wairole:alert"  
ROLE_CANVAS No<br /> *** XXX File bug to support for <canvas> ***  
ROLE_CHECK_BOX XUL: <checkbox><br /> HTML: <input type="checkbox"><br /> DHTML: role="wairole:checkbox" Fires object:state-changed when radiobutton is set/unset when checkbox is toggled. *** Note: Some objects which appear to be checkboxes are in fact cyclers and have ROLE_CELL. Look for the "cycles" attribute to handle these.
ROLE_CHECK_MENU_ITEM XUL: <menuitem type="checkbox"><br /> DHTML: *** XXX file bug to support via role="wairole:menuitemcheckbox" *** Supports STATE_CHECKED
ROLE_COLUMN_HEADER XUL: tree column headers<br /> HTML: <th><br /> DHTML: role="wairole:columnheader"  
ROLE_COMBO_BOX XUL: <menulist><br /> HTML: <select size="1"><br /> DHTML: role="wairole:combobox" What event do we fire for changes in closed combo box?
Role Supported? Special features
ROLE_DIALOG <p> XUL: <dialog><br /> DHTML: role="wairole:dialog"</p> accessible name exposes the <title> of the current dialog
ROLE_FILE_CHOOSER Supported for native filepicker  
ROLE_FRAME Top level window  
ROLE_IMAGE XUL: <image><br /> HTML: <img> XUL: <image><br /> HTML: <img>
ROLE_LABEL XUL: <label><br /> HTML: <label><br /> DHTML: role="wairole:label" Supports RELATION_LABEL_FOR (although technically anthing can) <p> XUL: <label> or <description><br /> HTML: <label><br /> DHTML: role="wairole:label"</p>
ROLE_LIST   XUL: <listbox><br /> HTML: <select size=""> where size > 1 -- STATE_READONLY is off<br /> HTML: <ol> or <ul> -- STATE_READONLY is on<br /> DHTML: role="wairole:list"
ROLE_LIST_ITEM XUL: <listitem><br /> HTML: <li>, <option> or <optgroup> <br /> DHTML: role="wairole:listitem" Sets STATE_SELECTED if the current listitem is selected.<br /> <br /> *** XXX Perhaps should support object attribute "level" when in ROLE_TREE or ROLE_TREE_TABLE, see <a href="#obj-attr">object attributes</a> section ***
ROLE_MENU XUL: <menuitem> with children<br /> DHTML: role="wairole:menuitem" with child menuitems *** XXX does this work? ***  
ROLE_MENU_BAR XUL: <menubar><br /> DHTML: role="wairole:menubar"  
Role Supported? Special features
ROLE_MENU_ITEM   <p> XUL: <menuitem><br /> DHTML: role="wairole:menuitem"</p>
ROLE_PAGE_TAB XUL: <tab><br /> DHTML: role="wairole:tab"  
ROLE_PAGE_TAB_LIST   <p> XUL: <tab><br /> DHTML: role="wairole:tablist"</p>
ROLE_PANEL XUL: <radiogroup>, <groupbox>, <iframe><br /> HTML: <fieldset>, <frame>, <iframe><br /> DHTML: role="wairole:group", role="wairole:radiogroup"  
ROLE_PASSWORD_TEXT XUL: <textbox type="password"><br /> HTML: <input type="password"><br /> DHTML: role="wairole:secret"  
ROLE_POPUP_MENU No, apparently we use ROLE_MENU even for the context menu. XXX *** Is this right? *** Supports Text and EditableText interfaces
ROLE_PROGRESS_BAR XUL: <progressmeter><br /> DHTML: role="wairole:progressbar" <p> Fires "object:property-change:accessible-value" when progressbar moves by at least 3%</p> <p> Supports Value interface</p>
ROLE_PUSH_BUTTON   <p> XUL: <button><br /> HTML: <input type="button"> or<button><br /> DHTML: role="wairole:button"</p>
ROLE_RADIO_BUTTON XUL: <radio><br /> HTML: <input type="radio"><br /> DHTML: role="wairole:radio" <p> Fires object:state-changed when radiobutton is set/unset</p>
ROLE_RADIO_MENU_ITEM XUL: <menuitem type="radio"><br /> DHTML: *** XXX file bug to support via role="wairole:menuitemradio" * Supports STATE_CHECKED
ROLE_ROW_HEADER DHTML: role="wairole:columnheader"  
ROLE_SCROLL_BAR Not yet, bug 285167  
Role Supported? Special features
ROLE_SEPARATOR   XUL: <separator><br /> HTML: <hr><br /> DHTML: role="wairole:separator"
ROLE_SLIDER XUL:slider support added via bug 109215
DHTML: role="wairole:slider"
Fires "object:property-change:accessible-value" when slider thumb is moved<br /> <br /> Supports Value interface
ROLE_SPIN_BUTTON DHTML: role="wairole:spinbutton" Fires "object:property-change:accessible-value" when changed<br /> <br /> Supports Value interface
ROLE_STATUS_BAR XUL: <statusbar>  
ROLE_TABLE HTML: <table><br /> DHTML: role="wairole:grid" Supports Table interface<br /> Supports object attribute "layout-guess", see <a href="#obj-attr">object attributes</a> section
ROLE_TABLE_CELL HTML: <td><br /> DHTML: role="wairole:gridcell" *** XXX Perhaps should support object attribute "level" when in ROLE_TREE or ROLE_TREE_TABLE, see <a href="#obj-attr">object attributes</a> section ***
ROLE_TABLE_COLUMN_HEADER HTML: <th><br /> DHTML: role="wairole:columnheader" *** XXX Actually, do we use this one or ROLE_COLUMN_HEADER? ***  
ROLE_TABLE_ROW_HEADER DHTML: role="wairole:rowheader" *** XXX Actually, do we use this one or ROLE_ROW_HEADER? ***  
ROLE_TEXT HTML: fallback for display-block styled elements with no known semantic role for the tag<br /> DHTML: role="wairole:description"<br /> XXX *** We are using ROLE_TEXT for DHTML descriptions but ROLE_LABEL for XUL ones, that's inconsistent XXX Supports Text interface
ROLE_TOOL_BAR XUL: <toolbar><br /> DHTML: role="wairole:toolbar"  
ROLE_TOOL_TIP   XUL: <tooltip> or tooltiptext attribute
ROLE_TREE No, XXX *** We should use this when there is only 1 column in the tree ***<br /> DHTML: ?  
ROLE_TREE_TABLE XUL: <tree><br /> DHTML: role="wairole:tree" ?  
Role Supported? Special features
ROLE_APPLICATION Root accessible object, parent of top level ROLE_FRAME's  
ROLE_AUTOCOMPLETE XUL: <textbox type="autocomplete">  
ROLE_EMBEDDED DHTML: role="wairole:application"  
ROLE_ENTRY  XUL: <textbox><br /> HTML: <input type="text"> or <textarea><br /> DHTML: role="wairole:textfield" or<br /> role="wairole:textarea" Supports Text interface
ROLE_CAPTION HTML: <caption>  
ROLE_DOCUMENT_FRAME HTML: <body> without a role on the <html> or <body> element (unless that is wairole:document)<br /> DHTML: role="wairole:document" Supports Document interface<br /> Fires object:state-changed for busy state when document load begins or ends
ROLE_HEADING HTML: <h1>, <h2>, <h3>, <h4>, <h5>, <h6> Supports Text interface<br /> <br /> Supports object attribute "level", see <a href="#obj-attr">object attributes</a> section ***
ROLE_SECTION HTML: <div> Supports Text interface
ROLE_FORM HTML: <form> Supports Text interface
ROLE_LINK XUL: <label class="text-link"><br /> HTML: <a>, <area><br /> DHTML: role="wairole:link"  
Role Supported? Special features

Supported AT-SPI States

The following states are currently supported:

State Supported? Where used
STATE_INVALID No Not a usable state -- should not be confused with STATE_INVALID_ENTRY for form controls, which is supported
STATE_ACTIVE Yes Top level window
STATE_ARMED No *** XXX Where should this be supported? Same as MSAA's STATE_HASPOPUP? ***
STATE_BUSY Yes Documents which are loading
STATE_CHECKED Yes Checkboxes as well as checkable menuitems and treeitems
STATE_COLLAPSED Yes Outline items which have children but are not expanded -- always used with STATE_EXPANDABLE
STATE_DEFUNCT Yes Old objects which are no longer available
STATE_EDITABLE Yes Anything that supports the EditableText interface
STATE_ENABLED Yes Form controls
STATE_EXPANDABLE Yes Outline items which have children
STATE_EXPANDED Yes Outline items which are expandable and the children are shown -- always used with STATE_EXPANDABLE
STATE_FOCUSABLE Yes Nearly any element can be focusable
STATE_FOCUSED Yes Only 1 item at a time is ever focused -- always used with STATE_FOCUSABLE
STATE_HAS_TOOLTIP No *** XXX Need to file bug ***
STATE_HORIZONTAL No *** XXX need to file a bug for this and STATE_VERTICAL -- check XUL CSS ***
STATE_MODAL Yes Modal dialog boxes
STATE_MULTISELECTABLE Yes ROLE_TREE, ROLE_LIST, ROLE_TREE_TABLE. Indicates that Enter will insert a new line.
STATE_SENSITIVE No Where should this be used?
STATE_SINGLE_LINE Yes ROLE_ENTRY -- always used with STATE_EDITABLE. Indicates that Enter will submit the default button.
STATE_STALE No Where should this be used?
STATE_TRANSIENT Yes Where should this be used?
STATE_VERTICAL No *** XXX need to file a bug for this and STATE_HORIZONTAL -- check XUL CSS ***
STATE_VISIBLE Yes Absence of this state is important on documents, popups and tree items
STATE_MANAGES_DESCENDANTS No Not needed, although potentially useful for trees
STATE_INDETERMINATE No *** XXX File bug to support this based on nsIAccessible::STATE_MIXED. Should work on ROLE_CHECK_BOX, ROLE_TREE_ITEM, ROLE_LIST_ITEM, ROLE_PROGRESS_BAR ***
STATE_REQUIRED Yes XForms form controls, and any element with aaa:required="true"
STATE_TRUNCATED No Where should we use this?
STATE_ANIMATED Yes Animated images.
STATE_INVALID_ENTRY Yes XForms form controls, and any element with aaa:invalid="true"
STATE_SUPPORTS_AUTOCOMPLETION No *** XXX File bug to support this ***
STATE_SELECTABLE_TEXT Yes Anything that supports the Text interface
STATE_IS_DEFAULT Yes Default ROLE_BUTTON's, such as OK in XUL dialogs or Submit in HTML

Supported AT-SPI Relations

The following relations are currently supported:


enum {RELATION_LABEL_FOR = 0x1002 };

These two relations can be used on object to determine what form control is being labelled or desribed.


enum {RELATION_LABELLED_BY = 0x1003 };
enum {RELATION_DESCRIBED_BY = 0x100e };


These two relations are they inverse; they can be used on form controls. If the form control has an accName, you can get the IAccessible that it was labelled by in order to get more formatting information. It is also useful to check for a description.

Note that the label and description relations may be used to prevent redundant information from being presented by the screen reader, since the label and description can occur both on their own, and in the name or description fields of an IAccessible.


enum {RELATION_EMBEDS = 0x1009 };


This relation is used on the root accessible object for a top level Mozilla window, corresponding to what's returned for OBJID_CLIENT for that window. It points to the accessible object corresponding to the root of content in that window. This relation is very useful for finding the content quickly, and will be the proper method for finding content in Firefox 3 and beyond.


enum {RELATION_CONTROLLED_BY = 0x1000 };


These two relations show what form controls may dynamically change areas of the document, in response to user changes in the form controls themselves. Both controlled_by and controller_for are set in markup from the single dynamic content accessibility dynamic content aaa:controls attribute. The inverse controlled_by relation is automatically calculated.


enum {RELATION_FLOWS_TO = 0x1006 };
enum {RELATION_FLOWS_FROM = 0x1007 };


These two relations allow the reading flow to break out of the normal DOM flow. Both flows_to and flows_from are set in markup from the single dynamic content accessibility aaa:flowsto relation -- the inverse flow_from relation is automatically calculated.

Supported AT-SPI Object Attributes

The following object attributes are currently supported:

Note: see AJAX:WAI_ARIA_Live_Regions/API_Support for additional special object attributes that improve the processing of live changes.

Object attribute Applies to (content/UI/any/role) Possible values
atomic any "true" when the entire region should be presented as a whole, when changes within it are considered important enough to automatically present. Often goes with live property. Generally set via ARIA properties.
channel any "notify" when live changes can be presented alongside changes of the same politeness level. If a second channel is not available, the live changes should be prioritized slightly higher than changes of the same politeness. The attribute container-channel gives the computed value for this node (e.g. if there is any container element with the channel attribute the closes thing with the channel attribute wins).
checkable any widget that has internal STATE_CHECKABLE "true" when the widget is known to behave like a checkbox. Note some widgets which appear to be checkboxes might in fact be cyclers (see "cycles" below). Action 0 is named either "check" or "uncheck".
cycles ROLE_CELL "true" when the tree cell is a cycler, which means each click will cycle to the next option. In this case action 0 is called "cycles", which moves to the next option in the same way a manual click does.
datatype any widget that accepts input A qname that refers to an XSD (schema) defined type. For example, a datatype may be xsd:integer. When this is not specified, the default is string, unless the Value interface is exposed, which indicates the type is numeric. For more information please read about schema datatypes.
formatting any object that supports the hypertext interface "block" if the object uses block formatting, and thus starts on a new line and ends with a hard line break that is not visible in the actual text. For example, a heading, paragraph or list item are typically formatted as a block, but there is no requirement that they do so. Their formatting may have been changed with CSS. An example of this is often horizontal navigation bars with list items that are formatted with CSS display: inline.
haspopup any "true" when the object displays a pop-up menu or window when invoked.
id any Any value, defined by UI/content developers. Used to indicate a persistant identifier for any object, useful for scripting
layout-guess ROLE_TABLE "true" when Gecko's heuristic determines that it is a table that is probably used for layout, not for table.
Value not set means it is probably a data table.
level any For headings, the heading level. For outline items, the indentation level. For diagrams with levels, each item can have its level specified. The level value is 1-based.
line-number any focusable accessible text object The current line number of the caret, whether simply because the "browse with caret" option is on, or the caret used for editing text. The line number is relative to the top of the currently focused area (the document, a rich text editable area, or an input control).
live any A hint as to whether changes within the current region or subtree should be automatically presented. Possible values are "off" which is the same as not being set -- this means the region is not live. Other possible values are "polite", "assertive" and "rude", which is a suggestion for the policy when interrupting the user for changes to this region. Please see the ARIA States and Properties module for more information. Additional information may be provide by the object attributes atomic and relevant.
posinset any If this item is in a group, what is the item number within the group, where the size is defined by the setsize attribute. The first item should have posinset="1", and the last item should have a posinset value equal to the setsize.
relevant any Space delimited string with keywords describing what kinds of changes in the subtree are informational, as opposed to presentational. If not specified, the default should be considered "additions text", which indicates that newly created objects and changes to text and text equivalents should be considered relevant, and that the hiding or removal of items is not. Please see the ARIA States and Properties module for more information.
setsize any If this item is in a group, this indicates the number of items in the group. This is useful when combined with the posinset object attribute.
sort any container if "ascending" or "descending", then child items within the container are currently sorted as indicated.
tag any The actual markup tag used to create this element (also used in XUL)
valuetext Anything that supports the value interface, especially a slider or progress meter A text equivalent to the current value, such as "High" in a slider or "Unzipping files" in a progress meter
xml-roles any If a dynamic content accessibility role string is used, it is exposed here. This may provide more information than the AT-SPI role, which is best-fit. In the future, this may be a space or comma delimited list of roles

Supported AT-SPI Text Attributes

The following text attributes are currently supported:


Text attribute Possible values
static "true" for list bullet/numbering text or layout-inserted text (such as via CSS pseudo styles :before or :after)

Supported AT-SPI Document Attributes

The following document attributes are currently supported:

Document attribute Possible values Notes
W3C-doctype Equivalent to what is specified in the <!DOCTYPE> header This attribute cannot change for the lifetime of a document.
DocURL The location of the current document, including possibly a named anchor jumped to, for example The document:attributes-changed event is fired if the DocURL changes due to a named anchor jump.
MimeType The MIME or media type, such as text/plain, text/html, image/jpeg, image/svg+xml, application/xml+xhtml and application/vnd.mozilla.xul+xml. This attribute cannot change for the lifetime of a document.

Supported AT-SPI Events

The following events are currently supported:

  • object:focus
  • object:property-change ... *** XXX fill in list of properties we support this for ***
  • object:state-changed for ... *** XXX fill in list of states we support this for ***
  • object:text-changed:delete
  • object:text-changed:insert
  • object:text-selection-changed
  • object:text-caret-moved
  • object:selection-changed
  • window:activate
  • window:deactivate
  • document:load-complete
  • document:reload
  • document:load-stopped
  • document:attributes-changed

The event object:link-selected is purposely not supported, but focus events are fired on ROLE_LINK objects instead.

AT-SPI Features We Currently Do Not Support

As just stated, the event object::link-selected is purposely not supported, but focus events are fired on ROLE_LINK objects instead.

See Firefox 3 dependencies, and in particular the New ATK blocking bugs.

Known Differences with Other Applications

*** XXX To Be Done ***

Avoiding Memory Leaks

It is the assistive technology's responsibility to watch for events that indicate when windows or content subtrees are being destroyed, and to release all Accessible objects related to that window. In addition, STATE_DEFUNCT is set on objects that should be released by the assistive technology. XXX *** Indicate what events, I think we need to add object:children-changed:foo support ***

To help developers in that regard, there is Memory Leak monitor, a Firefox extension.

Keyboard User Interface and API

Fortunately, Gecko uses the standard keyboard API's for each supported platform.

The Mozilla keyboard shortcuts for content are similar to what is used in other browsers. Here is a list of Firefox keyboard shortcuts.


HTML Examples

Each AT-SPI accessible object is encapsulated in braces ("{}"), and meaningful AT-SPI interfaces and attributes, including specializations, are represented as name/value pairs inside the braces.
For convenience, accessible text is shown merely as 'text="contents of the text"'.
* = Embedded object character (0xfffc), used when no text from the object will be inserted in the parent Hypertext
HTML content HTML source AT-SPI representation

This is a heading

This is a paragraph with an <img src="image.gif" alt="some image"> image in it.

This is another heading

<h1>This is a heading</h1>
This is a paragraph with an
<image src="image.gif"
alt="some image"/>
image in it.
<h2>This is another heading</h2>
{parent Text, role=ROLE_HEADING, objattr="xhtml:tag=h1",
text="This is a heading"}
{parent Hypertext, role=ROLE_PARAGRAPH, attr="xhtml:tag=p"
text="This is a paragraph with an * image in it"}
{child Image, Hyperlink, role=ROLE_IMAGE,
ImageDescription ="some image",
AccessibleName = "" the HTML title attribute, if present
hyperlink-range= 28,29
{parent Text, role=ROLE_HEADING, objattr="xhtml-role:h2",
text="This is another heading"}

Tell me something.

<p>Hey!<br>Tell me something.</p>
{parent Text, role=ROLE_PARAGRAPH, attr="xhtml:tag=p"}
text="Hey!\nTell me something"}
<a href="">Hey!
Tell me something.</a>
<a href="">Hey!
<br>Tell me something.</a>
{parent Hyperlink, Text, role=ROLE_LINK
text="Hey!\nTell me something",
hyperlink-range= depends on the containing context,


Tell me something

<p>Tell me something</p>
{parent1 Text, role=ROLE_PARAGRAPH,

{parent2 role=ROLE_SEPARATOR,
 'note' .. : .. ' State doesn't include STATE_VERTICAL,
       to distinguish from vsep

{parent3 Text, role=ROLE_PARAGRAPH, 

 text="Tell me something"}

You are a nice person.

You <em>are</em> a nice person.
{parent Text,

role=ROLE_PARAGRAPH, attr="html:tag=p", 

       text="You are a nice


       attribute run for

"are", with objattr="role

= html:em", textattr="css:text-style=oblique"}

Here is a <a href="">bartending site</a>.

  Here is a
  <a href="">
   bartending site
{parent Hypertext,

role=ROLE_PARAGRAPH, attr="html:tag=p"
  text="Here is a *.",
  attribute run for "bartending site." with textattr="link=true,    
  css:text-decoration=underline, css:color=(0,0,255)"}
   {child Text,  Hyperlink,
     role=ROLE_LINK, attr="html:tag=a, link-type:anchor",
     text="bartending site",
     hyperlink-indices= 10,11


Here is a <a href=""> <img src="beerglass.GIF" alt="beer glass">bartending site</a>.

Here is a
<a href="">
<image src="beerglass.GIF"
alt="beer glass"/>
bartending site
{parent Hypertext,

role=ROLE_PARAGRAPH, attr="html:tag=p"

       text="Here is a *."
       attribute run for "bartending site."

with textattr="link=true,    


css:text-decoration=underline, css:color=(0,0,255)"}


Hypertext, Hyperlink,



           text="*bartending site" 

           hypertext-indices= 10,11,

     [not sure if we need to dup textattrs

here, or add them to defaulttextattrs] ,




  {grandchild Image, Hyperlink


     role=ROLE_IMAGE, attr="html:tag=img, link-type=image"


   AccName/ImageDescription="beer glass",

     [don't know if the URIs should

always be fully specified, or if omitting the base URI is OK

       At the moment, not planning to do this, instead plan
         to expose repair text in the name if no alt/title exists ] 

Here is a <img src="beerglass.GIF" alt="beer glass"> <a href=""> bartending site</a> .

Here is a
<image src="beerglass.GIF"
alt="beer glass"/>
<a href="">
bartending site
{parent Hypertext,

role=ROLE_PARAGRAPH, attr="html:tag=p", 
  text="Here is a **."}
   {child Image, Hyperlink,
     role=ROLE_IMAGE, attr="html:tag=img, link-type=image"
     AccName/ImageDescription="beer glass",
     hyperlink-indices= 10,11
   {child Text, Hyperlink, Action,
    Hypertext, role=ROLE_LINK,

     attr="html:tag=a, link-type=anchor"
     text="bartending site",
as in above examples
     hypertext-indices= 11,22,
<IMG SRC="sitemap.gif"
ALT="Site map"
<MAP NAME="mymap" title="site map">
<AREA HREF="1.html" ALT="Bar"
<AREA HREF="2.html" ALT="Baz"
<AREA HREF="3.html" ALT="Fu"
{parent Hypertext, role=ROLE_PARAGRAPH,
{child Image, Hypertext, text=" ***", Hyperlink,
ImageBounds= entire map area
AccName and ImageDescription="Site map"}
{grandchild Hyperlink, Action,
action-names="click", role=ROLE_LINK,
attr="html:tag=area", hyperlink-URI="1.html", name="Bar"}
{grandchild Hyperlink, Action,
action-names="click", role=ROLE_LINK,
attr="html:tag=area", hyperlink-URI="2.html", name="Baz"}
{grandchild Hyperlink, Action,
action-names="click", role=ROLE_LINK,
attr="html:tag=area", hyperlink-URI="3.html", name="Fu"}
note that the component bounds of the areas correspond to their rectangular bounding boxes
     * This is a list item.
     * This is another list item.
<li>This is a list item.</li>
<li>This is another list item.</li>

{parent Object, role=ROLE_LIST, attr="css:list-style-type=disc"}
{child Text, role=ROLE_LIST_ITEM,
text="This is a list item.", attribute run "static" first 2 chars}
{child Text, role=ROLE_LIST_ITEM,
text="This is another list item.", attribute run "static" first 2 chars}
       [Bill: we

should be able to support list-style=image, and "list-style-image=URL()", etc. this way.  In the above example, it's not clear whether the bullet should be a unicode char or just omitted and implied by the list style..  my guess is the latter (i.e. bullets don't appear in the text)]

  1. This is a list item.
  2. This is another list item.
<li>This is a list item.</li>
<li>This is another list item.</li>
{parent Object, role=ROLE_LIST, attr="html:tag=ol, css:list-style-type:decimal"}
{child Text, role=ROLE_LIST_ITEM,
text="1. This is a list item.", attribute run "static" first 3 chars}
{child Text, role=ROLE_LIST_ITEM,
text="2. This is another list item.", attribute run "static" first 3 chars}
  • This is a list item
    • Nested item 1.
    • Nested item 2.
  • This is another list item.
This is a list item.
<li>Nested item 1</li>
<li>Nested item 2</li>
<li>This is another list item.</li>

{parent Object, role=ROLE_LIST, attr="html:tag=ul, css:list-style-type=disc"}
{child Hypertext, role=ROLE_LIST_ITEM,
text="This is a list item.*"}
{grandchild Object, Hyperlink, role=ROLE_LIST,
attr="html:tag=ul, css:list-style-type=circle, link-type=child",
hyperlink-indices= 20,21,
hyperlink-URI="", Hmm, degenerate case here... }
{great-grandchild Text, role=ROLE_LIST_ITEM, attr="html:tag=li"
text="Nested item 1"}
{great-grandchild Text, role=ROLE_LIST_ITEM, attr="html:tag=li"
text="Nested item 2"}
   {child Text, role=ROLE_LIST_ITEM,
text="This is another list item."}

Note that unlike user interface ROLE_LIST objects, these lists don't
implement Selection, and the list items' StateSets do not include
STATE_SELECTABLE. There is a question here as to whether
  • and
    1. elements
      should always implement Text or not. I think it would be better if they did not, unless they had
      non-empty text content, but this may prove impractical.
<label for="self"> Tell me a little more: </label>
<textarea> I am a monkey

with a long tail. I like to swing from trees and eat bananas. I've

recently taken up typing and plan to write my memoirs. </textarea>
 <label for="self"/>
Tell me a little more:
I am a monkey with a long
tail. I like to swing from
trees and eat bananas. I've
recently taken up typing
and plan to write my memoirs.
{parent Object, role=ROLE_FORM, text=""}
{child1 Object, role=ROLE_SECTION? or should we use ROLE_PANE? }
{grandchild Text,
text="Tell me a little more:"}
{child2 role=ROLE_SECTION?}
{grandchild EditableText,
Relation, StateSet, Action,
text="I am a monkey with ..."},

[ attribute run over the portion of the text scrolled into view?
CONTROLLER_FOR/CONTROLLED_BY for the scrollbar/viewport?
Alternative would be to treat all the text content as though it were visible, but that's no good
for magnifiers and ATs for the mobility-impaired. Probably the textarea needs to be expanded somewhat,
or at least fitted with Actions for scrolling plus text attribution for determining what parts of the text are
currently scrolled into view, without the AT client having to resort to bounds checking in the
"screen review" fashion. This is, however, a general problem with multiline text in viewports.
The relatively new Text getBoundedRanges API reduces the pain somewhat since you can
feed it the Component bounds and it will give you back the visible text.]

Check one or more: <input id="cb1" type="checkbox"><label for="cb1">Red</label> <input id="cb2" type="checkbox"><label for="cb2">Blue</label> <input id="cb3" type="checkbox"><label for="cb3">Green</label>

<form aaa:describedby="checkhelp">
Check one or more:
<input id="cb1" type="checkbox"/>
<label for="cb1">Red</label>
<input id="cb2" type="checkbox"/>
<label for="cb2">Blue</label>
<input id="cb3" type="checkbox"/>
<label for="cb3">Green</label>
{parent Object,
{child Text,
role=ROLE_PARAGRAPH, attr="html:tag=p", text=""}
{grandchild1 Text,
text="Check one or more:"}
{grandchild2 Action,
StateSet, role=ROLE_CHECK_BOX,
attr="html:tag=input", and same with other elements, expose html' .. : .. 'role
note also that these objects do NOT have accessible names, because they are labelled;
accessible-name would presumably come from the HTML title attribute or other attribute.
This is mainly to make it easier for ATs to avoid highly redundant speech in these cases.

{grandchild3 Text,
role=ROLE_LABEL, text="Red",
{grandchild4 Action,
StateSet, role=ROLE_CHECK_BOX,
{grandchild5 Text,
role=ROLE_LABEL, text="Blue",
{grandchild6 Action,
StateSet, role=ROLE_CHECK_BOX,
{grandchild7 Text,
role=ROLE_LABEL, text="Green",

and RELATION_DESCRIPTION_FOR to match AT-SPI/DHTML. Also, I thought we had
ROLE_FORM, but it seems not to be there. Did I miss something?
      <label for="beverage">Make a selection:</label>
       <select id="beverage">
<label for="beverage">
Make a selection:
<select id="beverage">
{parent role=ROLE_FORM?}
{child Text,
text="Make a selection:"}
{child Action,
StateSet, Selection,
role=ROLE_LIST_ITEM, text="Water"}
role=ROLE_LIST_ITEM, text="Wine"}
{grandchild Text,

[note that because the entry field is not editable, but just displays the current
selection, I think it should not be exposed (especially since it represents a node
which is not present in the HTML DOM. The list items need not implement Action,
since the Selection interface is used by the client to select among them.]

Which sports do you like?
<select name="sports" multiple="multiple" size="3"> <option>Hockey</option> <option>Basketball</option> <option>Football</option> <option>Baseball</option> </select>

<label for="sports">
Which sports do you like:
<select id="sports"
<img src="beerglass.gif"
{parent role=ROLE_FORM?}
{child1 Text,
text="Which sports do you like:\n*"}
{child2 Object,
accessible-name="sports" not sure exposing the id is a good idea though,
Selection, Hyperlink,
role=ROLE_LIST_ITEM, text="*Baseball"}
{great-grandchild Image, Hyperlink,
attr="html:tag=img, link-type=image",
hyperlink-indices= 0,1}
role=ROLE_LIST_ITEM, text="Basketball"}
{grandchild3 Text,
To do: HTML table example    
To do: DHTML role example    

Beyond HTML: Other Types of Web Content

  • You may have heard of some content types beyond HTML, and want to know if Gecko based products will support them:
  • DHTML and AJAX: Gecko and other browsers have long supported dynamic content, where the page appearance changes because of JavaScript. This can be used to create the appearance of desktop-style widgets like menus, spreadsheets and tree views which HTML lacks. Or, it can be used to completely change content on the fly, without loading a new page. Previously it was not posible to make this accessible, but Mozilla supports Accessible DHTML, which allows authors to make advanced widgets and web applications accessible.
  • MathML: an XML dialect used to display full math notation on web pages. Here's the ongoing Mozilla project to support MathML . We do not currently have plans to support MSAA for MathML - we will likely suggest use of the external DOM for this, because MSAA simply does not have the right semantics in it to support mathematics. MathML support is currently built into Firefox.
  • SVG : Scalable Vector Graphics. Essentially W3C's XML-based version of Flash - mixes well with other markup based content, supports the DOM and has accessibility features. Mozilla's SVG Project has been through several stalls and rebirths -- SVG will probably become more of a priority if other well known browsers support it. We will not know how, or whether, we will support SVG accessibility until a better implementation comes along. Firefox 1.5 supports SVG. Potentially it can make use of the same namespaced role and state attributes as DHTML accessibility, but it may require more powerful author-definable relationships.
  • XForms: XForms is the future of online forms as envisioned by the W3C. Drawing on other W3C standards like XML Schema, XPath, and XML Events, XForms tries to address some of the limitations with the current HTML forms model. One of the key features of XForms is accessibility. XForms accessibility development is currently being developed for Mozilla 1.9 (Firefox 3) by Alexander Surkov.
  • XUL: The XML-based language used by Firefox and Mozilla to develop the UI. Similar to HTML in that it can be combined with CSS and Javascript to make powerful applications. Contains more desktop-style widgets than HTML and follows a box layout model, rather than being text-flow based. In the future more standalone applications will use XUL via Xulrunner.

Questions or Comments?

Please discuss accessibility issues on the Mozilla Accessibility mailing list or on the Mozilla Accessibility IRC channel.

Document Tags and Contributors

 Last updated by: teoli,