1 /* ATK - Accessibility Toolkit
2 * Copyright 2001 Sun Microsystems Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 #include "atkmarshal.h"
25 * @Short_description: The ATK interface implemented for UI components
26 * which contain tabular or row/column information.
29 * #AtkTable should be implemented by components which present
30 * elements ordered via rows and columns. It may also be used to
31 * present tree-structured information if the nodes of the trees can
32 * be said to contain multiple "columns". Individual elements of an
33 * #AtkTable are typically referred to as "cells", and these cells are
34 * exposed by #AtkTable as child #AtkObjects of the #AtkTable. Both
35 * row/column and child-index-based access to these children is
38 * Children of #AtkTable are frequently "lightweight" objects, that
39 * is, they may not have backing widgets in the host UI toolkit. They
40 * are therefore often transient.
41 * Since tables are often very complex, #AtkTable includes provision
42 * for offering simplified summary information, as well as row and
43 * column headers and captions. Headers and captions are #AtkObjects
44 * which may implement other interfaces (#AtkText, #AtkImage, etc.) as
45 * appropriate. #AtkTable summaries may themselves be (simplified)
60 static void atk_table_base_init (gpointer *g_class);
62 static guint atk_table_signals[LAST_SIGNAL] = { 0 };
65 atk_table_get_type (void)
67 static GType type = 0;
72 sizeof (AtkTableIface),
73 (GBaseInitFunc) atk_table_base_init,
74 (GBaseFinalizeFunc) NULL,
78 type = g_type_register_static (G_TYPE_INTERFACE, "AtkTable", &tinfo, 0);
86 atk_table_base_init (gpointer *g_class)
88 static gboolean initialized = FALSE;
93 * AtkTable::row-inserted:
94 * @atktable: the object which received the signal.
95 * @arg1: The index of the first row inserted.
96 * @arg2: The number of rows inserted.
98 * The "row-inserted" signal is emitted by an object which
99 * implements the AtkTable interface when a row is inserted.
101 atk_table_signals[ROW_INSERTED] =
102 g_signal_new ("row_inserted",
105 G_STRUCT_OFFSET (AtkTableIface, row_inserted),
106 (GSignalAccumulator) NULL, NULL,
107 atk_marshal_VOID__INT_INT,
109 2, G_TYPE_INT, G_TYPE_INT);
111 * AtkTable::column-inserted:
112 * @atktable: the object which received the signal.
113 * @arg1: The index of the column inserted.
114 * @arg2: The number of colums inserted.
116 * The "column-inserted" signal is emitted by an object which
117 * implements the AtkTable interface when a column is inserted.
119 atk_table_signals[COLUMN_INSERTED] =
120 g_signal_new ("column_inserted",
123 G_STRUCT_OFFSET (AtkTableIface, column_inserted),
124 (GSignalAccumulator) NULL, NULL,
125 atk_marshal_VOID__INT_INT,
127 2, G_TYPE_INT, G_TYPE_INT);
129 * AtkTable::row-deleted:
130 * @atktable: the object which received the signal.
131 * @arg1: The index of the first row deleted.
132 * @arg2: The number of rows deleted.
134 * The "row-deleted" signal is emitted by an object which
135 * implements the AtkTable interface when a row is deleted.
137 atk_table_signals[ROW_DELETED] =
138 g_signal_new ("row_deleted",
141 G_STRUCT_OFFSET (AtkTableIface, row_deleted),
142 (GSignalAccumulator) NULL, NULL,
143 atk_marshal_VOID__INT_INT,
145 2, G_TYPE_INT, G_TYPE_INT);
147 * AtkTable::column-deleted:
148 * @atktable: the object which received the signal.
149 * @arg1: The index of the first column deleted.
150 * @arg2: The number of columns deleted.
152 * The "column-deleted" signal is emitted by an object which
153 * implements the AtkTable interface when a column is deleted.
155 atk_table_signals[COLUMN_DELETED] =
156 g_signal_new ("column_deleted",
159 G_STRUCT_OFFSET (AtkTableIface, column_deleted),
160 (GSignalAccumulator) NULL, NULL,
161 atk_marshal_VOID__INT_INT,
163 2, G_TYPE_INT, G_TYPE_INT);
165 * AtkTable::row-reordered:
166 * @atktable: the object which received the signal.
168 * The "row-reordered" signal is emitted by an object which
169 * implements the AtkTable interface when the rows are
172 atk_table_signals[ROW_REORDERED] =
173 g_signal_new ("row_reordered",
176 G_STRUCT_OFFSET (AtkTableIface, row_reordered),
177 (GSignalAccumulator) NULL, NULL,
178 g_cclosure_marshal_VOID__VOID,
182 * AtkTable::column-reordered:
183 * @atktable: the object which received the signal.
185 * The "column-reordered" signal is emitted by an object which
186 * implements the AtkTable interface when the columns are
189 atk_table_signals[COLUMN_REORDERED] =
190 g_signal_new ("column_reordered",
193 G_STRUCT_OFFSET (AtkTableIface, column_reordered),
194 (GSignalAccumulator) NULL, NULL,
195 g_cclosure_marshal_VOID__VOID,
200 * AtkTable::model-changed:
201 * @atktable: the object which received the signal.
203 * The "model-changed" signal is emitted by an object which
204 * implements the AtkTable interface when the model displayed by
207 atk_table_signals[MODEL_CHANGED] =
208 g_signal_new ("model_changed",
211 G_STRUCT_OFFSET (AtkTableIface, model_changed),
212 (GSignalAccumulator) NULL, NULL,
213 g_cclosure_marshal_VOID__VOID,
222 * @table: a GObject instance that implements AtkTableIface
223 * @row: a #gint representing a row in @table
224 * @column: a #gint representing a column in @table
226 * Get a reference to the table cell at @row, @column.
228 * Returns: (transfer full): a AtkObject* representing the referred to
232 atk_table_ref_at (AtkTable *table,
236 AtkTableIface *iface;
238 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
239 g_return_val_if_fail (row >= 0, NULL);
240 g_return_val_if_fail (column >= 0, NULL);
242 iface = ATK_TABLE_GET_IFACE (table);
245 return (iface->ref_at) (table, row, column);
251 * atk_table_get_index_at:
252 * @table: a GObject instance that implements AtkTableIface
253 * @row: a #gint representing a row in @table
254 * @column: a #gint representing a column in @table
256 * Gets a #gint representing the index at the specified @row and @column.
258 * Returns: a #gint representing the index at specified position.
259 * The value -1 is returned if the object at row,column is not a child
260 * of table or table does not implement this interface.
263 atk_table_get_index_at (AtkTable *table,
267 AtkTableIface *iface;
269 g_return_val_if_fail (ATK_IS_TABLE (table), -1);
270 g_return_val_if_fail (row >= 0, -1);
271 g_return_val_if_fail (column >= 0, -1);
273 iface = ATK_TABLE_GET_IFACE (table);
275 if (iface->get_index_at)
276 return (iface->get_index_at) (table, row, column);
282 * atk_table_get_row_at_index:
283 * @table: a GObject instance that implements AtkTableInterface
284 * @index_: a #gint representing an index in @table
286 * Gets a #gint representing the row at the specified @index_.
288 * Returns: a gint representing the row at the specified index,
289 * or -1 if the table does not implement this interface
292 atk_table_get_row_at_index (AtkTable *table,
295 AtkTableIface *iface;
297 g_return_val_if_fail (ATK_IS_TABLE (table), -1);
299 iface = ATK_TABLE_GET_IFACE (table);
301 if (iface->get_row_at_index)
302 return (iface->get_row_at_index) (table, index);
308 * atk_table_get_column_at_index:
309 * @table: a GObject instance that implements AtkTableInterface
310 * @index_: a #gint representing an index in @table
312 * Gets a #gint representing the column at the specified @index_.
314 * Returns: a gint representing the column at the specified index,
315 * or -1 if the table does not implement this interface
318 atk_table_get_column_at_index (AtkTable *table,
321 AtkTableIface *iface;
323 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
325 iface = ATK_TABLE_GET_IFACE (table);
327 if (iface->get_column_at_index)
328 return (iface->get_column_at_index) (table, index);
334 * atk_table_get_caption:
335 * @table: a GObject instance that implements AtkTableInterface
337 * Gets the caption for the @table.
339 * Returns: (transfer none): a AtkObject* representing the table caption, or
340 * %NULL if value does not implement this interface.
343 atk_table_get_caption (AtkTable *table)
345 AtkTableIface *iface;
347 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
349 iface = ATK_TABLE_GET_IFACE (table);
351 if (iface->get_caption)
352 return (iface->get_caption) (table);
358 * atk_table_get_n_columns:
359 * @table: a GObject instance that implements AtkTableIface
361 * Gets the number of columns in the table.
363 * Returns: a gint representing the number of columns, or 0
364 * if value does not implement this interface.
367 atk_table_get_n_columns (AtkTable *table)
369 AtkTableIface *iface;
371 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
373 iface = ATK_TABLE_GET_IFACE (table);
375 if (iface->get_n_columns)
376 return (iface->get_n_columns) (table);
382 * atk_table_get_column_description:
383 * @table: a GObject instance that implements AtkTableIface
384 * @column: a #gint representing a column in @table
386 * Gets the description text of the specified @column in the table
388 * Returns: a gchar* representing the column description, or %NULL
389 * if value does not implement this interface.
392 atk_table_get_column_description (AtkTable *table,
395 AtkTableIface *iface;
397 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
399 iface = ATK_TABLE_GET_IFACE (table);
401 if (iface->get_column_description)
402 return (iface->get_column_description) (table, column);
408 * atk_table_get_column_extent_at:
409 * @table: a GObject instance that implements AtkTableIface
410 * @row: a #gint representing a row in @table
411 * @column: a #gint representing a column in @table
413 * Gets the number of columns occupied by the accessible object
414 * at the specified @row and @column in the @table.
416 * Returns: a gint representing the column extent at specified position, or 0
417 * if value does not implement this interface.
420 atk_table_get_column_extent_at (AtkTable *table,
424 AtkTableIface *iface;
426 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
428 iface = ATK_TABLE_GET_IFACE (table);
430 if (iface->get_column_extent_at)
431 return (iface->get_column_extent_at) (table, row, column);
437 * atk_table_get_column_header:
438 * @table: a GObject instance that implements AtkTableIface
439 * @column: a #gint representing a column in the table
441 * Gets the column header of a specified column in an accessible table.
443 * Returns: (transfer none): a AtkObject* representing the specified column
444 * header, or %NULL if value does not implement this interface.
447 atk_table_get_column_header (AtkTable *table, gint column)
449 AtkTableIface *iface;
451 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
453 iface = ATK_TABLE_GET_IFACE (table);
455 if (iface->get_column_header)
456 return (iface->get_column_header) (table, column);
462 * atk_table_get_n_rows:
463 * @table: a GObject instance that implements AtkTableIface
465 * Gets the number of rows in the table.
467 * Returns: a gint representing the number of rows, or 0
468 * if value does not implement this interface.
471 atk_table_get_n_rows (AtkTable *table)
473 AtkTableIface *iface;
475 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
477 iface = ATK_TABLE_GET_IFACE (table);
479 if (iface->get_n_rows)
480 return (iface->get_n_rows) (table);
486 * atk_table_get_row_description:
487 * @table: a GObject instance that implements AtkTableIface
488 * @row: a #gint representing a row in @table
490 * Gets the description text of the specified row in the table
492 * Returns: a gchar* representing the row description, or %NULL
493 * if value does not implement this interface.
496 atk_table_get_row_description (AtkTable *table,
499 AtkTableIface *iface;
501 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
503 iface = ATK_TABLE_GET_IFACE (table);
505 if (iface->get_row_description)
506 return (iface->get_row_description) (table, row);
512 * atk_table_get_row_extent_at:
513 * @table: a GObject instance that implements AtkTableIface
514 * @row: a #gint representing a row in @table
515 * @column: a #gint representing a column in @table
517 * Gets the number of rows occupied by the accessible object
518 * at a specified @row and @column in the @table.
520 * Returns: a gint representing the row extent at specified position, or 0
521 * if value does not implement this interface.
524 atk_table_get_row_extent_at (AtkTable *table,
528 AtkTableIface *iface;
530 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
532 iface = ATK_TABLE_GET_IFACE (table);
534 if (iface->get_row_extent_at)
535 return (iface->get_row_extent_at) (table, row, column);
541 * atk_table_get_row_header:
542 * @table: a GObject instance that implements AtkTableIface
543 * @row: a #gint representing a row in the table
545 * Gets the row header of a specified row in an accessible table.
547 * Returns: (transfer none): a AtkObject* representing the specified row
548 * header, or %NULL if value does not implement this interface.
551 atk_table_get_row_header (AtkTable *table, gint row)
553 AtkTableIface *iface;
555 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
557 iface = ATK_TABLE_GET_IFACE (table);
559 if (iface->get_row_header)
560 return (iface->get_row_header) (table, row);
566 * atk_table_get_summary:
567 * @table: a GObject instance that implements AtkTableIface
569 * Gets the summary description of the table.
571 * Returns: (transfer full): a AtkObject* representing a summary description
572 * of the table, or zero if value does not implement this interface.
575 atk_table_get_summary (AtkTable *table)
577 AtkTableIface *iface;
579 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
581 iface = ATK_TABLE_GET_IFACE (table);
583 if (iface->get_summary)
584 return (iface->get_summary) (table);
590 * atk_table_get_selected_rows:
591 * @table: a GObject instance that implements AtkTableIface
592 * @selected: a #gint** that is to contain the selected row numbers
594 * Gets the selected rows of the table by initializing **selected with
595 * the selected row numbers. This array should be freed by the caller.
597 * Returns: a gint representing the number of selected rows,
598 * or zero if value does not implement this interface.
601 atk_table_get_selected_rows (AtkTable *table, gint **selected)
603 AtkTableIface *iface;
605 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
607 iface = ATK_TABLE_GET_IFACE (table);
609 if (iface->get_selected_rows)
610 return (iface->get_selected_rows) (table, selected);
616 * atk_table_get_selected_columns:
617 * @table: a GObject instance that implements AtkTableIface
618 * @selected: a #gint** that is to contain the selected columns numbers
620 * Gets the selected columns of the table by initializing **selected with
621 * the selected column numbers. This array should be freed by the caller.
623 * Returns: a gint representing the number of selected columns,
624 * or %0 if value does not implement this interface.
627 atk_table_get_selected_columns (AtkTable *table, gint **selected)
629 AtkTableIface *iface;
631 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
633 iface = ATK_TABLE_GET_IFACE (table);
635 if (iface->get_selected_columns)
636 return (iface->get_selected_columns) (table, selected);
642 * atk_table_is_column_selected:
643 * @table: a GObject instance that implements AtkTableIface
644 * @column: a #gint representing a column in @table
646 * Gets a boolean value indicating whether the specified @column
649 * Returns: a gboolean representing if the column is selected, or 0
650 * if value does not implement this interface.
653 atk_table_is_column_selected (AtkTable *table,
656 AtkTableIface *iface;
658 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
660 iface = ATK_TABLE_GET_IFACE (table);
662 if (iface->is_column_selected)
663 return (iface->is_column_selected) (table, column);
669 * atk_table_is_row_selected:
670 * @table: a GObject instance that implements AtkTableIface
671 * @row: a #gint representing a row in @table
673 * Gets a boolean value indicating whether the specified @row
676 * Returns: a gboolean representing if the row is selected, or 0
677 * if value does not implement this interface.
680 atk_table_is_row_selected (AtkTable *table,
683 AtkTableIface *iface;
685 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
687 iface = ATK_TABLE_GET_IFACE (table);
689 if (iface->is_row_selected)
690 return (iface->is_row_selected) (table, row);
696 * atk_table_is_selected:
697 * @table: a GObject instance that implements AtkTableIface
698 * @row: a #gint representing a row in @table
699 * @column: a #gint representing a column in @table
701 * Gets a boolean value indicating whether the accessible object
702 * at the specified @row and @column is selected
704 * Returns: a gboolean representing if the cell is selected, or 0
705 * if value does not implement this interface.
708 atk_table_is_selected (AtkTable *table,
712 AtkTableIface *iface;
714 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
716 iface = ATK_TABLE_GET_IFACE (table);
718 if (iface->is_selected)
719 return (iface->is_selected) (table, row, column);
725 * atk_table_add_row_selection:
726 * @table: a GObject instance that implements AtkTableIface
727 * @row: a #gint representing a row in @table
729 * Adds the specified @row to the selection.
731 * Returns: a gboolean representing if row was successfully added to selection,
732 * or 0 if value does not implement this interface.
735 atk_table_add_row_selection (AtkTable *table,
738 AtkTableIface *iface;
740 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
742 iface = ATK_TABLE_GET_IFACE (table);
744 if (iface->add_row_selection)
745 return (iface->add_row_selection) (table, row);
750 * atk_table_remove_row_selection:
751 * @table: a GObject instance that implements AtkTableIface
752 * @row: a #gint representing a row in @table
754 * Removes the specified @row from the selection.
756 * Returns: a gboolean representing if the row was successfully removed from
757 * the selection, or 0 if value does not implement this interface.
760 atk_table_remove_row_selection (AtkTable *table,
763 AtkTableIface *iface;
765 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
767 iface = ATK_TABLE_GET_IFACE (table);
769 if (iface->remove_row_selection)
770 return (iface->remove_row_selection) (table, row);
775 * atk_table_add_column_selection:
776 * @table: a GObject instance that implements AtkTableIface
777 * @column: a #gint representing a column in @table
779 * Adds the specified @column to the selection.
781 * Returns: a gboolean representing if the column was successfully added to
782 * the selection, or 0 if value does not implement this interface.
785 atk_table_add_column_selection (AtkTable *table,
788 AtkTableIface *iface;
790 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
792 iface = ATK_TABLE_GET_IFACE (table);
794 if (iface->add_column_selection)
795 return (iface->add_column_selection) (table, column);
800 * atk_table_remove_column_selection:
801 * @table: a GObject instance that implements AtkTableIface
802 * @column: a #gint representing a column in @table
804 * Adds the specified @column to the selection.
806 * Returns: a gboolean representing if the column was successfully removed from
807 * the selection, or 0 if value does not implement this interface.
810 atk_table_remove_column_selection (AtkTable *table,
813 AtkTableIface *iface;
815 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
817 iface = ATK_TABLE_GET_IFACE (table);
819 if (iface->remove_column_selection)
820 return (iface->remove_column_selection) (table, column);
826 * atk_table_set_caption:
827 * @table: a GObject instance that implements AtkTableIface
828 * @caption: a #AtkObject representing the caption to set for @table
830 * Sets the caption for the table.
833 atk_table_set_caption (AtkTable *table,
836 AtkTableIface *iface;
838 g_return_if_fail (ATK_IS_TABLE (table));
840 iface = ATK_TABLE_GET_IFACE (table);
842 if (iface->set_caption)
843 (iface->set_caption) (table, caption);
847 * atk_table_set_column_description:
848 * @table: a GObject instance that implements AtkTableIface
849 * @column: a #gint representing a column in @table
850 * @description: a #gchar representing the description text
851 * to set for the specified @column of the @table
853 * Sets the description text for the specified @column of the @table.
856 atk_table_set_column_description (AtkTable *table,
858 const gchar *description)
860 AtkTableIface *iface;
862 g_return_if_fail (ATK_IS_TABLE (table));
864 iface = ATK_TABLE_GET_IFACE (table);
866 if (iface->set_column_description)
867 (iface->set_column_description) (table, column, description);
871 * atk_table_set_column_header:
872 * @table: a GObject instance that implements AtkTableIface
873 * @column: a #gint representing a column in @table
874 * @header: an #AtkTable
876 * Sets the specified column header to @header.
879 atk_table_set_column_header (AtkTable *table,
883 AtkTableIface *iface;
885 g_return_if_fail (ATK_IS_TABLE (table));
887 iface = ATK_TABLE_GET_IFACE (table);
889 if (iface->set_column_header)
890 (iface->set_column_header) (table, column, header);
894 * atk_table_set_row_description:
895 * @table: a GObject instance that implements AtkTableIface
896 * @row: a #gint representing a row in @table
897 * @description: a #gchar representing the description text
898 * to set for the specified @row of @table
900 * Sets the description text for the specified @row of @table.
903 atk_table_set_row_description (AtkTable *table,
905 const gchar *description)
907 AtkTableIface *iface;
909 g_return_if_fail (ATK_IS_TABLE (table));
911 iface = ATK_TABLE_GET_IFACE (table);
913 if (iface->set_row_description)
914 (iface->set_row_description) (table, row, description);
918 * atk_table_set_row_header:
919 * @table: a GObject instance that implements AtkTableIface
920 * @row: a #gint representing a row in @table
921 * @header: an #AtkTable
923 * Sets the specified row header to @header.
926 atk_table_set_row_header (AtkTable *table,
930 AtkTableIface *iface;
932 g_return_if_fail (ATK_IS_TABLE (table));
934 iface = ATK_TABLE_GET_IFACE (table);
936 if (iface->set_row_header)
937 (iface->set_row_header) (table, row, header);
941 * atk_table_set_summary:
942 * @table: a GObject instance that implements AtkTableIface
943 * @accessible: an #AtkObject representing the summary description
946 * Sets the summary description of the table.
949 atk_table_set_summary (AtkTable *table,
950 AtkObject *accessible)
952 AtkTableIface *iface;
954 g_return_if_fail (ATK_IS_TABLE (table));
956 iface = ATK_TABLE_GET_IFACE (table);
958 if (iface->set_summary)
959 (iface->set_summary) (table, accessible);