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)
64 cspi_return_val_if_fail (obj != NULL, NULL);
66 retval = cspi_object_add (
67 Accessibility_Table__get_caption (CSPI_OBJREF (obj), cspi_ev ()));
68 cspi_return_val_if_ev ("getCaption", NULL);
73 * AccessibleTable_getSummary:
74 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
76 * Get an accessible object which summarizes the contents of an #AccessibleTable.
78 * Returns: an #Accessible object that serves as the table's summary (often a
79 * reduced #AccessibleTable).
82 AccessibleTable_getSummary (AccessibleTable *obj)
86 cspi_return_val_if_fail (obj != NULL, NULL);
88 retval = cspi_object_add (
89 Accessibility_Table__get_summary (CSPI_OBJREF (obj), cspi_ev ()));
90 cspi_return_val_if_ev ("getSummary", NULL);
95 * AccessibleTable_getNRows:
96 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
98 * Get the number of rows in an #AccessibleTable,
99 * exclusive of any rows that are programmatically hidden, but inclusive
100 * of rows that may be outside of the current scrolling window or viewport.
102 * Returns: a #long integer indicating the number of rows in the table.
105 AccessibleTable_getNRows (AccessibleTable *obj)
109 cspi_return_val_if_fail (obj != NULL, -1);
112 Accessibility_Table__get_nRows (CSPI_OBJREF (obj), cspi_ev ());
114 cspi_return_val_if_ev ("getNRows", -1);
121 * AccessibleTable_getNColumns:
122 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
124 * Get the number of columns in an #AccessibleTable,
125 * exclusive of any columns that are programmatically hidden, but inclusive
126 * of columns that may be outside of the current scrolling window or viewport.
128 * Returns: a #long integer indicating the number of columns in the table.
131 AccessibleTable_getNColumns (AccessibleTable *obj)
135 cspi_return_val_if_fail (obj != NULL, -1);
138 Accessibility_Table__get_nColumns (CSPI_OBJREF (obj), cspi_ev ());
140 cspi_return_val_if_ev ("getNColumns", -1);
146 * AccessibleTable_getAccessibleAt:
147 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
148 * @row: the specified table row, zero-indexed.
149 * @column: the specified table column, zero-indexed.
151 * Get the table cell at the specified row and column indices.
152 * To get the accessible object at a particular (x, y) screen coordinate,
153 * use #Accessible_getAccessibleAtPoint ().
155 * Returns: an #Accessible object representing the specified table cell.
158 AccessibleTable_getAccessibleAt (AccessibleTable *obj,
164 cspi_return_val_if_fail (obj != NULL, NULL);
166 retval = cspi_object_add (
167 Accessibility_Table_getAccessibleAt (
168 CSPI_OBJREF (obj), row,
169 column, cspi_ev ()));
170 cspi_return_val_if_ev ("getAccessibleAt", NULL);
175 * AccessibleTable_getIndexAt:
176 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
177 * @row: the specified table row, zero-indexed.
178 * @column: the specified table column, zero-indexed.
180 * Get the 1-D child index corresponding to the specified 2-D row and column indices.
181 * To get the accessible object at a particular (x, y) screen coordinate,
182 * use #Accessible_getAccessibleAtPoint ().
183 * @see #AccessibleTable_getRowAtIndex(), #AccessibleTable_getColumnAtIndex()
185 * Returns: a long integer which serves as the index of a specified cell in the
186 * table, in a form usable by #Accessible_getChildAtIndex().
189 AccessibleTable_getIndexAt (AccessibleTable *obj,
195 cspi_return_val_if_fail (obj != NULL, -1);
198 Accessibility_Table_getIndexAt (
199 CSPI_OBJREF (obj), row,
202 cspi_return_val_if_ev ("getIndexAt", -1);
208 * AccessibleTable_getRowAtIndex:
209 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
210 * @index: the specified child index, zero-indexed.
212 * Get the table row index occupied by the child at a particular 1-D child index.
214 * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getColumnAtIndex()
216 * Returns: a long integer indicating the first row spanned by the child of a
217 * table, at the specified 1-D (zero-offset) @index.
220 AccessibleTable_getRowAtIndex (AccessibleTable *obj,
225 cspi_return_val_if_fail (obj != NULL, -1);
228 Accessibility_Table_getRowAtIndex (CSPI_OBJREF (obj),
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,
254 cspi_return_val_if_fail (obj != NULL, -1);
257 Accessibility_Table_getColumnAtIndex (CSPI_OBJREF (obj),
260 cspi_return_val_if_ev ("getColumnAtIndex", -1);
266 * AccessibleTable_getRowDescription:
267 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
268 * @row: the specified table row, zero-indexed.
270 * Get a text description of a particular table row. This differs from
271 * AccessibleTable_getRowHeader, which returns an #Accessible.
273 * Returns: a UTF-8 string describing the specified table row, if available.
276 AccessibleTable_getRowDescription (AccessibleTable *obj,
281 cspi_return_val_if_fail (obj != NULL, NULL);
284 Accessibility_Table_getRowDescription (CSPI_OBJREF (obj),
287 cspi_return_val_if_ev ("getRowDescription", NULL);
293 * AccessibleTable_getColumnDescription:
294 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
295 * @column: the specified table column, zero-indexed.
297 * Get a text description of a particular table column. This differs from
298 * AccessibleTable_getColumnHeader, which returns an #Accessible.
300 * Returns: a UTF-8 string describing the specified table column, if available.
303 AccessibleTable_getColumnDescription (AccessibleTable *obj,
308 cspi_return_val_if_fail (obj != NULL, NULL);
311 Accessibility_Table_getColumnDescription (CSPI_OBJREF (obj),
314 cspi_return_val_if_ev ("getColumnDescription", NULL);
320 * AccessibleTable_getRowExtentAt:
321 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
322 * @row: the specified table row, zero-indexed.
323 * @column: the specified table column, zero-indexed.
325 * Get the number of rows spanned by the table cell at the specific row and column.
326 * (some tables can have cells which span multiple rows and/or columns).
328 * Returns: a long integer indicating the number of rows spanned by the specified cell.
331 AccessibleTable_getRowExtentAt (AccessibleTable *obj,
337 cspi_return_val_if_fail (obj != NULL, -1);
340 Accessibility_Table_getRowExtentAt (
341 CSPI_OBJREF (obj), row,
344 cspi_return_val_if_ev ("getRowExtentAt", -1);
350 * AccessibleTable_getColumnExtentAt:
351 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
352 * @row: the specified table row, zero-indexed.
353 * @column: the specified table column, zero-indexed.
355 * Get the number of columns spanned by the table cell at the specific row and column.
356 * (some tables can have cells which span multiple rows and/or columns).
358 * Returns: a long integer indicating the number of columns spanned by the specified cell.
361 AccessibleTable_getColumnExtentAt (AccessibleTable *obj,
367 cspi_return_val_if_fail (obj != NULL, -1);
370 Accessibility_Table_getColumnExtentAt (
371 CSPI_OBJREF (obj), row,
374 cspi_return_val_if_ev ("getColumnExtentAt", -1);
380 * AccessibleTable_getRowHeader:
381 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
382 * @row: the specified table row, zero-indexed.
384 * Get the header associated with a table row, if available. This differs from
385 * AccessibleTable_getRowDescription, which returns a string.
387 * Returns: a #Accessible representatin of the specified table row, if available.
390 AccessibleTable_getRowHeader (AccessibleTable *obj,
395 cspi_return_val_if_fail (obj != NULL, NULL);
397 retval = cspi_object_add (
398 Accessibility_Table_getRowHeader (CSPI_OBJREF (obj),
400 cspi_return_val_if_ev ("getRowHeader", NULL);
406 * AccessibleTable_getColumnHeader:
407 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
408 * @column: the specified table column, zero-indexed.
410 * Get the header associated with a table column, if available. This differs from
411 * AccessibleTable_getColumnDescription, which returns a string.
413 * Returns: a #Accessible representatin of the specified table column, if available.
416 AccessibleTable_getColumnHeader (AccessibleTable *obj,
421 cspi_return_val_if_fail (obj != NULL, NULL);
423 retval = cspi_object_add (
424 Accessibility_Table_getColumnHeader (CSPI_OBJREF (obj),
425 column, cspi_ev ()));
426 cspi_return_val_if_ev ("getColumnHeader", NULL);
432 * AccessibleTable_getNSelectedRows:
433 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
435 * Query a table to find out how many rows are currently selected. Not all tables
436 * support row selection.
438 * Returns: a long integer indicating the number of rows currently selected.
441 AccessibleTable_getNSelectedRows (AccessibleTable *obj)
445 cspi_return_val_if_fail (obj != NULL, -1);
448 Accessibility_Table__get_nSelectedRows (CSPI_OBJREF (obj), cspi_ev ());
450 cspi_return_val_if_ev ("getNSelectedRows", -1);
456 cspi_long_seq_to_array (Accessibility_LongSeq *seq, long int **array)
461 if (!cspi_check_ev ("getSelectionItems"))
467 length = seq->_length;
469 j = *array = malloc (sizeof (long) * length);
471 for (i = 0; i < length; i++)
473 j[i] = seq->_buffer [i];
482 * AccessibleTable_getSelectedRows:
483 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
484 * @selectedRows: a doubly indirected pointer which will be set to the address
485 * of an array of long integers, specifying which rows are currently selected.
487 * Query a table for a list of indices of rows which are currently selected.
489 * Returns: a long integer indicating the length of the array returned in @selectedRows.
492 AccessibleTable_getSelectedRows (AccessibleTable *obj,
493 long int **selectedRows)
495 Accessibility_LongSeq *rows;
497 *selectedRows = NULL;
499 cspi_return_val_if_fail (obj != NULL, 0);
501 rows = Accessibility_Table_getSelectedRows (CSPI_OBJREF (obj), cspi_ev ());
503 cspi_return_val_if_ev ("getSelectedRows", -1);
505 return cspi_long_seq_to_array (rows, selectedRows);
509 * AccessibleTable_getNSelectedColumns:
510 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
512 * Query a table to find out how many columns are currently selected. Not all tables
513 * support column selection.
515 * Returns: a long integer indicating the number of columns currently selected.
518 AccessibleTable_getNSelectedColumns (AccessibleTable *obj)
522 cspi_return_val_if_fail (obj != NULL, -1);
525 Accessibility_Table__get_nSelectedColumns (CSPI_OBJREF (obj), cspi_ev ());
527 cspi_return_val_if_ev ("getNSelectedColumns", -1);
533 * AccessibleTable_getSelectedColumns:
534 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
535 * @selectedColumns: a doubly indirected pointer which will be set to the address
536 * of an array of long integers, specifying which columns are currently selected.
538 * Query a table for a list of indices of columns which are currently selected.
539 * Not all tables support column selection.
541 * Returns: a long integer indicating the length of the array returned in @selectedColumns.
544 AccessibleTable_getSelectedColumns (AccessibleTable *obj,
545 long int **selectedColumns)
547 Accessibility_LongSeq *columns;
549 *selectedColumns = NULL;
551 cspi_return_val_if_fail (obj != NULL, 0);
553 columns = Accessibility_Table_getSelectedColumns (CSPI_OBJREF (obj), cspi_ev ());
555 cspi_return_val_if_ev ("getSelectedColumns", -1);
556 return cspi_long_seq_to_array (columns, selectedColumns);
560 * AccessibleTable_isRowSelected:
561 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
564 * Determine whether a table row is selected. Not all tables support row selection.
566 * Returns: #TRUE if the specified row is currently selected, #FALSE if not.
569 AccessibleTable_isRowSelected (AccessibleTable *obj,
574 cspi_return_val_if_fail (obj != NULL, FALSE);
577 Accessibility_Table_isRowSelected (CSPI_OBJREF (obj),
580 cspi_return_val_if_ev ("isRowSelected", FALSE);
586 * AccessibleTable_isColumnSelected:
587 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
590 * Determine whether specified table column is selected.
591 * Not all tables support column selection.
593 * Returns: #TRUE if the specified column is currently selected, #FALSE if not.
596 AccessibleTable_isColumnSelected (AccessibleTable *obj,
601 cspi_return_val_if_fail (obj != NULL, FALSE);
604 Accessibility_Table_isColumnSelected (CSPI_OBJREF (obj),
607 cspi_return_val_if_ev ("isColumnSelected", FALSE);
613 * AccessibleTable_addRowSelection:
614 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
617 * Select the specified row, adding it to the current row selection.
618 * Not all tables support row selection.
620 * Returns: #TRUE if the specified row was successfully selected, #FALSE if not.
623 AccessibleTable_addRowSelection (AccessibleTable *obj,
628 cspi_return_val_if_fail (obj != NULL, FALSE);
631 Accessibility_Table_addRowSelection (CSPI_OBJREF (obj),
634 cspi_return_val_if_ev ("addRowSelection", FALSE);
640 * AccessibleTable_addColumnSelection:
641 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
644 * Select the specified column, adding it to the current column selection.
645 * Not all tables support column selection.
647 * Returns: #TRUE if the specified column was successfully selected, #FALSE if not.
650 AccessibleTable_addColumnSelection (AccessibleTable *obj,
655 cspi_return_val_if_fail (obj != NULL, FALSE);
658 Accessibility_Table_addColumnSelection (CSPI_OBJREF (obj),
661 cspi_return_val_if_ev ("addColumnSelection", FALSE);
667 * AccessibleTable_removeRowSelection:
668 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
671 * De-select the specified row, removing it to the current row selection.
672 * Not all tables support row selection.
674 * Returns: #TRUE if the specified row was successfully de-selected, #FALSE if not.
677 AccessibleTable_removeRowSelection (AccessibleTable *obj,
682 cspi_return_val_if_fail (obj != NULL, FALSE);
685 Accessibility_Table_removeRowSelection (CSPI_OBJREF (obj),
688 cspi_return_val_if_ev ("removeRowSelection", FALSE);
694 * AccessibleTable_removeColumnSelection:
695 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
698 * De-select the specified column, removing it to the current column selection.
699 * Not all tables support column selection.
701 * Returns: #TRUE if the specified column was successfully de-selected, #FALSE if not.
704 AccessibleTable_removeColumnSelection (AccessibleTable *obj,
709 cspi_return_val_if_fail (obj != NULL, FALSE);
712 Accessibility_Table_removeColumnSelection (CSPI_OBJREF (obj),
715 cspi_return_val_if_ev ("removeColumnSelection", FALSE);
721 * AccessibleTable_isSelected:
722 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
726 * Determine whether the cell at a specific row and column is selected.
728 * Returns: #TRUE if the specified cell is currently selected, #FALSE if not.
731 AccessibleTable_isSelected (AccessibleTable *obj,
737 cspi_return_val_if_fail (obj != NULL, FALSE);
740 Accessibility_Table_isSelected (CSPI_OBJREF (obj),
744 cspi_return_val_if_ev ("isSelected", FALSE);