[atk] doc: documentation for AtkTableCell, AtkTable, deprecations and padding
- From: Alejandro Piñeiro Iglesias <apinheiro src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [atk] doc: documentation for AtkTableCell, AtkTable, deprecations and padding
- Date: Tue, 18 Feb 2014 16:28:10 +0000 (UTC)
commit a3b6bb15885b5c59fc7bf2283bbb1fb06b602ba7
Author: Alejandro Piñeiro <apinheiro igalia com>
Date: Mon Feb 10 17:02:11 2014 +0100
doc: documentation for AtkTableCell, AtkTable, deprecations and padding
Index based methods forced ATK implementations to expose
the cells are direct children of the table. Something that
was complex in the practice. In fact some implementation
were not doing it, making the index-based methods not
properly implemented. This became even more clear with the
addition of AtkTableCell.
Additionally, this patch documents AtkTableCell and that
those cells should implement the newly added AtkTableCell
interface.
atk/atktable.c | 41 ++++++++++++++++++++++++++++++-----------
atk/atktable.h | 9 +++------
atk/atktablecell.c | 42 ++++++++++++++++++++++++++++--------------
atk/atktablecell.h | 39 +++++++++++++++++----------------------
docs/atk-docs.sgml | 2 ++
docs/atk-sections.txt | 20 ++++++++++++++++++++
docs/atk.types | 1 +
7 files changed, 101 insertions(+), 53 deletions(-)
---
diff --git a/atk/atktable.c b/atk/atktable.c
index 6371bf3..b5ab7e3 100755
--- a/atk/atktable.c
+++ b/atk/atktable.c
@@ -30,20 +30,30 @@
* 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", and these cells are
- * exposed by #AtkTable as child #AtkObjects of the #AtkTable. Both
- * row/column and child-index-based access to these children is
- * provided.
+ * #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 {
@@ -223,10 +233,11 @@ 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: (transfer full): a AtkObject* representing the referred to
- * accessible
+ * Returns: (transfer full): an #AtkObject representing the referred
+ * to accessible
**/
AtkObject*
atk_table_ref_at (AtkTable *table,
@@ -253,7 +264,11 @@ atk_table_ref_at (AtkTable *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
@@ -285,8 +300,10 @@ atk_table_get_index_at (AtkTable *table,
*
* Gets 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 interface
+ * or -1 if the table does not implement this method.
**/
gint
atk_table_get_row_at_index (AtkTable *table,
@@ -309,10 +326,12 @@ atk_table_get_row_at_index (AtkTable *table,
* @table: a GObject instance that implements AtkTableInterface
* @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_.
+ *
+ * Deprecated: Since 2.12.
*
* Returns: a gint representing the column at the specified index,
- * or -1 if the table does not implement this interface
+ * or -1 if the table does not implement this method.
**/
gint
atk_table_get_column_at_index (AtkTable *table,
diff --git a/atk/atktable.h b/atk/atktable.h
index 124cfbc..8aace1f 100755
--- a/atk/atktable.h
+++ b/atk/atktable.h
@@ -28,12 +28,6 @@
G_BEGIN_DECLS
-/*
- * AtkTable describes a user-interface component that presents data in
- * two-dimensional table format.
- */
-
-
#define ATK_TYPE_TABLE (atk_table_get_type ())
#define ATK_IS_TABLE(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_TABLE)
#define ATK_TABLE(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_TABLE, AtkTable)
@@ -139,11 +133,14 @@ GType atk_table_get_type (void);
AtkObject* atk_table_ref_at (AtkTable *table,
gint row,
gint column);
+G_DEPRECATED_FOR(atk_table_ref_at)
gint atk_table_get_index_at (AtkTable *table,
gint row,
gint column);
+G_DEPRECATED
gint atk_table_get_column_at_index (AtkTable *table,
gint index_);
+G_DEPRECATED
gint atk_table_get_row_at_index (AtkTable *table,
gint index_);
gint atk_table_get_n_columns (AtkTable *table);
diff --git a/atk/atktablecell.c b/atk/atktablecell.c
index 20baf1a..9218b09 100644
--- a/atk/atktablecell.c
+++ b/atk/atktablecell.c
@@ -19,14 +19,28 @@
#include "atktablecell.h"
+
+/**
+ * SECTION:atktablecell
+ * @Short_description: The ATK interface implemented for a cell inside
+ * a two-dimentional #AtkTable
+ * @Title:AtkTableCell
+ *
+ * Being #AtkTable a component which present elements ordered via rows
+ * and columns, an #AtkTableCell is the interface which each of those
+ * elements, so "cells" should implement.
+ *
+ * See also #AtkTable.
+ */
+
typedef AtkTableCellIface AtkTableCellInterface;
G_DEFINE_INTERFACE (AtkTableCell, atk_table_cell, ATK_TYPE_OBJECT)
static gboolean atk_table_cell_real_get_row_column_span (AtkTableCell *cell,
- gint *row,
- gint *column,
- gint *row_span,
- gint *column_span);
+ gint *row,
+ gint *column,
+ gint *row_span,
+ gint *column_span);
static void
atk_table_cell_default_init (AtkTableCellInterface *iface)
@@ -85,8 +99,8 @@ atk_table_cell_get_column_header_cells (AtkTableCell *cell)
/**
* atk_table_cell_get_position:
* @cell: a GObject instance that implements AtkTableCellIface
- * row: (out): the row of the given cell.
- * column: (out): the column of the given cell.
+ * @row: (out): the row of the given cell.
+ * @column: (out): the column of the given cell.
*
* Retrieves the tabular position of this cell.
*
@@ -181,10 +195,10 @@ atk_table_cell_get_row_header_cells (AtkTableCell *cell)
*/
gboolean
atk_table_cell_get_row_column_span (AtkTableCell *cell,
- gint *row,
- gint *column,
- gint *row_span,
- gint *column_span)
+ gint *row,
+ gint *column,
+ gint *row_span,
+ gint *column_span)
{
AtkTableCellIface *iface;
gint local_row = 0, local_column = 0;
@@ -234,10 +248,10 @@ atk_table_cell_get_table (AtkTableCell *cell)
static gboolean
atk_table_cell_real_get_row_column_span (AtkTableCell *cell,
- gint *row,
- gint *column,
- gint *row_span,
- gint *column_span)
+ gint *row,
+ gint *column,
+ gint *row_span,
+ gint *column_span)
{
atk_table_cell_get_position (cell, row, column);
*row_span = atk_table_cell_get_row_span (cell);
diff --git a/atk/atktablecell.h b/atk/atktablecell.h
index 7926f9f..ef4bfda 100755
--- a/atk/atktablecell.h
+++ b/atk/atktablecell.h
@@ -28,11 +28,6 @@
G_BEGIN_DECLS
-/*
- * AtkTableCell gives access to the cells of a two-dimentional table.
- */
-
-
#define ATK_TYPE_TABLE_CELL (atk_table_cell_get_type ())
#define ATK_IS_TABLE_CELL(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_TABLE_CELL)
#define ATK_TABLE_CELL(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_TABLE_CELL,
AtkTableCell)
@@ -48,31 +43,31 @@ struct _AtkTableCellIface
{
GTypeInterface parent;
- gint (*get_column_span) (AtkTableCell *cell);
- GPtrArray * (*get_column_header_cells) (AtkTableCell *cell);
- gboolean (*get_position) (AtkTableCell *cell,
- gint *row,
- gint *column);
- gint (*get_row_span) (AtkTableCell *cell);
-GPtrArray * (*get_row_header_cells) (AtkTableCell *cell);
- gboolean (*get_row_column_span) (AtkTableCell *cell,
- gint *row,
- gint *column,
- gint *row_span,
- gint *column_span);
- AtkObject * (*get_table) (AtkTableCell *cell);
+ gint (*get_column_span) (AtkTableCell *cell);
+ GPtrArray * (*get_column_header_cells) (AtkTableCell *cell);
+ gboolean (*get_position) (AtkTableCell *cell,
+ gint *row,
+ gint *column);
+ gint (*get_row_span) (AtkTableCell *cell);
+ GPtrArray * (*get_row_header_cells) (AtkTableCell *cell);
+ gboolean (*get_row_column_span) (AtkTableCell *cell,
+ gint *row,
+ gint *column,
+ gint *row_span,
+ gint *column_span);
+ AtkObject * (*get_table) (AtkTableCell *cell);
};
GType atk_table_cell_get_type (void);
-gint atk_table_cell_get_column_span (AtkTableCell *cell);
+gint atk_table_cell_get_column_span (AtkTableCell *cell);
GPtrArray * atk_table_cell_get_column_header_cells (AtkTableCell *cell);
-gboolean atk_table_cell_get_position (AtkTableCell *cell,
+gboolean atk_table_cell_get_position (AtkTableCell *cell,
gint *row,
gint *column);
-gint atk_table_cell_get_row_span (AtkTableCell *cell);
+gint atk_table_cell_get_row_span (AtkTableCell *cell);
GPtrArray * atk_table_cell_get_row_header_cells (AtkTableCell *cell);
-gboolean atk_table_cell_get_row_column_span (AtkTableCell *cell,
+gboolean atk_table_cell_get_row_column_span (AtkTableCell *cell,
gint *row,
gint *column,
gint *row_span,
diff --git a/docs/atk-docs.sgml b/docs/atk-docs.sgml
index fa12bc6..6061efc 100644
--- a/docs/atk-docs.sgml
+++ b/docs/atk-docs.sgml
@@ -25,6 +25,7 @@
<!ENTITY atk-AtkStateSet SYSTEM "xml/atkstateset.xml">
<!ENTITY atk-AtkStreamableContent SYSTEM "xml/atkstreamablecontent.xml">
<!ENTITY atk-AtkTable SYSTEM "xml/atktable.xml">
+ <!ENTITY atk-AtkTableCell SYSTEM "xml/atktablecell.xml">
<!ENTITY atk-AtkText SYSTEM "xml/atktext.xml">
<!ENTITY atk-AtkUtil SYSTEM "xml/atkutil.xml">
<!ENTITY atk-AtkValue SYSTEM "xml/atkvalue.xml">
@@ -65,6 +66,7 @@
&atk-AtkStateSet;
&atk-AtkStreamableContent;
&atk-AtkTable;
+ &atk-AtkTableCell;
&atk-AtkText;
&atk-AtkUtil;
&atk-AtkValue;
diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt
index 36e9b57..7f2fd38 100644
--- a/docs/atk-sections.txt
+++ b/docs/atk-sections.txt
@@ -392,6 +392,26 @@ atk_table_get_type
</SECTION>
<SECTION>
+<FILE>atktablecell</FILE>
+<TITLE>AtkTableCell</TITLE>
+AtkTableCell
+atk_table_cell_get_column_span
+atk_table_cell_get_column_header_cells
+atk_table_cell_get_position
+atk_table_cell_get_row_span
+atk_table_cell_get_row_header_cells
+atk_table_cell_get_row_column_span
+atk_table_cell_get_table
+<SUBSECTION Standard>
+AtkTableCellIface
+ATK_TABLE_CELL
+ATK_IS_TABLE_CELL
+ATK_TYPE_TABLE_CELL
+ATK_TABLE_CELL_GET_IFACE
+atk_table_cell_get_type
+</SECTION>
+
+<SECTION>
<FILE>atktext</FILE>
<TITLE>AtkText</TITLE>
AtkText
diff --git a/docs/atk.types b/docs/atk.types
index bdbd870..e1a33e4 100644
--- a/docs/atk.types
+++ b/docs/atk.types
@@ -21,6 +21,7 @@ atk_selection_get_type
atk_state_set_get_type
atk_streamable_content_get_type
atk_table_get_type
+atk_table_cell_get_type
atk_text_get_type
atk_util_get_type
atk_value_get_type
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
