[gtk+] treeview: Deprecated rules-hint

[Matthias Clasen <matthiasc src gnome org>]

commit 0ed766ec866a2da7e3db05b1db2fc2519d6b1cdc
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Jul 17 12:53:01 2014 +0100

    treeview: Deprecated rules-hint
    
    The rules-hint property has always been a fairly bad application API, as
    it set some wrong expectations for the developers; deferring to the
    theme makes it impossible to design application reliably, and if this is
    a usability setting we should either impose this setting on every theme,
    or simply drop it.
    
    Our own default theme does not honour the zebra striping, which makes
    this function even more questionable.
    
    In practice, usability studies on zebra striping have demonstrated that
    alternating colors on a list it improves readability just as much as
    clear ruling between rows, or by visually differentiating the selected
    row. Zebra striping improves readability (or, at least, it does not
    hinder it) on static displays, like a table on paper or a document; on a
    dynamic display, like an application's UI, there are different
    strategies that yield similar, if not better, results.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=733312

 gtk/gtktreeview.c |   41 +++++++++++++++++++++++++++--------------
 gtk/gtktreeview.h |    4 ++--
 2 files changed, 29 insertions(+), 16 deletions(-)
---
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 5e24060..400c908 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -1042,13 +1042,20 @@ gtk_tree_view_class_init (GtkTreeViewClass *class)
                                                          FALSE,
                                                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
 
+  /**
+   * GtkTreeView:rules-hint:
+   *
+   * Sets a hint to the theme to draw rows in alternating colors.
+   *
+   * Deprecated: 3.14
+   */
   g_object_class_install_property (o_class,
                                    PROP_RULES_HINT,
                                    g_param_spec_boolean ("rules-hint",
                                                          P_("Rules Hint"),
                                                          P_("Set a hint to the theme engine to draw rows in 
alternating colors"),
                                                          FALSE,
-                                                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY));
+                                                         GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY | 
G_PARAM_DEPRECATED));
 
   g_object_class_install_property (o_class,
                                    PROP_ENABLE_SEARCH,
@@ -11843,20 +11850,24 @@ gtk_tree_view_get_headers_clickable (GtkTreeView *tree_view)
  * @tree_view: a #GtkTreeView
  * @setting: %TRUE if the tree requires reading across rows
  *
- * This function tells GTK+ that the user interface for your
+ * Sets a hint for the theme to draw even/odd rows in the @tree_view
+ * with different colors, also known as "zebra striping".
+ *
+ * This function tells the GTK+ theme that the user interface for your
  * application requires users to read across tree rows and associate
- * cells with one another. By default, GTK+ will then render the tree
- * with alternating row colors. Do not use it
- * just because you prefer the appearance of the ruled tree; that’s a
- * question for the theme. Some themes will draw tree rows in
- * alternating colors even when rules are turned off, and users who
- * prefer that appearance all the time can choose those themes. You
- * should call this function only as a semantic
- * hint to the theme engine that your tree makes alternating colors
- * useful from a functional standpoint (since it has lots of columns,
+ * cells with one another.
+ *
+ * Do not use it just because you prefer the appearance of the ruled
+ * tree; that’s a question for the theme. Some themes will draw tree
+ * rows in alternating colors even when rules are turned off, and
+ * users who prefer that appearance all the time can choose those
+ * themes. You should call this function only as a semantic hint to
+ * the theme engine that your tree makes alternating colors useful
+ * from a functional standpoint (since it has lots of columns,
  * generally).
  *
- **/
+ * Deprecated: 3.14
+ */
 void
 gtk_tree_view_set_rules_hint (GtkTreeView  *tree_view,
                               gboolean      setting)
@@ -11879,8 +11890,10 @@ gtk_tree_view_set_rules_hint (GtkTreeView  *tree_view,
  *
  * Gets the setting set by gtk_tree_view_set_rules_hint().
  *
- * Returns: %TRUE if rules are useful for the user of this tree
- **/
+ * Returns: %TRUE if the hint is set
+ *
+ * Deprecated: 3.14
+ */
 gboolean
 gtk_tree_view_get_rules_hint (GtkTreeView  *tree_view)
 {
diff --git a/gtk/gtktreeview.h b/gtk/gtktreeview.h
index 121e10a..c3233b4 100644
--- a/gtk/gtktreeview.h
+++ b/gtk/gtktreeview.h
@@ -242,10 +242,10 @@ gboolean               gtk_tree_view_get_headers_clickable         (GtkTreeView
 GDK_AVAILABLE_IN_ALL
 void                   gtk_tree_view_set_headers_clickable         (GtkTreeView               *tree_view,
                                                                    gboolean                   setting);
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_14
 void                   gtk_tree_view_set_rules_hint                (GtkTreeView               *tree_view,
                                                                    gboolean                   setting);
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_14
 gboolean               gtk_tree_view_get_rules_hint                (GtkTreeView               *tree_view);
 GDK_AVAILABLE_IN_3_8
 gboolean               gtk_tree_view_get_activate_on_single_click  (GtkTreeView               *tree_view);