a11y atspi: Support AT-SPI Collection interfaceHEADdev

This introduces support for the AT-SPI Collection interface [1], which
provides an efficient way to search for accessible objects in an
application's accessibility (sub)tree while avoiding the DBus
overhead that would be necessary when iterating over the tree
on the client side.

Recently, browse mode in the Orca screen reader was made available for
non-browser applications, which also depends on the AT-SPI Collection
interface. Therefore, this commit also helps to support that, see
also earlier discussion in [2].

This implements demarshalling of the AT-SPI DBus data structure
that defines the match rule which defines the criteria to use for
the search, as well as all the logic to find and return the
accessibles that match those criteria.
Matching is based on 4 types: AT-SPI states, roles,
interfaces and attributes.

Since the XML description of the AT-SPI Collection interface
wasn't documented so far, figuring out details on how to implement
it correctly depended mostly on reading related libatspi documentation
as well as reading libatspi and libatk source code. Pending/suggested
at-spi2-core change [3] adds documentation gained along the way
to the XML description for future reference, too.

Match rules are described in the libatspi doc for
AtSpiMatchRule [4] and atspi_match_rule_new [5].

The newly introduced logic is mostly encapsulated into the newly
introduced QSpiMatchRuleMatcher class whose members are similar to
those of the QSpiMatchRule (demarshalled from DBus), but
adjusted to simplify the matching of the QAccessibleInterface
information later when traversing the a11y tree.

Avoid any potential mismatch/ambiguity that might arise by trying
to convert the AT-SPI2 input data (from the match rule) to Qt's
equivalent. Instead, "stay in the AT-SPI world" by converting Qt's
internal a11y information to the AT-SPI equivalent for consistency
and use that for comparison.

Sample use of the newly implemented Collection interface for the
qtbase spinboxes sample program to query the first three accessible objects
that are visible, have an AT-SPI SPIN_BUTTON role, and support the
Action and Accessible interfaces (queried using Accerciser's IPython
console with the application's root object selected, s. QTBUG-139334
for more details):

    In [99]: collection = acc.queryCollection()
    rule = collection.createMatchRule(Atspi.StateSet(Atspi.StateType.VISIBLE), Atspi.CollectionMatchType.ALL,
                                      [], Atspi.CollectionMatchType.ALL,
                                      [Atspi.Role.SPIN_BUTTON], Atspi.CollectionMatchType.ALL,
                                      ["Action", "Accessible"], Atspi.CollectionMatchType.ALL,
                                      False)
    collection.getMatches(rule, Atspi.CollectionSortOrder.CANONICAL, 3, True)
    Out[99]:
    [<Atspi.Accessible object at 0x7fc6552b0c80 (AtspiAccessible at 0x37cf0f80)>,
     <Atspi.Accessible object at 0x7fc65525adc0 (AtspiAccessible at 0x36751de0)>,
     <Atspi.Accessible object at 0x7fc6552ac240 (AtspiAccessible at 0x37da9af0)>]

[1] https://gitlab.gnome.org/GNOME/at-spi2-core/-/blob/6a8c84903f773a4b9aa5978bb0817ee1a2d88b1d/xml/Collection.xml
[2] https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues/139
[3] https://gitlab.gnome.org/GNOME/at-spi2-core/-/merge_requests/198
[4] https://docs.gtk.org/atspi2/class.MatchRule.html
[5] https://docs.gtk.org/atspi2/ctor.MatchRule.new.html

Fixes: QTBUG-139334
Change-Id: I36771b19528ee4cca9348f326a543a69239344e8
Reviewed-by: Volker Hilsheimer <[email protected]>

0 files changed, 0 insertions, 0 deletions