AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity
83d8ae2f30
gtk2/docs/reference/gtk/section-accessibility.md

291 lines
14 KiB
Markdown
Raw Normal View History

Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
# GTK Accessibility {#gtk-accessibility}
## The standard accessibility interface
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.
docs: Document a11y attributes
2020-07-27 12:50:01 +00:00
## Accessible roles and attributes
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
docs: Document a11y attributes
2020-07-27 12:50:01 +00:00
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*.
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
### Roles
Roles define the taxonomy and semantics of a UI control to any assistive
technology application; for instance, a button will have a role of
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
`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.
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
Each role is part of the widget's instance, and **cannot** be changed over
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
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.
#### List of accessible roles
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
Each role name is part of the #GtkAccessibleRole enumeration.
docs: Document a11y attributes
2020-07-27 12:50:01 +00:00
| Role name | Description | Related GTK widget |
|-----------|-------------|--------------------|
a11y: Set an accessible role for GtkExpander Use the button accessible role for GtkExpander and set attributes as appropriate. Update the documentation and add a test.
2020-07-30 01:55:34 +00:00
| `BUTTON` | A control that performs an action when pressed | #GtkButton, #GtkLinkButton, #GtkExpander |
docs: Document a11y attributes
2020-07-27 12:50:01 +00:00
| `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 |
columnview: Set accessible roles Use the TREE_GRID, ROW, COLUMN_HEADER and GRID_CELL roles for the various widgets involved in a GtkColumnView. To enable this, we subclass GtkListView for the internal list in the column view.
2020-10-15 04:09:06 +00:00
| `COLUMN_HEADER` | A header in a columned list | #GtkColumnView |
docs: Flesh out the role table in the a11y intro Add cross-references for all the widgets currently implementing non-default roles.
2020-07-27 15:10:58 +00:00
| `DIALOG` | A dialog that prompts the user to enter information or require a response | #GtkDialog and subclasses |
columnview: Set accessible roles Use the TREE_GRID, ROW, COLUMN_HEADER and GRID_CELL roles for the various widgets involved in a GtkColumnView. To enable this, we subclass GtkListView for the internal list in the column view.
2020-10-15 04:09:06 +00:00
| `GRID` | A grid of items | #GtkFlowBox, #GtkGridView |
| `GRID_CELL` | An item in a grid | #GtkFlowBoxChild, #GtkGridView, #GtkColumnView |
a11y: Set accessible roles for GtkImage and GtkPicture Use the img accessible role for these. Also update the documentation and add tests.
2020-07-28 19:44:12 +00:00
| `IMG` | An image | #GtkImage, #GtkPicture |
a11y: Set an accessible role for GtkLevelBar Use the 'meter' role for GtkLevelBar, and set the appropriate properties. Update the docs and add a test.
2020-07-30 02:10:56 +00:00
| `LABEL` | A visible name or caption for a user interface component | #GtkLabel |
listbox: Set accessible roles Use the LIST and LIST_ITEM roles for GtkListBox and GtkListBoxRow.
2020-10-15 02:16:00 +00:00
| `LIST` | A list of items | #GtkListBox |
| `LIST_ITEM` | An item in a list | #GtkListBoxRow |
a11y: Set an accessible role for GtkLevelBar Use the 'meter' role for GtkLevelBar, and set the appropriate properties. Update the docs and add a test.
2020-07-30 02:10:56 +00:00
| `METER` | Represents a value within a known range | #GtkLevelBar |
docs: Flesh out the role table in the a11y intro Add cross-references for all the widgets currently implementing non-default roles.
2020-07-27 15:10:58 +00:00
| `PROGRESS_BAR` | An element that display progress | #GtkProgressBar |
Drop GtkRadioButton
2020-08-31 02:25:36 +00:00
| `RADIO` | A checkable input in a group of radio roles | #GtkCheckButton |
columnview: Set accessible roles Use the TREE_GRID, ROW, COLUMN_HEADER and GRID_CELL roles for the various widgets involved in a GtkColumnView. To enable this, we subclass GtkListView for the internal list in the column view.
2020-10-15 04:09:06 +00:00
| `ROW` | A row in a columned list | #GtkColumnView |
*: Fix spelling mistakes found by codespell
2020-08-21 12:41:13 +00:00
| `SCROLLBAR` | A graphical object controlling the scrolling of content | #GtkScrollbar |
a11y: Set an accessible role for GtkSearchEntry Use the searchbox accessible role for GtkSearchEntry. And set properties as appropriate. Update the documentation and add a test.
2020-07-28 22:15:01 +00:00
| `SEARCH_BOX` | A text box for entering search criteria | #GtkSearchEntry |
docs: Flesh out the role table in the a11y intro Add cross-references for all the widgets currently implementing non-default roles.
2020-07-27 15:10:58 +00:00
| `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 |
Document accessible roles for stacks and notebooks This was forgotten when I implemented the Tabs pattern.
2020-10-15 02:27:09 +00:00
| `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 |
a11y: Set an accessible role for GtkTextView Use the text-box accessible role for GtkTextView and set properties as appropriate. Update the documentation and add a test.
2020-07-29 22:18:04 +00:00
| `TEXT_BOX` | A type of input that allows free-form text as its value. | #GtkEntry, #GtkPasswordEntry, #GtkTextView |
columnview: Set accessible roles Use the TREE_GRID, ROW, COLUMN_HEADER and GRID_CELL roles for the various widgets involved in a GtkColumnView. To enable this, we subclass GtkListView for the internal list in the column view.
2020-10-15 04:09:06 +00:00
| `TREE_GRID` | A treeview-like columned list | #GtkColumnView |
a11y: Set an accessible role for GtkWindow Use the window accessible role for GtkWindow, and set the modal accessible property.
2020-07-27 22:25:37 +00:00
| `WINDOW` | An application window | #GtkWindow |
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
| `...` | … |
See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list
of roles for additional information.
docs: Document a11y attributes
2020-07-27 12:50:01 +00:00
### Attributes
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
docs: Document a11y attributes
2020-07-27 12:50:01 +00:00
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:
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
docs: Document a11y attributes
2020-07-27 12:50:01 +00:00
- *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](https://www.w3.org/WAI/PF/aria/appendices#quickref) list
of attributes for additional information.
#### List of accessible properties
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 #GtkWidget:sensitive property on #GtkWidget |
| %GTK_ACCESSIBLE_STATE_EXPANDED | “aria-expanded” | boolean or undefined | Corresponds to the #GtkExpander:expanded property on #GtkExpander |
| %GTK_ACCESSIBLE_STATE_HIDDEN | “aria-hidden” | boolean | Corresponds to the #GtkWidget: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 |
#### List of accessible relations
Each state name is part of the #GtkAccessibleRelation enumeration.
| State name | ARIA attribute | Value type |
|------------|----------------|------------|
| %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE | “aria-autocomplete” | #GtkAccessibleAutocomplete |
| %GTK_ACCESSIBLE_PROPERTY_DESCRIPTION | “aria-description” | translatable string |
| %GTK_ACCESSIBLE_PROPERTY_HAS_POPUP | “aria-haspopup” | boolean |
| %GTK_ACCESSIBLE_PROPERTY_KEY_SHORTCUTS | “aria-keyshortcuts” | string |
| %GTK_ACCESSIBLE_PROPERTY_LABEL | “aria-label” | translatable string |
| %GTK_ACCESSIBLE_PROPERTY_LEVEL | “aria-level” | integer |
| %GTK_ACCESSIBLE_PROPERTY_MODAL | “aria-modal” | boolean |
| %GTK_ACCESSIBLE_PROPERTY_MULTI_LINE | “aria-multiline” | boolean |
| %GTK_ACCESSIBLE_PROPERTY_MULTI_SELECTABLE | “aria-multiselectable” | boolean |
| %GTK_ACCESSIBLE_PROPERTY_ORIENTATION | “aria-orientation” | #GtkOrientation |
| %GTK_ACCESSIBLE_PROPERTY_PLACEHOLDER | “aria-placeholder” | translatable string |
| %GTK_ACCESSIBLE_PROPERTY_READ_ONLY | “aria-readonly” | boolean |
| %GTK_ACCESSIBLE_PROPERTY_REQUIRED | “aria-required” | boolean |
| %GTK_ACCESSIBLE_PROPERTY_ROLE_DESCRIPTION | “aria-roledescription” | translatable string |
| %GTK_ACCESSIBLE_PROPERTY_SORT | “aria-sort” | #GtkAccessibleSort |
| %GTK_ACCESSIBLE_PROPERTY_VALUE_MAX | “aria-valuemax” | double |
| %GTK_ACCESSIBLE_PROPERTY_VALUE_MIN | “aria-valuemin” | double |
| %GTK_ACCESSIBLE_PROPERTY_VALUE_NOW | “aria-valuenow” | double |
| %GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT | “aria-valuetext” | translatable string |
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
#### List of accessible states
Each state name is part of the #GtkAccessibleState enumeration.
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
docs: Document a11y attributes
2020-07-27 12:50:01 +00:00
| State name | ARIA attribute | Value type |
|------------|----------------|------------|
| %GTK_ACCESSIBLE_RELATION_ACTIVE_DESCENDANT | “aria-activedescendant” | #GtkAccessible |
| %GTK_ACCESSIBLE_RELATION_COL_COUNT | “aria-colcount” | integer |
| %GTK_ACCESSIBLE_RELATION_COL_INDEX | “aria-colindex” | integer |
| %GTK_ACCESSIBLE_RELATION_COL_INDEX_TEXT | “aria-colindextext” | translatable string |
| %GTK_ACCESSIBLE_RELATION_COL_SPAN | “aria-colspan” | integer |
| %GTK_ACCESSIBLE_RELATION_CONTROLS | “aria-controls” | a #GList of #GtkAccessible |
| %GTK_ACCESSIBLE_RELATION_DESCRIBED_BY | “aria-describedby” | a #GList of #GtkAccessible |
| %GTK_ACCESSIBLE_RELATION_DETAILS | “aria-details” | a #GList of #GtkAccessible |
| %GTK_ACCESSIBLE_RELATION_ERROR_MESSAGE | “aria-errormessage” | #GtkAccessible |
| %GTK_ACCESSIBLE_RELATION_FLOW_TO | “aria-flowto” | a #GList of #GtkAccessible |
| %GTK_ACCESSIBLE_RELATION_LABELLED_BY | “aria-labelledby” | a #GList of #GtkAccessible |
| %GTK_ACCESSIBLE_RELATION_OWNS | “aria-owns” | a #GList of #GtkAccessible |
| %GTK_ACCESSIBLE_RELATION_POS_IN_SET | “aria-posinset” | integer |
| %GTK_ACCESSIBLE_RELATION_ROW_COUNT | “aria-rowcount” | integer |
| %GTK_ACCESSIBLE_RELATION_ROW_INDEX | “aria-rowindex” | integer |
| %GTK_ACCESSIBLE_RELATION_ROW_INDEX_TEXT | “aria-rowindextext” | translatable string |
| %GTK_ACCESSIBLE_RELATION_ROW_SPAN | “aria-rowspan” | integer |
| %GTK_ACCESSIBLE_RELATION_SET_SIZE | “aria-setsize” | integer |
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
## Application development rules
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:
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
* 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
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
Another example: if you create a tool bar containing buttons with only icons,
you should ensure that:
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
* the container has a `GTK_ACCESSIBLE_ROLE_TOOLBAR` role
* each button has a `GTK_ACCESSIBLE_PROPERTY_LABEL` property set with the user
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
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
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
`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.
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
Application developers using GTK **should** ensure that their UI controls
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
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.
## Implementations
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
Each UI control implements the #GtkAccessible interface to allow widget and
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
application developers to specify the roles, state, and relations between UI
controls. This API is purely descriptive.
docs: Fix up some issues in the a11y docs Fix up syntax errors and links in the introductory section about accessibility.
2020-07-27 00:54:57 +00:00
Each `GtkAccessible` implementation must provide a #GtkATContext instance,
Start documenting the Accessibility API Add the introductory text from #2833, and the various types to the API reference.
2020-07-08 13:42:32 +00:00
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.
docs: Start outlining a11y authoring practices We should have documentation for application developers and widget authors, so they can deal with the new accessibility API.
2020-10-19 17:37:30 +00:00
## Authoring practices {#authoring-practices}
The authoring practices are aimed at application developers, as well as
developers of GUI elements based on GTK.
Functionally, #GtkAccessible roles, states, properties, and relations are
analogous to a CSS for assistive technologies. For screen reader users, for
instance, the various accessible attributes control the rendering of their
non-visual experience. Incorrect roles and attributes may result in a
completely inaccessible user interface.
### A role is a promise
The following code:
```c
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.
### Attributes can both hide and enhance
Accessible attributes can be used to override the content of a UI element,
for instance:
```c
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:
```c
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.
docs: Add a section on a11y patterns
2020-10-19 17:39:40 +00:00
## Design patterns and custom widgets
...
Reference in New Issue Copy Permalink