Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members
Accessibility::Collection

Accessibility::Collection Interface Reference

An interface designed to allow a subset of the complete accessible object 'tree' to be returned which satisfies a set of criteria. More...

import "Accessibility_Collection.idl";

List of all members.

Public Types

enum  SortOrder {
  SORT_ORDER_INVALID,
  SORT_ORDER_CANONICAL,
  SORT_ORDER_FLOW,
  SORT_ORDER_TAB,
  SORT_ORDER_REVERSE_CANONICAL,
  SORT_ORDER_REVERSE_FLOW,
  SORT_ORDER_REVERSE_TAB,
  SORT_ORDER_LAST_DEFINED
}
 Order in which an AccessibleSet should be returned. More...
enum  MatchType {
  MATCH_INVALID,
  MATCH_ALL,
  MATCH_ANY,
  MATCH_NONE,
  MATCH_EMPTY,
  MATCH_LAST_DEFINED
}
 Enumeration used to specify how attribute matching is done in Collection::getChildren. More...

Public Member Functions

boolean isAncestorOf (in Accessible object)
 Query whether an object is a descendant of another in the accessibility hierarchy.
MatchRule createMatchRule (in StateSet states, in MatchType statematchtype, in AttributeSet attributes, in MatchType attributematchtype, in RoleSet roles, in MatchType rolematchtype, in string interfaces, in MatchType interfacematchtype, in boolean invert)
 Create a MatchRule for the purposes of doing a getChildren query on a container.
void freeMatchRule (in MatchRule rule)
 Frees the resources associated with the specified MatchRule.
AccessibleSet getChildren (in MatchRule rule, in SortOrder sortby, in boolean recurse, inOut long count)
 Query a Collection for objects within it which match a certain set of criteria.
AccessibleSet getPreviousChildren (in Accessible current_object, in MatchRule rule, in SortOrder sortby, in boolean recurse, inout long count)
 Find a list of the previous elements in a collection which match a particular search criterion, relative to a subelement of the specified container.
AccessibleSet getNextChildren (in Accessible current_object, in MatchRule rule, in SortOrder sortby, in boolean recurse, inout long count)
 Find a list of the next elements in a collection which match a particular search criterion.
Accessible getActiveDescendant ()
 Query an object for the current 'active descendant', i.e.

Detailed Description

An interface designed to allow a subset of the complete accessible object 'tree' to be returned which satisfies a set of criteria.

This interface can be used to avoid iteration or client-side search of the object tree.

Collection is an interface which is particularly useful within large containers, for instance Table instances, and for complex documents. For that reason, implementors of Document are encouraged to implement Collection as well.

Because the Collection API is recursive, in general only a few elements in the accessibility hierarchy need implement it, for instance Document containers, Table instances, and toplevel windows.

Note:
events fired by Collection instances include
Since:
AT-SPI 1.7.0

Definition at line 63 of file Accessibility_Collection.idl.

Member Enumeration Documentation

enum Accessibility::Collection::SortOrder
 

Order in which an AccessibleSet should be returned.

Enumerator:
SORT_ORDER_INVALID 
SORT_ORDER_CANONICAL  The order of children as defined by Accessibility::Accessible::getIndexInParent.
SORT_ORDER_FLOW  The order in which content 'flows', for instance text flow.
SORT_ORDER_TAB  The 'TAB' order, e.g.

the order in which objects obtain focus via 'TAB' or similar forward keyboard navigation. Primary useful for objects with STATE_FOCUSSABLE.

SORT_ORDER_REVERSE_CANONICAL  The reverse of the order of children as defined by Accessibility::Accessible::getIndexInParent.
SORT_ORDER_REVERSE_FLOW  The reverse of the order in which content 'flows', for instance text flow from last to first.
SORT_ORDER_REVERSE_TAB  The reverse 'TAB' order, e.g.

the order in which objects obtain focus via 'Shift-TAB' or similar backwards keyboard navigation. Primary useful for objects with STATE_FOCUSSABLE.

SORT_ORDER_LAST_DEFINED 

Definition at line 66 of file Accessibility_Collection.idl.

enum Accessibility::Collection::MatchType
 

Enumeration used to specify how attribute matching is done in Collection::getChildren.

Enumerator:
MATCH_INVALID 
MATCH_ALL  TRUE if all of the criteria are met
MATCH_ANY  TRUE if any of the criteria are met
MATCH_NONE  TRUE if none of the criteria are met
MATCH_EMPTY  Same as MATCH_ALL if the criteria is non-empty; for empty criteria this rule requires returned value to also have empty set.
MATCH_LAST_DEFINED 

