Accessibility/Comparisons:ATK To UA
ATK to UA, interfaces
This page attempts to provide an overview of UA, comparing it to some interfaces in ATK. I highgly recommend to read the introduction to UA before reading this document.
Any developer serious in implementing UA support should always read Apple's official accessibility documentation; this is by no means an end-all be-all document, but can give you an idea about how things work. Feel free to add and edit entries.
Interfaces
Actions (AtkAction)
There are only three APIs dealing with actions in UA:
- accessibilityActionNames
- gives an array of strings telling the available actions that this widget supports.
- accessibilityActionDescription
- returns a human-readable (localized) description of a specified action.
- accessibilityPerformAction
- performs a specified action.
Making a view/widget accessible (AtkComponent)
In UA, every widget has to implement a few methods to be made accessible. Those views that are invisible, and uninteresting to the user should implement the accessibilityIsIgnored method to return NO (false).
The position and size of a widget is not accessible-specific, so you call the necessary NSView methods to get that information.
Hit-testing (getting the accessible object at a given point on the screen) can be done using the accessibilityHitTest: method on any view.
To get the currently focused widget's accessibility object, accessibilityFocusedUIElement is used, which will return the deepest accessible descendant.
To set focus, there is the AXFocused attribute that is often settable. To see if a specified attribute is settable, use the accessibilityIsAttributeSettable: and then accessibilitySetValue:forAttribute: to set it.
To "manually" traverse and inspect the accessibility hierarchy of a view/widget, you get the value of these attributes:
- AXChildrenAttribute
- will return an array of all accessible children of the widget, skipping any ignored widgets on the way.
- AXParentAttribute
- will return the accessible parent of this widget, skipping any ignored widgets on the way.
Traversing the DOM (AtkDocument, AtkHypertext)
AtkDocument is ATK's way to expose the DOM to client applications. To my knowledge, this does not (yet) exist in UA, as with many advanced features (particularly those web-specific).
AtkHypertext seems to be ATK's APIs to let a client application easily traverse the links on a page. No such feature exists in OS X, although I don't think it's necessarily impossible to do.
Text editing (AtkEditableText)
Basic
To get/set the value of a text widget you use the AXValueAttribute. There are also some text-specific attributes.
Copying, cutting, pasting etc. are not actions in UA, but the user invokes the menu on the text widget (AXShowMenu action) and then picks the action (copy, paste, cut, etc).
A third-party could of course use standard Cocoa methods on the text widget to let the user perform this in some other way.
Rich text-editing
Rich text-editing is done by querying a text widget for the attributes of specific ranges. For example, you can:
- Get the bounds of a range
- Get the styled text of a range (as an NSAttributedText object)
- Get the range for a line, or an index, or all visible characters
In other words, contrary to ATK, text runs themselves do not contain accessible objects.
Links (AtkHyperlink)
In UA there's the AXLink role for links (10.4+). Then there's a AXTextLink subrole, and WebKit even defines a custom AXImageMap role for image maps. They also define an AXURL attribute on those links that gives the URL as a string.
For links, the actual linkified object (an image, a text) seems to be a child of an AXLink object in the hierarchy. So some text + an image would be children of the AXLink object.
From WebKit's code, it appears that another extension is an AXVisited attribute that links (and other objects) can have, when they have been visited. (All WebKit extensions can be found here.)
Links usually sport the AXPressAction (just like buttons).