Merge branch 'a11y-docs' into 'master'

a11y: Document roles of widgets

See merge request GNOME/gtk!2299

docs/reference/gtk/section-accessibility.md

@@ -50,6 +50,13 @@ Each role name is part of the #GtkAccessibleRole enumeration.
 | `CHECKBOX` | A control that has three possible value: `true`, `false`, or `undefined` | #GtkCheckButton |
 | `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 | #GtkComboBox |
+| `DIALOG` | A dialog that prompts the user to enter information or require a response | #GtkDialog and subclasses |
+| `PROGRESS_BAR` | An element that display progress | #GtkProgressBar |
+| `RADIO` | A checkable input in a group of radio roles | #GtkRadioButton |
+| `SCROLLBAR` | A graphical object controlling the scolling of content | #GtkScrollbar |
+| `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 |
 | `...` | … |
 
 See the [WAI-ARIA](https://www.w3.org/WAI/PF/aria/appendices#quickref) list

gtk/gtkbutton.c

@@ -49,6 +49,10 @@
  * #GtkLockButton, #GtkColorButton or #GtkFontButton use style classes such as
  * .toggle, .popup, .scale, .lock, .color on the button node
  * to differentiate themselves from a plain GtkButton.
+ *
+ * # Accessibility
+ *
+ * GtkButton uses the #GTK_ACCESSIBLE_ROLE_BUTTON role.
  */
 
 #include "config.h"

gtk/gtkcheckbutton.c

@@ -73,6 +73,10 @@
  * A GtkCheckButton without indicator changes the name of its main node
  * to button and adds a .check style class to it. The subnode is invisible
  * in this case.
+ *
+ * # Accessibility
+ *
+ * GtkCheckButton uses the #GTK_ACCESSIBLE_ROLE_CHECKBOX role.
  */
 
 typedef struct {

gtk/gtkdialog.c

@@ -157,6 +157,10 @@
  *   </action-widgets>
  * </object>
  * ]|
+ *
+ * # Accessibility
+ *
+ * GtkDialog uses the #GTK_ACCESSIBLE_ROLE_DIALOG role.
  */
 
 typedef struct _ResponseData ResponseData;

gtk/gtkprogressbar.c

@@ -85,6 +85,10 @@
  * .right, .top or .bottom added when the progress 'touches' the corresponding
  * end of the GtkProgressBar. The .osd class on the progressbar node is for use
  * in overlays like the one Epiphany has for page loading progress.
+ *
+ * # Accessibility
+ *
+ * GtkProgressBar uses the #GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role.
  */
 
 typedef struct _GtkProgressBarClass         GtkProgressBarClass;

gtk/gtkradiobutton.c

@@ -69,27 +69,6 @@
  * The group list does not need to be freed, as each #GtkRadioButton will remove
  * itself and its list item when it is destroyed.
  *
- * # CSS nodes
- *
- * |[<!-- language="plain" -->
- * radiobutton
- * ├── radio
- * ╰── <child>
- * ]|
- *
- * A GtkRadioButton with indicator (see gtk_check_button_set_draw_indicator())) has a
- * main CSS node with name radiobutton and a subnode with name radio.
- *
- * |[<!-- language="plain" -->
- * button.radio
- * ├── radio
- * ╰── <child>
- * ]|
- *
- * A GtkRadioButton without indicator changes the name of its main node
- * to button and adds a .radio style class to it. The subnode is invisible
- * in this case.
- *
  * ## How to create a group of two radio buttons.
  *
  * |[<!-- language="C" -->
@@ -124,6 +103,31 @@
  * selected button.
  * Inside the #GtkToggleButton::toggled handler, gtk_toggle_button_get_active()
  * can be used to determine if the button has been selected or deselected.
+ *
+ * # CSS nodes
+ *
+ * |[<!-- language="plain" -->
+ * radiobutton
+ * ├── radio
+ * ╰── <child>
+ * ]|
+ *
+ * A GtkRadioButton with indicator (see gtk_check_button_set_draw_indicator())) has a
+ * main CSS node with name radiobutton and a subnode with name radio.
+ *
+ * |[<!-- language="plain" -->
+ * button.radio
+ * ├── radio
+ * ╰── <child>
+ * ]|
+ *
+ * A GtkRadioButton without indicator changes the name of its main node
+ * to button and adds a .radio style class to it. The subnode is invisible
+ * in this case.
+ *
+ * # Accessibility
+ *
+ * GtkRadioButton uses the #GTK_ACCESSIBLE_ROLE_RADIO role.
  */
 
 typedef struct _GtkRadioButtonClass         GtkRadioButtonClass;

