[at-spi2-core] Add an "announcement" event/signal to allow objects to send notifications

[Mike Gorse <mgorse src gnome org>]

commit 28d732a20180b5b3f07cb0079b9d9943b881b929
Author: Mike Gorse <mgorse suse com>
Date:   Fri Jul 1 21:11:59 2022 -0500

    Add an "announcement" event/signal to allow objects to send notifications
    
    Fixes #63

 atk-adaptor/event.c          | 24 ++++++++++++++++++++++++
 atk/atkobject.c              | 19 +++++++++++++++++++
 atk/atkobject.h              |  7 +++++++
 atspi/atspi-event-listener.c |  1 +
 xml/Event.xml                |  3 +++
 5 files changed, 54 insertions(+)
---
diff --git a/atk-adaptor/event.c b/atk-adaptor/event.c
index bd38eef7..b66310eb 100644
--- a/atk-adaptor/event.c
+++ b/atk-adaptor/event.c
@@ -885,6 +885,28 @@ active_descendant_event_listener (GSignalInvocationHint * signal_hint,
   return TRUE;
 }
 
+static gboolean
+announcement_event_listener (GSignalInvocationHint * signal_hint,
+                             guint n_param_values,
+                             const GValue * param_values, gpointer data)
+{
+  AtkObject *accessible;
+  gchar *text;
+  GSignalQuery signal_query;
+  const gchar *name;
+
+  g_signal_query (signal_hint->signal_id, &signal_query);
+  name = signal_query.signal_name;
+
+  accessible = ATK_OBJECT (g_value_get_object (&param_values[0]));
+  text = (gchar *)g_value_get_pointer (&param_values[1]);
+  g_return_val_if_fail (text != NULL, TRUE);
+
+  emit_event (accessible, ITF_EVENT_OBJECT, name, "", 0, 0,
+              "s", text, append_basic);
+  return TRUE;
+}
+
 /*---------------------------------------------------------------------------*/
 
 /* 
@@ -1289,6 +1311,8 @@ spi_atk_register_event_listeners (void)
   /* TODO */
   add_signal_listener (active_descendant_event_listener,
                        "Gtk:AtkObject:active-descendant-changed");
+  add_signal_listener (announcement_event_listener,
+                       "Gtk:AtkObject:announcement");
   add_signal_listener (bounds_event_listener,
                        "Gtk:AtkComponent:bounds-changed");
   add_signal_listener (text_selection_changed_event_listener,
diff --git a/atk/atkobject.c b/atk/atkobject.c
index 63986dd9..f8fa8fc6 100644
--- a/atk/atkobject.c
+++ b/atk/atkobject.c
@@ -89,6 +89,7 @@ enum {
   STATE_CHANGE,
   VISIBLE_DATA_CHANGED,
   ACTIVE_DESCENDANT_CHANGED,
+  ANNOUNCEMENT,
   
   LAST_SIGNAL
 };
@@ -683,6 +684,24 @@ atk_object_class_init (AtkObjectClass *klass)
                  g_cclosure_marshal_VOID__POINTER,
                  G_TYPE_NONE,
                  1, G_TYPE_POINTER);
+
+  /**
+   * AtkObject::announcement
+   * @atkobject: the object which received the signal.
+   * @arg1: (type gchar *): the text to be announced.
+   *
+   * The "announcement" signal can be emitted to pass an announcement on to
+   * be read by a screen reader.
+   */
+  atk_object_signals[ANNOUNCEMENT] =
+    g_signal_new ("announcement",
+                 G_TYPE_FROM_CLASS (klass),
+                 G_SIGNAL_RUN_LAST,
+                 G_STRUCT_OFFSET (AtkObjectClass, announcement),
+                 NULL, NULL,
+                 g_cclosure_marshal_VOID__STRING,
+                 G_TYPE_NONE,
+                 1, G_TYPE_STRING);
 }
 
 static void
diff --git a/atk/atkobject.h b/atk/atkobject.h
index 9a32fedc..f8715890 100644
--- a/atk/atkobject.h
+++ b/atk/atkobject.h
@@ -670,6 +670,13 @@ void                      (* initialize)                         (AtkObject
   void                    (*active_descendant_changed) (AtkObject                  *accessible,
                                                         gpointer                   *child);
 
+  /*
+   * The signal handler which is executed when an object has text to be
+   * announced by a screen reader.
+   */
+  void                    (*announcement)         (AtkObject                  *accessible,
+                                                   gchar                      *text);
+
   /*           
    * Gets a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of 
name-value pairs. 
    * Since ATK 1.12
diff --git a/atspi/atspi-event-listener.c b/atspi/atspi-event-listener.c
index b4a07af4..c45ad91b 100644
--- a/atspi/atspi-event-listener.c
+++ b/atspi/atspi-event-listener.c
@@ -449,6 +449,7 @@ listener_entry_free (EventListenerEntry *e)
  *            object:column-deleted
  *            object:model-changed
  *            object:active-descendant-changed
+ *            object:announcement
  *
  *  (screen reader events)
 *             screen-reader:region-changed
diff --git a/xml/Event.xml b/xml/Event.xml
index ba867590..3f3af7a2 100644
--- a/xml/Event.xml
+++ b/xml/Event.xml
@@ -29,6 +29,9 @@
        <signal name="ActiveDescendantChanged"><arg type="(suuv)"/>
           <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiEvent"/>
         </signal>
+       <signal name="Announcement"><arg type="(suuv)"/>
+          <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiEvent"/>
+        </signal>
        <signal name="RowInserted"><arg type="(suuv)"/>
           <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiEvent"/>
         </signal>