[gtk+] table: Deprecate GtkTable for GtkGrid

[Benjamin Otte <otte src gnome org>]

commit 08d578dfcbbbc4769d8c26de4ea0de4f76e1b2de
Author: Benjamin Otte <otte redhat com>
Date:   Thu Sep 29 01:30:16 2011 +0200

    table: Deprecate GtkTable for GtkGrid

 gtk/gtktable.c |   49 ++++++++++++++++++++++++++++++++++++++++++++++---
 gtk/gtktable.h |    3 +++
 2 files changed, 49 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtktable.c b/gtk/gtktable.c
index dee3d34..1c4cb9f 100644
--- a/gtk/gtktable.c
+++ b/gtk/gtktable.c
@@ -26,6 +26,8 @@
 
 #include "config.h"
 
+#undef GTK_DISABLE_DEPRECATED
+
 #include "gtktable.h"
 
 #include "gtktypebuiltins.h"
@@ -61,9 +63,9 @@
  * table will resize themselves to the size of the largest widget in the table.
  *
  * <note>
- * Note that #GtkGrid provides the same capabilities as GtkTable for arranging
- * widgets in a rectangular grid, and additionally supports height-for-width
- * geometry management.
+ * #GtkTable has been deprecated. Use #GtkGrid instead. It provides the same
+ * capabilities as GtkTable for arranging widgets in a rectangular grid, but
+ * does support height-for-width geometry management.
  * </note>
  */
 
@@ -600,6 +602,8 @@ gtk_table_init (GtkTable *table)
  * as well and is silently interpreted as 1.
  *
  * Returns: A pointer to the the newly created table widget.
