AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Start documenting the Accessibility API

Browse Source 
Add the introductory text from #2833, and the various types to the API
reference.
This commit is contained in:
Emmanuele Bassi 2020-07-08 14:42:32 +01:00
parent 3ea069a8d3
commit 5a173df3da
5 changed files with 168 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/reference/gtk/gtk4-docs.xml
View File

@ -338,6 +338,13 @@
<xi:include href="xml/gtkshortcutlabel.xml" />
</chapter>
<chapter id="Accessibility">
<title>Accessibility</title>
<xi:include href="section-accessibility.xml"/>
<xi:include href="xml/gtkaccessible.xml" />
<xi:include href="xml/gtkatcontext.xml" />
</chapter>
<chapter id="MiscObjects">
<title>Miscellaneous</title>
<xi:include href="xml/gtkadjustment.xml" />

38
docs/reference/gtk/gtk4-sections.txt
View File

@ -7652,3 +7652,41 @@ gtk_selection_filter_model_new_for_type
gtk_selection_filter_model_set_model
gtk_selection_filter_model_get_model
</SECTION>
<SECTION>
<FILE>gtkaccessible</FILE>
GtkAccessible
GtkAccessibleRole
GtkAccessibleState
GtkAccessibleProperty
gtk_accessible_update_state
<SUBSECTION Standard>
GTK_TYPE_ACCESSIBLE
GTK_TYPE_ACCESSIBLE_PROPERTY
GTK_TYPE_ACCESSIBLE_ROLE
GTK_TYPE_ACCESSIBLE_STATE
GTK_ACCESSIBLE
GTK_ACCESSIBLE_GET_IFACE
GTK_IS_ACCESSIBLE
<SUBSECTION Private>
gtk_accessible_get_type
</SECTION>
<SECTION>
<FILE>gtkatcontext</FILE>
GtkATContext
gtk_at_context_get_accessible
gtk_at_context_get_accessible_role
<SUBSECTION>
gtk_at_context_create
<SUBSECTION Standard>
GTK_TYPE_AT_CONTEXT
GTK_AT_CONTEXT
GTK_AT_CONTEXT_CLASS
GTK_AT_CONTEXT_GET_CLASS
GTK_IS_AT_CONTEXT
GTK_IS_AT_CONTEXT_CLASS
<SUBSECTION Private>
GtkATContextClass
gtk_at_context_get_type
</SECTION>

1
docs/reference/gtk/gtk4.types.in
View File

@ -17,6 +17,7 @@ gtk_application_window_get_type
gtk_aspect_frame_get_type
gtk_assistant_get_type
gtk_assistant_page_get_type
gtk_at_context_get_type
gtk_bin_layout_get_type
gtk_bitset_get_type
gtk_expression_get_type

1
docs/reference/gtk/meson.build
View File

@ -393,6 +393,7 @@ expand_content_md_files = [
'drawing-model.md',
'css-overview.md',
'css-properties.md',
'section-accessibility.md',
'section-text-widget.md',
'section-tree-widget.md',
'section-list-widget.md',

121
docs/reference/gtk/section-accessibility.md Normal file
View File

@ -0,0 +1,121 @@
# 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.
## Accessible roles and states
The fundamental concepts of an accessible widget are *roles* and *states*;
each GTK control fills out a role and its functionality is described by a
set of *states*.
### 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
%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.
#### List of accessible roles
Each role name is part of the `GtkAccessibleRole` enumeration.
| Role name | Description |
|-----------|-------------|
| `ALERT` | A message with important information |
| `BUTTON` | A control that performs an action when pressed |
| `CHECKBOX` | A control that has three possible value: `true`, `false`, or `undefined` |
| `COLUMNHEADER` | The header of a column in a list or grid |
| `COMBOBOX` | A control that can be expanded to show a list of possible values to select |
| `...` | … |
See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list
of roles for additional information.
### States
States, or properties, provide specific information about an accessible UI
control, and describe it for the assistive technology applications.
Unlike roles, states 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.
#### List of accessible states
Each state name is part of the #GtkAccessibleState enumeration.
| State name | Description |
|------------|-------------|
| `...` | … |
See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list of states for additional information.
## 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:
* the container of the form has a `Gtk.AccessibleRole.FORM` role
* each text entry widget in the form has the `GtkAccessible:labelled-by`
property 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.AccessibleRole.TOOLBAR` role
* each button has a `GtkAccessible: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
`GtkAccessible:label` or the `GtkAccessible:labelled-by` properties 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.
## Implementations
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.