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.
7 * Copyright 2010, 2011 Novell, Inc.
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Library General Public License for more details.
19 * You should have received a copy of the GNU Library General Public
20 * License along with this library; if not, write to the
21 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
22 * Boston, MA 02111-1307, USA.
25 #include <stdlib.h> /* for malloc */
26 #include "atspi-private.h"
29 * atspi_table_get_caption:
30 * @obj: a pointer to the #AtspiTable implementor on which to operate.
32 * Gets an accessible representation of the caption for an #AtspiTable.
34 * Returns: (transfer full): an #AtspiAccessible object that serves as
35 * the table's caption.
39 atspi_table_get_caption (AtspiTable *obj, GError **error)
41 AtspiAccessible *retval = NULL;
43 g_return_val_if_fail (obj != NULL, NULL);
45 _atspi_dbus_get_property (obj, atspi_interface_table, "Caption", error, "(so)", &retval);
50 * atspi_table_get_summary:
51 * @obj: a pointer to the #AtspiTable implementor on which to operate.
53 * Gets an accessible object which summarizes the contents of an #AtspiTable.
55 * Returns: (transfer full): an #AtspiAccessible object that serves as the
56 * table's summary (often a reduced #AtspiTable).
59 atspi_table_get_summary (AtspiTable *obj, GError **error)
61 AtspiAccessible *retval;
63 g_return_val_if_fail (obj != NULL, NULL);
65 _atspi_dbus_get_property (obj, atspi_interface_table, "Summary", error, "(so)", &retval);
71 * atspi_table_get_n_rows:
72 * @obj: a pointer to the #AtspiTable implementor on which to operate.
74 * Gets the number of rows in an #AtspiTable,
75 * exclusive of any rows that are programmatically hidden, but inclusive
76 * of rows that may be outside of the current scrolling window or viewport.
78 * Returns: a #gint indicating the number of rows in the table.
81 atspi_table_get_n_rows (AtspiTable *obj, GError **error)
83 dbus_int32_t retval = -1;
85 g_return_val_if_fail (obj != NULL, -1);
87 _atspi_dbus_get_property (obj, atspi_interface_table, "NRows", error, "i", &retval);
93 * atspi_table_get_n_columns:
94 * @obj: a pointer to the #AtspiTable implementor on which to operate.
96 * Gets the number of columns in an #AtspiTable,
97 * exclusive of any columns that are programmatically hidden, but inclusive
98 * of columns that may be outside of the current scrolling window or viewport.
100 * Returns: a #gint indicating the number of columns in the table.
103 atspi_table_get_n_columns (AtspiTable *obj, GError **error)
105 dbus_int32_t retval = -1;
107 g_return_val_if_fail (obj != NULL, -1);
109 _atspi_dbus_get_property (obj, atspi_interface_table, "NColumns", error, "i", &retval);
115 * atspi_table_get_accessible_at:
116 * @obj: a pointer to the #AtspiTable implementor on which to operate.
117 * @row: the specified table row, zero-indexed.
118 * @column: the specified table column, zero-indexed.
120 * Gets the table cell at the specified row and column indices.
121 * To get the accessible object at a particular (x, y) screen
122 * coordinate, use #atspi_component_get_accessible_at_point.
124 * Returns: (transfer full): an #AtspiAccessible object representing the
125 * specified table cell.
128 atspi_table_get_accessible_at (AtspiTable *obj,
133 dbus_int32_t d_row = row, d_column = column;
136 g_return_val_if_fail (obj != NULL, NULL);
138 reply = _atspi_dbus_call_partial (obj, atspi_interface_table, "GetAccessibleAt", error, "ii", d_row, d_column);
140 return _atspi_dbus_return_accessible_from_message (reply);
144 * atspi_table_get_index_at:
145 * @obj: a pointer to the #AtspiTable implementor on which to operate.
146 * @row: the specified table row, zero-indexed.
147 * @column: the specified table column, zero-indexed.
149 * Gets the 1-D child index corresponding to the specified 2-D row and
150 * column indices. To get the accessible object at a particular (x, y) screen
151 * coordinate, use #atspi_component_get_accessible_at_point.
153 * @see #atspi_table_get_row_at_index, #atspi_table_get_column_at_index
155 * Returns: a #gint which serves as the index of a specified cell in the
156 * table, in a form usable by #atspi_get_child_at_index.
159 atspi_table_get_index_at (AtspiTable *obj,
164 dbus_int32_t d_row = row, d_column = column;
165 dbus_int32_t retval = -1;
167 g_return_val_if_fail (obj != NULL, -1);
169 _atspi_dbus_call (obj, atspi_interface_table, "GetIndexAt", error, "ii=>i", d_row, d_column, &retval);
175 * atspi_table_get_row_at_index:
176 * @obj: a pointer to the #AtspiTable implementor on which to operate.
177 * @index: the specified child index, zero-indexed.
179 * Gets the table row index occupied by the child at a particular 1-D
182 * @see #atspi_table_get_index_at, #atspi_table_get_column_at_index
184 * Returns: a #gint indicating the first row spanned by the child of a
185 * table, at the specified 1-D (zero-offset) @index.
188 atspi_table_get_row_at_index (AtspiTable *obj,
192 dbus_int32_t d_index = index;
193 dbus_int32_t retval = -1;
195 g_return_val_if_fail (obj != NULL, -1);
197 _atspi_dbus_call (obj, atspi_interface_table, "GetRowAtIndex", error, "i=>i", d_index, &retval);
203 * atspi_table_get_column_at_index:
204 * @obj: a pointer to the #AtspiTable implementor on which to operate.
205 * @index: the specified child index, zero-indexed.
207 * Gets the table column index occupied by the child at a particular 1-D
210 * @see #atspi_table_get_index_at, #atspi_table_get_row_at_index
212 * Returns: a #gint indicating the first column spanned by the child of a
213 * table, at the specified 1-D (zero-offset) @index.
216 atspi_table_get_column_at_index (AtspiTable *obj,
220 dbus_int32_t d_index = index;
221 dbus_int32_t retval = -1;
223 g_return_val_if_fail (obj != NULL, -1);
225 _atspi_dbus_call (obj, atspi_interface_table, "GetColumnAtIndex", error, "i=>i", d_index, &retval);
231 * atspi_table_get_row_description:
232 * @obj: a pointer to the #AtspiTable implementor on which to operate.
233 * @row: the specified table row, zero-indexed.
235 * Gets a text description of a particular table row. This differs from
236 * #atspi_table_get_row_header, which returns an #AtspiAccessible.
238 * Returns: a UTF-8 string describing the specified table row, if available.
241 atspi_table_get_row_description (AtspiTable *obj,
245 dbus_int32_t d_row = row;
248 g_return_val_if_fail (obj != NULL, NULL);
250 _atspi_dbus_call (obj, atspi_interface_table, "GetRowDescription", error, "i=>s", d_row, &retval);
256 * atspi_table_get_column_description:
257 * @obj: a pointer to the #AtspiTable implementor on which to operate.
258 * @column: the specified table column, zero-indexed.
260 * Gets a text description of a particular table column. This differs from
261 * #atspi_table_get_column_header, which returns an #Accessible.
263 * Returns: a UTF-8 string describing the specified table column, if available.
266 atspi_table_get_column_description (AtspiTable *obj,
267 gint column, GError **error)
269 dbus_int32_t d_column = column;
272 g_return_val_if_fail (obj != NULL, NULL);
274 _atspi_dbus_call (obj, atspi_interface_table, "GetColumnDescription", error, "i=>s", d_column, &retval);
280 * atspi_table_get_row_extent_at:
281 * @obj: a pointer to the #AtspiTable implementor on which to operate.
282 * @row: the specified table row, zero-indexed.
283 * @column: the specified table column, zero-indexed.
285 * Gets the number of rows spanned by the table cell at the specific row
286 * and column. (some tables can have cells which span multiple rows
289 * Returns: a #gint indicating the number of rows spanned by the specified cell.
292 atspi_table_get_row_extent_at (AtspiTable *obj,
297 dbus_int32_t d_row = row, d_column = column;
298 dbus_int32_t retval = -1;
300 g_return_val_if_fail (obj != NULL, -1);
302 _atspi_dbus_call (obj, atspi_interface_table, "GetRowExtentAt", error, "ii=>i", d_row, d_column, &retval);
308 * atspi_table_get_column_extent_at:
309 * @obj: a pointer to the #AtspiTable implementor on which to operate.
310 * @row: the specified table row, zero-indexed.
311 * @column: the specified table column, zero-indexed.
313 * Gets the number of columns spanned by the table cell at the specific
314 * row and column (some tables can have cells which span multiple
315 * rows and/or columns).
317 * Returns: a #gint indicating the number of columns spanned by the specified cell.
320 atspi_table_get_column_extent_at (AtspiTable *obj,
325 dbus_int32_t d_row = row, d_column = column;
326 dbus_int32_t retval = -1;
328 g_return_val_if_fail (obj != NULL, -1);
330 _atspi_dbus_call (obj, atspi_interface_table, "GetColumnExtentAt", error, "ii=>i", d_row, d_column, &retval);
336 * atspi_table_get_row_header:
337 * @obj: a pointer to the #AtspiTable implementor on which to operate.
338 * @row: the specified table row, zero-indexed.
340 * Gets the header associated with a table row, if available. This differs from
341 * #atspi_table_get_row_description, which returns a string.
343 * Returns: (transfer full): an #AtspiAccessible representatin of the specified
344 * table row, if available.
347 atspi_table_get_row_header (AtspiTable *obj,
351 dbus_int32_t d_row = row;
354 g_return_val_if_fail (obj != NULL, NULL);
356 reply = _atspi_dbus_call_partial (obj, atspi_interface_table, "GetRowHeader", error, "i", d_row);
358 return _atspi_dbus_return_accessible_from_message (reply);
362 * atspi_table_get_column_header:
363 * @obj: a pointer to the #AtspiTable implementor on which to operate.
364 * @column: the specified table column, zero-indexed.
366 * Gets the header associated with a table column, if available.
367 * This differs from #atspi_table_get_column_description, which
370 * Returns: (transfer full): an #AtspiAccessible representation of the
371 * specified table column, if available.
374 atspi_table_get_column_header (AtspiTable *obj,
378 dbus_int32_t d_column = column;
381 g_return_val_if_fail (obj != NULL, NULL);
383 reply = _atspi_dbus_call_partial (obj, atspi_interface_table, "GetColumnHeader", error, "i", d_column);
385 return _atspi_dbus_return_accessible_from_message (reply);
389 * atspi_table_get_n_selected_rows:
390 * @obj: a pointer to the #AtspiTable implementor on which to operate.
392 * Query a table to find out how many rows are currently selected.
393 * Not all tables support row selection.
395 * Returns: a #gint indicating the number of rows currently selected.
398 atspi_table_get_n_selected_rows (AtspiTable *obj, GError **error)
400 dbus_int32_t retval = -1;
402 g_return_val_if_fail (obj != NULL, -1);
404 _atspi_dbus_get_property (obj, atspi_interface_table, "NSelectedRows", error, "i", &retval);
410 * atspi_table_get_selected_rows:
411 * @obj: a pointer to the #AtspiTable implementor on which to operate.
413 * Queries a table for a list of indices of rows which are currently selected.
415 * Returns: (element-type gint) (transfer full): an array of #gint values,
416 * specifying which rows are currently selected.
419 atspi_table_get_selected_rows (AtspiTable *obj,
424 g_return_val_if_fail (obj != NULL, 0);
426 _atspi_dbus_call (obj, atspi_interface_table, "GetSelectedRows", error, "=>ai", &rows);
432 * atspi_table_get_selected_columns:
433 * @obj: a pointer to the #AtspiTable implementor on which to operate.
435 * Queries a table for a list of indices of columns which are currently
438 * Returns: (element-type gint) (transfer full): an array of #gint values,
439 * specifying which columns are currently selected.
442 atspi_table_get_selected_columns (AtspiTable *obj,
445 GArray *columns = NULL;
447 g_return_val_if_fail (obj != NULL, 0);
449 _atspi_dbus_call (obj, atspi_interface_table, "GetSelectedColumns", error, "=>ai", &columns);
455 * atspi_table_get_n_selected_columns:
456 * @obj: a pointer to the #AtspiTable implementor on which to operate.
458 * Queries a table to find out how many columns are currently selected.
459 * Not all tables support column selection.
461 * Returns: a #gint indicating the number of columns currently selected.
464 atspi_table_get_n_selected_columns (AtspiTable *obj, GError **error)
466 dbus_int32_t retval = -1;
468 g_return_val_if_fail (obj != NULL, -1);
470 _atspi_dbus_get_property (obj, atspi_interface_table, "NSelectedColumns", error, "i", &retval);
476 * atspi_table_is_row_selected:
477 * @obj: a pointer to the #AtspiTable implementor on which to operate.
478 * @row: the zero-indexed row number of the row being queried.
480 * Determines whether a table row is selected. Not all tables support
483 * Returns: #TRUE if the specified row is currently selected, #FALSE if not.
486 atspi_table_is_row_selected (AtspiTable *obj,
490 dbus_int32_t d_row = row;
491 dbus_bool_t retval = FALSE;
493 g_return_val_if_fail (obj != NULL, FALSE);
495 _atspi_dbus_call (obj, atspi_interface_table, "IsRowSelected", error, "i=>b", d_row, &retval);
501 * atspi_table_is_column_selected:
502 * @obj: a pointer to the #AtspiTable implementor on which to operate.
503 * @column: the zero-indexed column number of the column being queried.
505 * Determines whether specified table column is selected.
506 * Not all tables support column selection.
508 * Returns: #TRUE if the specified column is currently selected, #FALSE if not.
511 atspi_table_is_column_selected (AtspiTable *obj,
515 dbus_int32_t d_column = column;
516 dbus_bool_t retval = FALSE;
518 g_return_val_if_fail (obj != NULL, FALSE);
520 _atspi_dbus_call (obj, atspi_interface_table, "IsColumnSelected", error, "i=>b", d_column, &retval);
526 * atspi_table_add_row_selection:
527 * @obj: a pointer to the #AtspiTable implementor on which to operate.
528 * @row: the zero-indexed row number of the row being selected.
530 * Selects the specified row, adding it to the current row selection.
531 * Not all tables support row selection.
533 * Returns: #TRUE if the specified row was successfully selected, #FALSE if not.
536 atspi_table_add_row_selection (AtspiTable *obj,
540 dbus_int32_t d_row = row;
541 dbus_bool_t retval = FALSE;
543 g_return_val_if_fail (obj != NULL, FALSE);
545 _atspi_dbus_call (obj, atspi_interface_table, "AddRowSelection", error, "i=>b", d_row, &retval);
551 * atspi_table_add_column_selection:
552 * @obj: a pointer to the #AtspiTable implementor on which to operate.
553 * @column: the zero-indexed column number of the column being selected.
555 * Selects the specified column, adding it to the current column selection.
556 * Not all tables support column selection.
558 * Returns: #TRUE if the specified column was successfully selected, #FALSE if not.
561 atspi_table_add_column_selection (AtspiTable *obj,
565 dbus_int32_t d_column = column;
566 dbus_bool_t retval = FALSE;
568 g_return_val_if_fail (obj != NULL, FALSE);
570 _atspi_dbus_call (obj, atspi_interface_table, "AddColumnSelection", error, "i=>b", d_column, &retval);
576 * atspi_table_remove_row_selection:
577 * @obj: a pointer to the #AtspiTable implementor on which to operate.
578 * @row: the zero-indexed number of the row being de-selected.
580 * De-selects the specified row, removing it from the current row selection.
581 * Not all tables support row selection.
583 * Returns: #TRUE if the specified row was successfully de-selected,
587 atspi_table_remove_row_selection (AtspiTable *obj,
591 dbus_int32_t d_row = row;
592 dbus_bool_t retval = FALSE;
594 g_return_val_if_fail (obj != NULL, FALSE);
596 _atspi_dbus_call (obj, atspi_interface_table, "RemoveRowSelection", error, "i=>b", d_row, &retval);
602 * atspi_table_remove_column_selection:
603 * @obj: a pointer to the #AtspiTable implementor on which to operate.
604 * @column: the zero-indexed column number of the column being de-selected.
606 * De-selects the specified column, removing it from the current column
608 * Not all tables support column selection.
610 * Returns: #TRUE if the specified column was successfully de-selected,
614 atspi_table_remove_column_selection (AtspiTable *obj,
618 dbus_int32_t d_column = column;
619 dbus_bool_t retval = FALSE;
621 g_return_val_if_fail (obj != NULL, FALSE);
623 _atspi_dbus_call (obj, atspi_interface_table, "RemoveColumnSelection", error, "i=>b", d_column, &retval);
629 * atspi_table_get_row_column_extents_at_index:
630 * @obj: a pointer to the #AtspiTable implementor on which to operate.
631 * @index: the index of the #AtspiTable child whose row/column
632 * extents are requested.
633 * @row: (out): back-filled with the first table row associated with
634 * the cell with child index.
635 * @col: (out): back-filled with the first table column associated
636 * with the cell with child index.
637 * @row_extents: (out): back-filled with the number of table rows
638 * across which child i extends.
639 * @col_extents: (out): back-filled with the number of table columns
640 * across which child i extends.
641 * @is_selected: (out): a boolean which is back-filled with #TRUE
642 * if the child at index i corresponds to a selected table cell,
645 * Given a child index, determines the row and column indices and
646 * extents, and whether the cell is currently selected. If
647 * the child at index is not a cell (for instance, if it is
648 * a summary, caption, etc.), #FALSE is returned.
651 * If the #AtspiTable child at index '6' extends across columns 5 and 6 of
652 * row 2 of an #AtspiTable instance, and is currently selected, then
654 * retval = atspi_table_get_row_column_extents_at_index (table, 6,
660 * will return #TRUE, and after the call
661 * row, col, row_extents, col_extents,
662 * and is_selected will contain 2, 5, 1, 2, and
663 * #TRUE, respectively.
665 * Returns: #TRUE if the index is associated with a valid table
666 * cell, #FALSE if the index does not correspond to a cell. If
667 * #FALSE is returned, the values of the out parameters are
671 atspi_table_get_row_column_extents_at_index (AtspiTable *obj,
672 gint index, gint *row, gint *col,
673 gint *row_extents, gint *col_extents,
674 gboolean *is_selected, GError **error)
676 dbus_int32_t d_index = index;
677 dbus_bool_t retval = FALSE;
678 dbus_int32_t d_row = 0, d_col = 0, d_row_extents = 0, d_col_extents = 0;
679 dbus_bool_t d_is_selected = FALSE;
681 g_return_val_if_fail (obj != NULL, FALSE);
683 _atspi_dbus_call (obj, atspi_interface_table, "GetRowColumnExtentsAtIndex", error, "i=>iiiibb", d_index, &d_row, &d_col, &d_row_extents, &d_col_extents, &d_is_selected, &retval);
686 *row_extents = d_row_extents;;
687 *col_extents = d_col_extents;
688 *is_selected = d_is_selected;;
695 * atspi_table_is_selected:
696 * @obj: a pointer to the #AtspiTable implementor on which to operate.
697 * @row: the zero-indexed row of the cell being queried.
698 * @column: the zero-indexed column of the cell being queried.
700 * Determines whether the cell at a specific row and column is selected.
702 * Returns: #TRUE if the specified cell is currently selected, #FALSE if not.
705 atspi_table_is_selected (AtspiTable *obj,
710 dbus_int32_t d_row = row, d_column = column;
711 dbus_bool_t retval = FALSE;
713 g_return_val_if_fail (obj != NULL, FALSE);
715 _atspi_dbus_call (obj, atspi_interface_table, "IsSelected", error, "ii=>b", d_row, d_column, &retval);
721 atspi_table_base_init (AtspiTable *klass)
726 atspi_table_get_type (void)
728 static GType type = 0;
731 static const GTypeInfo tinfo =
734 (GBaseInitFunc) atspi_table_base_init,
735 (GBaseFinalizeFunc) NULL,
738 type = g_type_register_static (G_TYPE_INTERFACE, "AtspiTable", &tinfo, 0);