Definition at line 95 of file Accessibility_Collection.idl.

Member Function Documentation

boolean Accessibility::Collection::isAncestorOf (  in Accessible  object  ) 
 

Query whether an object is a descendant of another in the accessibility hierarchy.

Note:
An object is not considered to be an ancestor of itself.
Parameters:
object,: the object to search for in the Collection.
Returns:
TRUE if object is a descendant of this Collection, FALSE otherwise.

MatchRule Accessibility::Collection::createMatchRule (  in StateSet  states,
in MatchType  statematchtype,
in AttributeSet  attributes,
in MatchType  attributematchtype,
in RoleSet  roles,
in MatchType  rolematchtype,
in string  interfaces,
in MatchType  interfacematchtype,
in boolean  invert
) 
 

Create a MatchRule for the purposes of doing a getChildren query on a container.

The resulting MatchRule should be freed by the caller when it is no longer needed, via freeMatchRule. If any of the following params are empty or NULL: states, attributes, roles, interfaces, then any value for the corresponding parameter in a queried child will constitute a match, unless the following MatchType is MATCH_EMPTY. For example, 

 createMatchRule (NULL, MATCH_ANY, 
                        NULL, MATCH_ANY, 
                        NULL, MATCH_ANY,
                        "", MATCH_ANY,
                        FALSE);
will create a match rule which returns all children of the specified Collection, whereas 
 createMatchRule (NULL, MATCH_ANY,
                        NULL, MATCH_EMPTY,
                        NULL, MATCH_ANY,
                        "", MATCH_ANY,
                        FALSE);
will return only those objects having an empty AttributeSet.
Note:
MATCH_EMPTY does not make sense for the rolematchtype or interfacematchtype parameters, as all children of a collection have non-empty Roles and implement at least one interface.
Parameters:
states An Accessibility::StateSet whose states are to be compared with the objects in the collection.
statematchtype A MatchType which determines the match requirements for the 'states' criterion.
attributes An AttributeSet, as a list of name-value pairs, of attributes which should present in members of a matching set. In the case of text attributes, the presence of the attribute somewhere within the content of an object is deemed to be a match, i.e. an object's entire content need not match the attribute if some subrange of the object content matches the attribute values.
attributematchtype A MatchType which determines the match requirements for the 'attributes' criterion.
roles A RoleSet specifying the Accessibility::Role values which are to be considered among the match criteria.
rolematchtype A MatchType which determines the match requirements for the 'roles' criterion.
interfaces A string which represents one or more IDL interface definitions which should be implemented by matching objects.
interfacematchtype A MatchType which determines the match requirements for the 'interfaces' criterion.
invert If TRUE, the resulting MatchRule will return objects which do NOT match the specified criteria, instead of those which do; i.e. this parameter "inverts" the sense of the resulting query.
Returns:
a MatchRule which encapsulates the specified criteria.

void Accessibility::Collection::freeMatchRule (  in MatchRule  rule  ) 
 

Frees the resources associated with the specified MatchRule.

The Matchrule should not be re-used by the client after freeing.

AccessibleSet Accessibility::Collection::getChildren (  in MatchRule  rule,
in SortOrder  sortby,
in boolean  recurse,
inOut long  count
) 
 

Query a Collection for objects within it which match a certain set of criteria.

Any criteria which are NULL below will be excluded from consideration unless rule is MATCH_EMPTY. MATCH_ANY will require that one or more of the non-empty parameters states, attributes, or repoid be an exact match. Parameters states, attributes, roles, and repoid may be empty sets.

Parameters:
rule The MatchRule which determines which children should be returned.
sortby The order in which the resulting AccessibleSet should be returned.
recurse If TRUE, the search will recurse into the sub-containers and may potentially include 'grandchildren' and their descendants. If FALSE, only immediate children will be tested against the match criteria.
count If >= 0, the maximum length of the sequence which should be returned to the caller. If -1, the caller may receive a sequence of any length. On successful completion, this parameter will be back-filled with the total number of matching elements (_not_ the number of elements in the returned list); this means that a value of 0 may be used to obtain the length of the complete match list. As a special case, if this param is backfilled with '-1', it means that the length of the resulting collection is either unbounded or unknown to the service being interrogated; in this case the client should supply an upper length bound in count and use multiple calls to getNextChildren to traverse the Collection.
Returns:
an AccessibleSet consisting of children which meet the criteria, or NIL if no matching objects were found in the AccessibleSet.

