Gecko info for Windows accessibility vendors

The MSAA tree and the DOM tree are parallel structures, although the MSAA tree is a subset of the DOM tree. QueryService() can be used to switch between the interfaces (IAccessible, ISimpleDOMDocument, ISimpleDOMNode and ISimpleDOMText). If there is no MSAA node for a DOM node, or vice-versa, QueryService() will return null.

Anything that is focusable or conveys important information about the structure of the document is exposed in the MSAA tree of IAccessibles.

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.

• MFCEMBED testing client: This is a very simple package, great for testing basic HTML accessibility with your products and the Gecko rendering engine.
• K-Meleon: a light, ultra-fast and more advanced (fully configurable) Gecko-based web browser available on the Windows platform

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).

• Firefox (please use version 1.1 alpha builds or later)
• Thunderbird (please use version 1.1 alpha builds or later)
• Mozilla Seamonkey (please use 1.8 alpha builds or later)

Ordinary zero-indexed child IDs are not practical for representing events. The problem is that the child ID system that is used by MSAA doesn't work well when you have a deep tree of objects in a window. It would be impractical to number all of the nodes in a document starting at 0, because whenever a node is inserted or removed it would be computationally very expensive to renumber things. So, the Firefox childID handed back from events is based on an algorithm that uses the pointer value of the related internal DOM node. This computed child ID for events is always a negative value, unique to the IAccessible firing the event

These negative childID's from events can be used with AccessibleObjectFromEvent(), or on the root accessible of a window with any IAccessible method that takes a VARIANT, such as get_accChild().

Because screen readers usually cache an entire document's worth of data, it can be extremely useful for them to receive a child ID that helps them correlate back to a known object. We provide support for this technique via ISimpleDOMNode::get_nodeInfo(), which returns a uniqueID for any IAccessible that can be cached in the internal model. When an event is received, the negative childID should match one of these cached uniqueID's, if the entire document has been stored and kept current. Keeping an internal cache current means getting new subtrees of IAccessibles whenever an EVENT_REORDER is received, indicating important changes have invalidated part of the model.

The accNavigate() method can be used with new constants defined for Gecko. The results are always returned via VT_DISPATCH.

enum { NAVRELATION_LABEL_FOR = 0x1002 };
enum { NAVRELATION_DESCRIPTION_FOR = 0x100f };

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

