From 470349c9028a574b2e2a78b3aad2a3620ac7dde6 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 28 Jul 2020 16:46:53 +0100
Subject: [PATCH] a11y: Add an explicit "reset to default" method

In some cases we explicitly want to unset an accessible attribute; for
instance, an accessible property is gated on a widget property, and if
the widget property gets unset, the accessible property should be reset.
---
 docs/reference/gtk/gtk4-sections.txt |  3 ++
 gtk/gtkaccessible.c                  | 75 ++++++++++++++++++++++++++--
 gtk/gtkaccessible.h                  | 10 ++++
 3 files changed, 85 insertions(+), 3 deletions(-)

diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 728c1ab7d1..943e9ab771 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -7647,10 +7647,13 @@ GtkAccessibleAutocomplete
 GtkAccessibleSort
 gtk_accessible_update_state
 gtk_accessible_update_state_value
+gtk_accessible_reset_state
 gtk_accessible_update_property
 gtk_accessible_update_property_value
+gtk_accessible_reset_property
 gtk_accessible_update_relation
 gtk_accessible_update_relation_value
+gtk_accessible_reset_relation
 
 <SUBSECTION Standard>
 GTK_TYPE_ACCESSIBLE
diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c
index fcaa6edb58..f8dc8640af 100644
--- a/gtk/gtkaccessible.c
+++ b/gtk/gtkaccessible.c
@@ -28,13 +28,13 @@
  * “AT”. Every accessible implementation has:
  *
  *  - a “role”, represented by a value of the #GtkAccessibleRole enumeration
- *  - a “state”, represented by a set of #GtkAccessibleState,
- *       #GtkAccessibleProperty and #GtkAccessibleRelation values
+ *  - an “attribute”, represented by a set of #GtkAccessibleState,
+ *    #GtkAccessibleProperty and #GtkAccessibleRelation values
  *
  * The role cannot be changed after instantiating a #GtkAccessible
  * implementation.
  *
- * The state is updated every time a UI element's state changes in a way that
+ * The attributes are updated every time a UI element's state changes in a way that
  * should be reflected by assistive technologies. For instance, if a #GtkWidget
  * visibility changes, the %GTK_ACCESSIBLE_STATE_HIDDEN state will also change
  * to reflect the #GtkWidget:visible property.
@@ -218,6 +218,29 @@ gtk_accessible_update_state_value (GtkAccessible      *self,
   gtk_at_context_update (context);
 }
 
+/**
+ * gtk_accessible_reset_state:
+ * @self: a #GtkAccessible
+ * @state: a #GtkAccessibleState
+ *
+ * Resets the accessible @state to its default value.
+ */
+void
+gtk_accessible_reset_state (GtkAccessible      *self,
+                            GtkAccessibleState  state)
+{
+  GtkATContext *context;
+
+  g_return_if_fail (GTK_IS_ACCESSIBLE (self));
+
+  context = gtk_accessible_get_at_context (self);
+  if (context == NULL)
+    return;
+
+  gtk_at_context_set_accessible_state (context, state, NULL);
+  gtk_at_context_update (context);
+}
+
 /**
  * gtk_accessible_update_property:
  * @self: a #GtkAccessible
@@ -333,6 +356,29 @@ gtk_accessible_update_property_value (GtkAccessible         *self,
   gtk_at_context_update (context);
 }
 
+/**
+ * gtk_accessible_reset_property:
+ * @self: a #GtkAccessible
+ * @property: a #GtkAccessibleProperty
+ *
+ * Resets the accessible @property to its default value.
+ */
+void
+gtk_accessible_reset_property (GtkAccessible         *self,
+                               GtkAccessibleProperty  property)
+{
+  GtkATContext *context;
+
+  g_return_if_fail (GTK_IS_ACCESSIBLE (self));
+
+  context = gtk_accessible_get_at_context (self);
+  if (context == NULL)
+    return;
+
+  gtk_at_context_set_accessible_property (context, property, NULL);
+  gtk_at_context_update (context);
+}
+
 /**
  * gtk_accessible_update_relation:
  * @self: a #GtkAccessible
@@ -438,3 +484,26 @@ gtk_accessible_update_relation_value (GtkAccessible         *self,
 
   gtk_at_context_update (context);
 }
+
+/**
+ * gtk_accessible_reset_relation:
+ * @self: a #GtkAccessible
+ * @relation: a #GtkAccessibleRelation
+ *
+ * Resets the accessible @relation to its default value.
+ */
+void
+gtk_accessible_reset_relation (GtkAccessible         *self,
+                               GtkAccessibleRelation  relation)
+{
+  GtkATContext *context;
+
+  g_return_if_fail (GTK_IS_ACCESSIBLE (self));
+
+  context = gtk_accessible_get_at_context (self);
+  if (context == NULL)
+    return;
+
+  gtk_at_context_set_accessible_relation (context, relation, NULL);
+  gtk_at_context_update (context);
+}
diff --git a/gtk/gtkaccessible.h b/gtk/gtkaccessible.h
index 0f7776a1e4..0aec20974f 100644
--- a/gtk/gtkaccessible.h
+++ b/gtk/gtkaccessible.h
@@ -63,4 +63,14 @@ void                    gtk_accessible_update_relation_value    (GtkAccessible
                                                                  GtkAccessibleRelation  relation,
                                                                  const GValue          *value);
 
+GDK_AVAILABLE_IN_ALL
+void                    gtk_accessible_reset_state              (GtkAccessible         *self,
+                                                                 GtkAccessibleState     state);
+GDK_AVAILABLE_IN_ALL
+void                    gtk_accessible_reset_property           (GtkAccessible         *self,
+                                                                 GtkAccessibleProperty  property);
+GDK_AVAILABLE_IN_ALL
+void                    gtk_accessible_reset_relation           (GtkAccessible         *self,
+                                                                 GtkAccessibleRelation  relation);
+
 G_END_DECLS