diff options
Diffstat (limited to 'xml/Cache.xml')
-rw-r--r-- | xml/Cache.xml | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/xml/Cache.xml b/xml/Cache.xml index 45fb1704..650e36bb 100644 --- a/xml/Cache.xml +++ b/xml/Cache.xml @@ -1,17 +1,100 @@ <?xml version="1.0" encoding="UTF-8"?> <node> + <!-- + org.a11y.atspi.Cache: + @short_description: Interface to query accessible objects in bulk. + + The application should expose this interface at the /org/a11y/atspi/cache object + path. + + 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. Transfering objects one by one and + then their properties produces a lot of traffic in the accessibility bus. + + 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. + + 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. + + Historical note: This method used to have a different signature for the return + value. Some old applications return a value whose signature is + "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. + --> <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 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 name="nodeRemoved" type="(so)"/> <annotation name="org.qtproject.QtDBus.QtTypeName.In0" value="QSpiObjectReference"/> |