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, see <http://www.gnu.org/licenses/>.
19 #include "atkmarshal.h"
23 * @Short_description: The ATK interface implemented for UI components
24 * which contain tabular or row/column information.
27 * #AtkTable should be implemented by components which present
28 * elements ordered via rows and columns. It may also be used to
29 * present tree-structured information if the nodes of the trees can
30 * be said to contain multiple "columns". Individual elements of an
31 * #AtkTable are typically referred to as "cells", and these cells are
32 * exposed by #AtkTable as child #AtkObjects of the #AtkTable. Both
33 * row/column and child-index-based access to these children is
36 * Children of #AtkTable are frequently "lightweight" objects, that
37 * is, they may not have backing widgets in the host UI toolkit. They
38 * are therefore often transient.
39 * Since tables are often very complex, #AtkTable includes provision
40 * for offering simplified summary information, as well as row and
41 * column headers and captions. Headers and captions are #AtkObjects
42 * which may implement other interfaces (#AtkText, #AtkImage, etc.) as
43 * appropriate. #AtkTable summaries may themselves be (simplified)
58 static void atk_table_base_init (gpointer *g_class);
60 static guint atk_table_signals[LAST_SIGNAL] = { 0 };
63 atk_table_get_type (void)
65 static GType type = 0;
70 sizeof (AtkTableIface),
71 (GBaseInitFunc) atk_table_base_init,
72 (GBaseFinalizeFunc) NULL,
76 type = g_type_register_static (G_TYPE_INTERFACE, "AtkTable", &tinfo, 0);
84 atk_table_base_init (gpointer *g_class)
86 static gboolean initialized = FALSE;
91 * AtkTable::row-inserted:
92 * @atktable: the object which received the signal.
93 * @arg1: The index of the first row inserted.
94 * @arg2: The number of rows inserted.
96 * The "row-inserted" signal is emitted by an object which
97 * implements the AtkTable interface when a row is inserted.
99 atk_table_signals[ROW_INSERTED] =
100 g_signal_new ("row_inserted",
103 G_STRUCT_OFFSET (AtkTableIface, row_inserted),
104 (GSignalAccumulator) NULL, NULL,
105 atk_marshal_VOID__INT_INT,
107 2, G_TYPE_INT, G_TYPE_INT);
109 * AtkTable::column-inserted:
110 * @atktable: the object which received the signal.
111 * @arg1: The index of the column inserted.
112 * @arg2: The number of colums inserted.
114 * The "column-inserted" signal is emitted by an object which
115 * implements the AtkTable interface when a column is inserted.
117 atk_table_signals[COLUMN_INSERTED] =
118 g_signal_new ("column_inserted",
121 G_STRUCT_OFFSET (AtkTableIface, column_inserted),
122 (GSignalAccumulator) NULL, NULL,
123 atk_marshal_VOID__INT_INT,
125 2, G_TYPE_INT, G_TYPE_INT);
127 * AtkTable::row-deleted:
128 * @atktable: the object which received the signal.
129 * @arg1: The index of the first row deleted.
130 * @arg2: The number of rows deleted.
132 * The "row-deleted" signal is emitted by an object which
133 * implements the AtkTable interface when a row is deleted.
135 atk_table_signals[ROW_DELETED] =
136 g_signal_new ("row_deleted",
139 G_STRUCT_OFFSET (AtkTableIface, row_deleted),
140 (GSignalAccumulator) NULL, NULL,
141 atk_marshal_VOID__INT_INT,
143 2, G_TYPE_INT, G_TYPE_INT);
145 * AtkTable::column-deleted:
146 * @atktable: the object which received the signal.
147 * @arg1: The index of the first column deleted.
148 * @arg2: The number of columns deleted.
150 * The "column-deleted" signal is emitted by an object which
151 * implements the AtkTable interface when a column is deleted.
153 atk_table_signals[COLUMN_DELETED] =
154 g_signal_new ("column_deleted",
157 G_STRUCT_OFFSET (AtkTableIface, column_deleted),
158 (GSignalAccumulator) NULL, NULL,
159 atk_marshal_VOID__INT_INT,
161 2, G_TYPE_INT, G_TYPE_INT);
163 * AtkTable::row-reordered:
164 * @atktable: the object which received the signal.
166 * The "row-reordered" signal is emitted by an object which
167 * implements the AtkTable interface when the rows are
170 atk_table_signals[ROW_REORDERED] =
171 g_signal_new ("row_reordered",
174 G_STRUCT_OFFSET (AtkTableIface, row_reordered),
175 (GSignalAccumulator) NULL, NULL,
176 g_cclosure_marshal_VOID__VOID,
180 * AtkTable::column-reordered:
181 * @atktable: the object which received the signal.
183 * The "column-reordered" signal is emitted by an object which
184 * implements the AtkTable interface when the columns are
187 atk_table_signals[COLUMN_REORDERED] =
188 g_signal_new ("column_reordered",
191 G_STRUCT_OFFSET (AtkTableIface, column_reordered),
192 (GSignalAccumulator) NULL, NULL,
193 g_cclosure_marshal_VOID__VOID,
198 * AtkTable::model-changed:
199 * @atktable: the object which received the signal.
201 * The "model-changed" signal is emitted by an object which
202 * implements the AtkTable interface when the model displayed by
205 atk_table_signals[MODEL_CHANGED] =
206 g_signal_new ("model_changed",
209 G_STRUCT_OFFSET (AtkTableIface, model_changed),
210 (GSignalAccumulator) NULL, NULL,
211 g_cclosure_marshal_VOID__VOID,
220 * @table: a GObject instance that implements AtkTableIface
221 * @row: a #gint representing a row in @table
222 * @column: a #gint representing a column in @table
224 * Get a reference to the table cell at @row, @column.
226 * Returns: (transfer full): a AtkObject* representing the referred to
230 atk_table_ref_at (AtkTable *table,
234 AtkTableIface *iface;
236 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
237 g_return_val_if_fail (row >= 0, NULL);
238 g_return_val_if_fail (column >= 0, NULL);
240 iface = ATK_TABLE_GET_IFACE (table);
243 return (iface->ref_at) (table, row, column);
249 * atk_table_get_index_at:
250 * @table: a GObject instance that implements AtkTableIface
251 * @row: a #gint representing a row in @table
252 * @column: a #gint representing a column in @table
254 * Gets a #gint representing the index at the specified @row and @column.
256 * Returns: a #gint representing the index at specified position.
257 * The value -1 is returned if the object at row,column is not a child
258 * of table or table does not implement this interface.
261 atk_table_get_index_at (AtkTable *table,
265 AtkTableIface *iface;
267 g_return_val_if_fail (ATK_IS_TABLE (table), -1);
268 g_return_val_if_fail (row >= 0, -1);
269 g_return_val_if_fail (column >= 0, -1);
271 iface = ATK_TABLE_GET_IFACE (table);
273 if (iface->get_index_at)
274 return (iface->get_index_at) (table, row, column);
280 * atk_table_get_row_at_index:
281 * @table: a GObject instance that implements AtkTableInterface
282 * @index_: a #gint representing an index in @table
284 * Gets a #gint representing the row at the specified @index_.
286 * Returns: a gint representing the row at the specified index,
287 * or -1 if the table does not implement this interface
290 atk_table_get_row_at_index (AtkTable *table,
293 AtkTableIface *iface;
295 g_return_val_if_fail (ATK_IS_TABLE (table), -1);
297 iface = ATK_TABLE_GET_IFACE (table);
299 if (iface->get_row_at_index)
300 return (iface->get_row_at_index) (table, index);
306 * atk_table_get_column_at_index:
307 * @table: a GObject instance that implements AtkTableInterface
308 * @index_: a #gint representing an index in @table
310 * Gets a #gint representing the column at the specified @index_.
312 * Returns: a gint representing the column at the specified index,
313 * or -1 if the table does not implement this interface
316 atk_table_get_column_at_index (AtkTable *table,
319 AtkTableIface *iface;
321 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
323 iface = ATK_TABLE_GET_IFACE (table);
325 if (iface->get_column_at_index)
326 return (iface->get_column_at_index) (table, index);
332 * atk_table_get_caption:
333 * @table: a GObject instance that implements AtkTableInterface
335 * Gets the caption for the @table.
337 * Returns: (transfer none): a AtkObject* representing the table caption, or
338 * %NULL if value does not implement this interface.
341 atk_table_get_caption (AtkTable *table)
343 AtkTableIface *iface;
345 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
347 iface = ATK_TABLE_GET_IFACE (table);
349 if (iface->get_caption)
350 return (iface->get_caption) (table);
356 * atk_table_get_n_columns:
357 * @table: a GObject instance that implements AtkTableIface
359 * Gets the number of columns in the table.
361 * Returns: a gint representing the number of columns, or 0
362 * if value does not implement this interface.
365 atk_table_get_n_columns (AtkTable *table)
367 AtkTableIface *iface;
369 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
371 iface = ATK_TABLE_GET_IFACE (table);
373 if (iface->get_n_columns)
374 return (iface->get_n_columns) (table);
380 * atk_table_get_column_description:
381 * @table: a GObject instance that implements AtkTableIface
382 * @column: a #gint representing a column in @table
384 * Gets the description text of the specified @column in the table
386 * Returns: a gchar* representing the column description, or %NULL
387 * if value does not implement this interface.
390 atk_table_get_column_description (AtkTable *table,
393 AtkTableIface *iface;
395 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
397 iface = ATK_TABLE_GET_IFACE (table);
399 if (iface->get_column_description)
400 return (iface->get_column_description) (table, column);
406 * atk_table_get_column_extent_at:
407 * @table: a GObject instance that implements AtkTableIface
408 * @row: a #gint representing a row in @table
409 * @column: a #gint representing a column in @table
411 * Gets the number of columns occupied by the accessible object
412 * at the specified @row and @column in the @table.
414 * Returns: a gint representing the column extent at specified position, or 0
415 * if value does not implement this interface.
418 atk_table_get_column_extent_at (AtkTable *table,
422 AtkTableIface *iface;
424 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
426 iface = ATK_TABLE_GET_IFACE (table);
428 if (iface->get_column_extent_at)
429 return (iface->get_column_extent_at) (table, row, column);
435 * atk_table_get_column_header:
436 * @table: a GObject instance that implements AtkTableIface
437 * @column: a #gint representing a column in the table
439 * Gets the column header of a specified column in an accessible table.
441 * Returns: (transfer none): a AtkObject* representing the specified column
442 * header, or %NULL if value does not implement this interface.
445 atk_table_get_column_header (AtkTable *table, gint column)
447 AtkTableIface *iface;
449 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
451 iface = ATK_TABLE_GET_IFACE (table);
453 if (iface->get_column_header)
454 return (iface->get_column_header) (table, column);
460 * atk_table_get_n_rows:
461 * @table: a GObject instance that implements AtkTableIface
463 * Gets the number of rows in the table.
465 * Returns: a gint representing the number of rows, or 0
466 * if value does not implement this interface.
469 atk_table_get_n_rows (AtkTable *table)
471 AtkTableIface *iface;
473 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
475 iface = ATK_TABLE_GET_IFACE (table);
477 if (iface->get_n_rows)
478 return (iface->get_n_rows) (table);
484 * atk_table_get_row_description:
485 * @table: a GObject instance that implements AtkTableIface
486 * @row: a #gint representing a row in @table
488 * Gets the description text of the specified row in the table
490 * Returns: a gchar* representing the row description, or %NULL
491 * if value does not implement this interface.
494 atk_table_get_row_description (AtkTable *table,
497 AtkTableIface *iface;
499 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
501 iface = ATK_TABLE_GET_IFACE (table);
503 if (iface->get_row_description)
504 return (iface->get_row_description) (table, row);
510 * atk_table_get_row_extent_at:
511 * @table: a GObject instance that implements AtkTableIface
512 * @row: a #gint representing a row in @table
513 * @column: a #gint representing a column in @table
515 * Gets the number of rows occupied by the accessible object
516 * at a specified @row and @column in the @table.
518 * Returns: a gint representing the row extent at specified position, or 0
519 * if value does not implement this interface.
522 atk_table_get_row_extent_at (AtkTable *table,
526 AtkTableIface *iface;
528 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
530 iface = ATK_TABLE_GET_IFACE (table);
532 if (iface->get_row_extent_at)
533 return (iface->get_row_extent_at) (table, row, column);
539 * atk_table_get_row_header:
540 * @table: a GObject instance that implements AtkTableIface
541 * @row: a #gint representing a row in the table
543 * Gets the row header of a specified row in an accessible table.
545 * Returns: (transfer none): a AtkObject* representing the specified row
546 * header, or %NULL if value does not implement this interface.
549 atk_table_get_row_header (AtkTable *table, gint row)
551 AtkTableIface *iface;
553 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
555 iface = ATK_TABLE_GET_IFACE (table);
557 if (iface->get_row_header)
558 return (iface->get_row_header) (table, row);
564 * atk_table_get_summary:
565 * @table: a GObject instance that implements AtkTableIface
567 * Gets the summary description of the table.
569 * Returns: (transfer full): a AtkObject* representing a summary description
570 * of the table, or zero if value does not implement this interface.
573 atk_table_get_summary (AtkTable *table)
575 AtkTableIface *iface;
577 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
579 iface = ATK_TABLE_GET_IFACE (table);
581 if (iface->get_summary)
582 return (iface->get_summary) (table);
588 * atk_table_get_selected_rows:
589 * @table: a GObject instance that implements AtkTableIface
590 * @selected: a #gint** that is to contain the selected row numbers
592 * Gets the selected rows of the table by initializing **selected with
593 * the selected row numbers. This array should be freed by the caller.
595 * Returns: a gint representing the number of selected rows,
596 * or zero if value does not implement this interface.
599 atk_table_get_selected_rows (AtkTable *table, gint **selected)
601 AtkTableIface *iface;
603 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
605 iface = ATK_TABLE_GET_IFACE (table);
607 if (iface->get_selected_rows)
608 return (iface->get_selected_rows) (table, selected);
614 * atk_table_get_selected_columns:
615 * @table: a GObject instance that implements AtkTableIface
616 * @selected: a #gint** that is to contain the selected columns numbers
618 * Gets the selected columns of the table by initializing **selected with
619 * the selected column numbers. This array should be freed by the caller.
621 * Returns: a gint representing the number of selected columns,
622 * or %0 if value does not implement this interface.
625 atk_table_get_selected_columns (AtkTable *table, gint **selected)
627 AtkTableIface *iface;
629 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
631 iface = ATK_TABLE_GET_IFACE (table);
633 if (iface->get_selected_columns)
634 return (iface->get_selected_columns) (table, selected);
640 * atk_table_is_column_selected:
641 * @table: a GObject instance that implements AtkTableIface
642 * @column: a #gint representing a column in @table
644 * Gets a boolean value indicating whether the specified @column
647 * Returns: a gboolean representing if the column is selected, or 0
648 * if value does not implement this interface.
651 atk_table_is_column_selected (AtkTable *table,
654 AtkTableIface *iface;
656 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
658 iface = ATK_TABLE_GET_IFACE (table);
660 if (iface->is_column_selected)
661 return (iface->is_column_selected) (table, column);
667 * atk_table_is_row_selected:
668 * @table: a GObject instance that implements AtkTableIface
669 * @row: a #gint representing a row in @table
671 * Gets a boolean value indicating whether the specified @row
674 * Returns: a gboolean representing if the row is selected, or 0
675 * if value does not implement this interface.
678 atk_table_is_row_selected (AtkTable *table,
681 AtkTableIface *iface;
683 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
685 iface = ATK_TABLE_GET_IFACE (table);
687 if (iface->is_row_selected)
688 return (iface->is_row_selected) (table, row);
694 * atk_table_is_selected:
695 * @table: a GObject instance that implements AtkTableIface
696 * @row: a #gint representing a row in @table
697 * @column: a #gint representing a column in @table
699 * Gets a boolean value indicating whether the accessible object
700 * at the specified @row and @column is selected
702 * Returns: a gboolean representing if the cell is selected, or 0
703 * if value does not implement this interface.
706 atk_table_is_selected (AtkTable *table,
710 AtkTableIface *iface;
712 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
714 iface = ATK_TABLE_GET_IFACE (table);
716 if (iface->is_selected)
717 return (iface->is_selected) (table, row, column);
723 * atk_table_add_row_selection:
724 * @table: a GObject instance that implements AtkTableIface
725 * @row: a #gint representing a row in @table
727 * Adds the specified @row to the selection.
729 * Returns: a gboolean representing if row was successfully added to selection,
730 * or 0 if value does not implement this interface.
733 atk_table_add_row_selection (AtkTable *table,
736 AtkTableIface *iface;
738 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
740 iface = ATK_TABLE_GET_IFACE (table);
742 if (iface->add_row_selection)
743 return (iface->add_row_selection) (table, row);
748 * atk_table_remove_row_selection:
749 * @table: a GObject instance that implements AtkTableIface
750 * @row: a #gint representing a row in @table
752 * Removes the specified @row from the selection.
754 * Returns: a gboolean representing if the row was successfully removed from
755 * the selection, or 0 if value does not implement this interface.
758 atk_table_remove_row_selection (AtkTable *table,
761 AtkTableIface *iface;
763 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
765 iface = ATK_TABLE_GET_IFACE (table);
767 if (iface->remove_row_selection)
768 return (iface->remove_row_selection) (table, row);
773 * atk_table_add_column_selection:
774 * @table: a GObject instance that implements AtkTableIface
775 * @column: a #gint representing a column in @table
777 * Adds the specified @column to the selection.
779 * Returns: a gboolean representing if the column was successfully added to
780 * the selection, or 0 if value does not implement this interface.
783 atk_table_add_column_selection (AtkTable *table,
786 AtkTableIface *iface;
788 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
790 iface = ATK_TABLE_GET_IFACE (table);
792 if (iface->add_column_selection)
793 return (iface->add_column_selection) (table, column);
798 * atk_table_remove_column_selection:
799 * @table: a GObject instance that implements AtkTableIface
800 * @column: a #gint representing a column in @table
802 * Adds the specified @column to the selection.
804 * Returns: a gboolean representing if the column was successfully removed from
805 * the selection, or 0 if value does not implement this interface.
808 atk_table_remove_column_selection (AtkTable *table,
811 AtkTableIface *iface;
813 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
815 iface = ATK_TABLE_GET_IFACE (table);
817 if (iface->remove_column_selection)
818 return (iface->remove_column_selection) (table, column);
824 * atk_table_set_caption:
825 * @table: a GObject instance that implements AtkTableIface
826 * @caption: a #AtkObject representing the caption to set for @table
828 * Sets the caption for the table.
831 atk_table_set_caption (AtkTable *table,
834 AtkTableIface *iface;
836 g_return_if_fail (ATK_IS_TABLE (table));
838 iface = ATK_TABLE_GET_IFACE (table);
840 if (iface->set_caption)
841 (iface->set_caption) (table, caption);
845 * atk_table_set_column_description:
846 * @table: a GObject instance that implements AtkTableIface
847 * @column: a #gint representing a column in @table
848 * @description: a #gchar representing the description text
849 * to set for the specified @column of the @table
851 * Sets the description text for the specified @column of the @table.
854 atk_table_set_column_description (AtkTable *table,
856 const gchar *description)
858 AtkTableIface *iface;
860 g_return_if_fail (ATK_IS_TABLE (table));
862 iface = ATK_TABLE_GET_IFACE (table);
864 if (iface->set_column_description)
865 (iface->set_column_description) (table, column, description);
869 * atk_table_set_column_header:
870 * @table: a GObject instance that implements AtkTableIface
871 * @column: a #gint representing a column in @table
872 * @header: an #AtkTable
874 * Sets the specified column header to @header.
877 atk_table_set_column_header (AtkTable *table,
881 AtkTableIface *iface;
883 g_return_if_fail (ATK_IS_TABLE (table));
885 iface = ATK_TABLE_GET_IFACE (table);
887 if (iface->set_column_header)
888 (iface->set_column_header) (table, column, header);
892 * atk_table_set_row_description:
893 * @table: a GObject instance that implements AtkTableIface
894 * @row: a #gint representing a row in @table
895 * @description: a #gchar representing the description text
896 * to set for the specified @row of @table
898 * Sets the description text for the specified @row of @table.
901 atk_table_set_row_description (AtkTable *table,
903 const gchar *description)
905 AtkTableIface *iface;
907 g_return_if_fail (ATK_IS_TABLE (table));
909 iface = ATK_TABLE_GET_IFACE (table);
911 if (iface->set_row_description)
912 (iface->set_row_description) (table, row, description);
916 * atk_table_set_row_header:
917 * @table: a GObject instance that implements AtkTableIface
918 * @row: a #gint representing a row in @table
919 * @header: an #AtkTable
921 * Sets the specified row header to @header.
924 atk_table_set_row_header (AtkTable *table,
928 AtkTableIface *iface;
930 g_return_if_fail (ATK_IS_TABLE (table));
932 iface = ATK_TABLE_GET_IFACE (table);
934 if (iface->set_row_header)
935 (iface->set_row_header) (table, row, header);
939 * atk_table_set_summary:
940 * @table: a GObject instance that implements AtkTableIface
941 * @accessible: an #AtkObject representing the summary description
944 * Sets the summary description of the table.
947 atk_table_set_summary (AtkTable *table,
948 AtkObject *accessible)
950 AtkTableIface *iface;
952 g_return_if_fail (ATK_IS_TABLE (table));
954 iface = ATK_TABLE_GET_IFACE (table);
956 if (iface->set_summary)
957 (iface->set_summary) (table, accessible);