Accessible.xml: document the GetRelationSet method

Copied the documentation from AtspiRelationType.

Also, put the order of descriptions for AtspiRelationType in the same
order as the enum values; DESCRIPTION_FOR was incorrectly below
ERROR_MESSAGE.

1 files changed, 123 insertions, 0 deletions

diff --git a/xml/Accessible.xml b/xml/Accessible.xml
index ad6d7d9e..c8fd8e0f 100644
--- a/xml/Accessible.xml
+++ b/xml/Accessible.xml
@@ -119,6 +119,129 @@
       <arg direction="out" type="i"/>
     </method>
 
+    <!--
+        GetRelationSet:
+
+        Returns a set of relationships between the current object and others.  Each
+        element in the outermost array contains a number that indicates the relation type
+        (see below), and an array of references to accessible objects to which that
+        relationship applies.  Each element in the inner array is a (so) with a string for
+        the application name, and an object path.
+
+        Each relationship between objects (possibly one-to-many or many-to-one) allows
+        better semantic identification of how objects are associated with one another.
+        For instance, the ATSPI_RELATION_LABELLED_BY relationship may be used to identify
+        labelling information that should accompany the accessible name property when
+        presenting an object's content or identity to the end user.  Similarly,
+        ATSPI_RELATION_CONTROLLER_FOR can be used to further specify the context in which
+        a valuator is useful, and/or the other UI components which are directly effected
+        by user interactions with the valuator. Common examples include association of
+        scrollbars with the viewport or panel which they control.
+
+        Relation types - these are the enum values from AtspiRelationType in atspi-constants.h:
+
+        0 - ATSPI_RELATION_NULL: Not a meaningful relationship; clients should not
+            normally encounter this value.
+
+        1 - ATSPI_RELATION_LABEL_FOR: Object is a label for one or more other objects.
+
+        2 - ATSPI_RELATION_LABELLED_BY: Object is labelled by one or more other
+            objects.
+
+        3 - ATSPI_RELATION_CONTROLLER_FOR: Object is an interactive object which
+            modifies the state, onscreen location, or other attributes of one or more
+            target objects.
+
+        4 - ATSPI_RELATION_CONTROLLED_BY: Object state, position, etc. is
+            modified/controlled by user interaction with one or more other objects.
+            For instance a viewport or scroll pane may be ATSPI_RELATION_CONTROLLED_BY
+            scrollbars.
+
+        5 - ATSPI_RELATION_MEMBER_OF: Object has a grouping relationship (e.g. 'same
+            group as') to one or more other objects.
+
+        6 - ATSPI_RELATION_TOOLTIP_FOR: Object is a tooltip associated with another
+            object.
+
+        7 - ATSPI_RELATION_NODE_CHILD_OF: Object is a child of the target.
+
+        8 - ATSPI_RELATION_NODE_PARENT_OF: Object is a parent of the target.
+
+        9 - ATSPI_RELATION_EXTENDED: Used to indicate that a relationship exists, but
+           its type is not specified in the enumeration.
+
+        10 - ATSPI_RELATION_FLOWS_TO: Object renders content which flows logically to
+             another object. For instance, text in a paragraph may flow to another
+             object which is not the 'next sibling' in the accessibility hierarchy.
+
+        11 - ATSPI_RELATION_FLOWS_FROM: Reciprocal of ATSPI_RELATION_FLOWS_TO.
+
+        12 - ATSPI_RELATION_SUBWINDOW_OF: Object is visually and semantically considered
+             a subwindow of another object, even though it is not the object's child.
+             Useful when dealing with embedded applications and other cases where the
+             widget hierarchy does not map cleanly to the onscreen presentation.
+
+        13 - ATSPI_RELATION_EMBEDS: Similar to ATSPI_RELATION_SUBWINDOW_OF, but
+             specifically used for cross-process embedding.
+
+        14 - ATSPI_RELATION_EMBEDDED_BY: Reciprocal of ATSPI_RELATION_EMBEDS. Used to
+             denote content rendered by embedded renderers that live in a separate process
+             space from the embedding context.
+
+        15 - ATSPI_RELATION_POPUP_FOR: Denotes that the object is a transient window or
+             frame associated with another onscreen object. Similar to ATSPI_TOOLTIP_FOR,
+             but more general. Useful for windows which are technically toplevels
+             but which, for one or more reasons, do not explicitly cause their
+             associated window to lose 'window focus'. Creation of an ATSPI_ROLE_WINDOW
+             object with the ATSPI_RELATION_POPUP_FOR relation usually requires
+             some presentation action on the part of assistive technology clients,
+             even though the previous toplevel ATSPI_ROLE_FRAME object may still be
+             the active window.
+
+        16 - ATSPI_RELATION_PARENT_WINDOW_OF: This is the reciprocal relation to
+             ATSPI_RELATION_POPUP_FOR.
+
+        17 - ATSPI_RELATION_DESCRIPTION_FOR: Reciprocal of ATSPI_RELATION_DESCRIBED_BY.
+             Indicates that this object provides descriptive information about the target
+             object(s). See also ATSPI_RELATION_DETAILS_FOR and ATSPI_RELATION_ERROR_FOR.
+
+        18 - ATSPI_RELATION_DESCRIBED_BY: Reciprocal of ATSPI_RELATION_DESCRIPTION_FOR.
+             Indicates that one or more target objects provide descriptive information
+             about this object. This relation type is most appropriate for information
+             that is not essential as its presentation may be user-configurable and/or
+             limited to an on-demand mechanism such as an assistive technology command.
+             For brief, essential information such as can be found in a widget's on-screen
+             label, use ATSPI_RELATION_LABELLED_BY. For an on-screen error message, use
+             ATSPI_RELATION_ERROR_MESSAGE. For lengthy extended descriptive information
+             contained in an on-screen object, consider using ATSPI_RELATION_DETAILS as
+             assistive technologies may provide a means for the user to navigate to
+             objects containing detailed descriptions so that their content can be more
+             closely reviewed.
+
+        19 - ATSPI_RELATION_DETAILS: Reciprocal of ATSPI_RELATION_DETAILS_FOR. Indicates
+             that this object has a detailed or extended description, the contents of
+             which can be found in the target object(s). This relation type is most
+             appropriate for information that is sufficiently lengthy as to make
+             navigation to the container of that information desirable. For less verbose
+             information suitable for announcement only, see ATSPI_RELATION_DESCRIBED_BY.
+             If the detailed information describes an error condition,
+             ATSPI_RELATION_ERROR_FOR should be used instead.  Since 2.26.
+
+        20 - ATSPI_RELATION_DETAILS_FOR: Reciprocal of ATSPI_RELATION_DETAILS. Indicates
+             that this object provides a detailed or extended description about the target
+             object(s). See also ATSPI_RELATION_DESCRIPTION_FOR and ATSPI_RELATION_ERROR_FOR.
+             Since 2.26.
+
+        21 - ATSPI_RELATION_ERROR_MESSAGE: Reciprocal of ATSPI_RELATION_ERROR_FOR.
+             Indicates that this object has one or more errors, the nature of which is
+             described in the contents of the target object(s). Objects that have this
+             relation type should also contain ATSPI_STATE_INVALID_ENTRY when their
+             GetState method is called.  Since: 2.26.
+
+        22 - ATSPI_RELATION_ERROR_FOR: Reciprocal of ATSPI_RELATION_ERROR_MESSAGE.
+             Indicates that this object contains an error message describing an invalid
+             condition in the target object(s). Since: 2.26.
+    -->
     <method name="GetRelationSet">
       <arg direction="out" type="a(ua(so))"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.Out0" value="QSpiRelationArray"/>