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