a11y: Rework accessible name/description computation

The ARIA spec determines the name and description of accessible elements
in a more complex way that simply mapping to a single property; instead,
it will chain up multiple definitions (if it finds them). For instance,
let's assume we have a button that saves a file selected from a file
selection widget; the widgets have the following attributes:

 - the file selection widget has a "label" attribute set to the
   selected file, e.g. "Final paper.pdf"
 - the "download" button has a "label" attribute set to the
   "Download" string
 - the "download" button has a "labelled-by" attribute set to
   reference the file selection widget

The ARIA spec says that the accessible name of the "Download" button
should be computed as "Download Final paper.pdf".

The algorithm defined in section 4.3 of the WAI-ARIA specification
applies to both accessible names (using the "label" and "labelled-by"
attributes), and to accessible descriptions (using the "description" and
"described-by" attributes).

1 files changed, 186 insertions, 26 deletions

diff --git a/gtk/gtkatcontext.c b/gtk/gtkatcontext.c
index de9dc79275..7bd1398ebb 100644
--- a/gtk/gtkatcontext.c
+++ b/gtk/gtkatcontext.c
@@ -730,47 +730,115 @@ gtk_at_context_get_accessible_relation (GtkATContext          *self,
   return gtk_accessible_attribute_set_get_value (self->relations, relation);
 }
 
-/*< private >
- * gtk_at_context_get_label:
- * @self: a #GtkATContext
- *
- * Retrieves the accessible label of the #GtkATContext.
- *
- * This is a convenience function meant to be used by #GtkATContext implementations.
- *
- * Returns: (transfer full): the label of the #GtkATContext
- */
-char *
-gtk_at_context_get_label (GtkATContext *self)
+/* See the WAI-ARIA § 4.3, "Accessible Name and Description Computation" */
+static void
+gtk_at_context_get_name_accumulate (GtkATContext *self,
+                                    GPtrArray    *names,
+                                    gboolean      recurse)
 {
-  g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
-
   GtkAccessibleValue *value = NULL;
 
+  if (gtk_accessible_attribute_set_contains (self->properties, GTK_ACCESSIBLE_PROPERTY_LABEL))
+    {
+      value = gtk_accessible_attribute_set_get_value (self->properties, GTK_ACCESSIBLE_PROPERTY_LABEL);
+
+      g_ptr_array_add (names, (char *) gtk_string_accessible_value_get (value));
+    }
+
+  if (recurse && gtk_accessible_attribute_set_contains (self->relations, GTK_ACCESSIBLE_RELATION_LABELLED_BY))
+    {
+      value = gtk_accessible_attribute_set_get_value (self->relations, GTK_ACCESSIBLE_RELATION_LABELLED_BY);
+
+      GList *list = gtk_reference_list_accessible_value_get (value);
+
+      for (GList *l = list; l != NULL; l = l->data)
+        {
+          GtkAccessible *rel = GTK_ACCESSIBLE (l->data);
+          GtkATContext *rel_context = gtk_accessible_get_at_context (rel);
+
+          gtk_at_context_get_name_accumulate (rel_context, names, FALSE);
+        }
+    }
+
+  GtkAccessibleRole role = gtk_at_context_get_accessible_role (self);
+
+  switch ((int) role)
+    {
+    case GTK_ACCESSIBLE_ROLE_RANGE:
+      {
+        int range_attrs[] = {
+          GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT,
+          GTK_ACCESSIBLE_PROPERTY_VALUE_NOW,
+        };
+
+        value = NULL;
+        for (int i = 0; i < G_N_ELEMENTS (range_attrs); i++)
+          {
+            if (gtk_accessible_attribute_set_contains (self->properties, range_attrs[i]))
+              {
+                value = gtk_accessible_attribute_set_get_value (self->properties, range_attrs[i]);
+                break;
+              }
+          }
+
+        if (value != NULL)
+          g_ptr_array_add (names, (char *) gtk_string_accessible_value_get (value));
+      }
+      break;
+
+    default:
+      break;
+    }
+
+  /* If there is no label or labelled-by attribute, hidden elements
+   * have no name
+   */
   if (gtk_accessible_attribute_set_contains (self->states, GTK_ACCESSIBLE_STATE_HIDDEN))
     {
       value = gtk_accessible_attribute_set_get_value (self->states, GTK_ACCESSIBLE_STATE_HIDDEN);
 
       if (gtk_boolean_accessible_value_get (value))
-        return g_strdup ("");
+        return;
     }
 
-  if (gtk_accessible_attribute_set_contains (self->properties, GTK_ACCESSIBLE_PROPERTY_LABEL))
+  /* This fallback is in place only for unlabelled elements */
+  if (names->len != 0)
+    return;
+
+  GEnumClass *enum_class = g_type_class_peek (GTK_TYPE_ACCESSIBLE_ROLE);
+  GEnumValue *enum_value = g_enum_get_value (enum_class, role);
+
+  if (enum_value != NULL)
+    g_ptr_array_add (names, (char *) enum_value->value_nick);
+}
+
+static void
+gtk_at_context_get_description_accumulate (GtkATContext *self,
+                                           GPtrArray    *labels,
+                                           gboolean      recurse)
+{
+  GtkAccessibleValue *value = NULL;
+
+  if (gtk_accessible_attribute_set_contains (self->properties, GTK_ACCESSIBLE_PROPERTY_DESCRIPTION))
     {
-      value = gtk_accessible_attribute_set_get_value (self->properties, GTK_ACCESSIBLE_PROPERTY_LABEL);
+      value = gtk_accessible_attribute_set_get_value (self->properties, GTK_ACCESSIBLE_PROPERTY_DESCRIPTION);
 
-      return g_strdup (gtk_string_accessible_value_get (value));
+      g_ptr_array_add (labels, (char *) gtk_string_accessible_value_get (value));
     }
 
-  if (gtk_accessible_attribute_set_contains (self->relations, GTK_ACCESSIBLE_RELATION_LABELLED_BY))
+  if (recurse && gtk_accessible_attribute_set_contains (self->relations, GTK_ACCESSIBLE_RELATION_DESCRIBED_BY))
     {
-      value = gtk_accessible_attribute_set_get_value (self->relations, GTK_ACCESSIBLE_RELATION_LABELLED_BY);
+      value = gtk_accessible_attribute_set_get_value (self->relations, GTK_ACCESSIBLE_RELATION_DESCRIBED_BY);
 
       GList *list = gtk_reference_list_accessible_value_get (value);
-      GtkAccessible *rel = GTK_ACCESSIBLE (list->data);
-      GtkATContext *rel_context = gtk_accessible_get_at_context (rel);
 
-      return gtk_at_context_get_label (rel_context);
+      for (GList *l = list; l != NULL; l = l->data)
+        {
+          GtkAccessible *rel = GTK_ACCESSIBLE (l->data);
+          GtkATContext *rel_context = gtk_accessible_get_at_context (rel);
+
+          gtk_at_context_get_description_accumulate (rel_context, labels, FALSE);
+        }
     }
 
   GtkAccessibleRole role = gtk_at_context_get_accessible_role (self);
@@ -784,6 +852,7 @@ gtk_at_context_get_label (GtkATContext *self)
           GTK_ACCESSIBLE_PROPERTY_VALUE_NOW,
         };
 
