Gecko Roles

 

« AT APIs Support Page

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>
<p>
This is a paragraph with an
<image src="image.gif"
alt="some image"/>
image in it.
</p>
<h2>This is another heading</h2>
{parent Text, role=ROLE_HEADING, objattr="xhtml:tag=h1",
text-attributes="css:font-size=LARGER",
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-attributes="css:font-size=LARGE",
text="This is another heading"}

Hey!
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="http://www.google.com/">Hey!
Tell me something.</a>
<a href="http://www.google.com">Hey!
<br>Tell me something.</a>
{parent Hyperlink, Text, role=ROLE_LINK
objattr="html:tag=a;link-type=anchor",
text="Hey!\nTell me something",
hyperlink-range=[depends on the containing context],
hyperlink-URI="http://www.google.com",
hyperlink-Object=Text}

Hey


Tell me something

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

 text="Hey"}
{parent2 role=ROLE_SEPARATOR,
  [State doesn't include STATE_VERTICAL to distinguish from vsep]
{parent3 Text, role=ROLE_PARAGRAPH, 

 text="Tell me something"}

You are a nice person.

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

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


       text="You are a nice

person",


       attribute run for

"are", with objattr="role

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

Here is a <a href="http://foo.bar.com/">bartending site</a>.

<p>
  Here is a
  <a href="http://foo.bar.com">
   bartending site
  </a>
.
</p>
{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]

     hyperlink-URI="http://foo.bar.com"}

Here is a <a href="http://foo.bar.com/"> <img src="beerglass.GIF" alt="beer glass">bartending site</a>.

<p>
Here is a
<a href="http://foo.bar.com">
<image src="beerglass.GIF"
alt="beer glass"/>
bartending site
</a>
.
</p>
{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

Hypertext, Hyperlink,

     
          

role=ROLE_LINK,

           text="*bartending site" 

           hypertext-indices=[10,11],

     [not sure if we need to dup textattrs

here, or add them to defaulttextattrs] ,

          

hypertext-URI="http://foo.bar.com"}

            

  {grandchild Image, Hyperlink

           

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

          

   AccName/ImageDescription="beer glass",
             hyperlink-indices=[0,1]

            
URI="beerglass.GIF"}
[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="http://foo.bar.com/"> bartending site</a> .

<p>
Here is a
<image src="beerglass.GIF"
alt="beer glass"/>
<a href="http://foo.bar.com">
bartending site
</a>
.
</p>
{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]
     hyperlink-URI="beerglass.GIF"}
   {child Text, Hyperlink, Action,
    Hypertext, role=ROLE_LINK,
     action-names="activate",

[others?]
     attr="html:tag=a, link-type=anchor"
     text="bartending site",
     textattr=
[as\nin above examples]
     hypertext-indices=[11,22],
     hypertext-URI="http://foo.bar.com"}
 
<p>
<IMG SRC="sitemap.gif"
ALT="Site map"
USEMAP="#mymap">
<MAP NAME="mymap" title="site map">
<AREA HREF="1.html" ALT="Bar"
COORDS="5,5,95,195">
<AREA HREF="2.html" ALT="Baz"
COORDS="105,5,195,195">
<AREA HREF="3.html" ALT="Fu"
COORDS="205,5,295,195">
</MAP>
</p>
{parent Hypertext, role=ROLE_PARAGRAPH,
text="*"}
{child Image, Hypertext, text=" ***", Hyperlink,
role=ROLE_IMAGE,
attr="html:tag=map",
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.
<ul>
<li>This is a list item.</li>
<li>This is another list item.</li>
</ul>

{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.
<ol>
<li>This is a list item.</li>
<li>This is another list item.</li>
</ol>

{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.
<ul>
<li>
This is a list item.
<ul>
<li>Nested item 1</li>
<li>Nested item 2</li>
</ul>
</li>
<li>This is another list item.</li>
</ul>


{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 <ul> and <ol> 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>
<form>
<div>
 <label for="self"/>
Tell me a little more:
</label>
</div>
<div>
<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>
</div>
</form>
{parent Object, role=ROLE_FORM, text=""}
{child1 Object, role=ROLE_SECTION? [or should we use ROLE_PANE?] }
{grandchild Text,
role=ROLE_LABEL,
RELATION_LABEL_FOR=child2,
text="Tell me a little more:"}
{child2 role=ROLE_SECTION?}
{grandchild EditableText,
Relation, StateSet, Action,
ROLE_ENTRY,
text="I am a monkey with ..."},
RELATION_LABELLED_BY=child1,
STATE_MULTILINE,
STATE_REQUIRED allowed}

[ 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">
<p>
<span
x2:tag="wairole:description"
id="checkhelp">
Check one or more:
</span>
<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>
</p>
</form>
{parent Object,
role=ROLE_FORM,
attr="html:tag=form",
RELATION_DESCRIBED_BY=grandchild1,
text="?"}
{child Text,
role=ROLE_PARAGRAPH, attr="html:tag=p", text=""}
{grandchild1 Text,
role=ROLE_LABEL,
RELATION_DESCRIPTION_FOR=parent,
attr="html:tag=wairole:description"}
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.]
RELATION_LABELLED_BY=grandchild3}
{grandchild3 Text,
role=ROLE_LABEL, text="Red",
RELATION_LABEL_FOR=grandchild2}
{grandchild4 Action,
StateSet, role=ROLE_CHECK_BOX,
RELATION_LABELLED_BY=grandchild5}
{grandchild5 Text,
role=ROLE_LABEL, text="Blue",
RELATION_LABEL_FOR=grandchild4}
{grandchild6 Action,
StateSet, role=ROLE_CHECK_BOX,
RELATION_LABELLED_BY=grandchild7}
{grandchild7 Text,
role=ROLE_LABEL, text="Green",
RELATION_LABEL_FOR=grandchild6}

[RFE .. : .. add RELATION_DESCRIBED_BY
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">
       <option>Water</option>
       <option>Wine</option>
       <option>Whiskey</option>
       </select>
     
<form>
<label for="beverage">
Make a selection:
</label>
<select id="beverage">
<option>Water</option>
<option>Wine</option>
<option>Whiskey</option>
</select>
</form>
{parent role=ROLE_FORM?}
{child Text,
role=ROLE_LABEL,
RELATION_LABEL_FOR=child,
text="Make a selection:"}
{child Action,
StateSet, Selection,
attr="html:tag=select",
role=ROLE_COMBO_BOX,
RELATION_LABELLED_BY}
{grandchild,
Text,
  StateSet=...SELECTABLE, SELECTED...,
attr="html:tag=option",
role=ROLE_LIST_ITEM, text="Water"}
{grandchild,
Text,
  StateSet=...SELECTABLE...,
attr="html:tag=option",
role=ROLE_LIST_ITEM, text="Wine"}
{grandchild Text,
StateSet=...SELECTABLE...,
role=ROLE_LIST_ITEM,
attr="html:tag=option",
text="Whiskey"}

[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>

<form>
<label for="sports">
Which sports do you like:
<br>
<select id="sports"
multiple="multiple"
size="3">
<option>
<img src="beerglass.gif"
alt="Beer"/>
Baseball
</option>
<option>Basketball</option>
<option>Football</option>
</select>
</label>
</form>
{parent role=ROLE_FORM?}
{child1 Text,
role=ROLE_LABEL,
RELATION_LABEL_FOR=child2,
text="Which sports do you like:\n*"}
{child2 Object,
accessible-name="sports" [not sure exposing the id is a good idea though],
Selection, Hyperlink,
StateSet=...MULTISELECT...
attr="html:tag=select",
role=ROLE_LIST,
RELATION_LABELLED_BY=child2}
{grandchild1,
HyperText,
  StateSet=...SELECTABLE, SELECTED...,
attr="html:tag=option",
role=ROLE_LIST_ITEM, text="*Baseball"}
{great-grandchild Image, Hyperlink,
role=ROLE_IMAGE,
attr="html:tag=img, link-type=image",
hyperlink-URI="beerglass.gif",
hyperlink-indices=[0,1]}
{grandchild2,
Text,
  StateSet=...SELECTABLE...,
attr="html:tag=option",
role=ROLE_LIST_ITEM, text="Basketball"}
{grandchild3 Text,
StateSet=...SELECTABLE...,
role=ROLE_LIST_ITEM,
attr="html:tag=option",
text="Football"}
To do: HTML table example    
To do: DHTML role example    

Document Tags and Contributors

Contributors to this page: Sheppy, fscholz, Surkov.alexander
Last updated by: Sheppy,