Accessibility/AT-Windows-API: Difference between revisions

This FAQ explains how makers of Windows screen readers, voice dictation packages and magnification software can support Gecko-based software. The base of our support for these products is MSAA (Microsoft Active Accessibility), external readonly DOM support, and the keyboard API/user interface.

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

: please read the MSAA documentation on MSDN if you are unfamiliar with these. in general we abbreviate by removing redundant words. For example, we may say EVENT_ALERT instead of the full EVENT_SYSTEM_ALERT.

[[Image:at-windows-api-tree-relativity.gif|Diagram showing MSAA tree is a subset of the DOM tree]]

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

Gecko is a rendering engine that Mozilla, Netscape and other new browsers 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.

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.

* [http://kmeleon.sourceforge.net/ K-Meleon]<nowiki>: a light, ultra-fast and more advanced (fully configurable) Gecko-based web browser available on the Windows platform</nowiki>

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

* Mozilla Seamonkey (''please use 1.8 alpha builds or later'')

Screen readers need to find the content window so that they know where to start grabbing the MSAA tree, in order to load the current document into a buffer in their own process. The content window always has the class MozillaContentWindowClass.

Gecko also helps determine when to load a new window by firing two EVENT_STATE_CHANGE's on the root ROLE_DOCUMENT accessible -- the first state change indicates the document pane is now busy loading. The second state change indicates the document pane has finished. When handling the event, use get_accState() to check the STATE_BUSY flag. When the document has finished loading the busy flag will be cleared.

To use MSAA with Gecko, you'll need the tools and docs that come with the [http://www.microsoft.com/downloads/details.aspx?FamilyId=3755582A-A707-460A-BF21-1373316E13F0&displaylang=en Active Accessibility 2.0 SDK Tools]. The method <code>AccessibleObjectFromWindow()</code> will get you the root IAccessible corresponding to the top level window. Hold on to this root IAccessible, and use it to walk through the entire tree of IAccessible's.

* get_accKeyboardShortcut

* EVENT_FOCUS is fired for focus changes on any kind of focusable object

* EVENT_SELECTIONWITHIN is fired on multi selection containers when the current selection changes within. In addition, EVENT_SELECTIONADD and EVENT_SELECTIONREMOVE are fired on the the child who's selection changed.

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

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.

<div class="indent">

  </div>

<div class="indent">

For the most part, where we support an MSAA feature, we have tried to duplicate Internet Explorer's use of it. Please let us know if you find any differences not listed here:

<div class="indent">

  </div>

<div class="indent">

  </div>

<div class="indent">

  </div>

<div class="indent">

  </div>

<div class="indent">

  </div>

<div class="indent">

  </div>

<div class="indent">

  </div> </div>

! scope="col" | Role

! scope="col" | Supported?

| DHTML: role="wairole:checkbox"

|-

|-

| rowspan="4" | ROLE_RADIOBUTTON

|}

<div class="indent">

  </div>

<div class="indent">

  </div>

<div class="indent">

* ISimpleDOMDocument contains basic document information, such title, URL, doctype and mime type.

<div class="indent">

  </div>

<div class="indent">

  </div> </div>

<div class="indent">

</pre>

<div class="indent">

</pre>

<div class="indent">

  </div>

* You may have heard of some content types beyond HTML, and want to know if Gecko based products will support them:

* [http://www.xulplanet.com/ XUL]<nowiki>: 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 </nowiki>[http://wiki.mozilla.org/XUL:Xul_Runner XULRunner].

<div class="indent">