gtk/gtkscale.c

@@ -125,6 +125,10 @@
  * If the scale is displaying the value (see #GtkScale:draw-value), there is
  * subnode with name value. This node will get the .top or .bottom style classes
  * similar to the marks node.
+ *
+ * # Accessibility
+ *
+ * GtkScale uses the #GTK_ACCESSIBLE_ROLE_SLIDER role.
  */
 
 

gtk/gtkscrollbar.c

@@ -78,6 +78,10 @@
  * Other style classes that may be added to scrollbars inside #GtkScrolledWindow
  * include the positional classes (.left, .right, .top, .bottom) and style
  * classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering).
+ *
+ * # Accessibility
+ *
+ * GtkScrollbar uses the #GTK_ACCESSIBLE_ROLE_SCROLLBAR role.
  */
 
 typedef struct _GtkScrollbarClass   GtkScrollbarClass;

gtk/gtkseparator.c

@@ -46,6 +46,10 @@
  *
  * GtkSeparator has a single CSS node with name separator. The node
  * gets one of the .horizontal or .vertical style classes.
+ *
+ * # Accessibility
+ *
+ * GtkSeparator uses the #GTK_ACCESSIBLE_ROLE_SEPARATOR role.
  */
 
 typedef struct _GtkSeparatorClass GtkSeparatorClass;

gtk/gtkspinbutton.c

@@ -90,32 +90,6 @@
  * not desired, the automatic sizing can be turned off by explicitly
  * setting #GtkSpinButton::width-chars to a value != -1.
  *
- * # CSS nodes
- *
- * |[<!-- language="plain" -->
- * spinbutton.horizontal
- * ├── text
- * │    ├── undershoot.left
- * │    ╰── undershoot.right
- * ├── button.down
- * ╰── button.up
- * ]|
- *
- * |[<!-- language="plain" -->
- * spinbutton.vertical
- * ├── button.up
- * ├── text
- * │    ├── undershoot.left
- * │    ╰── undershoot.right
- * ╰── button.down
- * ]|
- *
- * GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes
- * for the entry and the two buttons, with these names. The button nodes have
- * the style classes .up and .down. The GtkText subnodes (if present) are put
- * below the text node. The orientation of the spin button is reflected in
- * the .vertical or .horizontal style class on the main node.
- *
  * ## Using a GtkSpinButton to get an integer
  *
  * |[<!-- language="C" -->
@@ -178,6 +152,36 @@
  *   gtk_widget_show (window);
  * }
  * ]|
+ *
+ * # CSS nodes
+ *
+ * |[<!-- language="plain" -->
+ * spinbutton.horizontal
+ * ├── text
+ * │    ├── undershoot.left
+ * │    ╰── undershoot.right
+ * ├── button.down
+ * ╰── button.up
+ * ]|
+ *
+ * |[<!-- language="plain" -->
+ * spinbutton.vertical
+ * ├── button.up
+ * ├── text
+ * │    ├── undershoot.left
+ * │    ╰── undershoot.right
+ * ╰── button.down
+ * ]|
+ *
+ * GtkSpinButtons main CSS node has the name spinbutton. It creates subnodes
+ * for the entry and the two buttons, with these names. The button nodes have
+ * the style classes .up and .down. The GtkText subnodes (if present) are put
+ * below the text node. The orientation of the spin button is reflected in
+ * the .vertical or .horizontal style class on the main node.
+ *
+ * # Accessiblity
+ *
+ * GtkSpinButton uses the #GTK_ACCESSIBLE_ROLE_SPIN_BUTTON role.
  */
 
 typedef struct _GtkSpinButton      GtkSpinButton;

gtk/gtkswitch.c

@@ -47,6 +47,10 @@
  *
  * GtkSwitch has four css nodes, the main node with the name switch and subnodes
  * for the slider and the on and off labels. Neither of them is using any style classes.
+ *
+ * # Accessibility
+ *
+ * GtkSwitch uses the #GTK_ACCESSIBLE_ROLE_SWITCH role.
  */
 
 #include "config.h"