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_XAccessibleTable_idl__
29#define __com_sun_star_accessibility_XAccessibleTable_idl__
30
31#ifndef __com_sun_star_uno_XInterface_idl__
32#include <com/sun/star/uno/XInterface.idl>
33#endif
34#ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
35#include <com/sun/star/lang/IndexOutOfBoundsException.idl>
36#endif
37
38module com { module sun { module star { module accessibility {
39
40 published interface XAccessible;
41
42/** Implement this interface to give access to a two-dimensional table.
43
44   <p>The <type>XAccessibleTable</type> interface is used to represent
45   two-dimensional tables.  This interface combines the two interfaces
46   <code>javax.accessibility.AccessibleTable</code> and
47   <code>javax.accessibility.AccessibleExtendedTable</code> of the Java Accessibility API
48   (version 1.4).</p>
49
50   <p>All <type>XAccessible</type> objects that represent cells or
51   cell-clusters of a table have to be at the same time children of the
52   table.  This is necessary to be able to convert row and column indices
53   into child indices and vice versa with the methods
54   <member>XAccessibleTable::getAccessibleIndex</member>,
55   <member>XAccessibleTable::getAccessibleRow</member>, and
56   <member>XAccessibleTable::getAccessibleColumn</member>.</p>
57
58   <p>The range of valid coordinates for this interface are implementation
59   dependent.  However, that range includes at least the intervals from the
60   from the first row or column with the index 0 up to the last (but not
61   including) used row or column as returned by
62   <member>XAccessibleTable::getAccessibleRowCount</member> and
63   <member>XAccessibleTable::getAccessibleColumnCount</member>.  In case of
64   the Calc the current range of valid indices for retrieving data include
65   the maximal table size--256 columns and 32000 rows--minus one.</p>
66
67    @since OOo 1.1.2
68*/
69published interface XAccessibleTable : ::com::sun::star::uno::XInterface
70{
71    /** Returns the number of used rows in the table.
72
73        <p>The implementation, however, may allow the access of columns
74        beyond this number.</p>
75
76        @return
77            Returns the number of used rows in the table or 0 for an empty
78            table.
79    */
80    long getAccessibleRowCount ();
81
82    /** Returns the number of used columns in the table.
83
84        <p>The implementation, however, may allow the access of columns
85        beyond this number.</p>
86
87        @return
88            Returns the number of used columns in the table or 0 for an empty
89            table.
90    */
91    long getAccessibleColumnCount ();
92
93    /** Returns the description text of the specified row in the
94        table.
95
96        @param nRow
97            The index of the row for which to retrieve the description.
98
99        @return
100            Returns the description text of the specified row in the table
101            if such a description exists.  Otherwise an empty string is
102            returned.
103        @throws ::com::sun::star::lang::IndexOutOfBoundsException
104            if the specified row index is not valid, i.e. lies not inside
105            the valide range of 0 up to
106            <member>XAccessibleTable::getAccessibleRowCount()</member> - 1.
107
108    */
109    string getAccessibleRowDescription ([in] long nRow)
110        raises (::com::sun::star::lang::IndexOutOfBoundsException);
111
112    /** Returns the description text of the specified column in the
113        table.
114
115        @param nColumn
116            The index of the column for which to retrieve the description.
117
118        @return
119            Returns the description text of the specified row in the table
120            if such a description exists.  Otherwise an empty string is
121            returned.
122        @throws ::com::sun::star::lang::IndexOutOfBoundsException
123            if the specified column index is not valid, i.e. lies not inside
124            the valide range of 0 up to
125            <member>XAccessibleTable::getAccessibleColumnCount()</member> - 1.
126	*/
127    string getAccessibleColumnDescription ([in] long nColumn)
128        raises (::com::sun::star::lang::IndexOutOfBoundsException);
129
130    /** Returns the number of rows occupied by the Accessible at the
131        specified row and column in the table.
132
133        <p>The result differs from 1 if the specified cell spans multiple
134        rows.</p>
135
136        @param nRow
137            Row index of the accessible for which to return the column
138            extent.
139
140        @param nColumn
141            Column index of the accessible for which to return the column
142            extent.
143
144        @return
145            Returns the row extent of the specified cell.
146
147        @throws ::com::sun::star::lang::IndexOutOfBoundsException
148            if the specified row index is not valid, i.e. lies not inside
149            the valide range of 0 up to
150            <member>XAccessibleTable::getAccessibleRowCount()</member> - 1.
151    */
152    long getAccessibleRowExtentAt ([in] long nRow, [in] long nColumn)
153        raises (::com::sun::star::lang::IndexOutOfBoundsException);
154
155    /** Returns the number of columns occupied by the Accessible at the
156        specified row and column in the table.
157
158        <p>The result differs from 1 if the specified cell spans multiple
159        columns.</p>
160
161        @param nRow
162            Row index of the accessible for which to return the column
163            extent.
164
165        @param nColumn
166            Column index of the accessible for which to return the column
167            extent.
168
169        @return
170            Returns the column extent of the specified.
171
172        @throws ::com::sun::star::lang::IndexOutOfBoundsException
173            if the specified column index is not valid, i.e. lies not inside
174            the valide range of 0 up to
175            <member>XAccessibleTable::getAccessibleColumnCount()</member> - 1.
176    */
177    long getAccessibleColumnExtentAt ([in] long nRow, [in] long nColumn)
178        raises (::com::sun::star::lang::IndexOutOfBoundsException);
179
180    /** Returns the row headers as an <type>XAccessibleTable</type>
181        object.
182
183        <p>Content and size of the returned table are implementation
184        dependent.</p>
185
186        @return
187            Returns allways a valid reference to an
188            <type>XAccessibleTable</type> object.
189    */
190    XAccessibleTable getAccessibleRowHeaders ();
191
192    /** Returns the column headers as an <type>XAccessibleTable</type>
193        object.
194
195        <p>Content and size of the returned table are implementation
196        dependent.</p>
197
198        @return
199            Returns allways a valid reference to an
200            <type>XAccessibleTable</type> object.
201    */
202    XAccessibleTable getAccessibleColumnHeaders ();
203
204    /** Returns a list of the indices of completely selected rows in a
205        table.
206
207        @return
208            The returned sequence contains indices of all completely
209            selected rows in the table.  This sequence is in ascending
210            order.  If no row is selected then the sequence is empty.
211    */
212    sequence<long> getSelectedAccessibleRows ();
213
214    /** Returns a list of the indices of completely selected columns in a
215        table.
216
217        @return
218            The returned sequence contains indices of all completely
219            selected columns in the table.  This sequence is in ascending
220            order.  If no column is selected then the sequence is empty.
221    */
222    sequence<long> getSelectedAccessibleColumns ();
223
224    /** Returns a boolean value indicating whether the specified row is
225        completely selected.
226
227        @param nRow
228            Index of the row for which to determine whether it is selected.
229
230        @return
231            Returns <TRUE/> if the specified row is selected completely and
232            <FALSE/> otherwise.
233
234        @throws ::com::sun::star::lang::IndexOutOfBoundsException
235            if the specified row index is not valid, i.e. lies not inside
236            the valide range of 0 up to
237            <member>XAccessibleTable::getAccessibleRowCount()</member> - 1.
238    */
239    boolean isAccessibleRowSelected ([in] long nRow)
240        raises (::com::sun::star::lang::IndexOutOfBoundsException);
241
242    /** Returns a boolean value indicating whether the specified column
243        is completely selected.
244
245        @param nColumn
246            Index of the column for which to determine whether it is
247            selected.
248
249        @return
250            Returns <TRUE/> if the specified column is selected completely
251            and <FALSE/> otherwise.
252
253        @throws ::com::sun::star::lang::IndexOutOfBoundsException
254            if the specified column index is not valid, i.e. lies not inside
255            the valide range of 0 up to
256            <member>XAccessibleTable::getAccessibleColumnCount()</member> - 1.
257    */
258    boolean isAccessibleColumnSelected ([in] long nColumn)
259        raises (::com::sun::star::lang::IndexOutOfBoundsException);
260
261    /** Returns the <type>XAccessible</type> object at the specified row
262        and column in the table.
263
264        <p>This method has been renamed from the Java name
265        <code>getAccessibleAt</code> to
266        <member>XAccessibleTable::getAccessibleCellAt</member> to avoid
267        ambiguities with the
268        <member>XAccessibleComponent::getAccessibleAt</member> method when
269        accessed, for instance, from StarBasic.</p>
270
271        @param nRow
272            The row index for which to retrieve the cell.
273
274        @param nColumn
275            The column index for which to retrieve the cell.
276
277        @return
278            If both row and column index are valid then the corresponding
279            <type>XAccessible</type> object is returned that represents the
280            requested cell regardless of whether the cell is currently
281            visible (on the screen).
282
283        @throws ::com::sun::star::lang::IndexOutOfBoundsException
284            if the specified column and/or row index is not valid, i.e. lies not inside
285            the valide range of 0 up to
286            <member>XAccessibleTable::getAccessibleColumnCount()</member> - 1.
287    */
288    XAccessible getAccessibleCellAt ([in] long nRow, [in] long nColumn)
289        raises (::com::sun::star::lang::IndexOutOfBoundsException);
290
291    /** Returns the caption for the table.
292
293        @return
294            If the table has a caption then a reference to it is returned,
295            else an empty reference is returned.
296    */
297    XAccessible getAccessibleCaption ();
298
299    /** Returns the summary description of the table.
300
301        @return
302            Returns a reference to an implementation dependent
303            <type>XAccessible</type> object representing the table's summary
304            or an empty reference if the table does not support a summary.
305    */
306    XAccessible getAccessibleSummary ();
307
308    /** Returns a boolean value indicating whether the accessible at the
309        specified row and column is selected.
310
311        @param nRow
312            Row index of the cell for which to determine if the accessible
313            object that spans that cell is selected.
314
315        @param nColumn
316            Column index of the cell for which to determine if the
317            accessible object that spans that cell is selected.
318
319        @return
320            Returns <TRUE/> if the given row and column indices are valid
321            and the specified accessible object is selected.  Otherwise
322            <FALSE/> is returned.
323    */
324    boolean isAccessibleSelected ([in] long nRow, [in] long nColumn)
325        raises (::com::sun::star::lang::IndexOutOfBoundsException);
326
327    /** Returns the child index of the accessible object that spans the
328        specified cell.
329
330        <p>This is the same index that would be returned by calling
331        <member>XAccessibleContext::getAccessibleIndexInParent</member> for
332        that accessible object.</p>
333
334        @param nRow
335            Row index of the accessible object for which to return the child
336            index.
337
338        @param nColumn
339            Row index of the accessible object for which to return the child
340            index.
341
342        @return
343            Child index of the specified accessible object or -1 if one or
344            both of the given indices is/are invalid.
345    */
346    long getAccessibleIndex ([in] long nRow, [in] long nColumn)
347        raises (::com::sun::star::lang::IndexOutOfBoundsException);
348
349    /** Translate the given child index into the corresponding row
350        index.
351
352        @param nChildIndex
353            Index of the child of the table for which to return the row
354            index.
355
356        @return
357            Returns the row index of the cell of the specified child or the
358            index of the first row if the child spans multiple rows.
359
360        @throws ::com::sun::star::lang::IndexOutOfBoundsException
361            if nChildIndex addresses an invalid row.
362    */
363    long getAccessibleRow ([in] long nChildIndex)
364        raises (::com::sun::star::lang::IndexOutOfBoundsException);
365
366    /** Translate the given child index into the corresponding column
367        index.
368
369        @param nChildIndex
370            Index of the child of the table for which to return the column
371            index.
372
373        @return
374            Returns the column index of the cell of the specified child or
375            the index of the first column if the child spans multiple
376            columns.
377
378        @throws ::com::sun::star::lang::IndexOutOfBoundsException
379            if nChildIndex addresses an invalid column.
380    */
381    long getAccessibleColumn ([in] long nChildIndex)
382        raises (::com::sun::star::lang::IndexOutOfBoundsException);
383};
384
385}; }; }; };
386
387#endif
388