![]() |
![]() |
![]() |
![]() |
The GtkAccessible interface provides the accessibility information about an application’s user interface elements. Assistive technology (AT) applications, like Orca, convey this information to users with disabilities, or reduced abilities, to help them use the application.
Standard GTK controls implement the GtkAccessible interface and are thus accessible to ATs by default. This means that if you use GTK controls such as GtkButton, GtkEntry, or GtkListView, you only need to supply application-specific details when the defaults values are incomplete. You can do this by setting the appropriate properties in your GtkBuilder template and UI definition files, or by setting the properties defined by the GtkAccessible interface.
If you are implementing your own GtkWidget derived type, you will need to set the GtkAccessible properties yourself, and provide an implementation of the GtkAccessible virtual functions.
The fundamental concepts of an accessible widget are roles and attributes; each GTK control has a role, while its functionality is described by a set of attributes.
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.
Each role name is part of the GtkAccessibleRole enumeration.
Role name | Description | Related GTK widget |
---|---|---|
BUTTON
|
A control that performs an action when pressed | GtkButton, GtkLinkButton, GtkExpander |
CHECKBOX
|
A control that has three possible value:
true , false , or
undefined
|
GtkCheckButton |
COMBOBOX
|
A control that can be expanded to show a list of possible values to select | GtkComboBox |
COLUMN_HEADER
|
A header in a columned list | GtkColumnView |
DIALOG
|
A dialog that prompts the user to enter information or require a response | GtkDialog and subclasses |
GRID
|
A grid of items | GtkFlowBox, GtkGridView |
GRID_CELL
|
An item in a grid | GtkFlowBoxChild, GtkGridView, GtkColumnView |
IMG
|
An image | GtkImage, GtkPicture |
LABEL
|
A visible name or caption for a user interface component | GtkLabel |
LIST
|
A list of items | GtkListBox |
LIST_ITEM
|
An item in a list | GtkListBoxRow |
METER
|
Represents a value within a known range | GtkLevelBar |
PROGRESS_BAR
|
An element that display progress | GtkProgressBar |
RADIO
|
A checkable input in a group of radio roles | GtkCheckButton |
ROW
|
A row in a columned list | GtkColumnView |
SCROLLBAR
|
A graphical object controlling the scrolling of content | GtkScrollbar |
SEARCH_BOX
|
A text box for entering search criteria | GtkSearchEntry |
SEPARATOR
|
A divider that separates sections of content or groups of items | GtkSeparator |
SPIN_BUTTON
|
A range control that allows seelcting among discrete choices | GtkSpinButton |
SWITCH
|
A control that represents on/off values | GtkSwitch |
TAB
|
A tab in a list of tabs for switching pages | GtkStackSwitcher, GtkNotebook |
TAB_LIST
|
A list of tabs for switching pages | GtkStackSwitcher, GtkNotebook |
TAB_PANEL
|
A page in a notebook or stack | GtkStack |
TEXT_BOX
|
A type of input that allows free-form text as its value. | GtkEntry, GtkPasswordEntry, GtkTextView |
TREE_GRID
|
A treeview-like columned list | GtkColumnView |
WINDOW
|
An application window | GtkWindow |
...
|
… |
See the WAI-ARIA list of roles for additional information.
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:
properties, described by the values of the GtkAccessibleProperty enumeration
relations, described by the values of the GtkAccessibleRelation enumeration
states, described by the values of the GtkAccessibleState enumeration
Each attribute accepts a value of a specific type.
Unlike roles, attributes may change over time, or in response to user action; for instance:
a toggle button will change its
GTK_ACCESSIBLE_STATE_CHECKED
state every time it is
toggled, either by the user or programmatically
setting the mnemonic widget on a GtkLabel will update the
GTK_ACCESSIBLE_RELATION_LABELLED_BY
relation on the widget
with a reference to the label
changing the GtkAdjustment instance on a GtkScrollbar will
change the GTK_ACCESSIBLE_PROPERTY_VALUE_MAX
,
GTK_ACCESSIBLE_PROPERTY_VALUE_MIN
, and
GTK_ACCESSIBLE_PROPERTY_VALUE_NOW
properties with the
upper, lower, and value properties of the GtkAdjustment
See the WAI-ARIA list of attributes for additional information.
Each state name is part of the GtkAccessibleProperty enumeration.
State name | ARIA attribute | Value type | Notes |
---|---|---|---|
GTK_ACCESSIBLE_STATE_BUSY
|
“aria-busy” | boolean | |
GTK_ACCESSIBLE_STATE_CHECKED
|
“aria-checked” | GtkAccessibleTristate | Indicates the current state of a GtkCheckButton |
GTK_ACCESSIBLE_STATE_DISABLED
|
“aria-disabled” | boolean | Corresponds to the “sensitive” property on GtkWidget |
GTK_ACCESSIBLE_STATE_EXPANDED
|
“aria-expanded” | boolean or undefined | Corresponds to the “expanded” property on GtkExpander |
GTK_ACCESSIBLE_STATE_HIDDEN
|
“aria-hidden” | boolean | Corresponds to the “visible” property on GtkWidget |
GTK_ACCESSIBLE_STATE_INVALID
|
“aria-invalid” | GtkAccessibleInvalidState | Set when a widget is showing an error |
GTK_ACCESSIBLE_STATE_PRESSED
|
“aria-pressed” | GtkAccessibleTristate | Indicates the current state of a GtkToggleButton |
GTK_ACCESSIBLE_STATE_SELECTED
|
“aria-selected” | boolean or undefined | Set when a widget is selected |
Each state name is part of the GtkAccessibleRelation enumeration.
Each state name is part of the GtkAccessibleState enumeration.
Even if standard UI controls provided by GTK have accessibility information out of the box, there are some additional properties and considerations for application developers. For instance, if your application presents the user with a form to fill out, you should ensure that:
the container of the form has a
GTK_ACCESSIBLE_ROLE_FORM
role
each text entry widget in the form has the
GTK_ACCESSIBLE_RELATION_LABELLED_BY
relation pointing to the label widget that describes it
Another example: if you create a tool bar containing buttons with only icons, you should ensure that:
the container has a
GTK_ACCESSIBLE_ROLE_TOOLBAR
role
each button has a
GTK_ACCESSIBLE_PROPERTY_LABEL
property set
with the user readable and localised action performed when
pressed; for instance “Copy”,
“Paste”, “Add layer”, or
“Remove”
GTK will try to fill in some information by using ancillary UI
control property, for instance the accessible label will be taken
from the label or placeholder text used by the UI control, or from
its tooltip, if the
GTK_ACCESSIBLE_PROPERTY_LABEL
property or the
GTK_ACCESSIBLE_RELATION_LABELLED_BY
relation
are unset. Nevertheless, it is good practice and project hygiene
to explicitly specify the accessible properties, just like it’s
good practice to specify tooltips and style classes.
Application developers using GTK
should ensure that their UI
controls are accessible as part of the development process. When
using GtkBuilder
templates and UI definition
files, GTK provides a validation tool that verifies that each UI
element has a valid role and properties; this tool can be used as
part of the application’s test suite to avoid regressions.
Each UI control implements the GtkAccessible interface to allow widget and application developers to specify the roles, state, and relations between UI controls. This API is purely descriptive.
Each GtkAccessible
implementation must provide
a GtkATContext instance, which acts as a proxy to the specific
platform’s accessibility API:
AT-SPI on Linux/BSD
NSAccessibility on macOS
Active Accessibility on Windows
Additionally, an ad hoc accessibility backend is available for the GTK testsuite, to ensure reproducibility of issues in the CI pipeline.