2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001 Sun Microsystems Inc.
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
23 #ifndef _ACCESSIBILITY_RELATION_IDL
24 #define _ACCESSIBILITY_RELATION_IDL
26 module Accessibility {
29 * RelationType specifies a relationship between objects (possibly one-to-many or many-to-one)
30 * outside of the normal parent/child hierarchical relationship. It allows better semantic
31 * identification of how objects are associated with one another.
32 * For instance the RELATION_LABELLED_BY relationship may be used to identify labelling information
33 * that should accompany the accessibleName property when presenting an object's content or identity
34 * to the end user. Similarly, RELATION_CONTROLLER_FOR can be used to further specify the context
35 * in which a valuator is useful, and/or the other UI components which are directly effected by
36 * user interactions with the valuator. Common examples include association of scrollbars with
37 * the viewport or panel which they control.
40 /** Not a meaningful relationship; clients should not normally encounter this RelationType value. */
42 /** Object is a label for one or more other objects. */
44 /** Object is labelled by one or more other objects. */
46 /** Object is an interactive object which modifies the state, onscreen location, or other attributes
47 * of one or more target objects. */
48 RELATION_CONTROLLER_FOR,
49 /** Object state, position, etc. is modified/controlled by user interaction with one or
50 * more other objects. For instance a viewport or scroll pane may be CONTROLLED_BY scrollbars. */
51 RELATION_CONTROLLED_BY,
52 /** Object has a grouping relationship (e.g. ¨same group as¨) to one or more other objects. */
54 /** Object is a tooltip associated with another object. */
56 /** Reserved for future use. */
57 RELATION_NODE_CHILD_OF,
58 /** Used to indicate that a relationship exists, but its type is not specified in the enumeration
59 * and must be obtained via a call to getRelationTypeName. */
61 /** Object renders content which flows logically to another object.
62 * For instance, text in a paragraph may flow to another object which is not the
63 * ¨next sibling¨ in the accessibility hierarchy. */
65 /** Reciprocal of RELATION_FLOWS_TO. */
67 /** Object is visually and semantically considered a subwindow of another object, even though
68 * it is not the object's child. Useful when dealing with embedded applications and other cases
69 * where the widget hierarchy does not map cleanly to the onscreen presentation. */
70 RELATION_SUBWINDOW_OF,
71 /** Similar to SUBWINDOW_OF, but specifically used for cross-process embedding. */
73 /** Reciprocal of RELATION_EMBEDS; Used to denote content rendered by embedded renderers that
74 * live in a separate process space from the embedding context. */
76 /** Denotes that the object is a transient window or frame associated with another onscreen object.
77 * Similar to TOOLTIP_FOR, but more general. Useful for windows which are technically
78 * toplevels but which, for one or more reasons, do not explicitly cause their associated
79 * window to lose ¨window focus¨. Creation of a ROLE_WINDOW object with the POPUP_FOR relation
80 * usually requires some presentation action on the part of assistive technology clients, even though
81 * the previous toplevel ROLE_FRAME object may still be the active window. */
83 /** This is the reciprocal relation to RELATION_POPUP_FOR. */
84 RELATION_PARENT_WINDOW_OF,
85 /** Indicates that an object provides descriptive information
86 * about another object; more verbose than RELATION_LABEL_FOR. */
87 RELATION_DESCRIPTION_FOR,
88 /** Indicates that another object provides descriptive information
89 * about this object; more verbose than RELATION_LABELLED_BY. */
90 RELATION_DESCRIBED_BY,
91 /** Do not use as a parameter value, used to determine the size of the enumeration. */
96 * An interface via which objects' non-hierarchical relationships to one another
97 * are indicated. An instance of Relations represents a "one-to-many" correspondance.
99 * @note This interface inherits from a base class implementing ref counts.
101 interface Relation : Bonobo::Unknown {
103 /** @returns the RelationType of this Relation. */
104 RelationType getRelationType ();
106 /** @returns an unlocalized string representing the relation type. */
107 string getRelationTypeName ();
109 /** @returns the number of objects to which this relationship applies. */
110 short getNTargets ();
112 /** @returns an Object which is the 'nth'target of this Relation, e.g. the Object at index i
113 * in the list of Objects having the specified relationship to this Accessible.
114 * \note This target should always implement Accessible, though it is returned as an Object.
115 * (In this respect this method is probably ill-specified.)
117 Object getTarget (in short index);
119 /** \cond placeholders for future expansion */
120 void unImplemented ();
121 void unImplemented2 ();
122 void unImplemented3 ();
123 void unImplemented4 ();