Recommended ATK Implementations for Common UI Components

This section specifies the accessibility information and behavior which should be exposed for common UI components for use by assistive technologies on the Gnome desktop.

All components should implement AtkComponent, AtkObject, AtkStateSet, and AtkRelationSet. Each section below identifies additional ATK properties, behaviors, events, sources of accessible information, interfaces and methods, and relations which should be implemented for common components in menus and dialogs as well as in documents.

All components can potentially set the following general ATK states: DEFUNCT, FOCUSED, SHOWING, VISIBLE, FOCUSABLE, SENSITIVE, and ENABLED.

Unless otherwise stated, refer to the GNOME Human Interface Guidelines under the Keyboard Interaction section for information about the standard keys for navigation (access keys indicated by underlined letters, shortcut keys, and ordered navigation) and interaction with the components.

General Notes:

1. An alternative to using the FLOWS_FROM and FLOWS_TO relation to identify a taborder different than document order (e.g. the use of tabindex attributes for interactive HTML controls and links) is to use object attributes. <Need to discuss this.>

<Add list of links (list of components) like a table of contents to go to each section>

Checkbox or Toggle Button

A checkbox, which can be selected (checked or toggled) to enable or disable one or more features or options from a set, usually contains a small box with adjoining text and can be found in dialog boxes or forms in a document. When selected, the box displays a check mark.

A toggle button looks like a push button, but it shows or changes a state rather than initiates an action. It's two states, set and unset, are indicated with a "pushed in" or "popped out" appearance, respectively.

Source of accessible name: Obtained from the checkbox or toggle button text.

Role: ATK_ROLE_CHECK_BOX or ATK_TOGGLE_BUTTON

Source for description: Tooltip text for the checkbox or toggle button, if it exists.

Possible supported states:

• ATK_STATE_INDETERMINATE if the checkbox is a tri-state checkbox.
• ATK_STATE_CHECKED if the checkbox is checked or the toggle button is set.
• ATK_STATE_EXPANDABLE if the checkbox is for a tree which is expanded.
• ATK_STATE_INVALID if the checkbox is in an invalid state.
• ATK_STATE_ACTIVE if the checkbox is in a list, table, or tree.
• ATK_STATE_ARMED if the user is pressing the Spacebar to check the box or change the toggle button state but has not yet released the Spacebar.

Actions:

• "Check" or "Click" if not selected or pushed in.
• "Uncheck" or "Click" if selected or popped out.
• "Toggle" if a tri-state checkbox.

Source of value: None.

Common relations:

• ATK_RELATION_MEMBER_OF if the checkbox or toggle button is in a group box.
• ATK_RELATION_NODE_CHILD_OF if the checkbox is in a tree.
• ATK_ RELATION_CONTROLLER_FOR if the checkbox or toggle button controls the state, onscreen location, or other attributes of one or more target objects.
• ATK_RELATION_CONTROLLED_BY if the checkbox or toggle button is modified/controlled by user interaction with one or more other objects.
• ATK_RELATION_LABELED_BY if the checkbox is not in a group and not self-describing but there is static text available that describes it.
• ATK_RELATION_FLOWS_FROM and ATK_RELATION_FLOWS_TO if the interactive objects in the tab order right before or after the checkbox are in a different order than the logical, visual tab order for a document (i.e. the previous/next object is not the previous/next sibling in the accessible hierarchy.)

Events:

• "property-change::accessible-name" if the text for the checkbox changes.
• "state-change" if the checkbox is toggled or checked/unchecked.

• "property-change::accessible-description" if the tooltip text for the checkbox changes.

• "focus" when the checkbox receives focus.

Special additional interfaces and methods:

• AtkAction to provide the keybindings and action descriptions (Check, Uncheck, Toggle).

• AtkText to expose text attributes.

• AtkImage if the checkbox has an image instead of text as a label to provide the image description.

Pushbutton

A small, rectangular object used to perform an action when activated. For example, the OK and Cancel buttons on a dialog box are push buttons.

Source of accessible name: Obtained from the button text, unless the button has an image instead of text. Then an alternative accessible name needs to be provided by the author. Example: "OK" is the accessible name for an OK pushbutton.

Role: ATK_ROLE_PUSH_BUTTON (or maybe ATK_ROLE_DEFAULT_BUTTON if the button is the default button for the dialog)

Source for description: Tooltip text for the pushbutton, if it exists.

Possible supported states:

• ATK_STATE_PRESSED if the pushbutton is currently being pressed.
• ATK_STATE_ARMED if the user is pressing the Enter key to press the pushbutton but has not yet released the Enter key.

Actions:

• "Press" or "Click"

Source of value: None.

Common relations:

• ATK_ RELATION_CONTROLLER_FOR if the pushbutton controls the state, onscreen location, or other attributes of one or more target objects.
• ATK_RELATION_CONTROLLED_BY if the pushbutton is modified/controlled by user interaction with one or more other objects.
• ATK_RELATION_FLOWS_FROM and ATK_RELATION_FLOWS_TO if the interactive objects in the tab order right before or after the pushbutton are in a different order than the logical, visual tab order for a document (i.e. the previous/next object is not the previous/next sibling in the accessible hierarchy.)

