2 * AT-SPI - Assistive Technology Service Provider Interface
3 * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
5 * Copyright 2001, 2002 Sun Microsystems Inc.,
6 * Copyright 2001, 2002 Ximian, Inc.
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
24 #include <stdlib.h> /* for malloc */
25 #include <cspi/spi-private.h>
28 * AccessibleTable_ref:
29 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
31 * Increment the reference count for an #AccessibleTable object.
34 AccessibleTable_ref (AccessibleTable *obj)
36 cspi_object_ref (obj);
40 * AccessibleTable_unref:
41 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
43 * Decrement the reference count for an #AccessibleTable object.
46 AccessibleTable_unref (AccessibleTable *obj)
48 cspi_object_unref (obj);
52 * AccessibleTable_getCaption:
53 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
55 * Get an accessible representation of the caption for an #AccessibleTable.
57 * Returns: an #Accessible object that serves as the table's caption.
60 AccessibleTable_getCaption (AccessibleTable *obj)
65 cspi_return_val_if_fail (obj != NULL, NULL);
67 cspi_dbus_get_property (obj, spi_interface_table, "caption", NULL, "o", &path);
68 cspi_return_val_if_ev ("getCaption", NULL);
69 retval = cspi_ref_related_accessible (obj, path);
75 * AccessibleTable_getSummary:
76 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
78 * Get an accessible object which summarizes the contents of an #AccessibleTable.
80 * Returns: an #Accessible object that serves as the table's summary (often a
81 * reduced #AccessibleTable).
84 AccessibleTable_getSummary (AccessibleTable *obj)
89 cspi_return_val_if_fail (obj != NULL, NULL);
91 cspi_dbus_get_property (obj, spi_interface_table, "summary", NULL, "o", &path);
92 cspi_return_val_if_ev ("getSummary", NULL);
93 retval = cspi_ref_related_accessible (obj, path);
99 * AccessibleTable_getNRows:
100 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
102 * Get the number of rows in an #AccessibleTable,
103 * exclusive of any rows that are programmatically hidden, but inclusive
104 * of rows that may be outside of the current scrolling window or viewport.
106 * Returns: a #long integer indicating the number of rows in the table.
109 AccessibleTable_getNRows (AccessibleTable *obj)
113 cspi_return_val_if_fail (obj != NULL, -1);
115 cspi_dbus_get_property (obj, spi_interface_table, "nRows", NULL, "i", &retval);
117 cspi_return_val_if_ev ("getNRows", -1);
124 * AccessibleTable_getNColumns:
125 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
127 * Get the number of columns in an #AccessibleTable,
128 * exclusive of any columns that are programmatically hidden, but inclusive
129 * of columns that may be outside of the current scrolling window or viewport.
131 * Returns: a #long integer indicating the number of columns in the table.
134 AccessibleTable_getNColumns (AccessibleTable *obj)
138 cspi_return_val_if_fail (obj != NULL, -1);
140 cspi_dbus_get_property (obj, spi_interface_table, "nColumns", NULL, "i", &retval);
142 cspi_return_val_if_ev ("getNColumns", -1);
148 * AccessibleTable_getAccessibleAt:
149 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
150 * @row: the specified table row, zero-indexed.
151 * @column: the specified table column, zero-indexed.
153 * Get the table cell at the specified row and column indices.
154 * To get the accessible object at a particular (x, y) screen coordinate,
155 * use #Accessible_getAccessibleAtPoint ().
157 * Returns: an #Accessible object representing the specified table cell.
160 AccessibleTable_getAccessibleAt (AccessibleTable *obj,
164 dbus_int32_t d_row = row, d_column = column;
168 cspi_return_val_if_fail (obj != NULL, NULL);
170 cspi_dbus_call (obj, spi_interface_table, "getAccessibleAt", NULL, "ii=>o", &d_row, &d_column, &path);
171 cspi_return_val_if_ev ("getAccessibleAt", NULL);
172 retval = cspi_ref_related_accessible (obj, path);
178 * AccessibleTable_getIndexAt:
179 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
180 * @row: the specified table row, zero-indexed.
181 * @column: the specified table column, zero-indexed.
183 * Get the 1-D child index corresponding to the specified 2-D row and column indices.
184 * To get the accessible object at a particular (x, y) screen coordinate,
185 * use #Accessible_getAccessibleAtPoint ().
186 * @see #AccessibleTable_getRowAtIndex(), #AccessibleTable_getColumnAtIndex()
188 * Returns: a long integer which serves as the index of a specified cell in the
189 * table, in a form usable by #Accessible_getChildAtIndex().
192 AccessibleTable_getIndexAt (AccessibleTable *obj,
196 dbus_int32_t d_row = row, d_column = column;
199 cspi_return_val_if_fail (obj != NULL, -1);
201 cspi_dbus_call (obj, spi_interface_table, "getIndexAt", NULL, "ii=>i", d_row, d_column, &retval);
203 cspi_return_val_if_ev ("getIndexAt", -1);
209 * AccessibleTable_getRowAtIndex:
210 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
211 * @index: the specified child index, zero-indexed.
213 * Get the table row index occupied by the child at a particular 1-D child index.
215 * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getColumnAtIndex()
217 * Returns: a long integer indicating the first row spanned by the child of a
218 * table, at the specified 1-D (zero-offset) @index.
221 AccessibleTable_getRowAtIndex (AccessibleTable *obj,
224 dbus_int32_t d_index = index;
227 cspi_return_val_if_fail (obj != NULL, -1);
229 cspi_dbus_call (obj, spi_interface_table, "getRowAtIndex", NULL, "i=>i", d_index, &retval);
231 cspi_return_val_if_ev ("getRowAtIndex", -1);
237 * AccessibleTable_getColumnAtIndex:
238 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
239 * @index: the specified child index, zero-indexed.
241 * Get the table column index occupied by the child at a particular 1-D child index.
243 * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getRowAtIndex()
245 * Returns: a long integer indicating the first column spanned by the child of a
246 * table, at the specified 1-D (zero-offset) @index.
249 AccessibleTable_getColumnAtIndex (AccessibleTable *obj,
252 dbus_int32_t d_index = index;
255 cspi_return_val_if_fail (obj != NULL, -1);
257 cspi_dbus_call (obj, spi_interface_table, "getColumnAtIndex", NULL, "i=>i", d_index, &retval);
259 cspi_return_val_if_ev ("getColumnAtIndex", -1);
265 * AccessibleTable_getRowDescription:
266 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
267 * @row: the specified table row, zero-indexed.
269 * Get a text description of a particular table row. This differs from
270 * AccessibleTable_getRowHeader, which returns an #Accessible.
272 * Returns: a UTF-8 string describing the specified table row, if available.
275 AccessibleTable_getRowDescription (AccessibleTable *obj,
278 dbus_int32_t d_row = row;
281 cspi_return_val_if_fail (obj != NULL, NULL);
283 cspi_dbus_call (obj, spi_interface_table, "getRowDescription", NULL, "i=>s", d_row, &retval);
285 cspi_return_val_if_ev ("getRowDescription", NULL);
291 * AccessibleTable_getColumnDescription:
292 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
293 * @column: the specified table column, zero-indexed.
295 * Get a text description of a particular table column. This differs from
296 * AccessibleTable_getColumnHeader, which returns an #Accessible.
298 * Returns: a UTF-8 string describing the specified table column, if available.
301 AccessibleTable_getColumnDescription (AccessibleTable *obj,
304 dbus_int32_t d_column = column;
307 cspi_return_val_if_fail (obj != NULL, NULL);
309 cspi_dbus_call (obj, spi_interface_table, "getColumnDescription", NULL, "i=>s", d_column, &retval);
311 cspi_return_val_if_ev ("getColumnDescription", NULL);
317 * AccessibleTable_getRowExtentAt:
318 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
319 * @row: the specified table row, zero-indexed.
320 * @column: the specified table column, zero-indexed.
322 * Get the number of rows spanned by the table cell at the specific row and column.
323 * (some tables can have cells which span multiple rows and/or columns).
325 * Returns: a long integer indicating the number of rows spanned by the specified cell.
328 AccessibleTable_getRowExtentAt (AccessibleTable *obj,
332 dbus_int32_t d_row = row, d_column = column;
335 cspi_return_val_if_fail (obj != NULL, -1);
337 cspi_dbus_call (obj, spi_interface_table, "getRowExtentAt", NULL, "ii=>i", d_row, d_column, &retval);
339 cspi_return_val_if_ev ("getRowExtentAt", -1);
345 * AccessibleTable_getColumnExtentAt:
346 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
347 * @row: the specified table row, zero-indexed.
348 * @column: the specified table column, zero-indexed.
350 * Get the number of columns spanned by the table cell at the specific row and column.
351 * (some tables can have cells which span multiple rows and/or columns).
353 * Returns: a long integer indicating the number of columns spanned by the specified cell.
356 AccessibleTable_getColumnExtentAt (AccessibleTable *obj,
360 dbus_int32_t d_row = row, d_column = column;
363 cspi_return_val_if_fail (obj != NULL, -1);
365 cspi_dbus_call (obj, spi_interface_table, "getColumnExtentAt", NULL, "ii=>i", d_row, d_column, &retval);
367 cspi_return_val_if_ev ("getColumnExtentAt", -1);
373 * AccessibleTable_getRowHeader:
374 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
375 * @row: the specified table row, zero-indexed.
377 * Get the header associated with a table row, if available. This differs from
378 * AccessibleTable_getRowDescription, which returns a string.
380 * Returns: a #Accessible representatin of the specified table row, if available.
383 AccessibleTable_getRowHeader (AccessibleTable *obj,
386 dbus_int32_t d_row = row;
390 cspi_return_val_if_fail (obj != NULL, NULL);
392 cspi_dbus_call (obj, spi_interface_table, "getRowHeader", NULL, "i=>o", d_row, &path);
393 cspi_return_val_if_ev ("getRowHeader", NULL);
394 retval = cspi_ref_related_accessible (obj, path);
401 * AccessibleTable_getColumnHeader:
402 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
403 * @column: the specified table column, zero-indexed.
405 * Get the header associated with a table column, if available. This differs from
406 * AccessibleTable_getColumnDescription, which returns a string.
408 * Returns: a #Accessible representatin of the specified table column, if available.
411 AccessibleTable_getColumnHeader (AccessibleTable *obj,
414 dbus_int32_t d_column = column;
418 cspi_return_val_if_fail (obj != NULL, NULL);
420 cspi_dbus_call (obj, spi_interface_table, "getColumnHeader", NULL, "i=>o", d_column, &path);
421 cspi_return_val_if_ev ("getColumnHeader", NULL);
422 retval = cspi_ref_related_accessible (obj, path);
429 * AccessibleTable_getNSelectedRows:
430 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
432 * Query a table to find out how many rows are currently selected. Not all tables
433 * support row selection.
435 * Returns: a long integer indicating the number of rows currently selected.
438 AccessibleTable_getNSelectedRows (AccessibleTable *obj)
442 cspi_return_val_if_fail (obj != NULL, -1);
444 cspi_dbus_get_property (obj, spi_interface_table, "nSelectedRows", NULL, "i", &retval);
446 cspi_return_val_if_ev ("getNSelectedRows", -1);
452 cspi_long_seq_to_array (GArray *seq, long int **array)
457 if (!cspi_check_ev ("getSelectionItems"))
465 j = *array = malloc (sizeof (long) * length);
467 for (i = 0; i < length; i++)
469 j[i] = g_array_index (seq, long, i);
472 g_array_free (seq, TRUE);
478 * AccessibleTable_getSelectedRows:
479 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
480 * @selectedRows: a doubly indirected pointer which will be set to the address
481 * of an array of long integers, specifying which rows are currently selected.
483 * Query a table for a list of indices of rows which are currently selected.
485 * Returns: a long integer indicating the length of the array returned in @selectedRows.
488 AccessibleTable_getSelectedRows (AccessibleTable *obj,
489 long int **selectedRows)
493 *selectedRows = NULL;
495 cspi_return_val_if_fail (obj != NULL, 0);
497 cspi_dbus_call (obj, spi_interface_table, "getSelectedRows", NULL, "=>ai", &rows);
499 cspi_return_val_if_ev ("getSelectedRows", -1);
501 return cspi_long_seq_to_array (rows, selectedRows);
505 * AccessibleTable_getNSelectedColumns:
506 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
508 * Query a table to find out how many columns are currently selected. Not all tables
509 * support column selection.
511 * Returns: a long integer indicating the number of columns currently selected.
514 AccessibleTable_getNSelectedColumns (AccessibleTable *obj)
518 cspi_return_val_if_fail (obj != NULL, -1);
520 cspi_dbus_get_property (obj, spi_interface_table, "nSelectedColumns", NULL, "i", &retval);
522 cspi_return_val_if_ev ("getNSelectedColumns", -1);
528 * AccessibleTable_getSelectedColumns:
529 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
530 * @selectedColumns: a doubly indirected pointer which will be set to the address
531 * of an array of long integers, specifying which columns are currently selected.
533 * Query a table for a list of indices of columns which are currently selected.
534 * Not all tables support column selection.
536 * Returns: a long integer indicating the length of the array returned in @selectedColumns.
539 AccessibleTable_getSelectedColumns (AccessibleTable *obj,
540 long int **selectedColumns)
544 *selectedColumns = NULL;
546 cspi_return_val_if_fail (obj != NULL, 0);
548 cspi_dbus_call (obj, spi_interface_table, "getSelectedColumns", NULL, "=>ai", &columns);
550 cspi_return_val_if_ev ("getSelectedColumns", -1);
551 return cspi_long_seq_to_array (columns, selectedColumns);
555 * AccessibleTable_isRowSelected:
556 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
557 * @row: the zero-indexed row number of the row being queried.
559 * Determine whether a table row is selected. Not all tables support row selection.
561 * Returns: #TRUE if the specified row is currently selected, #FALSE if not.
564 AccessibleTable_isRowSelected (AccessibleTable *obj,
567 dbus_int32_t d_row = row;
570 cspi_return_val_if_fail (obj != NULL, FALSE);
572 cspi_dbus_call (obj, spi_interface_table, "isRowSelected", NULL, "i=>b", d_row, &retval);
574 cspi_return_val_if_ev ("isRowSelected", FALSE);
580 * AccessibleTable_isColumnSelected:
581 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
582 * @column: the zero-indexed column number of the column being queried.
584 * Determine whether specified table column is selected.
585 * Not all tables support column selection.
587 * Returns: #TRUE if the specified column is currently selected, #FALSE if not.
590 AccessibleTable_isColumnSelected (AccessibleTable *obj,
593 dbus_int32_t d_column = column;
596 cspi_return_val_if_fail (obj != NULL, FALSE);
598 cspi_dbus_call (obj, spi_interface_table, "isColumnSelected", NULL, "i=>b", d_column, &retval);
600 cspi_return_val_if_ev ("isColumnSelected", FALSE);
606 * AccessibleTable_addRowSelection:
607 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
608 * @row: the zero-indexed row number of the row being selected.
610 * Select the specified row, adding it to the current row selection.
611 * Not all tables support row selection.
613 * Returns: #TRUE if the specified row was successfully selected, #FALSE if not.
616 AccessibleTable_addRowSelection (AccessibleTable *obj,
619 dbus_int32_t d_row = row;
622 cspi_return_val_if_fail (obj != NULL, FALSE);
624 cspi_dbus_call (obj, spi_interface_table, "addRowSelection", NULL, "i=>b", d_row, &retval);
626 cspi_return_val_if_ev ("addRowSelection", FALSE);
632 * AccessibleTable_addColumnSelection:
633 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
634 * @column: the zero-indexed column number of the column being selected.
636 * Select the specified column, adding it to the current column selection.
637 * Not all tables support column selection.
639 * Returns: #TRUE if the specified column was successfully selected, #FALSE if not.
642 AccessibleTable_addColumnSelection (AccessibleTable *obj,
645 dbus_int32_t d_column = column;
648 cspi_return_val_if_fail (obj != NULL, FALSE);
650 cspi_dbus_call (obj, spi_interface_table, "addColumnSelection", NULL, "i=>b", d_column, &retval);
652 cspi_return_val_if_ev ("addColumnSelection", FALSE);
658 * AccessibleTable_removeRowSelection:
659 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
660 * @row: the zero-indexed number of the row being deselected.
662 * De-select the specified row, removing it to the current row selection.
663 * Not all tables support row selection.
665 * Returns: #TRUE if the specified row was successfully de-selected, #FALSE if not.
668 AccessibleTable_removeRowSelection (AccessibleTable *obj,
671 dbus_int32_t d_row = row;
674 cspi_return_val_if_fail (obj != NULL, FALSE);
676 cspi_dbus_call (obj, spi_interface_table, "removeRowSelection", NULL, "i=>b", d_row, &retval);
678 cspi_return_val_if_ev ("removeRowSelection", FALSE);
684 * AccessibleTable_removeColumnSelection:
685 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
686 * @column: the zero-indexed column number of the column being de-selected.
688 * De-select the specified column, removing it to the current column selection.
689 * Not all tables support column selection.
691 * Returns: #TRUE if the specified column was successfully de-selected, #FALSE if not.
694 AccessibleTable_removeColumnSelection (AccessibleTable *obj,
697 dbus_int32_t d_column = column;
700 cspi_return_val_if_fail (obj != NULL, FALSE);
702 cspi_dbus_call (obj, spi_interface_table, "removeColumnSelection", NULL, "i=>b", d_column, &retval);
704 cspi_return_val_if_ev ("removeColumnSelection", FALSE);
710 * AccessibleTable_getRowColumnExtentsAtIndex:
711 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
712 * @index: the index of the Table child whose row/column
713 * extents are requested.
714 * @row: back-filled with the first table row associated with
715 * the cell with child index \c index.
716 * @col: back-filled with the first table column associated
717 * with the cell with child index \c index.
718 * @row_extents: back-filled with the number of table rows
719 * across which child \c i extends.
720 * @col_extents: back-filled with the number of table columns
721 * across which child \c i extends.
722 * @is_selected: a boolean which is back-filled with \c True
723 * if the child at index \c i corresponds to a selected table cell,
724 * \c False otherwise.
726 * Given a child index, determine the row and column indices and
727 * extents, and whether the cell is currently selected. If
728 * the child at \c index is not a cell (for instance, if it is
729 * a summary, caption, etc.), \c False is returned.
732 * If the Table child at index '6' extends across columns 5 and 6 of
733 * row 2 of a Table instance, and is currently selected, then
735 * retval = table::getRowColumnExtentsAtIndex (6, row, col,
740 * will return True, and after the call
741 * row, col, row_extents, col_extents,
742 * and \c is_selected will contain 2, 5, 1, 2, and
743 * True, respectively.
745 * Returns: \c True if the index is associated with a valid table
746 * cell, \c False if the index does not correspond to a cell. If
747 * \c False is returned, the values of the out parameters are
753 AccessibleTable_getRowColumnExtentsAtIndex (AccessibleTable *obj,
754 long int index, long int *row, long int *col,
755 long int *row_extents, long int *col_extents,
756 long int *is_selected)
758 dbus_int32_t d_index = index;
760 dbus_int32_t d_row, d_col, d_row_extents, d_col_extents;
761 dbus_bool_t d_is_selected;
763 cspi_return_val_if_fail (obj != NULL, FALSE);
765 cspi_dbus_call (obj, spi_interface_table, "getRowColumnExtentsAtIndex", NULL, "i=>iiiibb", d_index, &d_row, &d_col, &d_row_extents, &d_col_extents, &d_is_selected, &retval);
767 if (!cspi_check_ev ("getRowColumnExtentsAtIndex")){
773 *is_selected = FALSE;
780 *row_extents = d_row_extents;;
781 *col_extents = d_col_extents;
782 *is_selected = d_is_selected;;
790 * AccessibleTable_isSelected:
791 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
792 * @row: the zero-indexed row of the cell being queried.
793 * @column: the zero-indexed column of the cell being queried.
795 * Determine whether the cell at a specific row and column is selected.
797 * Returns: #TRUE if the specified cell is currently selected, #FALSE if not.
800 AccessibleTable_isSelected (AccessibleTable *obj,
804 dbus_int32_t d_row = row, d_column = column;
807 cspi_return_val_if_fail (obj != NULL, FALSE);
809 cspi_dbus_call (obj, spi_interface_table, "isSelected", NULL, "ii=>b", d_row, d_column, &retval);
811 cspi_return_val_if_ev ("isSelected", FALSE);