User:Frederik.gladhorn/atspi-scratch
GNOME Accessibility Team
ATK/AT-SPI Best Practices Guide for Implementors
DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
Introduction
This guide is for implementors of ATK and AT-SPI 2. It should say how to describe the user interface through the use of the AT-SPI Accessibility APIs. Having consistent representations of widgets makes the implementation of assisitive technology much easier.
ATK and AT-SPI should be identical to large parts. Especially roles and enums should be the same, so this guide applies to both.
The aim is to have a defined structure where applicable. For example an editable Combo Box should have a list or table and an editable text as children.
In addition the expected signals such as accessible-name changed should be documented so that it is clear which signals to emit.
States
Accessible objects always have a set of states. For each widget below it is mentioned which states should be implemented. Over AT-SPI2 the states are split into two 32 bit uints. (yes, it's that horrible).
FIXME link to states list
ATSPI States (from at-spi2-core/atspi/atspi-constants.c)
* ATSPI_STATE_INVALID: * ATSPI_STATE_ACTIVE: Indicates a window is currently the active window, or is an active subelement within a container or table * ATSPI_STATE_ARMED: Indicates that the object is armed * ATSPI_STATE_BUSY: Indicates the current object is busy, i.e. onscreen representation is in the process of changing, or the object is temporarily unavailable for interaction due to activity already in progress. * ATSPI_STATE_CHECKED: Indicates this object is currently checked * ATSPI_STATE_COLLAPSED: Indicates this object is collapsed * ATSPI_STATE_DEFUNCT: Indicates that this object no longer has a valid backing widget (for instance, if its peer object has been destroyed) * ATSPI_STATE_EDITABLE: Indicates the user can change the contents of this object * ATSPI_STATE_ENABLED: Indicates that this object is enabled, i.e. that it currently reflects some application state. Objects that are "greyed out" may lack this state, and may lack the STATE_SENSITIVE if direct user interaction cannot cause them to acquire STATE_ENABLED. @see STATE_SENSITIVE. * ATSPI_STATE_EXPANDABLE: Indicates this object allows progressive disclosure of its children * ATSPI_STATE_EXPANDED: Indicates this object its expanded * ATSPI_STATE_FOCUSABLE: Indicates this object can accept keyboard focus, which means all events resulting from typing on the keyboard will normally be passed to it when it has focus * ATSPI_STATE_FOCUSED: Indicates this object currently has the keyboard focus * ATSPI_STATE_HAS_TOOLTIP: Indicates that the object has an associated tooltip * ATSPI_STATE_HORIZONTAL: Indicates the orientation of thsi object is horizontal * ATSPI_STATE_ICONIFIED: Indicates this object is minimized and is represented only by an icon * ATSPI_STATE_MODAL: Indicates something must be done with this object before the user can interact with an object in a different window. * ATSPI_STATE_MULTI_LINE: Indicates this (text) object can contain multiple lines of text * ATSPI_STATE_MULTISELECTABLE: Indicates this object allows more than one of its children to be selected at the same time, or in the case of text objects, that the object supports non-contiguous text selections. * ATSPI_STATE_OPAQUE: Indicates this object paints every pixel within its rectangular region. It also indicates an alpha value of unity, if it supports alpha blending. * ATSPI_STATE_PRESSED: Indicates this object is currently pressed * ATSPI_STATE_RESIZABLE: Indicates the size of this object's size is not fixed * ATSPI_STATE_SELECTABLE: Indicates this object is the child of an object that allows its children to be selected and that this child is one of those children that can be selected. * ATSPI_STATE_SELECTED: Indicates this object is the child of an object that allows its children to be selected and that this child is one of those children that has been selected. * ATSPI_STATE_SENSITIVE: Indicates this object is sensitive, e.g. to user interaction. STATE_SENSITIVE usually accompanies STATE_ENABLED for user-actionable controls, but may be found in the absence of STATE_ENABLED if the current visible state of the control is "disconnected" from the application state. In such cases, direct user interaction can often result in the object gaining STATE_SENSITIVE, for instance if a user makes an explicit selection using an object whose current state is ambiguous or undefined. @see STATE_ENABLED, STATE_INDETERMINATE. * ATSPI_STATE_SHOWING: Indicates this object, the object's parent, the object's parent's parent, and so on, are all 'shown' to the end-user, i.e. subject to "exposure" if blocking or obscuring objects do not interpose between this object and the top of the window stack. * ATSPI_STATE_SINGLE_LINE: Indicates this (text) object can contain only a single line of text * ATSPI_STATE_STALE: Indicates that the information returned for this object may no longer be synchronized with the application state. This can occur if the object has STATE_TRANSIENT, and can also occur towards the end of the object peer's lifecycle. * ATSPI_STATE_TRANSIENT: Indicates this object is transient * ATSPI_STATE_VERTICAL: Indicates the orientation of this object is vertical; for example this state may appear on such objects as scrollbars, text objects (with vertical text flow), separators, etc. * ATSPI_STATE_VISIBLE: Indicates this object is visible, e.g. has been explicitly marked for exposure to the user. STATE_VISIBLE is no guarantee that the object is actually unobscured on the screen, only that it is 'potentially' visible, barring obstruction, being scrolled or clipped out of the field of view, or having an ancestor container that has not yet made visible. A widget is potentially onscreen if it has both STATE_VISIBLE and STATE_SHOWING. The absence of STATE_VISIBLE and STATE_SHOWING is semantically equivalent to saying that an object is 'hidden'. * ATSPI_STATE_MANAGES_DESCENDANTS: Indicates that "active-descendant-changed" event is sent when children become 'active' (i.e. are selected or navigated to onscreen). Used to prevent need to enumerate all children in very large containers, like tables. The presence of STATE_MANAGES_DESCENDANTS is an indication to the client. that the children should not, and need not, be enumerated by the client. Objects implementing this state are expected to provide relevant state notifications to listening clients, for instance notifications of visibility changes and activation of their contained child objects, without the client having previously requested references to those children. * ATSPI_STATE_INDETERMINATE: Indicates that a check box or other boolean indicator is in a state other than checked or not checked. This usually means that the boolean value reflected or controlled by the object does not apply consistently to the entire current context. For example, a checkbox for the "Bold" attribute of text may have STATE_INDETERMINATE if the currently selected text contains a mixture of weight attributes. In many cases interacting with a STATE_INDETERMINATE object will cause the context's corresponding boolean attribute to be homogenized, whereupon the object will lose STATE_INDETERMINATE and a corresponding state-changed event will be fired. * ATSPI_STATE_REQUIRED: Indicates that user interaction with this object is 'required' from the user, for instance before completing the processing of a form. * ATSPI_STATE_TRUNCATED: Indicates that an object's onscreen content is truncated, e.g. a text value in a spreadsheet cell. * ATSPI_STATE_ANIMATED: Indicates this object's visual representation is dynamic, not static. This state may be applied to an object during an animated 'effect' and be removed from the object once its visual representation becomes static. some applications, notably content viewers, may not be able to detect all kinds of animated content. Therefore the absence of this state should not be taken as definitive evidence that the object's visual representation is static; this state is advisory. * ATSPI_STATE_INVALID_ENTRY: This object has indicated an error condition due to failure of input validation. For instance, a form control may acquire this state in response to invalid or malformed user input. * ATSPI_STATE_SUPPORTS_AUTOCOMPLETION: This state indicates that the object in question implements some form of ¨typeahead¨ or pre-selection behavior whereby entering the first character of one or more sub-elements causes those elements to scroll into view or become selected. Subsequent character input may narrow the selection further as long as one or more sub-elements match the string. This state is normally only useful and encountered on objects that implement Selection. In some cases the typeahead behavior may result in full or partial ¨completion¨ of the data in the input field, in which case these input events may trigger text-changed events from the source. * ATSPI_STATE_SELECTABLE_TEXT: This state indicates that the object in question supports text selection. It should only be exposed on objects which implement the Text interface, in order to distinguish this state from STATE_SELECTABLE, which infers that the object in question is a selectable child of an object which implements Selection. While similar, text selection and subelement selection are distinct operations. * ATSPI_STATE_IS_DEFAULT: This state indicates that the object in question is the 'default' interaction object in a dialog, i.e. the one that gets activated if the user presses "Enter" when the dialog is initially posted. * ATSPI_STATE_VISITED: This state indicates that the object (typically a hyperlink) has already been activated or invoked, with the result that some backing data has been downloaded or rendered. * ATSPI_STATE_LAST_DEFINED: This value of the enumeration should not be used as a parameter, it indicates the number of items in the StateType enumeration.
Some states are valid for all widgets:
* Visible?
Roles
* ATSPI_ROLE_INVALID: A Role indicating an error condition, such as uninitialized Role data. * ATSPI_ROLE_ACCELERATOR_LABEL: Object is a label indicating the keyboard accelerators for the parent * ATSPI_ROLE_ALERT: Object is used to alert the user about something * ATSPI_ROLE_ANIMATION: Object contains a dynamic or moving image of some kind * ATSPI_ROLE_ARROW: Object is a 2d directional indicator * ATSPI_ROLE_CALENDAR: Object contains one or more dates, usually arranged into a 2d list * ATSPI_ROLE_CANVAS: Object that can be drawn into and is used to trap events * ATSPI_ROLE_CHECK_BOX: A choice that can be checked or unchecked and provides a separate indicator for the current state. * ATSPI_ROLE_CHECK_MENU_ITEM: A menu item that behaves like a check box (see ROLE_CHECK_BOX) * ATSPI_ROLE_COLOR_CHOOSER: A specialized dialog that lets the user choose a color. * ATSPI_ROLE_COLUMN_HEADER: The header for a column of data * ATSPI_ROLE_COMBO_BOX: A list of choices the user can select from * ATSPI_ROLE_DATE_EDITOR: An object which allows entry of a date * ATSPI_ROLE_DESKTOP_ICON: An inconifed internal frame within a DESKTOP_PANE * ATSPI_ROLE_DESKTOP_FRAME: A pane that supports internal frames and iconified versions of those internal frames. * ATSPI_ROLE_DIAL: An object that allows a value to be changed via rotating a visual element, or which displays a value via such a rotating element. * ATSPI_ROLE_DIALOG: A top level window with title bar and a border * ATSPI_ROLE_DIRECTORY_PANE: A pane that allows the user to navigate through and select the contents of a directory * ATSPI_ROLE_DRAWING_AREA: A specialized dialog that displays the files in the directory and lets the user select a file, browse a different directory, or specify a filename. * ATSPI_ROLE_FILE_CHOOSER: An object used for drawing custom user interface elements. * ATSPI_ROLE_FILLER: A object that fills up space in a user interface * ATSPI_ROLE_FOCUS_TRAVERSABLE: Don't use, reserved for future use. * ATSPI_ROLE_FONT_CHOOSER: Allows selection of a display font * ATSPI_ROLE_FRAME: A top level window with a title bar, border, menubar, etc. * ATSPI_ROLE_GLASS_PANE: A pane that is guaranteed to be painted on top of all panes beneath it * ATSPI_ROLE_HTML_CONTAINER: A document container for HTML, whose children represent the document content. * ATSPI_ROLE_ICON: A small fixed size picture, typically used to decorate components * ATSPI_ROLE_IMAGE: An image, typically static. * ATSPI_ROLE_INTERNAL_FRAME: A frame-like object that is clipped by a desktop pane. * ATSPI_ROLE_LABEL: An object used to present an icon or short string in an interface * ATSPI_ROLE_LAYERED_PANE: A specialized pane that allows its children to be drawn in layers, providing a form of stacking order. * ATSPI_ROLE_LIST: An object that presents a list of objects to the user and allows the user to select one or more of them. * ATSPI_ROLE_LIST_ITEM: An object that represents an element of a list. * ATSPI_ROLE_MENU: An object usually found inside a menu bar that contains a list of actions the user can choose from. * ATSPI_ROLE_MENU_BAR: An object usually drawn at the top of the primary dialog box of an application that contains a list of menus the user can choose from. * ATSPI_ROLE_MENU_ITEM: An object usually contained in a menu that presents an action the user can choose. * ATSPI_ROLE_OPTION_PANE: A specialized pane whose primary use is inside a DIALOG * ATSPI_ROLE_PAGE_TAB: An object that is a child of a page tab list * ATSPI_ROLE_PAGE_TAB_LIST: An object that presents a series of panels (or page tabs), one at a time, through some mechanism provided by the object. * ATSPI_ROLE_PANEL: A generic container that is often used to group objects. * ATSPI_ROLE_PASSWORD_TEXT: A text object uses for passwords, or other places where the text content is not shown visibly to the user. * ATSPI_ROLE_POPUP_MENU: A temporary window that is usually used to offer the user a list of choices, and then hides when the user selects one of those choices. * ATSPI_ROLE_PROGRESS_BAR: An object used to indicate how much of a task has been completed. * ATSPI_ROLE_PUSH_BUTTON: An object the user can manipulate to tell the application to do something. * ATSPI_ROLE_RADIO_BUTTON: A specialized check box that will cause other radio buttons in the same group to become uncghecked when this one is checked. * ATSPI_ROLE_RADIO_MENU_ITEM: Object is both a menu item and a "radio button" (see ROLE_RADIO_BUTTON) * ATSPI_ROLE_ROOT_PANE: A specialized pane that has a glass pane and a layered pane as its children. * ATSPI_ROLE_ROW_HEADER: The header for a row of data * ATSPI_ROLE_SCROLL_BAR: An object usually used to allow a user to incrementally view a large amount of data by moving the bounds of a viewport along a one-dimensional axis. * ATSPI_ROLE_SCROLL_PANE: An object that allows a user to incrementally view a large amount of information. ROLE_SCROLL_PANE objects are usually accompanied by ROLE_SCROLL_BAR controllers, on which the RELATION_CONTROLLER_FOR and RELATION_CONTROLLED_BY reciprocal relations are set; \see Accessibility::RelationSet. * ATSPI_ROLE_SEPARATOR: An object usually contained in a menu to provide a visible and logical separation of the contents in a menu. * ATSPI_ROLE_SLIDER: An object that allows the user to select from a bounded range * ATSPI_ROLE_SPIN_BUTTON: An object which allows one of a set of choices to be selected, and which displays the current choice. Unlike ROLE_SCROLL_BAR, ROLE_SLIDER objects need not control 'viewport'-like objects. * ATSPI_ROLE_SPLIT_PANE: A specialized panel that presents two other panels at the same time. * ATSPI_ROLE_STATUS_BAR: Object displays non-quantitative status information (c.f. ROLE_PROGRESS_BAR) * ATSPI_ROLE_TABLE: An object used to repesent information in terms of rows and columns. * ATSPI_ROLE_TABLE_CELL: A 'cell' or discrete child within a Table. \note Table cells need not have ROLE_TABLE_CELL, other RoleType values are valid as well. * ATSPI_ROLE_TABLE_COLUMN_HEADER: An object which labels a particular column in a Table. * ATSPI_ROLE_TABLE_ROW_HEADER: An object which labels a particular row in a Table. Table rows and columns may also be labelled via the RELATION_LABEL_FOR/RELATION_LABELLED_BY relationships; see Accessibility.RelationSet. * ATSPI_ROLE_TEAROFF_MENU_ITEM: Object allows menu to be removed from menubar and shown in its own window. * ATSPI_ROLE_TERMINAL: An object that emulates a terminal * ATSPI_ROLE_TEXT: An object that presents text to the user, of nonspecific type. * ATSPI_ROLE_TOGGLE_BUTTON: A specialized push button that can be checked or unchecked, but does not procide a separate indicator for the current state. * ATSPI_ROLE_TOOL_BAR: A bar or palette usually composed of push buttons or toggle buttons * ATSPI_ROLE_TOOL_TIP: An object that provides information about another object * ATSPI_ROLE_TREE: An object used to repsent hierarchical information to the user. * ATSPI_ROLE_TREE_TABLE: An object that presents both tabular and hierarchical info to the user * ATSPI_ROLE_UNKNOWN: The object contains some Accessible information, but its role is not known. * ATSPI_ROLE_VIEWPORT: An object usually used in a scroll pane, or to otherwise clip a larger object or content renderer to a specific onscreen viewport. * ATSPI_ROLE_WINDOW: A ¨top level window¨ with no title or border. * ATSPI_ROLE_EXTENDED: means that the role for this item is known, but not included in the core enumeration * ATSPI_ROLE_HEADER: An object that serves as a document header. * ATSPI_ROLE_FOOTER: An object that serves as a document footer. * ATSPI_ROLE_PARAGRAPH: An object which is contains a single paragraph of text content. See also ROLE_TEXT. * ATSPI_ROLE_RULER: An object which describes margins and tab stops, etc. for text objects which it controls (should have CONTROLLER_FOR relation to such). * ATSPI_ROLE_APPLICATION: An object corresponding to the toplevel accessible of an application, which may contain ROLE_FRAME objects or other accessible objects. Children of AccessibleDesktop objects are generally ROLE_APPLICATION objects. * ATSPI_ROLE_AUTOCOMPLETE: The object is a dialog or list containing items for insertion into an entry widget, for instance a list of words for completion of a text entry. * ATSPI_ROLE_EDITBAR: The object is an editable text object in a toolbar. * ATSPI_ROLE_EMBEDDED: The object is an embedded component container. This role is a "grouping" hint that the contained objects share a context which is different from the container in which this accessible is embedded. In particular, it is used for some kinds of document embedding, and for embedding of out-of-process component, "panel applets", etc. * ATSPI_ROLE_ENTRY: The object is a component whose textual content may be entered or modified by the user, provided STATE_EDITABLE is present. A readonly ROLE_ENTRY object (i.e. where STATE_EDITABLE is not present) implies a read-only 'text field' in a form, as opposed to a title, label, or caption. * ATSPI_ROLE_CHART: The object is a graphical depiction of quantitative data. It may contain multiple subelements whose attributes and/or description may be queried to obtain both the quantitative data and information about how the data is being presented. The LABELLED_BY relation is particularly important in interpreting objects of this type, as is the accessible-description property. See ROLE_CAPTION * ATSPI_ROLE_CAPTION: The object contains descriptive information, usually textual, about another user interface element such as a table, chart, or image. * ATSPI_ROLE_DOCUMENT_FRAME: The object is a visual frame or container which contains a view of document content. Document frames may occur within another Document instance, in which case the second document may be said to be embedded in the containing instance. HTML frames are often ROLE_DOCUMENT_FRAME. Either this object, or a singleton descendant, should implement the Document interface. * ATSPI_ROLE_HEADING: The object serves as a heading for content which follows it in a document. The 'heading level' of the heading, if availabe, may be obtained by querying the object's attributes. * ATSPI_ROLE_PAGE: The object is a containing instance which encapsulates a page of information. ROLE_PAGE is used in documents and content which support a paginated navigation model. * ATSPI_ROLE_SECTION: The object is a containing instance of document content which constitutes a particular 'logical' section of the document. The type of content within a section, and the nature of the section division itself, may be obtained by querying the object's attributes. Sections may be nested. * ATSPI_ROLE_REDUNDANT_OBJECT: The object is redundant with another object in the hierarchy, and is exposed for purely technical reasons. Objects of this role should be ignored by clients, if they are encountered at all. * ATSPI_ROLE_FORM: The object is a containing instance of document content which has within it components with which the user can interact in order to input information; i.e. the object is a container for pushbuttons, comboboxes, text input fields, and other 'GUI' components. ROLE_FORM should not, in general, be used for toplevel GUI containers or dialogs, but should be reserved for 'GUI' containers which occur within document content, for instance within Web documents, presentations, or text documents. Unlike other GUI containers and dialogs which occur inside application instances, ROLE_FORM containers' components are associated with the current document, rather than the current foreground application or viewer instance. * ATSPI_ROLE_LINK: The object is a hypertext anchor, i.e. a "link" in a hypertext document. Such objects are distinct from 'inline' content which may also use the Hypertext/Hyperlink interfaces to indicate the range/location within a text object where an inline or embedded object lies. * ATSPI_ROLE_INPUT_METHOD_WINDOW: The object is a window or similar viewport which is used to allow composition or input of a 'complex character', in other words it is an "input method window." * ATSPI_ROLE_LAST_DEFINED: Not a valid role, used for finding end of enumeration.
Events
Focus
One of the most important events is the focus change. FIXME document here what needs to happen when focus changes.
Objects and their Properties
* Add AtkObject, AtkRoles, Names, Descriptions and the like * Talk about when to include versus when to omit or "fold in" (e.g. button whose child is a label, filler, etc.)
Matthias: I would really like to get some clarification about signals, when to emit them, what their expected semantics are, etc. E.g: do I emit 'visible-data-changed' when a label gains a mnemonic underline ?
Interfaces
Note from JD: For now, I'm including the Documentation along with a Do's and Don'ts. Those ultimately might need to be merged. For now, having them both makes it more obvious to me what we should be questioning, docs we might need to go back and update, etc., etc.
Most accessible objects are expected to implement a variety of interfaces based on the purpose served by the backing toolkit widget, along with the ways users can interact with that widget.
AtkAction
Description from the Documentation
[[1]] should be implemented by instances of AtkObject classes with which the user can interact directly, i.e. buttons, checkboxes, scrollbars, e.g. components which are not "passive" providers of UI information.
Exceptions: when the user interaction is already covered by another appropriate interface such as AtkEditableText (insert/delete test, etc.) or AtkValue (set value) then these actions should not be exposed by [[2]] as well.
Also note that the [[3]] API is limited in that parameters may not be passed to the object being activated; thus the action must be self-contained and specifiable via only a single "verb". Concrete examples include "press", "release", "click" for buttons, "drag" (meaning initiate drag) and "drop" for drag sources and drop targets, etc.
Though most UI interactions on components should be invocable via keyboard as well as mouse, there will generally be a close mapping between "mouse actions" that are possible on a component and the [[4]]. Where mouse and keyboard actions are redundant in effect, [[5]] should expose only one action rather than exposing redundant actions if possible. By convention we have been using "mouse centric" terminology for [[6]] names.
Note from Matthias: Should point out here that actions have keybindings associated with them. What are those good for, anyway ?
How Assistive Technologies Use This Interface
* Write me
Do's and Don'ts
* Write me * TODO: There was some discussion in #a11y with Benjamin and Joanie regarding the 'exception' above. We need to decide if it is good to have this "It's an AtkAction unless it happens to be an interface and then, well, it's not" situation. Surely that is confusing to implementors. Should Actiony things always be actions? * TODO: The verdict on press/release versus just click for buttons is still out.
Implementations in the Wild
* Write me
Related Bugs/ATK 3 Changes
* Write me
AtkComponent
Description from the Documentation
[[7]] should be implemented by most if not all UI elements with an actual on-screen presence, i.e. components which can be said to have a screen-coordinate bounding box. Virtually all widgets will need to have [[8]] implementations provided for their corresponding AtkObject class. In short, only UI elements which are *not* GUI elements will omit this ATK interface.
A possible exception might be textual information with a transparent background, in which case text glyph bounding box information is provided by [[9]].
How Assistive Technologies Use This Interface
* Write me
Do's and Don'ts
* Write me
Implementations in the Wild
* Write me
Related Bugs/ATK 3 Changes
* Write me
AtkDocument
Description from the Documentation
The [[10]] interface should be supported by any object whose content is a representation or view of a document. The [[11]] interface should appear on the toplevel container for the document content; however [[12]] instances may be nested (i.e. an [[13]] may be a descendant of another [[14]]) in those cases where one document contains "embedded content" which can reasonably be considered a document in its own right.
How Assistive Technologies Use This Interface
* Write me
Do's and Don'ts
* Write me
Implementations in the Wild
* Write me
Related Bugs/ATK 3 Changes
* Write me
AtkHypertext and AtkHyperlinkImpl
Description from the Documentation
[[15]] is an interface used for objects which implement linking between multiple resource or content locations, or multiple 'markers' within a single document. A Hypertext instance is associated with one or more Hyperlinks, which are associated with particular offsets within the Hypertext's included content. While this interface is derived from Text, there is no requirement that Hypertext instances have textual content; they may implement Image as well, and Hyperlinks need not have non-zero text offsets.
[[16]] allows AtkObjects to refer to their associated AtkHyperlink instance, if one exists. [[17]] differs from AtkHyperlink in that [[18]] is an interface, whereas AtkHyperlink is a object type. The [[19]] interface allows a client to query an AtkObject for the availability of an associated AtkHyperlink instance, and obtain that instance. It is thus particularly useful in cases where embedded content or inline content within a text object is present, since the embedding text object implements [[20]] and the inline/embedded objects are exposed as children which implement [[21]], in addition to their being obtainable via [[22]]:getLink followed by AtkHyperlink:getObject.
How Assistive Technologies Use These Interfaces
* Write me
Do's and Don'ts
* Write me
Implementations in the Wild
* Write me
Matthias: I have used the hyperlink classes in the accessible implementation for GtkLinkButton, and I'd love to know if my implementation is using these classes as intended.
Related Bugs/ATK 3 Changes
* Write me
AtkImage
Description from the Documentation
[[23]] should be implemented by AtkObject subtypes on behalf of components which display image/pixmap information onscreen, and which provide information (other than just widget borders, etc.) via that image content. For instance, icons, buttons with icons, toolbar elements, and image viewing panes typically should implement [[24]].
[[25]] primarily provides two types of information: coordinate information (useful for screen review mode of screenreaders, and for use by onscreen magnifiers), and descriptive information. The descriptive information is provided for alternative, text-only presentation of the most significant information present in the image.
How Assistive Technologies Use This Interface
* Write me
Do's and Don'ts
* Write me
Implementations in the Wild
* Write me
Related Bugs/ATK 3 Changes
* Write me
AtkSelection
Description from the Documentation
[[26]] should be implemented by UI components with children which are exposed by atk_object_ref_child and atk_object_get_n_children, if the use of the parent UI component ordinarily involves selection of one or more of the objects corresponding to those AtkObject children - for example, selectable lists.
Note that other types of "selection" (for instance text selection) are accomplished a other ATK interfaces - [[27]] is limited to the selection/deselection of children.
How Assistive Technologies Use This Interface
* Write me
Do's and Don'ts
* Write me
Implementations in the Wild
* Write me
Related Bugs/ATK 3 Changes
* Write me
AtkTable
Description from the Documentation
[[28]] should be implemented by components which present elements ordered via rows and columns. It may also be used to present tree-structured information if the nodes of the trees can be said to contain multiple "columns". Individual elements of an [[29]] are typically referred to as "cells", and these cells are exposed by [[30]] as child AtkObjects of the [[31]]. Both row/column and child-index-based access to these children is provided.
Children of [[32]] are frequently "lightweight" objects, that is, they may not have backing widgets in the host UI toolkit. They are therefore often transient.
Since tables are often very complex, [[33]] includes provision for offering simplified summary information, as well as row and column headers and captions. Headers and captions are AtkObjects which may implement other interfaces ([[34]], [[35]], etc.) as appropriate. [[36]] summaries may themselves be (simplified) [[37]], etc.
How Assistive Technologies Use This Interface
* Write me
Do's and Don'ts
* Write me
Implementations in the Wild
* Write me
Related Bugs/ATK 3 Changes
* Write me
AtkText
Description from the Documentation
[[38]] should be implemented by AtkObjects on behalf of widgets that have text content which is either attributed or otherwise non-trivial. AtkObjects whose text content is simple, unattributed, and very brief may expose that content via atk_object_get_name instead; however if the text is editable, multi-line, typically longer than three or four words, attributed, selectable, or if the object already uses the 'name' ATK property for other information, the [[39]] interface should be used to expose the text content. In the case of editable text content, AtkEditableText (a subtype of the [[40]] interface) should be implemented instead.
[[41]] provides not only traversal facilities and change notification for text content, but also caret tracking and glyph bounding box calculations. Note that the text strings are exposed as UTF-8, and are therefore potentially multi-byte, and caret-to-byte offset mapping makes no assumptions about the character length; also bounding box glyph-to-offset mapping may be complex for languages which use ligatures.
[[42]] should be implemented by UI components which contain text which the user can edit, via the AtkObject corresponding to that component (see AtkObject).
[[43]] is a subclass of [[44]], and as such, an object which implements [[45]] is by definition an [[46]] implementor as well.
How Assistive Technologies Use These Interface
* Write me
Do's and Don'ts
As a general rule, only implement [[47]] for widgets which:
* Are text the user can interact with by doing things such as: arrowing amongst characters, selecting, copying, etc., OR * Present a substantial message and/or have significant, important-to-convey formatting attributes
Thus you DO want to implement [[48]] for:
* Documents and any other place the text contents can be changed by the user. * Labels serving as static text (e.g. in a message box).
You do NOT want to implement [[49]] for:
* The displayed text/label of buttons (instead set the AtkObject's name to reflect the text) * The displayed/functional value of widgets implementing AtkValue (instead set the AtkObject's description to reflect the text)
Implementations in the Wild
* Write me
Related Bugs/ATK 3 Changes
* Write me
AtkValue
Description from the Documentation
[[50]] should be implemented for components which either display a value from a bounded range, or which allow the user to specify a value from a bounded range, or both. For instance, most sliders and range controls, as well as dials, should have AtkObject representations which implement [[51]] on the component's behalf. [[52]] may be read-only, in which case attempts to alter the value return FALSE to indicate failure.
How Assistive Technologies Use This Interface
* Write me
Do's and Don'ts
* Write me
Implementations in the Wild
* Write me
Related Bugs/ATK 3 Changes
* Write me
Relations
Add the AtkRelation types here
Widgets
Two main properties of widgets are Name and Description. The name reflects the primary text for the widget: The text of a label, the text on a button. The description gives additional information: A button labeled "OK" could have the description "Accepts the dialog". FIXME more sensible example?
Label
Structure of Accessibles and their roles.
States:
Events:
Interfaces:
Button
Structure of Accessibles and their roles.
States:
Events:
Interfaces:
Line Edit
Structure of Accessibles and their roles.
States:
Events:
Interfaces:
Table
Structure of Accessibles and their roles.
States:
Events:
Interfaces:
Tree
Structure of Accessibles and their roles.
States:
Events:
Interfaces:
Menu
This is the menu bar of an application - File, Edit etc.
* menu bar * menu* * menu* can contain more menu and menu item * menu item*
There is one menu bar as root element, it has any number of menu as children. menu can have menu and menu item as children. menu item does not have children.
List
* list * list item*
A list has only one column. It contains items.
States: STATE_MANAGES_DESCENDANTS
Events: FIXME: what do we need? active descendant and more black magic
Interfaces: Table
Table
current state in gtk: it would be difficult to provide row objects
* table * table column header * table cell sometimes gtk has image+text in one cell. it represents that as two child objects of type table cell
Web: firefox usually has rows, but sometimes it can happen that rows are not present (like html role presentation or css hidden)
* table
* table row the first row only contains headers
* table row header once for the top-left header
* table column header* as many as columns
* table row*
* table row header[0-1] for the left header
* table cell* as many as columns, can be less if cell-span > 1
should headers be mandatory? should it be table header row for the first row?
IA2: all cells are children of the table object. there are no row objects. like gtk.
One big concern was notifications about selection changes. It would be great to get notified for things such as row selected. There are two ways to tackle this:
in the first approach (gtk) we could define a signal: rows-selected() and rows-deselected or somesuch
in the second approach with rows, the row object could be sent as selected. this has the downside that there is no way to do the same for columns. it is less flexible.
IA2 has functions to get selected rows/columns
Trees
The reason for the variety of trees that are possible is mostly that ARIA has very flexible tree definitions. The web implementators will simply expose that.
Tree has exactly one column. For trees with more than one column the tree table has to be used.
Tree items can contain a grouping element. In the grouping element it can have other items.
Tree 1: define hierarchy through relations and group positions
* tree * tree item with relations and group positions that define hierarchy * tree item * ...
This tree works with add/remove tree items when they get expanded/collapsed.
Tree 2: real hierarchy
The items are arranged as children.
* tree
* tree item* with parent child relations to describe hierarchy
* tree item*
* tree
* tree item group
* tree item* with parent child relations to describe hierarchy
* tree item group
* tree item*
No need for add/remove for expanding/collapsing of sub items.
Tree 3: Tree Table
Tree tables can not be hierarchical. tree table can have more than one column
* tree table * tree table cell*
* tree table
* tree table row*
* tree table cell*
Scroll Bars
Structure of Accessibles and their roles.
States:
Events:
Interfaces:
Combo Box
* ATSPI_ROLE_COMBO_BOX is the root element * ATSPI_ROLE_TABLE see table. Usually this is a flat list of items. * ATSPI_ROLE_TEXT [optional] is present when the combo box is editable.
The Accessible Name of the combo box accessible is the current text that is displayed. This text can be typed by the user or one of the selected items.
States: Focused, Editable
Events: Focus
Interfaces: None required
The name of the ATSPI_ROLE_COMBO_BOX should always reflect the current text. FIXME: what should combo box send when the current item/text changed?
Foo Bar Template
Structure of Accessibles and their roles.
States:
Events:
Interfaces:
Stuff we Mustn't Forget
(But are not sure where all to put it yet.)
* "Hint text" - Gtk+ has it as an AtkObject attribute ('placeholder-text').
* Window management stuff - what happens when a window gains focus etc
* Registry - give an overview what it is, why and how clients and servers register to it.]\
* Relations
* make sure to mention them with the widgets that most likely need them (labelled-by for line edit)
* document what they are in general