nsIAccessible

« Gecko AT Interfaces Page

Summary

The nsIAccessible interface is a cross-platform interface that supports platform-specific accessibility APIs like MSAA and ATK. Contains the sum of what's needed to support IAccessible as well as ATK's generic accessibility objects.

Can also be used by in-process accessibility clients to get information about objects in the accessible tree. The accessible tree is a subset of nodes in the DOM tree -- such as documents, focusable elements and text. Mozilla creates the implementations of nsIAccessible on demand.

 [scriptable, uuid=(c7520419-87ec-42bc-98cc-04c0bf173530)]
 interface nsIAccessible : nsISupports { ... };

Overview

This section provides short overview of methods and attributes of this interface. All methods and attributes are grouped by categories.

Role, states and name

These includes main properties used to describe the accessible.

• nsIAccessible.role to get the role of the accessible
• nsIAccessible.getState() to get states of the accessibe
• nsIAccessible.name, nsIAccessible.value to get the name and the value of the accessible

Tree navigation

You can navigate through the accessible tree by the following methods and attributes.

• nsIAccessible.parent to get the parent accessible
• nsIAccessible.nextSibling, nsIAccessible.previousSibling to get sibling accessibles
• nsIAccessible.firstChild, nsIAccessible.lastChild to get first and last child
• nsIAccessible.children, nsIAccessible.getChildAt(), nsIAccessible.childCount to navigate through the children by index

Accessible position

You can use nsIAccessible.indexInParent to get accessible index in its parent. Use nsIAccessible.groupPosition() to get information about this accessible in its group.

Relations

Many accessibles are linked with each other, for example, if one accessible gives the accessible name for another accessible (for example, html:label and html control) then these accessibles are related, please refer to relations documentation for more information. You can get related accessibles by methods

• nsIAccessible.getAccessibleRelated()
• nsIAccessible.getRelations()
• nsIAccessible.getRelation() and nsIAccessible.relationsCount.

Focus and selection

In order to focus an accessible or get focused child accessible use nsIAccessible.takeFocus() and nsIAccessible.focusedChild.

To select an accessible you can use nsIAccessible.setSelected(), nsIAccessible.takeSelection() and nsIAccessible.extendSelection().

Actions

You can prepare actions on some accessibles (for example on button accessible). The following methods are intended for this nsIAccessible.actionCount, nsIAccessible.getActionName(), nsIAccessible.getActionDescription() and nsIAccessible.doAction().

Descriptions

nsIAccessible.description and nsIAccessible.help provides additional text information about accessible.

Attributes

Many accessibles exposes attributes to provide more details that cannot be fit into existing API methods, please refer to attributes documentation for more information. You can use nsIAccessible.attributes to get a map of attributes.

Keyboard shortcuts

Some actions on accessibles can be performed by keyboard shortcuts. Following methods are used to get them nsIAccessible.defaultKeyBinding(), nsIAccessible.getKeyBindings(), nsIAccessible.keyboardShortcut.

Size and screen position

You can use nsIAccessible.getBounds() to get size and coordinates of the accessible.

Layout oriented methods

• nsIAccessible.getChildAtPoint() to get child accessible from point
• nsIAccessible.getAccessibleToLeft(), nsIAccessible.getAccessibleToRight(), nsIAccessible.getAccessibleAbove() or nsIAccessible.getAccessibleBelow() to get left, right, top or below placed accessible

Methods

getKeyBindings

Provides array of localized string of global keyboard accelerator for the given action index supported by accessible.

getState

Provides a bit fields of accessible states which describe boolean properties of accessible. 

groupPosition

This method returns grouping information. Used for tree items, list items, tab panel labels, radio buttons, etc. Also used for collectons of non-text objects.

getChildAtPoint

This method returns an accessible child which contains the coordinate at (x, y) in screen pixels.

getChildAt

This method returns Nth accessible child using zero-based index or last child if index than less than zero.

getAccessibleToRight

This method returns an accessible node geometrically to the right of this one.

getAccessibleToLeft

This method returns an accessible node geometrically to the left of this one.

getAccessibleAbove

This method returns an accessible node geometrically above this one.

getAccessibleBelow

This method returns an accessible node geometrically below this one.

getAccessibleRelated

This method returns an accessible related to this one by the given relation type.

getRelation

This method returns one accessible relation for this object.

getRelations

This method returns multiple accessible relations for this object.

getBounds

This method returns accessible's (x and y) coordinates relative to the screen and accessible's width and height.

setSelected

This method adds or remove this accessible to the current selection.

extendSelection

This method extends the current selection from its current accessible anchor node to this accessible.

takeSelection

This method selects this accessible node only.

takeFocus

This method focuses this accessible node.

getActionName

This method retrieves the name of the accessible action at the given zero-based index.

getActionDescription

This method retrieves the description of the accessible action at the given zero-based index.

doAction

This method performs the accessible action at the given zero-based index. Action number 0 is the default action.

Attributes

parent

Parent node in accessible tree.

nextSibling

Next sibling in accessible tree.

previousSibling

Previous sibling in accessible tree.

firstChild

First child in accessible tree.

lastChild

Last child in accessible tree.

children

Array of all this element's children.

childCount

Number of accessible children.

indexInParent

The 0-based index of this accessible in its parent's list of children, or -1 if this accessible does not have a parent.

name

Accessible name -- the main text equivalent for this node.

value

Accessible value -- a number or a secondary text equivalent for this node. Widgets that use role attribute can force a value using the valuenow attribute.

description

Accessible description -- long text associated with this node.

keyboardShortcut

Provides localized string of accesskey name, such as Alt+D. The modifier may be affected by user and platform preferences. Usually alt+letter, or just the letter alone for menu items.

defaultKeyBinding

Provides localized string of global keyboard accelerator for default action, such as Ctrl+O for Open file.

role

Enumerated accessible role for the associated element.

help

Help text associated with node.

focusedChild

Focused accessible child of node.

attributes

Attributes of accessible.

relationsCount

Returns the number of accessible relations for this object.

numActions

The number of accessible actions associated with this accessible.