* 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,
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,
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,
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,
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,
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_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_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,
* @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 *table,
AtkTableIface *iface;
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 (table);
* @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.
+ * Gets a #gint representing the index at the specified @row and
+ * @column.
+ *
+ * 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.
- *
- * Returns: a #gint representing the index at specified position
**/
gint
atk_table_get_index_at (AtkTable *table,
/**
* 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 -1
- * if the table does not implement this interface
+ * Gets a #gint representing the row at the specified @index_.
*
- * Returns: a gint representing the row at the specified index.
+ * 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 *table,
/**
* 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_.
*
- * Gets a #gint representing the column at the specified @index, or -1
- * if the table does not implement this interface
+ * Deprecated: Since 2.12.
*
- * Returns: a gint representing the column at the specified index.
+ * 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 *table,
*
* Gets the caption for the @table.
*
- * Returns: a AtkObject* 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.
**/
AtkObject*
atk_table_get_caption (AtkTable *table)
* Returns: a gchar* representing the column description, or %NULL
* if value does not implement this interface.
**/
-G_CONST_RETURN gchar*
+const gchar*
atk_table_get_column_description (AtkTable *table,
gint column)
{
*
* Gets the column header of a specified column in an accessible table.
*
- * 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 *table, gint column)
*
* Gets the description text of the specified row in the table
*
- * 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.
**/
-G_CONST_RETURN gchar*
+const gchar*
atk_table_get_row_description (AtkTable *table,
gint row)
{
*
* Gets the row header of a specified row in an accessible table.
*
- * 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 *table, gint row)
*
* Gets the summary description of the table.
*
- * Returns: a AtkObject* representing a summary description of the table,
- * or zero 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 *table)
projects / platform / upstream / atk.git / blobdiff