[gtk/ebassi/new-a11y: 41/71] Start documenting the Accessibility API

[Emmanuele Bassi <ebassi src gnome org>]

commit 4c8037ca750cbcb25f78711fa3581dccf22cffb5
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Jul 8 14:42:32 2020 +0100

    Start documenting the Accessibility API
    
    Add the introductory text from #2833, and the various types to the API
    reference.

 docs/reference/gtk/gtk4-docs.xml            |   7 ++
 docs/reference/gtk/gtk4-sections.txt        |  38 +++++++++
 docs/reference/gtk/gtk4.types.in            |   1 +
 docs/reference/gtk/meson.build              |   1 +
 docs/reference/gtk/section-accessibility.md | 121 ++++++++++++++++++++++++++++
 5 files changed, 168 insertions(+)
---
diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml
index 8a10fe4908..0b2e721d9d 100644
--- a/docs/reference/gtk/gtk4-docs.xml
+++ b/docs/reference/gtk/gtk4-docs.xml
@@ -337,6 +337,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" />
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index c1f16f2cb1..fabe9ac1d7 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -7638,3 +7638,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>
diff --git a/docs/reference/gtk/gtk4.types.in b/docs/reference/gtk/gtk4.types.in
index e24296bb44..39c3ab5572 100644
--- a/docs/reference/gtk/gtk4.types.in
+++ b/docs/reference/gtk/gtk4.types.in
@@ -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
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index af14959544..d13686fec7 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -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',
diff --git a/docs/reference/gtk/section-accessibility.md b/docs/reference/gtk/section-accessibility.md
new file mode 100644
index 0000000000..84c361a92f
--- /dev/null
+++ b/docs/reference/gtk/section-accessibility.md
@@ -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.