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 #include <Accessibility_Accessible.idl>
25 module Accessibility {
27 typedef sequence<long> LongSeq;
30 * An interface used by containers whose contained data is arranged in
31 * a "tabular" (i.e.\ row-column) fashion. Tables may resemble a two-dimensional
32 * grid, as in a spreadsheet, or may feature objects which span multiple rows and/or
33 * columns, but whose bounds are aligned on a row/column matrix. Thus, the Table
34 * interface may be used to represent "spreadsheets" as well as "frames".
36 * Objects within tables are children of the Table instance, and they may be referenced
37 * either via a child index or via a row/column pair.
38 * Their role may be ROLE_TABLE_CELL, but table 'cells' may have other roles as well.
39 * These 'cells' may implement other interfaces, such as Text, Action, Image,
40 * and Component, and should do so as appropriate to their onscreen representation
43 interface Table : Bonobo::Unknown {
45 * The total number of rows in this table (including empty rows),
46 * exclusive of any rows which are programmatically hidden.
47 * Rows which are merely scrolled out of view are included.
49 readonly attribute long nRows;
51 * The total number of columns in this table (including empty columns),
52 * exclusive of columns which are programmatically hidden.
53 * Columns which are scrolled out of view or clipped by the current
54 * viewport are included.
56 readonly attribute long nColumns;
58 * An Accessible which represents of a caption for a Table.
60 readonly attribute Accessible caption;
62 * An accessible object which summarizes the contents of a Table.
63 * This object is frequently itself a Table instance, albeit a simplified one.
65 readonly attribute Accessible summary;
67 * The number of rows currently selected.
68 * A selected row is one in which all included cells are selected.
69 * @note Not all tables support row selection.
71 readonly attribute long nSelectedRows;
73 * The number of columns currently selected.
74 * A selected column is one in which all included cells are selected.
75 * @note Not all tables support column selection.
77 readonly attribute long nSelectedColumns;
79 * Get the table cell at the specified row and column indices.
80 * @note To get the accessible object at a particular (x, y) screen coordinate,
81 * use Accessible::getAccessibleAtPoint ().
83 * @param row: the specified table row, zero-indexed.
84 * @param column: the specified table column, zero-indexed.
86 * @returns an Accessible object representing the specified table cell.
88 Accessible getAccessibleAt (in long row, in long column);
90 * Get the 1-D child index corresponding to the specified 2-D row and column indices.
91 * @note To get the accessible object at a particular (x, y) screen coordinate,
92 * use Accessible::getAccessibleAtPoint.
94 * @param row: the specified table row, zero-indexed.
95 * @param column: the specified table column, zero-indexed.
97 * @see getRowAtIndex, getColumnAtIndex
99 * @returns a long integer which serves as the index of a specified cell in the
100 * table, in a form usable by Accessible::getChildAtIndex.
102 long getIndexAt (in long row, in long column);
104 * Get the table row index occupied by the child at a particular 1-D child index.
106 * @param index: the specified child index, zero-indexed.
108 * @see getIndexAt(), getColumnAtIndex()
110 * @returns a long integer indicating the first row spanned by the child of a
111 * table, at the specified 1-D (zero-offset) \c index.
113 long getRowAtIndex (in long index);
115 * Get the table column index occupied by the child at a particular 1-D child index.
117 * @param index: the specified child index, zero-indexed.
119 * @see getIndexAt(), getRowAtIndex()
121 * @returns a long integer indicating the first column spanned by the child of a
122 * table, at the specified 1-D (zero-offset) \c index.
124 long getColumnAtIndex (in long index);
126 * Get a text description of a particular table row. This differs from
127 * AccessibleTable_getRowHeader, which returns an Accessible.
128 * @param row: the specified table row, zero-indexed.
130 * @returns a UTF-8 string describing the specified table row, if available.
132 string getRowDescription (in long row);
134 * Get a text description of a particular table column. This differs from
135 * AccessibleTable_getColumnHeader, which returns an Accessible.
136 * @param column: the specified table column, zero-indexed.
138 * @returns a UTF-8 string describing the specified table column, if available.
140 string getColumnDescription (in long column);
142 * Get the number of rows spanned by the table cell at the specific row and column.
143 * (some tables can have cells which span multiple rows and/or columns).
145 * @param row: the specified table row, zero-indexed.
146 * @param column: the specified table column, zero-indexed.
148 * @returns a long integer indicating the number of rows spanned by the specified cell.
150 long getRowExtentAt (in long row, in long column);
152 * Get the number of columns spanned by the table cell at the specific row and column.
153 * (some tables can have cells which span multiple rows and/or columns).
155 * @param row: the specified table row, zero-indexed.
156 * @param column: the specified table column, zero-indexed.
158 * @returns a long integer indicating the number of columns spanned by the
161 long getColumnExtentAt (in long row, in long column);
163 * Get the header associated with a table row, if available. This differs from
164 * getRowDescription, which returns a string.
166 * @param row: the specified table row, zero-indexed.
168 * @returns an Accessible representatin of the specified table row, if available.
170 Accessible getRowHeader (in long row);
172 * Get the header associated with a table column, if available, as an
173 * instance of Accessible. This differs from
174 * getColumnDescription, which returns a string.
176 * @param column: the specified table column, zero-indexed.
178 * @returns an Accessible representatin of the specified table column, if available.
180 Accessible getColumnHeader (in long column);
182 * Obtain the indices of all rows which are currently selected.
183 * @note Not all tables support row selection.
185 * @returns a sequence of integers comprising the indices of rows currently selected.
187 LongSeq getSelectedRows ();
189 * Obtain the indices of all columns which are currently selected.
190 * @note Not all tables support column selection.
192 * @returns a sequence of integers comprising the indices of columns currently selected.
194 LongSeq getSelectedColumns ();
196 * Determine whether a table row is selected.
197 * @note Not all tables support row selection.
199 * @param row: the row being queried.
201 * @returns \c True if the specified row is currently selected, \c False if not.
203 boolean isRowSelected (in long row);
205 * Determine whether a table column is selected.
206 * @note Not all tables support column selection.
208 * @param column: the column being queried.
210 * @returns \c True if the specified column is currently selected, \c False if not.
212 boolean isColumnSelected (in long column);
214 * Determine whether the cell at a specific row and column is selected.
215 * @param row a row occupied by the cell whose state is being queried.
216 * @param column a column occupied by the cell whose state is being queried.
218 * @returns \c True if the specified cell is currently selected,
221 boolean isSelected (in long row, in long column);
223 * Select the specified row, adding it to the current row selection,
224 * if the table's selection model permits it.
227 * @note Possible reasons for addRowSelection to return \c False
229 * \li The table does not support Selection
230 * \li The table row includes cells which do not have STATE_SELECTABLE
231 * \li The table does not support selection by row
232 * \li The table does not support selection of multiple rows, and
233 * one row is already selected.
234 * \li The table does not support non-contiguous selections (i.e.
235 * does not include STATE_MULTISELECTABLE), and the specified row
236 * would result in selection of non-contiguous rows.
237 * \li The table does not support user-instigated selection.
239 * @returns \c True if the specified row was successfully selected,
242 boolean addRowSelection (in long row);
244 * Select the specified column, adding it to the current column selection,
245 * if the table's selection model permits it.
248 * @note Possible reasons for addColumnSelection to return \c False
250 * \li The table does not support Selection
251 * \li The table column includes cells which do not have STATE_SELECTABLE
252 * \li The table does not support selection by column
253 * \li The table does not support selection of multiple columns, and
254 * one column is already selected.
255 * \li The table does not support non-contiguous selections (i.e.
256 * does not include STATE_MULTISELECTABLE), and the specified column
257 * would result in selection of non-contiguous columns.
258 * \li The table does not support user-instigated selection.
260 * @returns \c True if the specified column was successfully selected,
263 boolean addColumnSelection (in long column);
265 * Remove the specified row from current row selection,
266 * if the table's selection model permits it.
269 * @note Possible reasons for removeRowSelection to return \c False
271 * \li The table does not support user-instigated Selection
272 * \li The table has no selected rows or does not support deselection by row
274 * @returns \c True if the specified row was successfully de-selected,
277 boolean removeRowSelection (in long row);
279 * Remove the specified column from current column selection,
280 * if the table's selection model permits it.
283 * @note Possible reasons for removeColumnSelection to return \c False
285 * \li The table does not support user-instigated modification of
287 * \li The table has no selected columns or does not support
288 * deselection by column.
290 * @returns \c True if the specified column was successfully de-selected,
293 boolean removeColumnSelection (in long column);
298 * placeholders for future expansion.
300 void unImplemented ();
301 void unImplemented2 ();
302 void unImplemented3 ();
303 void unImplemented4 ();
304 void unImplemented5 ();
305 void unImplemented6 ();
306 void unImplemented7 ();
307 void unImplemented8 ();