AccessibleSet Accessibility::Collection::getPreviousChildren (  in Accessible  current_object,
in MatchRule  rule,
in SortOrder  sortby,
in boolean  recurse,
inout long  count
) 
 

Find a list of the previous elements in a collection which match a particular search criterion, relative to a subelement of the specified container.

Note:
For applications interested in an entire ordered list from a collection, getChildren API is more efficient; getPreviousMatch is primarily intended for navigation from the user's current point of regard or keyboard focus.
Parameters:
current_object the Accessibility::Accessible within the Collection which forms one boundary for the search set; only objects which precede this object in the requested sortby sort order will be returned. If the specified sortby order does not apply to current_object (for instance if SORT_ORDER_TAB has been requested, but current_object is not in the tab sequence), then SORT_ORDER_CANONICAL will be used to determine the "previous" matching element for the purposes of bounding the returned set. The returned set, thus bounded, will however respect the sortby order requested by the user.
rule The match criteria which determines what constitutes a 'match'.
sortby The order in which the resulting AccessibleSet should be returned.
recurse If TRUE, the search will recurse into the sub-containers and may potentially include 'grandchildren' and their descendants. If FALSE, only siblings and immediate children will be tested against the match criteria.
count If >= 0, the maximum length of the sequence which should be returned to the caller. If -1, the caller may receive a sequence of any length. On successful completion, this parameter will be back-filled with the total number of matching elements (_not_ the number of elements in the returned list); this means that a value of 0 may be used to obtain the length of the complete match list. As a special case, if this param is backfilled with '-1', it means that the length of the resulting collection is either unbounded or unknown to the service being interrogated; in this case the client should supply an upper length bound in count and use multiple calls to getPreviousChildren to traverse the Collection.
Returns:
an AccessibleSet consisting of the elements in a collection which match a set of match criteria and which precede the given object, according to a specified sort order.

AccessibleSet Accessibility::Collection::getNextChildren (  in Accessible  current_object,
in MatchRule  rule,
in SortOrder  sortby,
in boolean  recurse,
inout long  count
) 
 

Find a list of the next elements in a collection which match a particular search criterion.

Note:
For applications interested in an entire ordered list from a collection, getChildren API is more efficient; getNextMatch is primarily intended for navigation from the user's current point of regard or keyboard focus.
Parameters:
current_object the Accessibility::Accessible within the Collection which forms one boundary for the search set; only objects which follow this object in the requested sortby sort order will be returned. If the specified sortby order does not apply to current_object (for instance if SORT_ORDER_TAB has been requested, but current_object is not in the tab sequence), then SORT_ORDER_CANONICAL will be used to determine the "previous" matching element for the purposes of bounding the returned set. The returned set, thus bounded, will however respect the sortby order requested by the user.
rule The match criteria which determines what constitutes a 'match'.
sortby The order in which the resulting AccessibleSet should be returned.
recurse If TRUE, the search will recurse into the sub-containers and may potentially include 'grandchildren' and their descendants. If FALSE, only siblings and immediate children will be tested against the match criteria.
count If >= 0, the maximum length of the sequence which should be returned to the caller. If -1, the caller may receive a sequence of any length. On successful completion, this parameter will be back-filled with the total number of matching elements (_not_ the number of elements in the returned list); this means that a value of 0 may be used to obtain the length of the complete match list. As a special case, if this param is backfilled with '-1', it means that the length of the resulting collection is either unbounded or unknown to the service being interrogated; in this case the client should supply an upper length bound in count and use multiple calls to getNextChildren to traverse the Collection.
Returns:
an AccessibleSet consisting of the elements in a collection which match a set of match criteria which follow the given object, according to a specified sort order.

Accessible Accessibility::Collection::getActiveDescendant (   ) 
 

Query an object for the current 'active descendant', i.e.

the descendant currently having STATE_ACTIVE and reacting to keyboard events. If the object being queried doesn't have state MANAGES_DESCENDANTS, this method will return NIL.

Returns:
: The currently active descendant, if there is one, otherwise NIL.

The documentation for this interface was generated from the following file:
Generated on Fri Dec 2 15:20:46 2005 for AT_SPI_IDL by  doxygen 1.4.3