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". Those cells should
34 * implement the interface #AtkTableCell, but #Atk doesn't require
35 * them to be direct children of the current #AtkTable. They can be
36 * grand-children, grand-grand-children etc. #AtkTable provides the
37 * API needed to get a individual cell based on the row and column
40 * Children of #AtkTable are frequently "lightweight" objects, that
41 * is, they may not have backing widgets in the host UI toolkit. They
42 * are therefore often transient.
44 * Since tables are often very complex, #AtkTable includes provision
45 * for offering simplified summary information, as well as row and
46 * column headers and captions. Headers and captions are #AtkObjects
47 * which may implement other interfaces (#AtkText, #AtkImage, etc.) as
48 * appropriate. #AtkTable summaries may themselves be (simplified)
51 * Note for implementors: in the past, #AtkTable required that all the
52 * cells should be direct children of #AtkTable, and provided some
53 * index based methods to request the cells. The practice showed that
54 * that forcing made #AtkTable implementation complex, and hard to
55 * expose other kind of children, like rows or captions. Right now,
56 * index-based methods are deprecated.
70 static void atk_table_base_init (gpointer *g_class);
72 static guint atk_table_signals[LAST_SIGNAL] = { 0 };
75 atk_table_get_type (void)
77 static GType type = 0;
82 sizeof (AtkTableIface),
83 (GBaseInitFunc) atk_table_base_init,
84 (GBaseFinalizeFunc) NULL,
88 type = g_type_register_static (G_TYPE_INTERFACE, "AtkTable", &tinfo, 0);
96 atk_table_base_init (gpointer *g_class)
98 static gboolean initialized = FALSE;
103 * AtkTable::row-inserted:
104 * @atktable: the object which received the signal.
105 * @arg1: The index of the first row inserted.
106 * @arg2: The number of rows inserted.
108 * The "row-inserted" signal is emitted by an object which
109 * implements the AtkTable interface when a row is inserted.
111 atk_table_signals[ROW_INSERTED] =
112 g_signal_new ("row_inserted",
115 G_STRUCT_OFFSET (AtkTableIface, row_inserted),
116 (GSignalAccumulator) NULL, NULL,
117 atk_marshal_VOID__INT_INT,
119 2, G_TYPE_INT, G_TYPE_INT);
121 * AtkTable::column-inserted:
122 * @atktable: the object which received the signal.
123 * @arg1: The index of the column inserted.
124 * @arg2: The number of colums inserted.
126 * The "column-inserted" signal is emitted by an object which
127 * implements the AtkTable interface when a column is inserted.
129 atk_table_signals[COLUMN_INSERTED] =
130 g_signal_new ("column_inserted",
133 G_STRUCT_OFFSET (AtkTableIface, column_inserted),
134 (GSignalAccumulator) NULL, NULL,
135 atk_marshal_VOID__INT_INT,
137 2, G_TYPE_INT, G_TYPE_INT);
139 * AtkTable::row-deleted:
140 * @atktable: the object which received the signal.
141 * @arg1: The index of the first row deleted.
142 * @arg2: The number of rows deleted.
144 * The "row-deleted" signal is emitted by an object which
145 * implements the AtkTable interface when a row is deleted.
147 atk_table_signals[ROW_DELETED] =
148 g_signal_new ("row_deleted",
151 G_STRUCT_OFFSET (AtkTableIface, row_deleted),
152 (GSignalAccumulator) NULL, NULL,
153 atk_marshal_VOID__INT_INT,
155 2, G_TYPE_INT, G_TYPE_INT);
157 * AtkTable::column-deleted:
158 * @atktable: the object which received the signal.
159 * @arg1: The index of the first column deleted.
160 * @arg2: The number of columns deleted.
162 * The "column-deleted" signal is emitted by an object which
163 * implements the AtkTable interface when a column is deleted.
165 atk_table_signals[COLUMN_DELETED] =
166 g_signal_new ("column_deleted",
169 G_STRUCT_OFFSET (AtkTableIface, column_deleted),
170 (GSignalAccumulator) NULL, NULL,
171 atk_marshal_VOID__INT_INT,
173 2, G_TYPE_INT, G_TYPE_INT);
175 * AtkTable::row-reordered:
176 * @atktable: the object which received the signal.
178 * The "row-reordered" signal is emitted by an object which
179 * implements the AtkTable interface when the rows are
182 atk_table_signals[ROW_REORDERED] =
183 g_signal_new ("row_reordered",
186 G_STRUCT_OFFSET (AtkTableIface, row_reordered),
187 (GSignalAccumulator) NULL, NULL,
188 g_cclosure_marshal_VOID__VOID,
192 * AtkTable::column-reordered:
193 * @atktable: the object which received the signal.
195 * The "column-reordered" signal is emitted by an object which
196 * implements the AtkTable interface when the columns are
199 atk_table_signals[COLUMN_REORDERED] =
200 g_signal_new ("column_reordered",
203 G_STRUCT_OFFSET (AtkTableIface, column_reordered),
204 (GSignalAccumulator) NULL, NULL,
205 g_cclosure_marshal_VOID__VOID,
210 * AtkTable::model-changed:
211 * @atktable: the object which received the signal.
213 * The "model-changed" signal is emitted by an object which
214 * implements the AtkTable interface when the model displayed by
217 atk_table_signals[MODEL_CHANGED] =
218 g_signal_new ("model_changed",
221 G_STRUCT_OFFSET (AtkTableIface, model_changed),
222 (GSignalAccumulator) NULL, NULL,
223 g_cclosure_marshal_VOID__VOID,
232 * @table: a GObject instance that implements AtkTableIface
233 * @row: a #gint representing a row in @table
234 * @column: a #gint representing a column in @table
236 * Get a reference to the table cell at @row, @column. This cell
237 * should implement the interface #AtkTableCell
239 * Returns: (transfer full): an #AtkObject representing the referred
243 atk_table_ref_at (AtkTable *table,
247 AtkTableIface *iface;
249 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
250 g_return_val_if_fail (row >= 0, NULL);
251 g_return_val_if_fail (column >= 0, NULL);
253 iface = ATK_TABLE_GET_IFACE (table);
256 return (iface->ref_at) (table, row, column);
262 * atk_table_get_index_at:
263 * @table: a GObject instance that implements AtkTableIface
264 * @row: a #gint representing a row in @table
265 * @column: a #gint representing a column in @table
267 * Gets a #gint representing the index at the specified @row and
270 * Deprecated: Since 2.12. Use atk_table_ref_at() in order to get the
271 * accessible that represents the cell at (@row, @column)
273 * Returns: a #gint representing the index at specified position.
274 * The value -1 is returned if the object at row,column is not a child
275 * of table or table does not implement this interface.
278 atk_table_get_index_at (AtkTable *table,
282 AtkTableIface *iface;
284 g_return_val_if_fail (ATK_IS_TABLE (table), -1);
285 g_return_val_if_fail (row >= 0, -1);
286 g_return_val_if_fail (column >= 0, -1);
288 iface = ATK_TABLE_GET_IFACE (table);
290 if (iface->get_index_at)
291 return (iface->get_index_at) (table, row, column);
297 * atk_table_get_row_at_index:
298 * @table: a GObject instance that implements AtkTableInterface
299 * @index_: a #gint representing an index in @table
301 * Gets a #gint representing the row at the specified @index_.
303 * Deprecated: since 2.12.
305 * Returns: a gint representing the row at the specified index,
306 * or -1 if the table does not implement this method.
309 atk_table_get_row_at_index (AtkTable *table,
312 AtkTableIface *iface;
314 g_return_val_if_fail (ATK_IS_TABLE (table), -1);
316 iface = ATK_TABLE_GET_IFACE (table);
318 if (iface->get_row_at_index)
319 return (iface->get_row_at_index) (table, index);
325 * atk_table_get_column_at_index:
326 * @table: a GObject instance that implements AtkTableInterface
327 * @index_: a #gint representing an index in @table
329 * Gets a #gint representing the column at the specified @index_.
331 * Deprecated: Since 2.12.
333 * Returns: a gint representing the column at the specified index,
334 * or -1 if the table does not implement this method.
337 atk_table_get_column_at_index (AtkTable *table,
340 AtkTableIface *iface;
342 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
344 iface = ATK_TABLE_GET_IFACE (table);
346 if (iface->get_column_at_index)
347 return (iface->get_column_at_index) (table, index);
353 * atk_table_get_caption:
354 * @table: a GObject instance that implements AtkTableInterface
356 * Gets the caption for the @table.
358 * Returns: (transfer none): a AtkObject* representing the table caption, or
359 * %NULL if value does not implement this interface.
362 atk_table_get_caption (AtkTable *table)
364 AtkTableIface *iface;
366 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
368 iface = ATK_TABLE_GET_IFACE (table);
370 if (iface->get_caption)
371 return (iface->get_caption) (table);
377 * atk_table_get_n_columns:
378 * @table: a GObject instance that implements AtkTableIface
380 * Gets the number of columns in the table.
382 * Returns: a gint representing the number of columns, or 0
383 * if value does not implement this interface.
386 atk_table_get_n_columns (AtkTable *table)
388 AtkTableIface *iface;
390 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
392 iface = ATK_TABLE_GET_IFACE (table);
394 if (iface->get_n_columns)
395 return (iface->get_n_columns) (table);
401 * atk_table_get_column_description:
402 * @table: a GObject instance that implements AtkTableIface
403 * @column: a #gint representing a column in @table
405 * Gets the description text of the specified @column in the table
407 * Returns: a gchar* representing the column description, or %NULL
408 * if value does not implement this interface.
411 atk_table_get_column_description (AtkTable *table,
414 AtkTableIface *iface;
416 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
418 iface = ATK_TABLE_GET_IFACE (table);
420 if (iface->get_column_description)
421 return (iface->get_column_description) (table, column);
427 * atk_table_get_column_extent_at:
428 * @table: a GObject instance that implements AtkTableIface
429 * @row: a #gint representing a row in @table
430 * @column: a #gint representing a column in @table
432 * Gets the number of columns occupied by the accessible object
433 * at the specified @row and @column in the @table.
435 * Returns: a gint representing the column extent at specified position, or 0
436 * if value does not implement this interface.
439 atk_table_get_column_extent_at (AtkTable *table,
443 AtkTableIface *iface;
445 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
447 iface = ATK_TABLE_GET_IFACE (table);
449 if (iface->get_column_extent_at)
450 return (iface->get_column_extent_at) (table, row, column);
456 * atk_table_get_column_header:
457 * @table: a GObject instance that implements AtkTableIface
458 * @column: a #gint representing a column in the table
460 * Gets the column header of a specified column in an accessible table.
462 * Returns: (transfer none): a AtkObject* representing the specified column
463 * header, or %NULL if value does not implement this interface.
466 atk_table_get_column_header (AtkTable *table, gint column)
468 AtkTableIface *iface;
470 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
472 iface = ATK_TABLE_GET_IFACE (table);
474 if (iface->get_column_header)
475 return (iface->get_column_header) (table, column);
481 * atk_table_get_n_rows:
482 * @table: a GObject instance that implements AtkTableIface
484 * Gets the number of rows in the table.
486 * Returns: a gint representing the number of rows, or 0
487 * if value does not implement this interface.
490 atk_table_get_n_rows (AtkTable *table)
492 AtkTableIface *iface;
494 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
496 iface = ATK_TABLE_GET_IFACE (table);
498 if (iface->get_n_rows)
499 return (iface->get_n_rows) (table);
505 * atk_table_get_row_description:
506 * @table: a GObject instance that implements AtkTableIface
507 * @row: a #gint representing a row in @table
509 * Gets the description text of the specified row in the table
511 * Returns: a gchar* representing the row description, or %NULL
512 * if value does not implement this interface.
515 atk_table_get_row_description (AtkTable *table,
518 AtkTableIface *iface;
520 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
522 iface = ATK_TABLE_GET_IFACE (table);
524 if (iface->get_row_description)
525 return (iface->get_row_description) (table, row);
531 * atk_table_get_row_extent_at:
532 * @table: a GObject instance that implements AtkTableIface
533 * @row: a #gint representing a row in @table
534 * @column: a #gint representing a column in @table
536 * Gets the number of rows occupied by the accessible object
537 * at a specified @row and @column in the @table.
539 * Returns: a gint representing the row extent at specified position, or 0
540 * if value does not implement this interface.
543 atk_table_get_row_extent_at (AtkTable *table,
547 AtkTableIface *iface;
549 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
551 iface = ATK_TABLE_GET_IFACE (table);
553 if (iface->get_row_extent_at)
554 return (iface->get_row_extent_at) (table, row, column);
560 * atk_table_get_row_header:
561 * @table: a GObject instance that implements AtkTableIface
562 * @row: a #gint representing a row in the table
564 * Gets the row header of a specified row in an accessible table.
566 * Returns: (transfer none): a AtkObject* representing the specified row
567 * header, or %NULL if value does not implement this interface.
570 atk_table_get_row_header (AtkTable *table, gint row)
572 AtkTableIface *iface;
574 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
576 iface = ATK_TABLE_GET_IFACE (table);
578 if (iface->get_row_header)
579 return (iface->get_row_header) (table, row);
585 * atk_table_get_summary:
586 * @table: a GObject instance that implements AtkTableIface
588 * Gets the summary description of the table.
590 * Returns: (transfer full): a AtkObject* representing a summary description
591 * of the table, or zero if value does not implement this interface.
594 atk_table_get_summary (AtkTable *table)
596 AtkTableIface *iface;
598 g_return_val_if_fail (ATK_IS_TABLE (table), NULL);
600 iface = ATK_TABLE_GET_IFACE (table);
602 if (iface->get_summary)
603 return (iface->get_summary) (table);
609 * atk_table_get_selected_rows:
610 * @table: a GObject instance that implements AtkTableIface
611 * @selected: a #gint** that is to contain the selected row numbers
613 * Gets the selected rows of the table by initializing **selected with
614 * the selected row numbers. This array should be freed by the caller.
616 * Returns: a gint representing the number of selected rows,
617 * or zero if value does not implement this interface.
620 atk_table_get_selected_rows (AtkTable *table, gint **selected)
622 AtkTableIface *iface;
624 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
626 iface = ATK_TABLE_GET_IFACE (table);
628 if (iface->get_selected_rows)
629 return (iface->get_selected_rows) (table, selected);
635 * atk_table_get_selected_columns:
636 * @table: a GObject instance that implements AtkTableIface
637 * @selected: a #gint** that is to contain the selected columns numbers
639 * Gets the selected columns of the table by initializing **selected with
640 * the selected column numbers. This array should be freed by the caller.
642 * Returns: a gint representing the number of selected columns,
643 * or %0 if value does not implement this interface.
646 atk_table_get_selected_columns (AtkTable *table, gint **selected)
648 AtkTableIface *iface;
650 g_return_val_if_fail (ATK_IS_TABLE (table), 0);
652 iface = ATK_TABLE_GET_IFACE (table);
654 if (iface->get_selected_columns)
655 return (iface->get_selected_columns) (table, selected);
661 * atk_table_is_column_selected:
662 * @table: a GObject instance that implements AtkTableIface
663 * @column: a #gint representing a column in @table
665 * Gets a boolean value indicating whether the specified @column
668 * Returns: a gboolean representing if the column is selected, or 0
669 * if value does not implement this interface.
672 atk_table_is_column_selected (AtkTable *table,
675 AtkTableIface *iface;
677 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
679 iface = ATK_TABLE_GET_IFACE (table);
681 if (iface->is_column_selected)
682 return (iface->is_column_selected) (table, column);
688 * atk_table_is_row_selected:
689 * @table: a GObject instance that implements AtkTableIface
690 * @row: a #gint representing a row in @table
692 * Gets a boolean value indicating whether the specified @row
695 * Returns: a gboolean representing if the row is selected, or 0
696 * if value does not implement this interface.
699 atk_table_is_row_selected (AtkTable *table,
702 AtkTableIface *iface;
704 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
706 iface = ATK_TABLE_GET_IFACE (table);
708 if (iface->is_row_selected)
709 return (iface->is_row_selected) (table, row);
715 * atk_table_is_selected:
716 * @table: a GObject instance that implements AtkTableIface
717 * @row: a #gint representing a row in @table
718 * @column: a #gint representing a column in @table
720 * Gets a boolean value indicating whether the accessible object
721 * at the specified @row and @column is selected
723 * Returns: a gboolean representing if the cell is selected, or 0
724 * if value does not implement this interface.
727 atk_table_is_selected (AtkTable *table,
731 AtkTableIface *iface;
733 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
735 iface = ATK_TABLE_GET_IFACE (table);
737 if (iface->is_selected)
738 return (iface->is_selected) (table, row, column);
744 * atk_table_add_row_selection:
745 * @table: a GObject instance that implements AtkTableIface
746 * @row: a #gint representing a row in @table
748 * Adds the specified @row to the selection.
750 * Returns: a gboolean representing if row was successfully added to selection,
751 * or 0 if value does not implement this interface.
754 atk_table_add_row_selection (AtkTable *table,
757 AtkTableIface *iface;
759 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
761 iface = ATK_TABLE_GET_IFACE (table);
763 if (iface->add_row_selection)
764 return (iface->add_row_selection) (table, row);
769 * atk_table_remove_row_selection:
770 * @table: a GObject instance that implements AtkTableIface
771 * @row: a #gint representing a row in @table
773 * Removes the specified @row from the selection.
775 * Returns: a gboolean representing if the row was successfully removed from
776 * the selection, or 0 if value does not implement this interface.
779 atk_table_remove_row_selection (AtkTable *table,
782 AtkTableIface *iface;
784 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
786 iface = ATK_TABLE_GET_IFACE (table);
788 if (iface->remove_row_selection)
789 return (iface->remove_row_selection) (table, row);
794 * atk_table_add_column_selection:
795 * @table: a GObject instance that implements AtkTableIface
796 * @column: a #gint representing a column in @table
798 * Adds the specified @column to the selection.
800 * Returns: a gboolean representing if the column was successfully added to
801 * the selection, or 0 if value does not implement this interface.
804 atk_table_add_column_selection (AtkTable *table,
807 AtkTableIface *iface;
809 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
811 iface = ATK_TABLE_GET_IFACE (table);
813 if (iface->add_column_selection)
814 return (iface->add_column_selection) (table, column);
819 * atk_table_remove_column_selection:
820 * @table: a GObject instance that implements AtkTableIface
821 * @column: a #gint representing a column in @table
823 * Adds the specified @column to the selection.
825 * Returns: a gboolean representing if the column was successfully removed from
826 * the selection, or 0 if value does not implement this interface.
829 atk_table_remove_column_selection (AtkTable *table,
832 AtkTableIface *iface;
834 g_return_val_if_fail (ATK_IS_TABLE (table), FALSE);
836 iface = ATK_TABLE_GET_IFACE (table);
838 if (iface->remove_column_selection)
839 return (iface->remove_column_selection) (table, column);
845 * atk_table_set_caption:
846 * @table: a GObject instance that implements AtkTableIface
847 * @caption: a #AtkObject representing the caption to set for @table
849 * Sets the caption for the table.
852 atk_table_set_caption (AtkTable *table,
855 AtkTableIface *iface;
857 g_return_if_fail (ATK_IS_TABLE (table));
859 iface = ATK_TABLE_GET_IFACE (table);
861 if (iface->set_caption)
862 (iface->set_caption) (table, caption);
866 * atk_table_set_column_description:
867 * @table: a GObject instance that implements AtkTableIface
868 * @column: a #gint representing a column in @table
869 * @description: a #gchar representing the description text
870 * to set for the specified @column of the @table
872 * Sets the description text for the specified @column of the @table.
875 atk_table_set_column_description (AtkTable *table,
877 const gchar *description)
879 AtkTableIface *iface;
881 g_return_if_fail (ATK_IS_TABLE (table));
883 iface = ATK_TABLE_GET_IFACE (table);
885 if (iface->set_column_description)
886 (iface->set_column_description) (table, column, description);
890 * atk_table_set_column_header:
891 * @table: a GObject instance that implements AtkTableIface
892 * @column: a #gint representing a column in @table
893 * @header: an #AtkTable
895 * Sets the specified column header to @header.
898 atk_table_set_column_header (AtkTable *table,
902 AtkTableIface *iface;
904 g_return_if_fail (ATK_IS_TABLE (table));
906 iface = ATK_TABLE_GET_IFACE (table);
908 if (iface->set_column_header)
909 (iface->set_column_header) (table, column, header);
913 * atk_table_set_row_description:
914 * @table: a GObject instance that implements AtkTableIface
915 * @row: a #gint representing a row in @table
916 * @description: a #gchar representing the description text
917 * to set for the specified @row of @table
919 * Sets the description text for the specified @row of @table.
922 atk_table_set_row_description (AtkTable *table,
924 const gchar *description)
926 AtkTableIface *iface;
928 g_return_if_fail (ATK_IS_TABLE (table));
930 iface = ATK_TABLE_GET_IFACE (table);
932 if (iface->set_row_description)
933 (iface->set_row_description) (table, row, description);
937 * atk_table_set_row_header:
938 * @table: a GObject instance that implements AtkTableIface
939 * @row: a #gint representing a row in @table
940 * @header: an #AtkTable
942 * Sets the specified row header to @header.
945 atk_table_set_row_header (AtkTable *table,
949 AtkTableIface *iface;
951 g_return_if_fail (ATK_IS_TABLE (table));
953 iface = ATK_TABLE_GET_IFACE (table);
955 if (iface->set_row_header)
956 (iface->set_row_header) (table, row, header);
960 * atk_table_set_summary:
961 * @table: a GObject instance that implements AtkTableIface
962 * @accessible: an #AtkObject representing the summary description
965 * Sets the summary description of the table.
968 atk_table_set_summary (AtkTable *table,
969 AtkObject *accessible)
971 AtkTableIface *iface;
973 g_return_if_fail (ATK_IS_TABLE (table));
975 iface = ATK_TABLE_GET_IFACE (table);
977 if (iface->set_summary)
978 (iface->set_summary) (table, accessible);