X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=atk%2Fatktable.c;h=082de56d15e03ecdae4c9aa0d9f8fef859b7bb0a;hb=refs%2Fchanges%2F24%2F93124%2F1;hp=fdfb754c3c358693b31a1e56becfb46ab1d1aca6;hpb=98f86f729edf46e056fb91cf24d7a60bc40a742d;p=platform%2Fupstream%2Fatk.git diff --git a/atk/atktable.c b/atk/atktable.c index fdfb754..082de56 100755 --- a/atk/atktable.c +++ b/atk/atktable.c @@ -17,9 +17,47 @@ * Boston, MA 02111-1307, USA. */ +#include "config.h" + #include "atktable.h" #include "atkmarshal.h" +/** + * SECTION:atktable + * @Short_description: The ATK interface implemented for UI components + * which contain tabular or row/column information. + * @Title:AtkTable + * + * #AtkTable should be implemented by components which present + * elements ordered via rows and columns. It may also be used to + * present tree-structured information if the nodes of the trees can + * be said to contain multiple "columns". Individual elements of an + * #AtkTable are typically referred to as "cells". Those cells should + * implement the interface #AtkTableCell, but #Atk doesn't require + * them to be direct children of the current #AtkTable. They can be + * grand-children, grand-grand-children etc. #AtkTable provides the + * API needed to get a individual cell based on the row and column + * numbers. + * + * Children of #AtkTable are frequently "lightweight" objects, that + * is, they may not have backing widgets in the host UI toolkit. They + * are therefore often transient. + * + * Since tables are often very complex, #AtkTable includes provision + * for offering simplified summary information, as well as row and + * column headers and captions. Headers and captions are #AtkObjects + * which may implement other interfaces (#AtkText, #AtkImage, etc.) as + * appropriate. #AtkTable summaries may themselves be (simplified) + * #AtkTables, etc. + * + * Note for implementors: in the past, #AtkTable required that all the + * cells should be direct children of #AtkTable, and provided some + * index based methods to request the cells. The practice showed that + * that forcing made #AtkTable implementation complex, and hard to + * expose other kind of children, like rows or captions. Right now, + * index-based methods are deprecated. + */ + enum { ROW_INSERTED, ROW_DELETED, @@ -27,37 +65,31 @@ enum { COLUMN_DELETED, ROW_REORDERED, COLUMN_REORDERED, + MODEL_CHANGED, LAST_SIGNAL }; -struct _AtkTableIfaceClass -{ - GObjectClass parent; -}; - -typedef struct _AtkTableIfaceClass AtkTableIfaceClass; - -static void atk_table_base_init (gpointer *g_class); +static void atk_table_base_init (gpointer *g_class); static guint atk_table_signals[LAST_SIGNAL] = { 0 }; GType -atk_table_get_type () +atk_table_get_type (void) { static GType type = 0; - + if (!type) { GTypeInfo tinfo = { sizeof (AtkTableIface), (GBaseInitFunc) atk_table_base_init, (GBaseFinalizeFunc) NULL, - + }; - + type = g_type_register_static (G_TYPE_INTERFACE, "AtkTable", &tinfo, 0); } - + return type; } @@ -66,65 +98,135 @@ static void atk_table_base_init (gpointer *g_class) { static gboolean initialized = FALSE; - - if (! initialized) - { - atk_table_signals[ROW_INSERTED] = - g_signal_newc ("row_inserted", - ATK_TYPE_TABLE, - G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (AtkTableIface, model_changed), - (GSignalAccumulator) NULL, NULL, - atk_marshal_VOID__INT_INT, - G_TYPE_NONE, - 2, G_TYPE_INT, G_TYPE_INT); - atk_table_signals[COLUMN_INSERTED] = - g_signal_newc ("column_inserted", - ATK_TYPE_TABLE, - G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (AtkTableIface, model_changed), - (GSignalAccumulator) NULL, NULL, - atk_marshal_VOID__INT_INT, - G_TYPE_NONE, - 2, G_TYPE_INT, G_TYPE_INT); - atk_table_signals[ROW_DELETED] = - g_signal_newc ("row_deleted", - ATK_TYPE_TABLE, - G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (AtkTableIface, model_changed), - (GSignalAccumulator) NULL, NULL, - atk_marshal_VOID__INT_INT, - G_TYPE_NONE, - 2, G_TYPE_INT, G_TYPE_INT); - atk_table_signals[COLUMN_DELETED] = - g_signal_newc ("column_deleted", - ATK_TYPE_TABLE, - G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (AtkTableIface, model_changed), - (GSignalAccumulator) NULL, NULL, - atk_marshal_VOID__INT_INT, - G_TYPE_NONE, - 2, G_TYPE_INT, G_TYPE_INT); - atk_table_signals[ROW_REORDERED] = - g_signal_newc ("row_reordered", - ATK_TYPE_TABLE, - G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (AtkTableIface, model_changed), - (GSignalAccumulator) NULL, NULL, - atk_marshal_VOID__INT_INT, - G_TYPE_NONE, - 0); - atk_table_signals[COLUMN_REORDERED] = - g_signal_newc ("column_reordered", - ATK_TYPE_TABLE, - G_SIGNAL_RUN_LAST, - G_STRUCT_OFFSET (AtkTableIface, model_changed), - (GSignalAccumulator) NULL, NULL, - atk_marshal_VOID__INT_INT, - G_TYPE_NONE, - 0); - initialized = TRUE; - } + + if (!initialized) + { + /** + * AtkTable::row-inserted: + * @atktable: the object which received the signal. + * @arg1: The index of the first row inserted. + * @arg2: The number of rows inserted. + * + * The "row-inserted" signal is emitted by an object which + * implements the AtkTable interface when a row is inserted. + */ + atk_table_signals[ROW_INSERTED] = + g_signal_new ("row_inserted", + ATK_TYPE_TABLE, + G_SIGNAL_RUN_LAST, + G_STRUCT_OFFSET (AtkTableIface, row_inserted), + (GSignalAccumulator) NULL, NULL, + atk_marshal_VOID__INT_INT, + G_TYPE_NONE, + 2, G_TYPE_INT, G_TYPE_INT); + /** + * AtkTable::column-inserted: + * @atktable: the object which received the signal. + * @arg1: The index of the column inserted. + * @arg2: The number of colums inserted. + * + * The "column-inserted" signal is emitted by an object which + * implements the AtkTable interface when a column is inserted. + */ + atk_table_signals[COLUMN_INSERTED] = + g_signal_new ("column_inserted", + ATK_TYPE_TABLE, + G_SIGNAL_RUN_LAST, + G_STRUCT_OFFSET (AtkTableIface, column_inserted), + (GSignalAccumulator) NULL, NULL, + atk_marshal_VOID__INT_INT, + G_TYPE_NONE, + 2, G_TYPE_INT, G_TYPE_INT); + /** + * AtkTable::row-deleted: + * @atktable: the object which received the signal. + * @arg1: The index of the first row deleted. + * @arg2: The number of rows deleted. + * + * The "row-deleted" signal is emitted by an object which + * implements the AtkTable interface when a row is deleted. + */ + atk_table_signals[ROW_DELETED] = + g_signal_new ("row_deleted", + ATK_TYPE_TABLE, + G_SIGNAL_RUN_LAST, + G_STRUCT_OFFSET (AtkTableIface, row_deleted), + (GSignalAccumulator) NULL, NULL, + atk_marshal_VOID__INT_INT, + G_TYPE_NONE, + 2, G_TYPE_INT, G_TYPE_INT); + /** + * AtkTable::column-deleted: + * @atktable: the object which received the signal. + * @arg1: The index of the first column deleted. + * @arg2: The number of columns deleted. + * + * The "column-deleted" signal is emitted by an object which + * implements the AtkTable interface when a column is deleted. + */ + atk_table_signals[COLUMN_DELETED] = + g_signal_new ("column_deleted", + ATK_TYPE_TABLE, + G_SIGNAL_RUN_LAST, + G_STRUCT_OFFSET (AtkTableIface, column_deleted), + (GSignalAccumulator) NULL, NULL, + atk_marshal_VOID__INT_INT, + G_TYPE_NONE, + 2, G_TYPE_INT, G_TYPE_INT); + /** + * AtkTable::row-reordered: + * @atktable: the object which received the signal. + * + * The "row-reordered" signal is emitted by an object which + * implements the AtkTable interface when the rows are + * reordered. + */ + atk_table_signals[ROW_REORDERED] = + g_signal_new ("row_reordered", + ATK_TYPE_TABLE, + G_SIGNAL_RUN_LAST, + G_STRUCT_OFFSET (AtkTableIface, row_reordered), + (GSignalAccumulator) NULL, NULL, + g_cclosure_marshal_VOID__VOID, + G_TYPE_NONE, + 0); + /** + * AtkTable::column-reordered: + * @atktable: the object which received the signal. + * + * The "column-reordered" signal is emitted by an object which + * implements the AtkTable interface when the columns are + * reordered. + */ + atk_table_signals[COLUMN_REORDERED] = + g_signal_new ("column_reordered", + ATK_TYPE_TABLE, + G_SIGNAL_RUN_LAST, + G_STRUCT_OFFSET (AtkTableIface, column_reordered), + (GSignalAccumulator) NULL, NULL, + g_cclosure_marshal_VOID__VOID, + G_TYPE_NONE, + 0); + + /** + * AtkTable::model-changed: + * @atktable: the object which received the signal. + * + * The "model-changed" signal is emitted by an object which + * implements the AtkTable interface when the model displayed by + * the table changes. + */ + atk_table_signals[MODEL_CHANGED] = + g_signal_new ("model_changed", + ATK_TYPE_TABLE, + G_SIGNAL_RUN_LAST, + G_STRUCT_OFFSET (AtkTableIface, model_changed), + (GSignalAccumulator) NULL, NULL, + g_cclosure_marshal_VOID__VOID, + G_TYPE_NONE, 0); + + initialized = TRUE; + } } /** @@ -133,24 +235,27 @@ atk_table_base_init (gpointer *g_class) * @row: a #gint representing a row in @table * @column: a #gint representing a column in @table * - * Get a reference to the table cell at @row, @column + * Get a reference to the table cell at @row, @column. This cell + * should implement the interface #AtkTableCell * - * Returns: a AtkObject* representing the referred to accessible + * Returns: (transfer full): an #AtkObject representing the referred + * to accessible **/ AtkObject* -atk_table_ref_at (AtkTable *obj, +atk_table_ref_at (AtkTable *table, gint row, gint column) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), NULL); + g_return_val_if_fail (row >= 0, NULL); + g_return_val_if_fail (column >= 0, NULL); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->ref_at) - return (iface->ref_at) (obj, row, column); + return (iface->ref_at) (table, row, column); else return NULL; } @@ -161,96 +266,89 @@ atk_table_ref_at (AtkTable *obj, * @row: a #gint representing a row in @table * @column: a #gint representing a column in @table * - * Gets a #gint representing the index at the specified @row and @column, - * or 0 if value does not implement this interface. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. + * Gets a #gint representing the index at the specified @row and + * @column. * - * Returns: a #gint representing the index at specified position, or 0 - * if value does not implement this interface. + * Deprecated: Since 2.12. Use atk_table_ref_at() in order to get the + * accessible that represents the cell at (@row, @column) + * + * Returns: a #gint representing the index at specified position. + * The value -1 is returned if the object at row,column is not a child + * of table or table does not implement this interface. **/ gint -atk_table_get_index_at (AtkTable *obj, +atk_table_get_index_at (AtkTable *table, gint row, gint column) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, 0); - g_return_val_if_fail (ATK_IS_TABLE (obj), 0); + g_return_val_if_fail (ATK_IS_TABLE (table), -1); + g_return_val_if_fail (row >= 0, -1); + g_return_val_if_fail (column >= 0, -1); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_index_at) - return (iface->get_index_at) (obj, row, column); + return (iface->get_index_at) (table, row, column); else - return 0; + return -1; } /** * atk_table_get_row_at_index: * @table: a GObject instance that implements AtkTableInterface - * @index: a #gint representing an index in @table + * @index_: a #gint representing an index in @table * - * Gets a #gint representing the row at the specified @index, or 0 - * if the value does not implement this interface - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. + * Gets a #gint representing the row at the specified @index_. * - * Returns: a gint representing the row at the specified index, or 0 - * if value does not implement this interface. + * Deprecated: since 2.12. + * + * Returns: a gint representing the row at the specified index, + * or -1 if the table does not implement this method. **/ gint -atk_table_get_row_at_index (AtkTable *obj, +atk_table_get_row_at_index (AtkTable *table, gint index) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, 0); - g_return_val_if_fail (ATK_IS_TABLE (obj), 0); + g_return_val_if_fail (ATK_IS_TABLE (table), -1); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_row_at_index) - return (iface->get_row_at_index) (obj, index); + return (iface->get_row_at_index) (table, index); else - return 0; + return -1; } /** * atk_table_get_column_at_index: * @table: a GObject instance that implements AtkTableInterface - * @index: a #gint representing an index in @table + * @index_: a #gint representing an index in @table * - * Gets a #gint representing the column at the specified @index, or 0 - * if the value does not implement this interface - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. + * Gets a #gint representing the column at the specified @index_. * - * Returns: a gint representing the column at the specified index, or 0 - * if value does not implement this interface. + * Deprecated: Since 2.12. + * + * Returns: a gint representing the column at the specified index, + * or -1 if the table does not implement this method. **/ gint -atk_table_get_column_at_index (AtkTable *obj, +atk_table_get_column_at_index (AtkTable *table, gint index) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, 0); - g_return_val_if_fail (ATK_IS_TABLE (obj), 0); + g_return_val_if_fail (ATK_IS_TABLE (table), 0); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_column_at_index) - return (iface->get_column_at_index) (obj, index); + return (iface->get_column_at_index) (table, index); else - return 0; + return -1; } /** @@ -258,26 +356,21 @@ atk_table_get_column_at_index (AtkTable *obj, * @table: a GObject instance that implements AtkTableInterface * * Gets the caption for the @table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * - * Returns: a gchar* representing the table caption, or %NULL - * if value does not implement this interface. + * Returns: (nullable) (transfer none): a AtkObject* representing the + * table caption, or %NULL if value does not implement this interface. **/ -gchar* -atk_table_get_caption (AtkTable *obj) +AtkObject* +atk_table_get_caption (AtkTable *table) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), NULL); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_caption) - return (iface->get_caption) (obj); + return (iface->get_caption) (table); else return NULL; } @@ -287,26 +380,21 @@ atk_table_get_caption (AtkTable *obj) * @table: a GObject instance that implements AtkTableIface * * Gets the number of columns in the table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * * Returns: a gint representing the number of columns, or 0 * if value does not implement this interface. **/ gint -atk_table_get_n_columns (AtkTable *obj) +atk_table_get_n_columns (AtkTable *table) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, 0); - g_return_val_if_fail (ATK_IS_TABLE (obj), 0); + g_return_val_if_fail (ATK_IS_TABLE (table), 0); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_n_columns) - return (iface->get_n_columns) (obj); + return (iface->get_n_columns) (table); else return 0; } @@ -317,27 +405,22 @@ atk_table_get_n_columns (AtkTable *obj) * @column: a #gint representing a column in @table * * Gets the description text of the specified @column in the table - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * * Returns: a gchar* representing the column description, or %NULL * if value does not implement this interface. **/ -gchar* -atk_table_get_column_description (AtkTable *obj, +const gchar* +atk_table_get_column_description (AtkTable *table, gint column) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), NULL); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_column_description) - return (iface->get_column_description) (obj, column); + return (iface->get_column_description) (table, column); else return NULL; } @@ -350,28 +433,23 @@ atk_table_get_column_description (AtkTable *obj, * * Gets the number of columns occupied by the accessible object * at the specified @row and @column in the @table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * * Returns: a gint representing the column extent at specified position, or 0 * if value does not implement this interface. **/ gint -atk_table_get_column_extent_at (AtkTable *obj, +atk_table_get_column_extent_at (AtkTable *table, gint row, gint column) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, 0); - g_return_val_if_fail (ATK_IS_TABLE (obj), 0); + g_return_val_if_fail (ATK_IS_TABLE (table), 0); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_column_extent_at) - return (iface->get_column_extent_at) (obj, row, column); + return (iface->get_column_extent_at) (table, row, column); else return 0; } @@ -382,26 +460,22 @@ atk_table_get_column_extent_at (AtkTable *obj, * @column: a #gint representing a column in the table * * Gets the column header of a specified column in an accessible table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * - * Returns: a AtkObject* representing the specified column header, or - * %NULL if value does not implement this interface. + * Returns: (nullable) (transfer none): a AtkObject* representing the + * specified column header, or %NULL if value does not implement this + * interface. **/ AtkObject* -atk_table_get_column_header (AtkTable *obj, gint column) +atk_table_get_column_header (AtkTable *table, gint column) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), NULL); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_column_header) - return (iface->get_column_header) (obj, column); + return (iface->get_column_header) (table, column); else return NULL; } @@ -411,26 +485,21 @@ atk_table_get_column_header (AtkTable *obj, gint column) * @table: a GObject instance that implements AtkTableIface * * Gets the number of rows in the table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * * Returns: a gint representing the number of rows, or 0 * if value does not implement this interface. **/ gint -atk_table_get_n_rows (AtkTable *obj) +atk_table_get_n_rows (AtkTable *table) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, 0); - g_return_val_if_fail (ATK_IS_TABLE (obj), 0); + g_return_val_if_fail (ATK_IS_TABLE (table), 0); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_n_rows) - return (iface->get_n_rows) (obj); + return (iface->get_n_rows) (table); else return 0; } @@ -438,30 +507,25 @@ atk_table_get_n_rows (AtkTable *obj) /** * atk_table_get_row_description: * @table: a GObject instance that implements AtkTableIface - * @r: a #gint representing a row in @table + * @row: a #gint representing a row in @table * * Gets the description text of the specified row in the table - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * - * Returns: a gchar* representing the row description, or %NULL - * if value does not implement this interface. + * Returns: (nullable): a gchar* representing the row description, or + * %NULL if value does not implement this interface. **/ -gchar* -atk_table_get_row_description (AtkTable *obj, +const gchar* +atk_table_get_row_description (AtkTable *table, gint row) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), NULL); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_row_description) - return (iface->get_row_description) (obj, row); + return (iface->get_row_description) (table, row); else return NULL; } @@ -474,28 +538,23 @@ atk_table_get_row_description (AtkTable *obj, * * Gets the number of rows occupied by the accessible object * at a specified @row and @column in the @table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * * Returns: a gint representing the row extent at specified position, or 0 * if value does not implement this interface. **/ gint -atk_table_get_row_extent_at (AtkTable *obj, +atk_table_get_row_extent_at (AtkTable *table, gint row, gint column) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, 0); - g_return_val_if_fail (ATK_IS_TABLE (obj), 0); + g_return_val_if_fail (ATK_IS_TABLE (table), 0); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_row_extent_at) - return (iface->get_row_extent_at) (obj, row, column); + return (iface->get_row_extent_at) (table, row, column); else return 0; } @@ -506,26 +565,22 @@ atk_table_get_row_extent_at (AtkTable *obj, * @row: a #gint representing a row in the table * * Gets the row header of a specified row in an accessible table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * - * Returns: a AtkObject* representing the specified row header, or - * %NULL if value does not implement this interface. + * Returns: (nullable) (transfer none): a AtkObject* representing the + * specified row header, or %NULL if value does not implement this + * interface. **/ AtkObject* -atk_table_get_row_header (AtkTable *obj, gint row) +atk_table_get_row_header (AtkTable *table, gint row) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), NULL); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_row_header) - return (iface->get_row_header) (obj, row); + return (iface->get_row_header) (table, row); else return NULL; } @@ -535,26 +590,21 @@ atk_table_get_row_header (AtkTable *obj, gint row) * @table: a GObject instance that implements AtkTableIface * * Gets the summary description of the table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * - * Returns: a AtkObject* representing a sumary description of the table, - * or %NULL if value does not implement this interface. + * Returns: (transfer full): a AtkObject* representing a summary description + * of the table, or zero if value does not implement this interface. **/ AtkObject* -atk_table_get_summary (AtkTable *obj) +atk_table_get_summary (AtkTable *table) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), NULL); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_summary) - return (iface->get_summary) (obj); + return (iface->get_summary) (table); else return NULL; } @@ -562,60 +612,53 @@ atk_table_get_summary (AtkTable *obj) /** * atk_table_get_selected_rows: * @table: a GObject instance that implements AtkTableIface + * @selected: a #gint** that is to contain the selected row numbers * - * Gets the selected rows of the table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. + * Gets the selected rows of the table by initializing **selected with + * the selected row numbers. This array should be freed by the caller. * - * Returns: a gint* representing the selected rows, - * or %NULL if value does not implement this interface. + * Returns: a gint representing the number of selected rows, + * or zero if value does not implement this interface. **/ -gint* -atk_table_get_selected_rows (AtkTable *obj) +gint +atk_table_get_selected_rows (AtkTable *table, gint **selected) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), 0); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_selected_rows) - return (iface->get_selected_rows) (obj); + return (iface->get_selected_rows) (table, selected); else - return NULL; + return 0; } /** * atk_table_get_selected_columns: * @table: a GObject instance that implements AtkTableIface + * @selected: a #gint** that is to contain the selected columns numbers * - * Gets the selected columns of the table. - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. - * - * Returns: a gint* representing the selected columns, - * or %NULL if value does not implement this interface. + * Gets the selected columns of the table by initializing **selected with + * the selected column numbers. This array should be freed by the caller. * + * Returns: a gint representing the number of selected columns, + * or %0 if value does not implement this interface. **/ -gint* -atk_table_get_selected_columns (AtkTable *obj) +gint +atk_table_get_selected_columns (AtkTable *table, gint **selected) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, NULL); - g_return_val_if_fail (ATK_IS_TABLE (obj), NULL); + g_return_val_if_fail (ATK_IS_TABLE (table), 0); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->get_selected_columns) - return (iface->get_selected_columns) (obj); + return (iface->get_selected_columns) (table, selected); else - return NULL; + return 0; } /** @@ -625,27 +668,22 @@ atk_table_get_selected_columns (AtkTable *obj) * * Gets a boolean value indicating whether the specified @column * is selected - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * * Returns: a gboolean representing if the column is selected, or 0 * if value does not implement this interface. **/ gboolean -atk_table_is_column_selected (AtkTable *obj, +atk_table_is_column_selected (AtkTable *table, gint column) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, FALSE); - g_return_val_if_fail (ATK_IS_TABLE (obj), FALSE); + g_return_val_if_fail (ATK_IS_TABLE (table), FALSE); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->is_column_selected) - return (iface->is_column_selected) (obj, column); + return (iface->is_column_selected) (table, column); else return FALSE; } @@ -657,27 +695,22 @@ atk_table_is_column_selected (AtkTable *obj, * * Gets a boolean value indicating whether the specified @row * is selected - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * * Returns: a gboolean representing if the row is selected, or 0 * if value does not implement this interface. **/ gboolean -atk_table_is_row_selected (AtkTable *obj, +atk_table_is_row_selected (AtkTable *table, gint row) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, FALSE); - g_return_val_if_fail (ATK_IS_TABLE (obj), FALSE); + g_return_val_if_fail (ATK_IS_TABLE (table), FALSE); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->is_row_selected) - return (iface->is_row_selected) (obj, row); + return (iface->is_row_selected) (table, row); else return FALSE; } @@ -688,30 +721,126 @@ atk_table_is_row_selected (AtkTable *obj, * @row: a #gint representing a row in @table * @column: a #gint representing a column in @table * - * Gets a boolean value indicating whether the acessible object + * Gets a boolean value indicating whether the accessible object * at the specified @row and @column is selected - * Note: callers should not rely on %NULL or on a zero value for - * indication of whether AtkSelectionIface is implemented, they should - * use type checking/interface checking macros or the - * atk_get_accessible_table() convenience method. * * Returns: a gboolean representing if the cell is selected, or 0 * if value does not implement this interface. **/ gboolean -atk_table_is_selected (AtkTable *obj, +atk_table_is_selected (AtkTable *table, gint row, gint column) { AtkTableIface *iface; - g_return_val_if_fail (obj != NULL, FALSE); - g_return_val_if_fail (ATK_IS_TABLE (obj), FALSE); + g_return_val_if_fail (ATK_IS_TABLE (table), FALSE); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->is_selected) - return (iface->is_selected) (obj, row, column); + return (iface->is_selected) (table, row, column); + else + return FALSE; +} + +/** + * atk_table_add_row_selection: + * @table: a GObject instance that implements AtkTableIface + * @row: a #gint representing a row in @table + * + * Adds the specified @row to the selection. + * + * Returns: a gboolean representing if row was successfully added to selection, + * or 0 if value does not implement this interface. + **/ +gboolean +atk_table_add_row_selection (AtkTable *table, + gint row) +{ + AtkTableIface *iface; + + g_return_val_if_fail (ATK_IS_TABLE (table), FALSE); + + iface = ATK_TABLE_GET_IFACE (table); + + if (iface->add_row_selection) + return (iface->add_row_selection) (table, row); + else + return FALSE; +} +/** + * atk_table_remove_row_selection: + * @table: a GObject instance that implements AtkTableIface + * @row: a #gint representing a row in @table + * + * Removes the specified @row from the selection. + * + * Returns: a gboolean representing if the row was successfully removed from + * the selection, or 0 if value does not implement this interface. + **/ +gboolean +atk_table_remove_row_selection (AtkTable *table, + gint row) +{ + AtkTableIface *iface; + + g_return_val_if_fail (ATK_IS_TABLE (table), FALSE); + + iface = ATK_TABLE_GET_IFACE (table); + + if (iface->remove_row_selection) + return (iface->remove_row_selection) (table, row); + else + return FALSE; +} +/** + * atk_table_add_column_selection: + * @table: a GObject instance that implements AtkTableIface + * @column: a #gint representing a column in @table + * + * Adds the specified @column to the selection. + * + * Returns: a gboolean representing if the column was successfully added to + * the selection, or 0 if value does not implement this interface. + **/ +gboolean +atk_table_add_column_selection (AtkTable *table, + gint column) +{ + AtkTableIface *iface; + + g_return_val_if_fail (ATK_IS_TABLE (table), FALSE); + + iface = ATK_TABLE_GET_IFACE (table); + + if (iface->add_column_selection) + return (iface->add_column_selection) (table, column); + else + return FALSE; +} +/** + * atk_table_remove_column_selection: + * @table: a GObject instance that implements AtkTableIface + * @column: a #gint representing a column in @table + * + * Adds the specified @column to the selection. + * + * Returns: a gboolean representing if the column was successfully removed from + * the selection, or 0 if value does not implement this interface. + **/ +gboolean +atk_table_remove_column_selection (AtkTable *table, + gint column) +{ + AtkTableIface *iface; + + g_return_val_if_fail (ATK_IS_TABLE (table), FALSE); + + iface = ATK_TABLE_GET_IFACE (table); + + if (iface->remove_column_selection) + return (iface->remove_column_selection) (table, column); else return FALSE; } @@ -719,23 +848,22 @@ atk_table_is_selected (AtkTable *obj, /** * atk_table_set_caption: * @table: a GObject instance that implements AtkTableIface - * @caption: a #gchar representing the caption to set for @table + * @caption: a #AtkObject representing the caption to set for @table * * Sets the caption for the table. **/ void -atk_table_set_caption (AtkTable *obj, - gchar *caption) +atk_table_set_caption (AtkTable *table, + AtkObject *caption) { AtkTableIface *iface; - g_return_if_fail (obj != NULL); - g_return_if_fail (ATK_IS_TABLE (obj)); + g_return_if_fail (ATK_IS_TABLE (table)); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->set_caption) - (iface->set_caption) (obj, caption); + (iface->set_caption) (table, caption); } /** @@ -748,19 +876,18 @@ atk_table_set_caption (AtkTable *obj, * Sets the description text for the specified @column of the @table. **/ void -atk_table_set_column_description (AtkTable *obj, +atk_table_set_column_description (AtkTable *table, gint column, - gchar *description) + const gchar *description) { AtkTableIface *iface; - g_return_if_fail (obj != NULL); - g_return_if_fail (ATK_IS_TABLE (obj)); + g_return_if_fail (ATK_IS_TABLE (table)); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->set_column_description) - (iface->set_column_description) (obj, column, description); + (iface->set_column_description) (table, column, description); } /** @@ -769,22 +896,21 @@ atk_table_set_column_description (AtkTable *obj, * @column: a #gint representing a column in @table * @header: an #AtkTable * - * Sets the specified column header to @header + * Sets the specified column header to @header. **/ void -atk_table_set_column_header (AtkTable *obj, +atk_table_set_column_header (AtkTable *table, gint column, AtkObject *header) { AtkTableIface *iface; - g_return_if_fail (obj != NULL); - g_return_if_fail (ATK_IS_TABLE (obj)); + g_return_if_fail (ATK_IS_TABLE (table)); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->set_column_header) - (iface->set_column_header) (obj, column, header); + (iface->set_column_header) (table, column, header); } /** @@ -797,19 +923,18 @@ atk_table_set_column_header (AtkTable *obj, * Sets the description text for the specified @row of @table. **/ void -atk_table_set_row_description (AtkTable *obj, +atk_table_set_row_description (AtkTable *table, gint row, - gchar *description) + const gchar *description) { AtkTableIface *iface; - g_return_if_fail (obj != NULL); - g_return_if_fail (ATK_IS_TABLE (obj)); + g_return_if_fail (ATK_IS_TABLE (table)); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->set_row_description) - (iface->set_row_description) (obj, row, description); + (iface->set_row_description) (table, row, description); } /** @@ -818,22 +943,21 @@ atk_table_set_row_description (AtkTable *obj, * @row: a #gint representing a row in @table * @header: an #AtkTable * - * Sets the specified row header to @header + * Sets the specified row header to @header. **/ void -atk_table_set_row_header (AtkTable *obj, +atk_table_set_row_header (AtkTable *table, gint row, AtkObject *header) { AtkTableIface *iface; - g_return_if_fail (obj != NULL); - g_return_if_fail (ATK_IS_TABLE (obj)); + g_return_if_fail (ATK_IS_TABLE (table)); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->set_row_header) - (iface->set_row_header) (obj, row, header); + (iface->set_row_header) (table, row, header); } /** @@ -842,19 +966,18 @@ atk_table_set_row_header (AtkTable *obj, * @accessible: an #AtkObject representing the summary description * to set for @table * - * Sets the summary description of the table + * Sets the summary description of the table. **/ void -atk_table_set_summary (AtkTable *obj, +atk_table_set_summary (AtkTable *table, AtkObject *accessible) { AtkTableIface *iface; - g_return_if_fail (obj != NULL); - g_return_if_fail (ATK_IS_TABLE (obj)); + g_return_if_fail (ATK_IS_TABLE (table)); - iface = ATK_TABLE_GET_IFACE (obj); + iface = ATK_TABLE_GET_IFACE (table); if (iface->set_summary) - (iface->set_summary) (obj, accessible); + (iface->set_summary) (table, accessible); }