Events:

• "property-change::accessible-name" if the text for the pushbutton changes.
• "state-change" if the pushbutton is pressed.

• "property-change::accessible-description" if the tooltip text for the pushbutton changes.

• "focus" when the pushbutton receives focus.

Special additional interfaces and methods:

• AtkAction to provide the keybindings and action description (Press).

• AtkImage if the button has an image instead of text as a label to provide the image description.

• AtkText to expose text attributes.

Radio button

Radio buttons are used to select one of several options within a group of objects, of which only one can be on at a time. When you select one button, all the others in the group are automatically deselected. A radio button contains a small circle with text next to it. When selected, the circle has a smaller, filled circle inside it.

Source of accessible name: Obtained from the radio button text, unless the button has an image instead of text. Then an alternative accessible name needs to be provided by the author. Example: "Yes" is the accessible name for a radio button that has the text string "Yes" as its label.

Role: ATK_ROLE_RADIO_BUTTON

Source for description: Tooltip text for the radio button, if it exists.

Possible supported states:

• ATK_STATE_CHECKED if the radio button is checked.
• ATK_STATE_ARMED if the user is pressing the Enter key to check the radio button but has not yet released the Enter key.
• ATK_STATE_ACTIVE if the radio button is in a list, table, or tree that manages descendants.

Actions:

• "Check" if not selected.
• "Uncheck" if selected.

Source of value: None.

Common relations:

• ATK_RELATION_MEMBER_OF if the radio button is in a group box.
• ATK_RELATION_NODE_CHILD_OF if the radio button is in a tree.
• ATK_ RELATION_CONTROLLER_FOR if the radio button controls the state, onscreen location, or other attributes of one or more target objects.
• ATK_RELATION_CONTROLLED_BY if the radio button is modified/controlled by user interaction with one or more other objects.
• ATK_RELATION_LABELED_BY if the radio button is not in a group and not self-describing but there is static text available that describes it.
• ATK_RELATION_FLOWS_FROM and ATK_RELATION_FLOWS_TO if the interactive objects in the tab order right before or after the radio button are in a different order than the logical, visual tab order for a document (i.e. the previous/next object is not the previous/next sibling in the accessible hierarchy.)

Events:

• "property-change::accessible-name" if the text for the radio button changes.
• "state-change" if the radio button is checked/unchecked.

• "property-change::accessible-description" if the tooltip text for the radio button changes.

Special additional interfaces and methods:

• AtkAction to provide the keybindings and action description (Check, Uncheck).

• AtkImage if the button has an image instead of text as a label to provide the image description.

• AtkText to expose text attributes.

Label or Static Text

Static text controls display text in dialog boxes and other windows, and often serve as labels for other controls. A label presents text that provides a short name or description associated with another object, like a text entry field. An accelerator label indicates the keyboard accelerators for its parent, like a menu item.

Source of accessible name: Obtained from the label or static text control.

Role: ATK_ROLE_LABEL, ATK_ROLE_ACCELERATOR_LABEL
<Is ATK_ROLE_ACCELERATOR_LABEL the right way to expose accelerators? Underlined access keys are showing up as the key bindings for menus in accerciser. So how should these accelerator (shortcut) keys be exposed?>

Source for description: None

Possible supported states: None. Note: ATK_STATE_MULTI_LINE and ATK_STATE_SINGLE_LINE should only be used for editable text.

Actions: None

Source of value: None.

Common relations:

• ATK_RELATION_LABEL_FOR if the static text or label provides a short descriptive name for a target object, like a text field, combo box, etc.
• ATK_RELATION_DESCRIPTION_FOR if the static text provides a more verbose description of another object, like a long description for a more complex image, or a prompt for a text field or other control.
• ATK_RELATION_CONTROLLED_BY if the label is modified/controlled by user interaction with one or more other objects.

Events: None

Special additional interfaces and methods:

• AtkText if the static text or label has text attributes and/or can be selected, such as in a Web or office suite document.

• AtkAction if there is an underlined access key in the label object to provide the keybindings. <Is this true?>

Combo box

A combo box has the following components:

• The combo box object which displays the currently selected item and has a drop-down arrow image.
• Optionally, an edit control for entering information.
• A menu which can be displayed when the user selects the drop-down arrow in the combo box, if there is one next to the edit control.
• Menu items in the menu.

Source of accessible name:

• For the combo box parent, the accessible name is the text equivalent of what is being displayed. Could be blank, typed text, or currently selected menu item.
• For the edit control, obtained from the currently selected item if one is selected or what is typed. If no item selected, the accessible name is blank.
• For the drop-down arrow push button and the list box, the accessible name is blank. While focused and the user is typing, the accessible name should not change.
• For the menu itself, the accessible name is blank.
• For the menu items, the accessible name is the text for the menu item.

Roles:

• ATK_ROLE_COMBO_BOX for the parent combo box object

• ATK_ROLE_TEXT or ATK_ROLE_ENTRY for an edit child control. <How are these 2 roles different?>

• ATK_ROLE_MENU for the menu object
• ATK_ROLE_MENUITEM for the menu item objects

