Accessibility

Roles define the taxonomy and semantics of a UI control to any assistive technology application; for instance, a button will have a role of GTK_ACCESSIBLE_ROLE_BUTTON; an entry will have a role of GTK_ACCESSIBLE_ROLE_TEXTBOX; a toggle button will have a role of GTK_ACCESSIBLE_ROLE_CHECKBOX; etc.

Each role is part of the widget’s instance, and cannot be changed over time or as the result of a user action. Roles allows assistive technology applications to identify a UI control and decide how to present it to a user; if a part of the application’s UI changes role, the control needs to be removed and replaced with another one with the appropriate role.

Attributes provide specific information about an accessible UI control, and describe it for the assistive technology applications. GTK divides the accessible attributes into three categories:

Each attribute accepts a value of a specific type.

Unlike roles, attributes may change over time, or in response to user action; for instance:

See the WAI-ARIA list of attributes for additional information.

The following code:

gtk_widget_class_set_accessible_role (widget_class, GTK_ACCESSIBLE_ROLE_BUTTON);

is a promise that the widget being created will provide the same keyboard interactions expected for a button. An accessible role of a button will not turn automatically any widget into a GtkButton; but if your widget behaves like a button, using the GTK_ACCESSIBLE_ROLE_BUTTON will allow any assistive technology to handle it like they would a GtkButton.

Accessible attributes can be used to override the content of a UI element, for instance:

gtk_label_set_text (GTK_LABEL (label), "Some text");
gtk_accessible_update_property (GTK_ACCESSIBLE (label),
                GTK_ACCESSIBLE_PROPERTY_LABEL,
                "Assistive technologies users will perceive "
                "this text, not the contents of the label",
                -1);

In the example above, the “label” property will override the contents of the label widget.

The attributes can also enhance the UI:

gtk_button_set_label (GTK_BUTTON (button), "Download");
gtk_box_append (GTK_BOX (button), button);

gtk_label_set_text (GTK_LABEL (label), "Final report.pdf");
gtk_box_append (GTK_BOX (box), label);

gtk_accessible_update_relation (GTK_ACCESSIBLE (button),
                GTK_ACCESSIBLE_RELATION_LABELLED_BY,
                g_list_append (NULL, label),
                -1);

In the example above, an assistive technology will read the button’s accessible label as “Download Final report.pdf”.

The power of hiding and enhancing can be a double-edged sword, as it can lead to inadvertently overriding the accessible semantics of existing widgets.

A button is a widget that enables users to trigger an action. While it is recommended you use GtkButton for anything that looks and behaves like a button, it is possible to apply a button behavior to UI elements like images by using a GtkGestureClick gesture. When doing so, you should:

For custom entries, it is highly recommended that you implement the GtkEditable interface by using a GtkText widget as delegate. If you do this, GTK will make your widgets text editing functionality accessible in the same way as a GtkSpinButton or GtkSearchEntry.

If you make a tab-based interface, you should consider using GtkStack as the core, and just make a custom tab widget to control the active stack page. When doing so, the following extra steps will ensure that your tabs are accessible in the same way as GtkStackSwitcher or GtkNotebook:

To allow changing the active tab via accessible technologies, you can export actions. Since the accessibility interfaces only support actions without parameters, you can either provide previous-tab and next-tab actions on the tab container that let users step through the tabs one-by-one, or add a activate-tab action on each tab.

A value control (ie a widget that controls a one-dimensional quantity that can be represented by a GtkAdjustment) can be represented to accessible technologies by setting the GTK_ACCESSIBLE_PROPERTY_VALUE_MIN, GTK_ACCESSIBLE_PROPERTY_VALUE_MAX, and GTK_ACCESSIBLE_PROPERTY_VALUE_NOW properties.

To allow changing the value via accessible technologies, you can export actions. Since the accessibility interfaces only support actions without parameters, you should provide actions such as increase-value and decrease-value.