AT-SPI's Collection

This wiki page is a scratch pad for the design and implementation of Collection for AT-SPI in the GNOME desktop.

Resources

• Feature Reqeust 326516: Add Accessibility::Collection to atkbridge

• Draft AT-SPI

• Collection Use Cases

• AT-SPI Best Practices

• Collection proof of concept in Guile Scheme. collection.scm

• Matchrule tests using above Scheme implementation. match-rule-test.scm

• Collection / Matchrule tests on Guile Scheme. collection-test.scm

• pypoke createMatchRule() test case: button_collection.py

• accessibility-atpi for design discussions

• gnome-accessibility-devel for implementation discussions

Test / Example Scripts

• Simple_at required file simple_at.py

• Gcalc example gcalc.py

• Firefox example firefox.py

• Performance test script

Documents

• Usage / Performance Document

Issues

• MatchType's MATCH_INVALID in the IDL needs a description

Architectural Decisions

• A collection request will not traverse into the scope of another collection.

• Clarification regarding getChildren()

• Leave getActiveDescendant out of the 'first rev' of Collection, and add it later when we have AtkCollection as well

• 2007/05/18 - Determined that the boolean recurse parameter of getChildren(), getNextChildren() and getPreviousChildren() does not enhance the interface. After evaluating the use cases, determined that recurse should always be true and the parameter should instead be interpreted as restrict. Where restrict limits the returned set from getNextChilren() to only include descendants of the current_object parameter. And it limits getPreviousChildren() to ancestors of the current_object parameter. For getChildren() that acts on the entire collection, the restrict parameter should be ignored.

• 2007/05/25 - Similar to -1 in the AccessibleText interface meaning to include all to the end, a null MatchRull should be interpreted as all to the end (or beginning) of the collection. A null MatchRule is equivalent to the MatchRule returned from createMatchRule when all parameters are null. This should primarily be used when restrict is true.

• Though the elements in a collection are descendants, the term "children" is confusing when working through the use cases. To reduce this confusion, the methods getChildren, getPreviousChildren, and getNextChildren, should be renamed to getMatches, getMatchesTo, and getMatchesFrom, respectively.

• To reduce the number of object references held by an AT, and to remove the performance impact of verifying that the current_object parameter is a member of the collection, any Collection interface should return equivalent results for the getMatches* methods. For instance, a Collection interface that has a descendant that also has a Collection interface should be able to return matches bound by the descendant collection when the referenced current_object is within the descendant collection.

Relevant Bugs

• Add Accessibility::Collection #326516

• Cannot create/add to StateSet object #360992

• Implement the Matchrule interface required for Collection #405774 (closed)

• RoleSet not present in cspi #407600 (closed)

• Discussion on the number of accessibles that will implement collection #433011

• StateSet.equals fails #437528

• Crash in Calculator related to use of Stateset #437958

Considerations

• Can the bridge be multi-threaded for performance?
• ORBit supports asynchronous calls. Will they work with Collection?