Source for description: Tooltip text for the parent combo box object, if it exists. None for all the child objects. <True?>

Possible supported states:

• ATK_STATE_REQUIRED for the parent combo box if a list item must be selected for the combo box.
• ATK_STATE_EDITABLE and ATK_STATE_SINGLE_LINE for the edit child control.
• ATK_STATE_INVALID_ENTRY if the edit child control has invalid user input.
• ATK_STATE_SUPPORTS_AUTOCOMPLETE if the edit control supports automatic selection of a menu item from the menu.

• ATK_STATE_EXPANDABLE for the menu object, ATK_STATE_EXPANDED if the menu is expanded, and ATK_STATE_COLLAPSED if the menu is collapsed. <Or should the state be ATK_STATE_SHOWING if the menu is open? How is this different from a tree?>

• ATK_STATE_SELECTABLE for the menu item objects. ATK_STATE_SELECTED if a menu item is selected.

Actions:

• "Open" for the combo box if the menu is closed. "Close" if menu is open.
• "Select" or "Unselect" for a menu item.
• None for the menu and edit control.

Source of value: None.

Common relations:

• ATK_RELATION_MEMBER_OF if the combo box is in a group box.
• ATK_ RELATION_CONTROLLER_FOR if the combo box controls the state, onscreen location, or other attributes of one or more target objects.
• ATK_RELATION_CONTROLLED_BY if the combo box is modified/controlled by user interaction with one or more other objects.
• ATK_RELATION_LABELED_BY if the combo box has a static text label that describes it.
• ATK_RELATION_FLOWS_FROM and ATK_RELATION_FLOWS_TO if the interactive objects in the tab order right before or after the combo box are in a different order than the logical, visual tab order for a document (i.e. the previous/next object is not the previous/next sibling in the accessible hierarchy.)
• ATK_RELATIon_DESCRIBED_BY if there is another object which provides a description of the combo box.

Events:

• "property-change::accessible-name" if the text label for the combo box changes, the currently selected item in the edit or static text control changes, or the list item text changes.
• "state-change" if the text in the edit control becomes invalid, if the drop-down arrow is pressed or released, if the drop-down list is expanded or collapsed, or if a list item becomes selected or unselected.

• "property-change::accessible-description" if the tooltip text for the combo box changes.

• "selection-changed" for the list box object when a different list item is selected.
• "focus-event" when the menu receives keyboard control or the selection changes.

Special additional interfaces and methods:

• AtkAction to provide the key bindings for the combo box object and the action descriptions (Open and Close, Select and Unselect ).

• AtkSelection for the menu.

• AtkText for the menu items and edit control.

• AtkEditableText to provide clipboard functions for the edit control.

List box

<Need to try to create a list box in Glade to to do this section.>

A list box displays a list from which a user can select one or more items. A list box may have a vertical scroll bar, a horizontal control bar, or both.

Source of accessible name:

• For the list box, the accessible name is obtained from the currently selected item if one is selected. If no item selected, the accessible name is blank.
• For the list box items, the accessible name is the text for the list item.

Roles:

• ATK_ROLE_LIST for the list box object
• ATK_ROLE_LISTITEM for the list item objects

Source for description: Tooltip text for the list box, if it exists. None for the list items. <True?>

Possible supported states:

• ATK_STATE_REQUIRED for the list box if a list item must be selected.
• ATK_STATE_MANAGES_DESCENDANTS for the list box object.
• ATK_STATE_MULTISELECTABLE for the list box object if more than one list item can be selected at the same time.
• ATK_STATE_ACTIVE and ATK_STATE_SELECTABLE for the list item objects. ATK_STATE_SELECTED if a list item is selected.

Actions:

• "Select" or "Unselect" for a list item.
• None for the list box, and edit or static text control.

Source of value: None.

Common relations:

• ATK_RELATION_MEMBER_OF if the list box is in a group box.
• ATK_ RELATION_CONTROLLER_FOR if the list box controls the state, onscreen location, or other attributes of one or more target objects.
• ATK_RELATION_CONTROLLED_BY if the list box is modified/controlled by user interaction with one or more other objects.
• ATK_RELATION_LABELED_BY if the list box has a static text label that describes it.
• ATK_RELATION_FLOWS_FROM and ATK_RELATION_FLOWS_TO if the interactive objects in the tab order right before or after the list box are in a different order than the logical, visual tab order for a document (i.e. the previous/next object is not the previous/next sibling in the accessible hierarchy.)

Events:

• "property-change::accessible-name" if the currently selected item in the list box changes, or the list item text changes.
• "state-change" if a list item becomes selected or unselected.

• "property-change::accessible-description" if the tooltip text for the list box changes.

• "active-descendant-changed" and "selection-changed" for the list box object when a different list item is selected.
• "focus-event" when the list box receives keyboard control or the selection changes.
• "children-changed" if the number or order of the list items in the list box changes.

Special additional interfaces and methods:

• AtkAction to provide the key bindings for the list box object and the action descriptions (Select and Unselect for the list items).

• AtkSelection for the list box.

• AtkText for the list items.