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_ACCESSIBLE_IDL
24 #define _ACCESSIBILITY_ACCESSIBLE_IDL
26 #include "Accessibility_Relation.idl"
27 #include "Accessibility_State.idl"
28 #include "Accessibility_Role.idl"
30 module Accessibility {
32 /** used by Text and Document: these correspond to the POSIX setlocale() enum values. **/
42 /** A list of Relations, which may be many-to-many. */
43 typedef sequence<Relation> RelationSet;
46 * A list of name-value pairs, returned as a sequence of strings;
47 * the name and value are separated by a colon.
48 * @note "Attributes" returned in AttributeSet lists are distinct from,
49 * and should not be confused with, "attribute" members of interfaces
50 * as defined by the IDL "attribute" keyword. IDL attributes are
51 * strongly-typed values which are individually obtained via
52 * language-specific bindings whose syntax is dictated by the OMG's
53 * IDL language bindings. For instance using the C language,
54 * the "Accessible::name" attribute is queried using
55 * \c Accessibility_Accessible__get_name (obj, &ev);
56 * Name-value pairs associated with Accessible instances are not
57 * normally redundant with these IDL attributes, i.e. there is no
58 * "accessible-name" attribute in the AttributeSet returned from
59 * Accessible::getAttributes().
61 * Where possible, the names and values in the name-value pairs
62 * should be chosen from well-established attribute namespaces
63 * using standard semantics. For example, metadata namespace and
64 * values should be chosen from the 'Dublin Core' Metadata
65 * namespace using Dublin Core semantics:
66 * http://dublincore.org/dcregistry/
67 * Similarly, relevant structural metadata should be exposed
68 * using attribute names and values chosen from the CSS2 and WICD specification:
69 * http://www.w3.org/TR/1998/REC-CSS2-19980512
70 * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
72 * Finally, note that typographic, semantic, and presentational annotations which
73 * are associated with text content, in particular which are associated with particular
74 * text ranges, should be exposed via Accessibility::Text::getAttributeRun instead of
75 * via these more general 'Object attributes'.
79 typedef sequence<string> AttributeSet;
82 * A list of accessible roles
85 typedef sequence<Role> RoleSet;
87 /** Used by Component and Text, a struct defining a bounding rectangle.
88 * The relevant coordinate system is determined by the context of the
89 * API call which returned or receives the value.
92 long x; /**< the value corresponding to the minimum or leftmost x position. */
93 long y; /**< the value corresponding to the minimum y value. */
94 long width; /**< the horizontal extent of the bounding box,
95 * that is, the difference between the maximum and minimum
96 * x coordinate bounds.
98 long height; /**< the vertical extent of the bounding box,
99 * that is, the difference between the maximum and minimum
100 * y coordinate bounds.
105 interface Application; /**< defined in Accessibility_Application.idl **/
108 * The base interface which is implemented by all accessible objects.
109 * All objects support interfaces for querying their contained 'children'
110 * and position in the accessible-object hierarchy, whether or not they
111 * actually have children.
113 * @note Events that may be emitted by instances of Accessible include:
114 * \li \c "object:property-change" A base (strongly-typed) object attribute has changed,
115 * for instance "object:property-change:accessible-name".
116 * Notifed property subtypes include accessible-name, accessible-description,
117 * and accessible-parent.
119 * \li \c "object:children-changed" The number or identity of an object's children
121 * \li \c "object:state-changed" The object's StateSet has had a state added
123 * \li \c "object:active-descendant-changed" If the object includes
124 * STATE_MANAGES_DESCENDANTS, this event is fired to indicate that the
125 * descendant having STATE_ACTIVE has changed; this corresponds to
126 * "micro" keyboard focus when the containing/emitting object has
127 * "macro" or technical keyboard focus. For instance, this event is
128 * usually emitted while traversing tables and/or spreadsheet cells.
129 * \li \c "object:attribute-change" A weakly-typed property, as contained in the
130 * AttributeSet returned by Accessible::getAttributes, has changed in value,
131 * been added, or been removed from the object.
132 * ("object:attribute-change" notifications were added in AT-SPI 1.7.0)
134 interface Accessible : Bonobo::Unknown {
137 * a (short) \c string representing the object's name.
139 attribute string name;
142 * a \c string describing the object in more detail than \a name.
144 attribute string description;
147 * an ::Accessible object which is this object's containing object.
149 readonly attribute Accessibility::Accessible parent;
152 * childCount: the number of children contained by this object.
154 readonly attribute long childCount;
157 * Determine whether an ::Accessible refers to the same object as another.
158 * This method should be used rather than brute-force comparison of
159 * object references (i.e. "by-value" comparison), as two object references
160 * may have different apparent values yet refer to the same object.
162 * @param obj: an ::Accessible object reference to compare to
163 * @returns: a \c boolean indicating whether the two object references
164 * point to the same object.
166 boolean isEqual (in Accessible obj);
169 * Get the accessible child of this object at \c index.
170 * @param index: an in parameter indicating which child is requested (zero-indexed).
171 * @returns: the 'nth' ::Accessible child of this object.
173 Accessible getChildAtIndex (in long index);
176 * Get the index of this object in its parent's child list.
177 * @returns: a long integer indicating this object's index in the parent's list.
179 long getIndexInParent ();
182 * Get a set defining this object's relationship to other accessible objects.
183 * @returns: a ::RelationSet defining this object's relationships.
185 RelationSet getRelationSet ();
188 * Get the ::Role indicating the type of UI role played by this object.
190 * @returns: a ::Role indicating the type of UI role played by this object.
195 * Get a string indicating the type of UI role played by this object.
197 * @returns: a UTF-8 string indicating the type of UI role played by this object.
199 string getRoleName ();
202 * Get a string indicating the type of UI role played by this object,
203 * translated to the current locale.
205 * @returns: a UTF-8 string indicating the type of UI role played by this object.
207 string getLocalizedRoleName ();
210 * Get the current state of the object as a ::StateSet.
211 * @returns: a ::StateSet encapsulating the currently true states of the object.
213 StateSet getState ();
216 * Get a list of properties applied to this object as a whole, as an
217 * ::AttributeSet consisting of name-value pairs. As such these attributes
218 * may be considered weakly-typed properties or annotations, as distinct
219 * from the strongly-typed interface instance data declared using the IDL
220 * "attribute" keyword.
222 * Not all objects have explicit "name-value pair" AttributeSet properties.
224 * Attribute names and values may have any UTF-8 string value, however where possible,
225 * in order to facilitate consistent use and exposure of "attribute" properties by
226 * applications and AT clients, attribute names and values should chosen from
227 * a publicly-specified namespace where appropriate.
229 * Where possible, the names and values in the name-value pairs
230 * should be chosen from well-established attribute namespaces
231 * using standard semantics.
232 * For example, attributes of ::Accessible objects corresponding to XHTML content
233 * elements should correspond to attribute names and values specified in the w3c
234 * XHTML specification, at http://www.w3.org/TR/xhtml2, where such values are not
235 * already exposed via a more strongly-typed aspect of the AT-SPI API.
237 * values should be chosen from the 'Dublin Core' Metadata
238 * namespace using Dublin Core semantics:
239 * http://dublincore.org/dcregistry/
240 * Similarly, relevant structural metadata should be exposed
241 * using attribute names and values chosen from the CSS2 and WICD specification:
242 * http://www.w3.org/TR/1998/REC-CSS2-19980512
243 * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).
245 * @note Clients seeking semantic or typographical attributes associated with
246 * specific character spans of text content should use ::Text::getAttributeRun instead.
247 * The attributes returned by Accessible::getAttributes do not include
250 * @see ::Accessibility::Text::getAttributeRun
252 * @returns: an ::AttributeSet encapsulating any "attribute values" currently
253 * defined for the object.
255 * @since AT-SPI 1.7.0
257 AttributeSet getAttributes ();
260 * Get the containing Application for this object.
262 * @returns the Application instance to which this object belongs.
263 * @since AT-SPI 1.7.0
265 Application getApplication ();
267 /** /cond future expansion */
268 void unimplemented ();