AtSpiAdaptor: sync Cache signatures to at-spi2-core 2.45.91

src/gui/accessible/linux/dbusxml/Cache.xml

@@ -1,21 +1,106 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<node name="/node">
-<interface name="org.a11y.atspi.Cache">
+<node>
+  <!--
+      org.a11y.atspi.Cache:
+      @short_description: Interface to query accessible objects in bulk.
 
-  <method name="GetItems">
-    <arg name="nodes" type="a((so)(so)a(so)assusau)" direction="out"/>
-    <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiAccessibleCacheArray"/>
-  </method>
+      The application should expose this interface at the /org/a11y/atspi/cache object
+      path.
 
-  <signal name="AddAccessible">
-    <arg name="nodeAdded" type="((so)(so)a(so)assusau)"/>
-    <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiAccessibleCacheItem"/>
-  </signal>
+      The org.a11y.atspi.Accessible interface has methods like GetChildren and
+      GetChildAtIndex, but these only transfer an object's DBus id.  The caller has to
+      then query the object's properties individually.  Transferring objects one by one and
+      then their properties produces a lot of traffic in the accessibility bus.
 
-  <signal name="RemoveAccessible">
-    <arg name="nodeRemoved" type="(so)"/>
-    <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiObjectReference"/>
-  </signal>
+      So, this Cache interface can be used to query objects in bulk.  Assistive tech
+      should try to do a bulk query of all the objects in a new window with the GetItems
+      method, and then update them dynamically from the AddAccessible and RemoveAccessible
+      signals.
 
-</interface>
+      FIXME: Does GetItems only get called if an application implements
+      GetApplicationBusAddress?  GTK4 doesn't implement that, but it implements GetItems -
+      does that ever get called?
+  -->
+  <interface name="org.a11y.atspi.Cache">
+
+    <!--
+        GetItems: bulk query an application's accessible objects.
+
+        Returns: an array with one element for each available object.  Each element's
+        fields are like this:
+
+        - (so): accessible object reference - DBus name and object
+          path.  The rest of the fields refer to this main object.
+
+        - (so): application reference - DBus name and object path.  This is the owner of
+          the main object; the root path of the application that registered via
+          the Embed method of the org.a11y.atspi.Socket interface.
+
+        - (so): parent object reference - DBus name and object path.
+                If the main object has no parent:
+
+                - If it is a control, or a window, return the parent application.
+
+                - If the object has the application role, return a null reference.  FIXME:
+                  atk-adaptor/adaptors/cache-adaptor.c:append_cache_item() returns a
+                  reference to the registry in this case (the one it obtained from the
+                  initial Socket::Embed call); GTK4 returns a null reference.
+
+                - Otherwise, return a null reference ("" for the application name name and
+                  "/org/a11y/atspi/null" for the object path).
+
+        - i: index in parent, or -1 for transient widgets/menu items.  Equivalent to the
+          GetIndexInParent method of the org.a11y.atspi.Accessible interface.
+
+        - i: child count of main object, or -1 for defunct/menus.  Equivalent to the
+          ChildCount property of the org.a11y.atspi.Accessible interface.
+
+        - as: array of names of the interfaces that the main object supports.  Equivalent
+          to the GetInterfaces method of the org.a11y.atspi.Accessible interface.
+
+        - s: human-readable, localized, short name for the main object.  Equivalent to the
+          Name property of the org.a11y.atspi.Accessible interface.
+
+        - u: role.  Equivalent to the GetRole method of the org.a11y.atspi.Accessible interface.
+
+        - s: human-readable, localized description of the object in more detail.
+          Equivalent to the Description property of the org.a11y.atspi.Accessible interface.
+
+        - au: Set of states currently held by an object.  Equivalent to the GetState
+          method of the org.a11y.atspi.Accessible interface.
+
+        Deprecation note: The signature for the return value of this method changed in
+        2015, in commit b2c8c4c7.  It used to be "a((so)(so)(so)a(so)assusau)".  The
+        "a(so)" instead of "ii" is a list of references to child objects.  The
+        implementation in atspi-misc.c can handle either version, although the intention
+        is to deprecate the code that handles the old version.  Qt still uses this old
+        signature and should be changed to the new scheme (see qspi_struct_marshallers.cpp
+        in the Qt source code).
+    -->
+    <method name="GetItems">
+      <arg direction="out" name="nodes" type="a((so)(so)(so)iiassusau)"/>
+      <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiAccessibleCacheArray"/>
+    </method>
+
+    <!--
+        AddAccessible: to be emitted when a new object is added.
+
+        See the GetItems method for a description of the signature.
+    -->
+    <signal name="AddAccessible">
+      <arg direction="in" name="nodeAdded" type="((so)(so)(so)iiassusau)"/>
+      <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiAccessibleCacheItem"/>
+    </signal>
+
+    <!--
+        RemoveAccessible: to be emitted when an object is no longer available.
+
+        @nodeRemoved: (so) string for the application name and object path.
+    -->
+    <signal name="RemoveAccessible">
+      <arg direction="in" name="nodeRemoved" type="(so)"/>
+      <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiObjectReference"/>
+    </signal>
+
+  </interface>
 </node>

src/gui/accessible/linux/qspi_struct_marshallers.cpp

@@ -44,7 +44,8 @@ QDBusArgument &operator<<(QDBusArgument &argument, const QSpiAccessibleCacheItem
     argument << item.path;
     argument << item.application;
     argument << item.parent;
-    argument << item.children;
+    argument << item.index_in_parent;
+    argument << item.child_count;
     argument << item.supportedInterfaces;
     argument << item.name;
     argument << item.role;
@@ -60,7 +61,8 @@ const QDBusArgument &operator>>(const QDBusArgument &argument, QSpiAccessibleCac
     argument >> item.path;
     argument >> item.application;
     argument >> item.parent;
-    argument >> item.children;
+    argument >> item.index_in_parent;
+    argument >> item.child_count;
     argument >> item.supportedInterfaces;
     argument >> item.name;
     argument >> item.role;

src/gui/accessible/linux/qspi_struct_marshallers_p.h

@@ -53,7 +53,8 @@ struct QSpiAccessibleCacheItem
     QSpiObjectReference         path;
     QSpiObjectReference         application;
     QSpiObjectReference         parent;
-    QSpiObjectReferenceArray children;
+    int                         index_in_parent;
+    int                         child_count;
     QStringList                 supportedInterfaces;
     QString                     name;
     uint                        role;