1 <node name="/node" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3 <tp:title>AT-SPI - Assistive Technology Service Provider Interface </tp:title>
4 <tp:copyright>Copyright 2008 Novell, Inc.</tp:copyright>
5 <tp:copyright>Copyright 2001 Sun Microsystems, Inc.</tp:copyright>
6 <tp:license xmlns="http://www.w3.org/1999/xhtml">
7 <p>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.</p>
12 <p>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.</p>
17 <p>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.</p>
22 <interface name="org.freedesktop.atspi.Table">
23 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
24 <p>An interface used by containers whose contained data is arranged in
25 a "tabular" (i.e.\ row-column) fashion. Tables may resemble a two-dimensional
26 grid, as in a spreadsheet, or may feature objects which span multiple rows and/or
27 columns, but whose bounds are aligned on a row/column matrix. Thus, the Table
28 interface may be used to represent "spreadsheets" as well as "frames". </p>
30 <p>Objects within tables are children of the Table instance, and they may be referenced
31 either via a child index or via a row/column pair.
32 Their role may be ROLE_TABLE_CELL, but table 'cells' may have other roles as well.
33 These 'cells' may implement other interfaces, such as Text, Action, Image,
34 and Component, and should do so as appropriate to their onscreen representation
37 <tp:property name="nRows" type="i" access="read">
38 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
39 <p>The total number of rows in this table (including empty rows),
40 exclusive of any rows which are programmatically hidden.
41 Rows which are merely scrolled out of view are included.</p>
44 <tp:property name="nColumns" type="i" access="read">
45 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
46 <p>The total number of columns in this table (including empty columns),
47 exclusive of columns which are programmatically hidden.
48 Columns which are scrolled out of view or clipped by the current
49 viewport are included. </p>
52 <tp:property name="caption" type="o" access="read">
54 An Accessible which represents of a caption for a Table.
57 <tp:property name="summary" type="o" access="read">
58 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
59 <p>An accessible object which summarizes the contents of a Table.
60 This object is frequently itself a Table instance, albeit a simplified one.</p>
63 <tp:property name="nSelectedRows" type="i" access="read">
64 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
65 <p>The number of rows currently selected.
66 A selected row is one in which all included cells are selected.
67 @note Not all tables support row selection.</p>
70 <tp:property name="nSelectedColumns" type="i" access="read">
71 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
72 <p>The number of columns currently selected.
73 A selected column is one in which all included cells are selected.
74 @note Not all tables support column selection.</p>
77 <method name="getAccessibleAt">
78 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
79 <p>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 (). </p>
83 <arg direction="in" name="row" type="i">
85 the specified table row, zero-indexed.
88 <arg direction="in" name="column" type="i">
90 the specified table column, zero-indexed.
93 <arg direction="out" type="o" tp:type="Accessible">
95 an Accessible object representing the specified table cell.
99 <method name="getIndexAt">
100 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
101 <p>Get the 1-D child index corresponding to the specified 2-D row and column indices.
102 @note To get the accessible object at a particular (x, y) screen coordinate,
103 use Accessible::getAccessibleAtPoint. </p>
105 <arg direction="in" name="row" type="i">
107 the specified table row, zero-indexed.
110 <arg direction="in" name="column" type="i">
112 the specified table column, zero-indexed.@see getRowAtIndex, getColumnAtIndex
115 <arg direction="out" type="i">
117 a long integer which serves as the index of a specified cell in thetable, in a form usable by Accessible::getChildAtIndex.
121 <method name="getRowAtIndex">
122 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
123 <p>Get the table row index occupied by the child at a particular 1-D child index. </p>
125 <arg direction="in" name="index" type="i">
127 the specified child index, zero-indexed.@see getIndexAt(), getColumnAtIndex()
130 <arg direction="out" type="i">
132 a long integer indicating the first row spanned by the child of atable, at the specified 1-D (zero-offset) \c index.
136 <method name="getColumnAtIndex">
137 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
138 <p>Get the table column index occupied by the child at a particular 1-D child index. </p>
140 <arg direction="in" name="index" type="i">
142 the specified child index, zero-indexed.@see getIndexAt(), getRowAtIndex()
145 <arg direction="out" type="i">
147 a long integer indicating the first column spanned by the child of atable, at the specified 1-D (zero-offset) \c index.
151 <method name="getRowDescription">
152 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
153 <p>Get a text description of a particular table row. This differs from
154 AccessibleTable_getRowHeader, which returns an Accessible.</p>
156 <arg direction="in" name="row" type="i">
158 the specified table row, zero-indexed.
161 <arg direction="out" type="s">
163 a UTF-8 string describing the specified table row, if available.
167 <method name="getColumnDescription">
168 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
169 <p>Get a text description of a particular table column. This differs from
170 AccessibleTable_getColumnHeader, which returns an Accessible.</p>
172 <arg direction="in" name="column" type="i">
174 the specified table column, zero-indexed.
177 <arg direction="out" type="s">
179 a UTF-8 string describing the specified table column, if available.
183 <method name="getRowExtentAt">
184 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
185 <p>Get the number of rows spanned by the table cell at the specific row and column.
186 (some tables can have cells which span multiple rows and/or columns). </p>
188 <arg direction="in" name="row" type="i">
190 the specified table row, zero-indexed.
193 <arg direction="in" name="column" type="i">
195 the specified table column, zero-indexed.
198 <arg direction="out" type="i">
200 a long integer indicating the number of rows spanned by the specified cell.
204 <method name="getColumnExtentAt">
205 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
206 <p>Get the number of columns spanned by the table cell at the specific row and column.
207 (some tables can have cells which span multiple rows and/or columns). </p>
209 <arg direction="in" name="row" type="i">
211 the specified table row, zero-indexed.
214 <arg direction="in" name="column" type="i">
216 the specified table column, zero-indexed.
219 <arg direction="out" type="i">
221 a long integer indicating the number of columns spanned by the specified cell.
225 <method name="getRowHeader">
226 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
227 <p>Get the header associated with a table row, if available. This differs from
228 getRowDescription, which returns a string. </p>
230 <arg direction="in" name="row" type="i">
232 the specified table row, zero-indexed.
235 <arg direction="out" type="o" tp:type="Accessible">
237 an Accessible representatin of the specified table row, if available.
241 <method name="getColumnHeader">
242 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
243 <p>Get the header associated with a table column, if available, as an
244 instance of Accessible. This differs from
245 getColumnDescription, which returns a string. </p>
247 <arg direction="in" name="column" type="i">
249 the specified table column, zero-indexed.
252 <arg direction="out" type="o" tp:type="Accessible">
254 an Accessible representatin of the specified table column, if available.
258 <method name="getSelectedRows">
259 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
260 <p>Obtain the indices of all rows which are currently selected.
261 @note Not all tables support row selection. </p>
263 <arg direction="out" type="ai" tp:type="LongSeq">
265 a sequence of integers comprising the indices of rows currently selected.
269 <method name="getSelectedColumns">
270 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
271 <p>Obtain the indices of all columns which are currently selected.
272 @note Not all tables support column selection. </p>
274 <arg direction="out" type="ai" tp:type="LongSeq">
276 a sequence of integers comprising the indices of columns currently selected.
280 <method name="isRowSelected">
281 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
282 <p>Determine whether a table row is selected.
283 @note Not all tables support row selection. </p>
285 <arg direction="in" name="row" type="i">
287 the row being queried.
290 <arg direction="out" type="b" tp:type="boolean">
292 \c True if the specified row is currently selected, \c False if not.
296 <method name="isColumnSelected">
297 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
298 <p>Determine whether a table column is selected.
299 @note Not all tables support column selection. </p>
301 <arg direction="in" name="column" type="i">
303 the column being queried.
306 <arg direction="out" type="b" tp:type="boolean">
308 \c True if the specified column is currently selected, \c False if not.
312 <method name="isSelected">
313 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
314 <p>Determine whether the cell at a specific row and column is selected.
315 @param row a row occupied by the cell whose state is being queried.
316 @param column a column occupied by the cell whose state is being queried. </p>
318 <arg direction="in" name="row" type="i"/>
319 <arg direction="in" name="column" type="i"/>
320 <arg direction="out" type="b" tp:type="boolean">
322 \c True if the specified cell is currently selected, \c False if not.
326 <method name="addRowSelection">
327 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
328 <p>Select the specified row, adding it to the current row selection,
329 if the table's selection model permits it. </p>
332 @note Possible reasons for addRowSelection to return \c False
334 \li The table does not support Selection
335 \li The table row includes cells which do not have STATE_SELECTABLE
336 \li The table does not support selection by row
337 \li The table does not support selection of multiple rows, and
338 one row is already selected.
339 \li The table does not support non-contiguous selections (i.e.
340 does not include STATE_MULTISELECTABLE), and the specified row
341 would result in selection of non-contiguous rows.
342 \li The table does not support user-instigated selection. </p>
344 <arg direction="in" name="row" type="i"/>
345 <arg direction="out" type="b" tp:type="boolean">
347 \c True if the specified row was successfully selected, \c False if not.
351 <method name="addColumnSelection">
352 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
353 <p>Select the specified column, adding it to the current column selection,
354 if the table's selection model permits it. </p>
357 @note Possible reasons for addColumnSelection to return \c False
359 \li The table does not support Selection
360 \li The table column includes cells which do not have STATE_SELECTABLE
361 \li The table does not support selection by column
362 \li The table does not support selection of multiple columns, and
363 one column is already selected.
364 \li The table does not support non-contiguous selections (i.e.
365 does not include STATE_MULTISELECTABLE), and the specified column
366 would result in selection of non-contiguous columns.
367 \li The table does not support user-instigated selection. </p>
369 <arg direction="in" name="column" type="i"/>
370 <arg direction="out" type="b" tp:type="boolean">
372 \c True if the specified column was successfully selected, \c False if not.
376 <method name="removeRowSelection">
377 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
378 <p>Remove the specified row from current row selection,
379 if the table's selection model permits it. </p>
382 @note Possible reasons for removeRowSelection to return \c False
384 \li The table does not support user-instigated Selection
385 \li The table has no selected rows or does not support deselection by row </p>
387 <arg direction="in" name="row" type="i"/>
388 <arg direction="out" type="b" tp:type="boolean">
390 \c True if the specified row was successfully de-selected, \c False if not.
394 <method name="removeColumnSelection">
395 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
396 <p>Remove the specified column from current column selection,
397 if the table's selection model permits it. </p>
400 @note Possible reasons for removeColumnSelection to return \c False
402 \li The table does not support user-instigated modification of
404 \li The table has no selected columns or does not support
405 deselection by column. </p>
407 <arg direction="in" name="column" type="i"/>
408 <arg direction="out" type="b" tp:type="boolean">
410 \c True if the specified column was successfully de-selected, \c False if not.
414 <method name="getRowColumnExtentsAtIndex">
415 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
416 <p>Given a child index, determine the row and column indices and
417 extents, and whether the cell is currently selected. If
418 the child at \c index is not a cell (for instance, if it is
419 a summary, caption, etc.), \c False is returned. </p>
421 <p>@param index the index of the Table child whose row/column
422 extents are requested.
423 @param row back-filled with the first table row associated with
424 the cell with child index \c index.
425 @param col back-filled with the first table column associated
426 with the cell with child index \c index.
427 @param row_extents back-filled with the number of table rows
428 across which child \c i extends.
429 @param col_extents back-filled with the number of table columns
430 across which child \c i extends.
431 @param is_selected a boolean which is back-filled with \c True
432 if the child at index \c i corresponds to a selected table cell,
433 \c False otherwise. </p>
436 If the Table child at index '6' extends across columns 5 and 6 of
437 row 2 of a Table instance, and is currently selected, then
439 retval = table::getRowColumnExtentsAtIndex (6, row, col,
444 will return True, and after the call
445 \c row, \c col, \c row_extents, \c col_extents,
446 and \c is_selected will contain \c 2, \c 5, \c 1, \c 2, and
447 \c True, respectively. </p>
449 <arg direction="in" name="index" type="i"/>
450 <arg direction="out" name="row" type="i"/>
451 <arg direction="out" name="col" type="i"/>
452 <arg direction="out" name="row_extents" type="i"/>
453 <arg direction="out" name="col_extents" type="i"/>
454 <arg direction="out" name="is_selected" type="b" tp:type="boolean"/>
455 <arg direction="out" type="b" tp:type="boolean">
457 \c True if the index is associated with a valid tablecell, \c False if the index does not correspond to a cell. If \c False is returned, the values of the out parameters are undefined.@since AT-SPI 1.7.0
461 <method name="unImplemented">
462 <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
466 <p>placeholders for future expansion.</p>
469 <method name="unImplemented2">
471 <method name="unImplemented3">
473 <method name="unImplemented4">
475 <method name="unImplemented5">
477 <method name="unImplemented6">
479 <method name="unImplemented7">