enum { NAVRELATION_LABELLED_BY = 0x1003 };
enum { NAVRELATION_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 { NAVRELATION_DEFAULT_BUTTON = 0x100d };

When used within an HTML form or a XUL dialog, the NAVRELATION_DEFAULT_BUTTON relation will return the IAccessible for the default button.

enum { NAVRELATION_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 is the proper method for finding content in Firefox 3 and beyond.

enum { NAVRELATION_CONTROLLED_BY = 0x1000 };
enum { NAVRELATION_CONTROLLER_FOR = 0x1001 };

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.

the DOMenum { NAVRELATION_FLOWS_TO = 0x1006 };

enum { NAVRELATION_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.

These relations can affect the calculation for the next next or previous item of a certain type. Here is an algorithm for iterating through the nodes, looking for an item of a particular type:

1. Store a pointer to the start_item
2. If the current item has a flows_to relation, follow that relation
3. Otherwise, go to the next item in depth first search order
4. If the current item matches your criteria, then return current_item
5. If the current_item == start_item, return null (no item found)
6. If the end has been reached, go back to the start if wrapping is desired, otherwise return null (no item found)
7. Go to step 2

Gecko defines three state constants using previously unused states:

const unsigned long STATE_CHECKABLE = STATE_MARQUEED; // Useful on menuitem, listitem
// and treeitem. Indicates that the absence of STATE_CHECKED should be spoken as
// "unchecked", and that EVENT_STATE_CHANGE will be fired in the event that the
// checkbox is toggled.

const unsigned long STATE_REQUIRED = STATE_ALERT_LOW;  // Used on form controls
// to indicate that this field must be filled out to submit the form

const unsigned long STATE_INVALID = STATE_ALERT_HIGH;  // Used on form controls to
// indicate the the field does not currently have a legal value

const unsigned long STATE_??? = STATE_ALERT_MEDIUM; // Reserved for future use.

BSTR roles are used for important roles that have not been defined by Microsoft. When the role is retrieved in a VARIANT returned from get_accRole, check to see if variant.vt == VT_BSTR. If it is, than variant.bstrVal contains the role string.

The role string may be an HTML tag name followed by comma, space and the namespace of the current element. In most current cases the namespace can be ignored, but it may become important in the future. The following HTML tags are exposed as BSTR's:

abbr, acronym, blockquote, dd, dl, dt, form, frame, h1, h2, h3, h4, h5,
h6, iframe, q, tbody, tfoot, thead

In addition, an HTML list uses the bullet BSTR role to expose bullets and numbers that are automatically inserted into the formatting by Gecko. In addition, ROLE_LIST with STATE_READONLY and ROLE_LISTITEM are used to expose the list structure. This makes it important to check the STATE_READONLY flag when encountering a ROLE_LIST, because the HTML list form element also uses ROLE_LIST, but without STATE_READONLY set.

The accDescription field is overriden for the following roles:

ROLE_LISTITEM, ROLE_MENUITEM, ROLE_RADIOBUTTON, ROLE_PAGETAB and ROLE_OUTLINEITEM

For everything other than outline item, the positional description is in the form "n of m" where n is an integer indicating the position within other similar objects in a group, and m represents the number of objects in that group. For example, "3 of 5" indicates the 3rd object out of 5.

For outline item, more information is provided, in a format that reads "L#, n of m with c" where # represents the level that the outline item is at, and c represents the number of children. The n of m position relates to the position within the current outline level.

Finally, true descriptions are now exposed with the text "Description: " prepending the description. This makes it clear that the description is truly intended to be read. Neither "Description:" or "of" in the above strings is ever localized, so they should be parsed out.

This means that you may encounter roles that are not typically in HTML content. Be prepared for new combinations of roles and states in content, such as ROLE_SLIDER, ROLE_PROGRESSBAR and STATE_REQUIRED. In addition, check the STATE_FOCUSABLE bit on tables, which indicates a traversable DHTML spreadsheet. Please see the DHTML accessibility documentation page for more information on this topic.

Unless the document changes, retrieving the IAccessible more than once for the same object will return the same IAccessible*. The uniqueID will remain the same as well. If the document does change, EVENT_REORDER, EVENT_HIDE and EVENT_SHOW are used to indicate where the changes will occur. Because of the persistence, relations and events can be mapped within an assistive technology's internal model.

When a new document is about to be loaded, an EVENT_STATE_CHANGE occurs on the root ROLE_DOCUMENT object for a window. The STATE_BUSY flag is now set for the root pane object.

Once the new page is ready to be displayed and traversed via its IAccessible tree, the old content window is destroyed, and a new window is created. Next, another EVENT_STATE_CHANGE is fired for the new root ROLE_DOCUMENT object for the window, with its STATE_BUSY flag cleared.

To use these interfaces, you'll need to get the ISimpleDOMNode.idl, ISimpleDOMText.idl and ISimpleDOMDocument.idl file. You must make a header files for them, by running these commands:

That will generate ISimpleDOMNode.h and ISimpleDOMDocument.h, which define the interfaces. It will also create ISimpleDOMNode_i.c and ISimpleDOMDocument_i.c, which contain the necessary IID constants.

To get to the ISimpleDOMNode interface for an object, you start with an IAccessible*, and then you QueryService to the ISimpleDOMNode*:

 IServiceProvider *pServProv = NULL;
 pAccessible->QueryInterface(IID_IServiceProvider, (void**)&pServProv);
 ISimpleDOMNode *pSimpleDOMNode;
 if (pServProv) {
 const GUID refguid = {0x0c539790, 0x12e4, 0x11cf,
 0xb6, 0x61, 0x00, 0xaa, 0x00, 0x4c, 0xd6, 0xd8};
 HRESULT result =
 pServProv->QueryService(refguid, IID_ISimpleDOMNode, (void**)&pSimpleDOMNode);
 if (SUCCEEDED(hresult) && pSimpleDOMNode != NULL) {
   /* This is a Mozilla node! Use special
     ISimpleDOMNode methods described in ISimpleDOMNode.idl.
   */

   }
  }

The get_nodeInfo method is used to get basic information about a node such as the tag name and namespace ID, node type (see ISimpleDOMNode.idl for definitions), node value (text held in the node), a unique ID for use in tracking where events occur, and the number of children. The namespace ID is meaningless until you get the namespace URI for it, through the ISimpleDOMDocument interface (see below).