+        value = NULL;
         for (int i = 0; i < G_N_ELEMENTS (range_attrs); i++)
           {
             if (gtk_accessible_attribute_set_contains (self->properties, range_attrs[i]))
@@ -794,7 +863,7 @@ gtk_at_context_get_label (GtkATContext *self)
           }
 
         if (value != NULL)
-          return g_strdup (gtk_string_accessible_value_get (value));
+          g_ptr_array_add (labels, (char *) gtk_string_accessible_value_get (value));
       }
       break;
 
@@ -802,13 +871,104 @@ gtk_at_context_get_label (GtkATContext *self)
       break;
     }
 
+  /* If there is no label or labelled-by attribute, hidden elements
+   * have no name
+   */
+  if (gtk_accessible_attribute_set_contains (self->states, GTK_ACCESSIBLE_STATE_HIDDEN))
+    {
+      value = gtk_accessible_attribute_set_get_value (self->states, GTK_ACCESSIBLE_STATE_HIDDEN);
+
+      if (gtk_boolean_accessible_value_get (value))
+        return;
+    }
+
+  /* This fallback is in place only for unlabelled elements */
+  if (labels->len != 0)
+    return;
+
   GEnumClass *enum_class = g_type_class_peek (GTK_TYPE_ACCESSIBLE_ROLE);
   GEnumValue *enum_value = g_enum_get_value (enum_class, role);
 
   if (enum_value != NULL)
-    return g_strdup (enum_value->value_nick);
+    g_ptr_array_add (labels, (char *) enum_value->value_nick);
+}
+
+/*< private >
+ * gtk_at_context_get_name:
+ * @self: a #GtkATContext
+ *
+ * Retrieves the accessible name of the #GtkATContext.
+ *
+ * This is a convenience function meant to be used by #GtkATContext implementations.
+ *
+ * Returns: (transfer full): the label of the #GtkATContext
+ */
+char *
+gtk_at_context_get_name (GtkATContext *self)
+{
+  g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
+
+  GPtrArray *names = g_ptr_array_new ();
+
+  gtk_at_context_get_name_accumulate (self, names, TRUE);
+
+  if (names->len == 0)
+    {
+      g_ptr_array_unref (names);
+      return g_strdup ("");
+    }
+
+  GString *res = g_string_new ("");
+  g_string_append (res, g_ptr_array_index (names, 0));
+
+  for (guint i = 1; i < names->len; i++)
+    {
+      g_string_append (res, " ");
+      g_string_append (res, g_ptr_array_index (names, i));
+    }
+
+  g_ptr_array_unref (names);
+
+  return g_string_free (res, FALSE);
+}
+
+/*< private >
+ * gtk_at_context_get_description:
+ * @self: a #GtkATContext
+ *
+ * Retrieves the accessible description of the #GtkATContext.
+ *
+ * This is a convenience function meant to be used by #GtkATContext implementations.
+ *
+ * Returns: (transfer full): the label of the #GtkATContext
+ */
+char *
+gtk_at_context_get_description (GtkATContext *self)
+{
+  g_return_val_if_fail (GTK_IS_AT_CONTEXT (self), NULL);
+
+  GPtrArray *names = g_ptr_array_new ();
+
+  gtk_at_context_get_description_accumulate (self, names, TRUE);
+
+  if (names->len == 0)
+    {
+      g_ptr_array_unref (names);
+      return g_strdup ("");
+    }
+
+  GString *res = g_string_new ("");
+  g_string_append (res, g_ptr_array_index (names, 0));
+
+  for (guint i = 1; i < names->len; i++)
+    {
+      g_string_append (res, " ");
+      g_string_append (res, g_ptr_array_index (names, i));
+    }
+
+  g_ptr_array_unref (names);
 
-  return g_strdup ("widget");
+  return g_string_free (res, FALSE);
 }
 
 void