+ *
+ * @Deprecated: 3.4: Use gtk_grid_new().
  */
 GtkWidget*
 gtk_table_new (guint	rows,
@@ -632,6 +636,8 @@ gtk_table_new (guint	rows,
  *
  * If you need to change a table's size <emphasis>after</emphasis>
  * it has been created, this function allows you to do so.
+ *
+ * @Deprecated: 3.4: #GtkGrid resizes automatically.
  */
 void
 gtk_table_resize (GtkTable *table,
@@ -737,6 +743,9 @@ gtk_table_resize (GtkTable *table,
  *                   xpadding, ypadding);
  * </programlisting></informalexample>
  * If you want to make the button span the entire bottom row, use @left_attach == 0 and @right_attach = 2 instead.
+ *
+ * @Deprecated: 3.4: Use gtk_grid_attach() with #GtkGrid. Note that the attach
+ *     arguments differ between those two functions.
  */
 void
 gtk_table_attach (GtkTable	  *table,
@@ -803,6 +812,9 @@ gtk_table_attach (GtkTable	  *table,
  * function provides the programmer with a means to add children to a table with
  * identical padding and expansion options. The values used for the #GtkAttachOptions
  * are <literal>GTK_EXPAND | GTK_FILL</literal>, and the padding is set to 0.
+ *
+ * @Deprecated: 3.4: Use gtk_grid_attach() with #GtkGrid. Note that the attach
+ *     arguments differ between those two functions.
  */
 void
 gtk_table_attach_defaults (GtkTable  *table,
@@ -827,6 +839,10 @@ gtk_table_attach_defaults (GtkTable  *table,
  * @spacing: number of pixels that the spacing should take up.
  *
  * Changes the space between a given table row and the subsequent row.
+ *
+ * @Deprecated: 3.4: Use gtk_widget_set_margin_top() and 
+ *     gtk_widget_set_margin_bottom() on the widgets contained in the row if
+ *     you need this functionality. #GtkGrid does not support per-row spacing.
  */
 void
 gtk_table_set_row_spacing (GtkTable *table,
@@ -859,6 +875,9 @@ gtk_table_set_row_spacing (GtkTable *table,
  * row @row + 1. See gtk_table_set_row_spacing().
  *
  * Return value: the row spacing
+ *
+ * @Deprecated: 3.4: #GtkGrid does not offer a replacement for this
+ *     functionality.
  **/
 guint
 gtk_table_get_row_spacing (GtkTable *table,
@@ -883,6 +902,10 @@ gtk_table_get_row_spacing (GtkTable *table,
  *
  * Alters the amount of space between a given table column and the following
  * column.
+ *
+ * @Deprecated: 3.4: Use gtk_widget_set_margin_left() and 
+ *     gtk_widget_set_margin_right() on the widgets contained in the row if
+ *     you need this functionality. #GtkGrid does not support per-row spacing.
  */
 void
 gtk_table_set_col_spacing (GtkTable *table,
@@ -915,6 +938,9 @@ gtk_table_set_col_spacing (GtkTable *table,
  * column @col + 1. See gtk_table_set_col_spacing().
  *
  * Return value: the column spacing
+ *
+ * @Deprecated: 3.4: #GtkGrid does not offer a replacement for this
+ *     functionality.
  **/
 guint
 gtk_table_get_col_spacing (GtkTable *table,
@@ -937,6 +963,8 @@ gtk_table_get_col_spacing (GtkTable *table,
  * @spacing: the number of pixels of space to place between every row in the table.
  *
  * Sets the space between every row in @table equal to @spacing.
+ *
+ * @Deprecated: 3.4: Use gtk_grid_set_row_spacing() with #GtkGrid.
  */
 void
 gtk_table_set_row_spacings (GtkTable *table,
@@ -968,6 +996,8 @@ gtk_table_set_row_spacings (GtkTable *table,
  * (See gtk_table_set_row_spacings())
  *
  * Return value: the default row spacing
+ *
+ * @Deprecated: 3.4: Use gtk_grid_get_row_spacing() with #GtkGrid.
  **/
 guint
 gtk_table_get_default_row_spacing (GtkTable *table)
@@ -984,6 +1014,8 @@ gtk_table_get_default_row_spacing (GtkTable *table)
  *   in the table.
  *
  * Sets the space between every column in @table equal to @spacing.
+ *
+ * @Deprecated: 3.4: Use gtk_grid_set_column_spacing() with #GtkGrid.
  */
 void
 gtk_table_set_col_spacings (GtkTable *table,
@@ -1015,6 +1047,8 @@ gtk_table_set_col_spacings (GtkTable *table,
  * (See gtk_table_set_col_spacings())
  *
  * Return value: the default column spacing
+ *
+ * @Deprecated: 3.4: Use gtk_grid_get_column_spacing() with #GtkGrid.
  **/
 guint
 gtk_table_get_default_col_spacing (GtkTable *table)
@@ -1032,6 +1066,9 @@ gtk_table_get_default_col_spacing (GtkTable *table)
  *
  * Changes the homogenous property of table cells, ie. whether all cells are
  * an equal size or not.
+ *
+ * @Deprecated: 3.4: Use gtk_grid_set_row_homogeneous() and
+ *     gtk_grid_set_column_homogeneous() with #GtkGrid.
  */
 void
 gtk_table_set_homogeneous (GtkTable *table,
@@ -1063,6 +1100,9 @@ gtk_table_set_homogeneous (GtkTable *table,
  * width and height. (See gtk_table_set_homogenous ())
  *
  * Return value: %TRUE if the cells are all constrained to the same size
+ *
+ * @Deprecated: 3.4: Use gtk_grid_get_row_homogeneous() and
+ *     gtk_grid_get_column_homogeneous() with #GtkGrid.
  **/
 gboolean
 gtk_table_get_homogeneous (GtkTable *table)
@@ -1083,6 +1123,9 @@ gtk_table_get_homogeneous (GtkTable *table)
  * Gets the number of rows and columns in the table.
  *
  * Since: 2.22
+ *
+ * @Deprecated: 3.4: #GtkGrid does not expose the number of columns and
+ *     rows.
  **/
 void
 gtk_table_get_size (GtkTable *table,
diff --git a/gtk/gtktable.h b/gtk/gtktable.h
index 4158a09..71a8594 100644
--- a/gtk/gtktable.h
+++ b/gtk/gtktable.h
@@ -37,6 +37,8 @@
 
 G_BEGIN_DECLS
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #define GTK_TYPE_TABLE			(gtk_table_get_type ())
 #define GTK_TABLE(obj)			(G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TABLE, GtkTable))
 #define GTK_TABLE_CLASS(klass)		(G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_TABLE, GtkTableClass))
@@ -146,6 +148,7 @@ void       gtk_table_get_size         (GtkTable        *table,
                                        guint           *rows,
                                        guint           *columns);
 
+#endif /* GTK_DISABLE_DEPRECATED */
 
 G_END_DECLS