        HRESULT get_nodeInfo(
        /* [out] */ BSTR *nodeName,
        // For elements, this is the tag name
         /* [out] */ short *nameSpaceID,
         /* [out] */ BSTR *nodeValue,
         /* [out] */ unsigned int *numChildren,
         /* [out] */ unsigned int *uniqueID, // see
        description of unique ID's in above section on events
         /* [out] */ unsigned short *nodeType);

The get_attributes method returns the set of attribute, value pairs for a given node, as well as the namespace ID for each attribute. The return value numAttribs specifies the number of attributes for this node, and the last 3 parameters return 3 arrays corresponding to attribute name, namespace ID, and attribute value.

 HRESULT get_attributes(
 /* [in] */ unsigned short maxAttribs,
 /* [out] */ BSTR *attribNames,
 /* [out] */ short *nameSpaceID,
 /* [out] */ BSTR *attribValues,
 /* [out] */ unsigned short *numAttribs);

A variation on this method is get_attributesForNames, which lets turns the attribNames array into an [in] parameter, letting you specify only those attributes you're interested in. This helps minimize the cost of marshalling for those times in which you're interested in only a few attributes per node.

 HRESULT get_attributesForNames(
 /* [in] */ unsigned short numAttribs,
 /* [in] */ BSTR __RPC_FAR *attribNames,
 /* [in] */ short __RPC_FAR *nameSpaceID,
 /* [out] */ BSTR __RPC_FAR *attribValues);

The get_computedStyle method is used to find out the cumulative, computed results for all style rules applied to a node. The return value numStyleProperties specifies the number of style properties for this node, and the last 2 parameters return 2 arrays corresponding to style property name and style property value. Another [in] parameter, useAlternativeMediaProperties, indicates whether you want style information for the default media type (usually screen), or a set of alternative media types specified in nsISimpleDOMDocument::set_alternateViewMediaType(mediaTypeString) . See the W3C's website for a list of official media type name. Unfortunately, at this time the argument useAlternateView is ignored.

 HRESULT get_computedStyle(
 /* [in] */ unsigned short maxStyleProperties,
 /* [in] */ boolean useAlternateView,
 // If TRUE, returns properties for media
 // as set in nsIDOMDocument::set_alternateViewMediaTypes
 /* [out] */ BSTR *styleProperties,
 /* [out] */ BSTR *styleValues,
 /* [out] */ unsigned short *numStyleProperties);

A variation on this method is get_computedStyleForProperties, which lets turns the styleProperties array into an [in] parameter, letting you specify only those style properties you're interested in. This helps minimize the cost of marshalling for those times in which you're interested in only a few style properties per node.

 HRESULT get_computedStyleForProperties(
 /* [in] */ unsigned short numStyleProperties,
 /* [in] */ boolean useAlternateView, //
 If TRUE, returns properties for media
 // as set in nsIDOMDocument::set_alternateViewMediaTypes
 /* [in] */ BSTR *styleProperties,
 /* [out] */ BSTR *styleValues);

To scroll the document in order make a specific element visible in the window, use scrollTo(boolean placeTopLeft). If the parameter placeTopLeft is TRUE the document will be scrolled so that the element is placed in the top left corner of the window. If placeTopLeft is FALSE, the document will only be scrolled if the element is not already visible, or the document will be scrolled the minimum amount to make the element visible anywhere within the current window.

You can also get to any other node by traversing the ISimpleDOMNode structure. The DOM content tree is a superset of the MSAA tree. In other words, you can always QueryInterface from an IAccessible to an ISimpleDOMNode, but often not the other way around.

 HRESULT get_parentNode     (/* [in] */ ISimpleDOMNode *newNodePtr);
 HRESULT get_firstChild     (/* [in] */ ISimpleDOMNode *newNodePtr);
 HRESULT get_lastChild      (/* [in] */ ISimpleDOMNode *newNodePtr);
 HRESULT get_previousSibling(/* [in] */ ISimpleDOMNode  *newNodePtr);
 HRESULT get_nextSibling    (/* [in] */ ISimpleDOMNode *newNodePtr);
 HRESULT get_childAt        (/* [in] */ unsigned childIndex,
 /* [out] */ ISimpleDOMNode **newNodePtr);

Next we provide a convenience method for getting the actual HTML within a DOM subtree. This only applies if the node is HTML.

Finally we provide a method for getting the current ISO 639 language code, such as "en" for English or even possible "en-cockney" for the British Cockney dialect.

Please look at the ISimpleDOMNode.idl file for parameter types and the definitions of the node type constants.