1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27
28#ifndef __com_sun_star_accessibility_XAccessibleContext_idl__
29#define __com_sun_star_accessibility_XAccessibleContext_idl__
30
31#ifndef __com_sun_star_accessibility_IllegalAccessibleComponentStateException_idl__
32#include <com/sun/star/accessibility/IllegalAccessibleComponentStateException.idl>
33#endif
34
35#ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
36#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
37#endif
38
39#ifndef __com_sun_star_beans_XPropertyChangeListener_idl__
40#include <com/sun/star/beans/XPropertyChangeListener.idl>
41#endif
42
43#ifndef __com_sun_star_lang_Locale_idl__
44#include <com/sun/star/lang/Locale.idl>
45#endif
46
47module com { module sun { module star { module accessibility {
48
49 published interface XAccessible;
50 published interface XAccessibleRelationSet;
51 published interface XAccessibleSelection;
52 published interface XAccessibleStateSet;
53
54/** Implement this interface for exposing various aspects of a class'
55    content.
56
57    <p>This interface serves two purposes: On the one hand it gives access
58    to the tree structure in which all accessible objects are
59    organized. Each node in this tree supports this interface.  On the other
60    hand it gives access to objects that expose the represented content.
61    That are role, state, name, description, and relations to other objects.
62    Take an OK button of a dialog as an example.  Its role is
63    <const>AccessibleRole::BUTTON</const>, its name is 'OK', and its description
64    is something like 'Accepts all changes made in the dialog'.</p>
65
66    @since OOo 1.1.2
67*/
68published interface XAccessibleContext : ::com::sun::star::uno::XInterface
69{
70    /** Return the number of children.
71
72        <p>Returns the number of accessible children of the object.</p>
73
74        @return
75            The returned value is non-negative.
76    */
77    long getAccessibleChildCount();
78
79    /** Returns the i-th child of this object.
80
81        <p>The order in which the children are enumerated is implementation
82        dependend.</p>
83
84        @param i
85            The index may have any value.  If it is outside the range from 0
86            to n-1, with n being the number of children as returned by
87            <member>XAccessibleContext::getAccessibleChild</member> an empty
88            reference is returned.
89        @return
90            If the object has an i-th child the returned value is a
91            reference to that child.  Otherwise an empty reference is
92            returned.
93        @throws ::com::sun::star::lang::IndexOutOfBoundsException
94            If no child with the given index exists then an
95            <type scope="::com::sun::star::lang">IndexOutOfBoundsException</type>
96            exception is thrown.
97    */
98    XAccessible getAccessibleChild ([in] long i)
99        raises (::com::sun::star::lang::IndexOutOfBoundsException);
100
101    /** Returns the parent of this object.
102
103        <p>This function may be called for every node, including the root
104        node, of the accessible tree.</p>
105
106        @return
107            The returned reference points to a valid object for all but the
108            root node.  If called for the root node an empty reference is
109            returned.
110    */
111    XAccessible getAccessibleParent ();
112
113    /** Returns the index of this object in its accessible parent.
114
115        <p>If you call getAccessibeChild on the object's parent with the
116        index returned by this function you get a reference to this
117        object.</p>
118
119        @return
120           The returned index is zero based.
121    */
122    long getAccessibleIndexInParent ();
123
124    /** Returns the role of this object.
125
126        <p>The role is a generic description of an objects function.  The
127        relation between role and name is similar to the relation between
128        class and object.</p>
129
130        @return
131            The returned value is a role defined in the enumeration
132            AccessibleRole.
133
134        @see AccessibleRole
135            for a list of the available roles.
136    */
137    short getAccessibleRole ();
138
139    /** Returns the object's description.
140
141        <p>Returns the object's localized description.  The description should
142        complement the more generic descriptions given by an object's role
143        and name.</p>
144
145        @return
146            The returned string is the object's localized description.
147    */
148    string getAccessibleDescription ();
149
150    /** Return the object's localized name.
151
152        <p>See <member>XAccessibleContext::getAccessibleRole</member>'s
153        documentation for the relation between an object's name and role.
154        Names should be unique, at least between children of the same
155        parent, although the uniqueness is neither enforced nor used inside
156        the API.</p>
157
158        @return
159            The returned string is the object's localized name.
160    */
161    string  getAccessibleName ();
162
163    /** Returns the set of relations defined for this object.
164
165        <p>The returned set of relations is a copy of this objects relation
166        set: changing the returned object does not change this objects
167        relations.</p>
168
169        <p>aThere are two ways to represent an empty list of relations:
170        Return an empty reference or return a valid object that contains an
171        empty list.
172
173        @return
174           The returned value is either an empty referece or a reference to
175           a valid object that represents a copy of the objects list of
176           relations.
177    */
178    XAccessibleRelationSet getAccessibleRelationSet ();
179
180    /** Returns the set of states that are currently active for this
181        object.
182
183        <p>The returned state set is a copy: Changing the returned state set
184        will not be refelected by changing the object's set of states.  See
185        the documentation of <type>XAccessibleStateSet</type> for a
186        description of the individual states.</p>
187
188        @return
189            A reference to this object's state set or an empty reference if
190            states are not supported.
191
192        @see XAccessibleStateSet
193    */
194    XAccessibleStateSet getAccessibleStateSet ();
195
196    /** Returns the locale of the component.
197
198        <p>This locale is used for example to determine the language to use
199        for the name and description texts.</p>
200
201        @return
202            If this object does not have a locale, the locale of its parent
203            is returned.  If it does not have (yet) a parent it throws the
204            exception <type>IllegalAccessibleComponentStateException</type>.
205
206        @throws IllegalAccessibleComponentStateException
207            when this object does not (yet) have a parent.
208    */
209    ::com::sun::star::lang::Locale getLocale ()
210        raises (IllegalAccessibleComponentStateException);
211};
212
213}; }; }; };
214
215#endif
216