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 <stdlib.h> /* for malloc */
24 #include <cspi/spi-private.h>
27 * AccessibleTable_ref:
28 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
30 * Increment the reference count for an #AccessibleTable object.
33 AccessibleTable_ref (AccessibleTable *obj)
35 cspi_object_ref (obj);
39 * AccessibleTable_unref:
40 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
42 * Decrement the reference count for an #AccessibleTable object.
45 AccessibleTable_unref (AccessibleTable *obj)
47 cspi_object_unref (obj);
51 * AccessibleTable_getCaption:
52 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
54 * Get an accessible representation of the caption for an #AccessibleTable.
56 * Returns: an #Accessible object that serves as the table's caption.
59 AccessibleTable_getCaption (AccessibleTable *obj)
61 return cspi_object_add (
62 Accessibility_Table__get_caption (CSPI_OBJREF (obj), cspi_ev ()));
66 * AccessibleTable_getSummary:
67 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
69 * Get an accessible object which summarizes the contents of an #AccessibleTable.
71 * Returns: an #Accessible object that serves as the table's summary (often a
72 * reduced #AccessibleTable).
75 AccessibleTable_getSummary (AccessibleTable *obj)
77 return cspi_object_add (
78 Accessibility_Table__get_summary (CSPI_OBJREF (obj), cspi_ev ()));
82 * AccessibleTable_getNRows:
83 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
85 * Get the number of rows in an #AccessibleTable,
86 * exclusive of any rows that are programmatically hidden, but inclusive
87 * of rows that may be outside of the current scrolling window or viewport.
89 * Returns: a #long integer indicating the number of rows in the table.
92 AccessibleTable_getNRows (AccessibleTable *obj)
96 cspi_return_val_if_fail (obj != NULL, -1);
99 Accessibility_Table__get_nRows (CSPI_OBJREF (obj), cspi_ev ());
101 cspi_return_val_if_ev ("getNRows", -1);
108 * AccessibleTable_getNColumns:
109 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
111 * Get the number of columns in an #AccessibleTable,
112 * exclusive of any columns that are programmatically hidden, but inclusive
113 * of columns that may be outside of the current scrolling window or viewport.
115 * Returns: a #long integer indicating the number of columns in the table.
118 AccessibleTable_getNColumns (AccessibleTable *obj)
122 cspi_return_val_if_fail (obj != NULL, -1);
125 Accessibility_Table__get_nColumns (CSPI_OBJREF (obj), cspi_ev ());
127 cspi_return_val_if_ev ("", -1);
133 * AccessibleTable_getAccessibleAt:
134 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
135 * @row: the specified table row, zero-indexed.
136 * @column: the specified table column, zero-indexed.
138 * Get the table cell at the specified row and column indices.
139 * To get the accessible object at a particular (x, y) screen coordinate,
140 * use #Accessible_getAccessibleAtPoint ().
142 * Returns: an #Accessible object representing the specified table cell.
145 AccessibleTable_getAccessibleAt (AccessibleTable *obj,
149 return cspi_object_add (
150 Accessibility_Table_getAccessibleAt (
151 CSPI_OBJREF (obj), (CORBA_long) row,
152 (CORBA_long) column, cspi_ev ()));
156 * AccessibleTable_getIndexAt:
157 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
158 * @row: the specified table row, zero-indexed.
159 * @column: the specified table column, zero-indexed.
161 * Get the 1-D child index corresponding to the specified 2-D row and column indices.
162 * To get the accessible object at a particular (x, y) screen coordinate,
163 * use #Accessible_getAccessibleAtPoint ().
164 * @see #AccessibleTable_getRowAtIndex(), #AccessibleTable_getColumnAtIndex()
166 * Returns: a long integer which serves as the index of a specified cell in the
167 * table, in a form usable by #Accessible_getChildAtIndex().
170 AccessibleTable_getIndexAt (AccessibleTable *obj,
176 cspi_return_val_if_fail (obj != NULL, -1);
179 Accessibility_Table_getIndexAt (
180 CSPI_OBJREF (obj), (CORBA_long) row,
181 (CORBA_long) column, cspi_ev ());
183 cspi_return_val_if_ev ("getIndexAt", -1);
189 * AccessibleTable_getRowAtIndex:
190 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
191 * @index: the specified child index, zero-indexed.
193 * Get the table row index occupied by the child at a particular 1-D child index.
195 * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getColumnAtIndex()
197 * Returns: a long integer indicating the first row spanned by the child of a
198 * table, at the specified 1-D (zero-offset) @index.
201 AccessibleTable_getRowAtIndex (AccessibleTable *obj,
206 cspi_return_val_if_fail (obj != NULL, -1);
209 Accessibility_Table_getRowAtIndex (CSPI_OBJREF (obj),
210 (CORBA_long) index, cspi_ev ());
212 cspi_return_val_if_ev ("", -1);
218 * AccessibleTable_getColumnAtIndex:
219 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
220 * @index: the specified child index, zero-indexed.
222 * Get the table column index occupied by the child at a particular 1-D child index.
224 * @see #AccessibleTable_getIndexAt(), #AccessibleTable_getRowAtIndex()
226 * Returns: a long integer indicating the first column spanned by the child of a
227 * table, at the specified 1-D (zero-offset) @index.
230 AccessibleTable_getColumnAtIndex (AccessibleTable *obj,
235 cspi_return_val_if_fail (obj != NULL, -1);
238 Accessibility_Table_getColumnAtIndex (CSPI_OBJREF (obj),
239 (CORBA_long) index, cspi_ev ());
241 cspi_return_val_if_ev ("getColumnAtIndex", -1);
247 * AccessibleTable_getRowDescription:
248 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
249 * @row: the specified table row, zero-indexed.
251 * Get a text description of a particular table row. This differs from
252 * AccessibleTable_getRowHeader, which returns an #Accessible.
254 * Returns: a UTF-8 string describing the specified table row, if available.
257 AccessibleTable_getRowDescription (AccessibleTable *obj,
262 cspi_return_val_if_fail (obj != NULL, NULL);
265 Accessibility_Table_getRowDescription (CSPI_OBJREF (obj),
266 (CORBA_long) row, cspi_ev ());
268 cspi_return_val_if_ev ("getRowDescription", NULL);
274 * AccessibleTable_getColumnDescription:
275 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
276 * @column: the specified table column, zero-indexed.
278 * Get a text description of a particular table column. This differs from
279 * AccessibleTable_getColumnHeader, which returns an #Accessible.
281 * Returns: a UTF-8 string describing the specified table column, if available.
284 AccessibleTable_getColumnDescription (AccessibleTable *obj,
289 cspi_return_val_if_fail (obj != NULL, NULL);
292 Accessibility_Table_getColumnDescription (CSPI_OBJREF (obj),
293 (CORBA_long) column, cspi_ev ());
295 cspi_return_val_if_ev ("getColumnDescription", NULL);
301 * AccessibleTable_getRowExtentAt:
302 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
303 * @row: the specified table row, zero-indexed.
304 * @column: the specified table column, zero-indexed.
306 * Get the number of rows spanned by the table cell at the specific row and column.
307 * (some tables can have cells which span multiple rows and/or columns).
309 * Returns: a long integer indicating the number of rows spanned by the specified cell.
312 AccessibleTable_getRowExtentAt (AccessibleTable *obj,
318 cspi_return_val_if_fail (obj != NULL, -1);
321 Accessibility_Table_getRowExtentAt (
322 CSPI_OBJREF (obj), (CORBA_long) row,
323 (CORBA_long) column, cspi_ev ());
325 cspi_return_val_if_ev ("getRowExtentAt", -1);
331 * AccessibleTable_getColumnExtentAt:
332 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
333 * @row: the specified table row, zero-indexed.
334 * @column: the specified table column, zero-indexed.
336 * Get the number of columns spanned by the table cell at the specific row and column.
337 * (some tables can have cells which span multiple rows and/or columns).
339 * Returns: a long integer indicating the number of columns spanned by the specified cell.
342 AccessibleTable_getColumnExtentAt (AccessibleTable *obj,
348 cspi_return_val_if_fail (obj != NULL, -1);
351 Accessibility_Table_getColumnExtentAt (
352 CSPI_OBJREF (obj), (CORBA_long) row,
353 (CORBA_long) column, cspi_ev ());
355 cspi_return_val_if_ev ("getColumnExtentAt", -1);
361 * AccessibleTable_getRowHeader:
362 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
363 * @row: the specified table row, zero-indexed.
365 * Get the header associated with a table row, if available. This differs from
366 * AccessibleTable_getRowDescription, which returns a string.
368 * Returns: a #Accessible representatin of the specified table row, if available.
371 AccessibleTable_getRowHeader (AccessibleTable *obj,
374 return cspi_object_add (
375 Accessibility_Table_getRowHeader (CSPI_OBJREF (obj),
376 (CORBA_long) row, cspi_ev ()));
380 * AccessibleTable_getColumnHeader:
381 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
382 * @column: the specified table column, zero-indexed.
384 * Get the header associated with a table column, if available. This differs from
385 * AccessibleTable_getColumnDescription, which returns a string.
387 * Returns: a #Accessible representatin of the specified table column, if available.
390 AccessibleTable_getColumnHeader (AccessibleTable *obj,
393 return cspi_object_add (
394 Accessibility_Table_getColumnHeader (CSPI_OBJREF (obj),
395 (CORBA_long) column, cspi_ev ()));
399 * AccessibleTable_getNSelectedRows:
400 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
402 * Query a table to find out how many rows are currently selected. Not all tables
403 * support row selection.
405 * Returns: a long integer indicating the number of rows currently selected.
408 AccessibleTable_getNSelectedRows (AccessibleTable *obj)
412 cspi_return_val_if_fail (obj != NULL, -1);
415 Accessibility_Table__get_nSelectedRows (CSPI_OBJREF (obj), cspi_ev ());
417 cspi_return_val_if_ev ("getNSelectedRows", -1);
423 cspi_long_seq_to_array (Accessibility_LongSeq *seq, long int **array)
427 if (!cspi_check_ev ("getSelectionItems"))
433 length = seq->_length;
435 j = *array = malloc (sizeof (long) * length);
437 for (i = 0; i < length; i++)
439 j[i] = seq->_buffer [i];
448 * AccessibleTable_getSelectedRows:
449 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
450 * @selectedRows: a doubly indirected pointer which will be set to the address
451 * of an array of long integers, specifying which rows are currently selected.
453 * Query a table for a list of indices of rows which are currently selected.
455 * Returns: a long integer indicating the length of the array returned in @selectedRows.
458 AccessibleTable_getSelectedRows (AccessibleTable *obj,
459 long int **selectedRows)
461 Accessibility_LongSeq *rows;
463 *selectedRows = NULL;
465 cspi_return_val_if_fail (obj != NULL, 0);
467 rows = Accessibility_Table_getSelectedRows (CSPI_OBJREF (obj), cspi_ev ());
469 return cspi_long_seq_to_array (rows, selectedRows);
473 * AccessibleTable_getNSelectedColumns:
474 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
476 * Query a table to find out how many columnss are currently selected. Not all tables
477 * support column selection.
479 * Returns: a long integer indicating the number of columns currently selected.
482 AccessibleTable_getNSelectedColumns (AccessibleTable *obj)
486 cspi_return_val_if_fail (obj != NULL, -1);
489 Accessibility_Table__get_nSelectedColumns (CSPI_OBJREF (obj), cspi_ev ());
491 cspi_return_val_if_ev ("getNSelectedColumns", -1);
497 * AccessibleTable_getSelectedColumns:
498 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
499 * @selectedColumns: a doubly indirected pointer which will be set to the address
500 * of an array of long integers, specifying which columns are currently selected.
502 * Query a table for a list of indices of columns which are currently selected.
503 * Not all tables support column selection.
505 * Returns: a long integer indicating the length of the array returned in @selectedColumns.
508 AccessibleTable_getSelectedColumns (AccessibleTable *obj,
509 long int **selectedColumns)
511 Accessibility_LongSeq *columns;
513 *selectedColumns = NULL;
515 cspi_return_val_if_fail (obj != NULL, 0);
517 columns = Accessibility_Table_getSelectedColumns (CSPI_OBJREF (obj), cspi_ev ());
519 return cspi_long_seq_to_array (columns, selectedColumns);
523 * AccessibleTable_isRowSelected:
524 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
527 * Determine whether a table row is selected. Not all tables support row selection.
529 * Returns: #TRUE if the specified row is currently selected, #FALSE if not.
532 AccessibleTable_isRowSelected (AccessibleTable *obj,
537 cspi_return_val_if_fail (obj != NULL, FALSE);
540 Accessibility_Table_isRowSelected (CSPI_OBJREF (obj),
541 (CORBA_long) row, cspi_ev ());
543 cspi_return_val_if_ev ("isRowSelected", FALSE);
549 * AccessibleTable_isColumnSelected:
550 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
553 * Determine whether specified table column is selected.
554 * Not all tables support column selection.
556 * Returns: #TRUE if the specified column is currently selected, #FALSE if not.
559 AccessibleTable_isColumnSelected (AccessibleTable *obj,
564 cspi_return_val_if_fail (obj != NULL, FALSE);
567 Accessibility_Table_isColumnSelected (CSPI_OBJREF (obj),
568 (CORBA_long) column, cspi_ev ());
570 cspi_return_val_if_ev ("isColumnSelected", FALSE);
576 * AccessibleTable_addRowSelection:
577 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
580 * Select the specified row, adding it to the current row selection.
581 * Not all tables support row selection.
583 * Returns: #TRUE if the specified row was successfully selected, #FALSE if not.
586 AccessibleTable_addRowSelection (AccessibleTable *obj,
591 cspi_return_val_if_fail (obj != NULL, FALSE);
594 Accessibility_Table_addRowSelection (CSPI_OBJREF (obj),
595 (CORBA_long) row, cspi_ev ());
597 cspi_return_val_if_ev ("addRowSelection", FALSE);
603 * AccessibleTable_addColumnSelection:
604 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
607 * Select the specified column, adding it to the current column selection.
608 * Not all tables support column selection.
610 * Returns: #TRUE if the specified column was successfully selected, #FALSE if not.
613 AccessibleTable_addColumnSelection (AccessibleTable *obj,
618 cspi_return_val_if_fail (obj != NULL, FALSE);
621 Accessibility_Table_addColumnSelection (CSPI_OBJREF (obj),
622 (CORBA_long) column, cspi_ev ());
624 cspi_return_val_if_ev ("addColumnSelection", FALSE);
630 * AccessibleTable_removeRowSelection:
631 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
634 * De-select the specified row, removing it to the current row selection.
635 * Not all tables support row selection.
637 * Returns: #TRUE if the specified row was successfully de-selected, #FALSE if not.
640 AccessibleTable_removeRowSelection (AccessibleTable *obj,
645 cspi_return_val_if_fail (obj != NULL, FALSE);
648 Accessibility_Table_removeRowSelection (CSPI_OBJREF (obj),
649 (CORBA_long) row, cspi_ev ());
651 cspi_return_val_if_ev ("removeRowSelection", FALSE);
657 * AccessibleTable_removeColumnSelection:
658 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
661 * De-select the specified column, removing it to the current column selection.
662 * Not all tables support column selection.
664 * Returns: #TRUE if the specified column was successfully de-selected, #FALSE if not.
667 AccessibleTable_removeColumnSelection (AccessibleTable *obj,
672 cspi_return_val_if_fail (obj != NULL, FALSE);
675 Accessibility_Table_removeColumnSelection (CSPI_OBJREF (obj),
676 (CORBA_long) column, cspi_ev ());
678 cspi_return_val_if_ev ("removeColumnSelection", FALSE);
684 * AccessibleTable_isSelected:
685 * @obj: a pointer to the #AccessibleTable implementor on which to operate.
689 * Determine whether the cell at a specific row and column is selected.
691 * Returns: #TRUE if the specified cell is currently selected, #FALSE if not.
694 AccessibleTable_isSelected (AccessibleTable *obj,
700 cspi_return_val_if_fail (obj != NULL, FALSE);
703 Accessibility_Table_isSelected (CSPI_OBJREF (obj),
705 (CORBA_long) column, cspi_ev ());
707 cspi_return_val_if_ev ("isSelected", FALSE);