Improve the docs

2009-01-03  Matthias Clasen  <mclasen@redhat.com>

        * gtk/gtktreesortable.c: Improve the docs

        * gtk/gtktreemodelsort.c: Don't assert when using the "unsorted"
        sort column id.

svn path=/trunk/; revision=22048

diff --git a/ChangeLog b/ChangeLog
index 825ddf870741d9b588b6fd83d4fa4dd8e1f7861a..064fb7cddeed554a84c11341d2675f9d5f27eb84 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2009-01-03  Matthias Clasen  <mclasen@redhat.com>
+
+       * gtk/gtktreesortable.c: Improve the docs
+
+       * gtk/gtktreemodelsort.c: Don't assert when using the "unsorted"
+       sort column id.
+
 2009-01-02  Matthias Clasen  <mclasen@redhat.com>
 
        Bug 565998 – configure script doesn't check for cairo-xlib.pc

diff --git a/gtk/gtktreemodelsort.c b/gtk/gtktreemodelsort.c
index 077b6023e7e60fa0946d9fd4121f17e4593dd42a..1dbdda41f8abf1b2c8a8ff5634b66a2158409bb1 100644 (file)
--- a/gtk/gtktreemodelsort.c
+++ b/gtk/gtktreemodelsort.c
@@ -1318,29 +1318,32 @@ gtk_tree_model_sort_set_sort_column_id (GtkTreeSortable *sortable,
 {
   GtkTreeModelSort *tree_model_sort = (GtkTreeModelSort *)sortable;
 
-  if (sort_column_id != GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID)
+  if (sort_column_id != GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID)
     {
-      GtkTreeDataSortHeader *header = NULL;
+      if (sort_column_id != GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID)
+        {
+          GtkTreeDataSortHeader *header = NULL;
 
-      header = _gtk_tree_data_list_get_header (tree_model_sort->sort_list,
-                                              sort_column_id);
+          header = _gtk_tree_data_list_get_header (tree_model_sort->sort_list,
+                                                  sort_column_id);
 
-      /* we want to make sure that we have a function */
-      g_return_if_fail (header != NULL);
-      g_return_if_fail (header->func != NULL);
-    }
-  else
-    g_return_if_fail (tree_model_sort->default_sort_func != NULL);
+          /* we want to make sure that we have a function */
+          g_return_if_fail (header != NULL);
+          g_return_if_fail (header->func != NULL);
+        }
+      else
+        g_return_if_fail (tree_model_sort->default_sort_func != NULL);
 
-  if (tree_model_sort->sort_column_id == sort_column_id)
-    {
-      if (sort_column_id != GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID)
-       {
-         if (tree_model_sort->order == order)
+      if (tree_model_sort->sort_column_id == sort_column_id)
+        {
+          if (sort_column_id != GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID)
+           {
+             if (tree_model_sort->order == order)
+               return;
+           }
+          else
            return;
-       }
-      else
-       return;
+        }
     }
 
   tree_model_sort->sort_column_id = sort_column_id;
@@ -1696,6 +1699,9 @@ gtk_tree_model_sort_sort_level (GtkTreeModelSort *tree_model_sort,
 static void
 gtk_tree_model_sort_sort (GtkTreeModelSort *tree_model_sort)
 {
+  if (tree_model_sort->sort_column_id == GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID)
+    return;
+
   if (!tree_model_sort->root)
     return;
 

diff --git a/gtk/gtktreesortable.c b/gtk/gtktreesortable.c
index 09bea0095c312a9ed86e882e8c8a45e337f53311..d6cd4e2d1e233dbdda485d0f4fb488ee398cb799 100644 (file)
--- a/gtk/gtktreesortable.c
+++ b/gtk/gtktreesortable.c
@@ -63,6 +63,14 @@ gtk_tree_sortable_base_init (gpointer g_class)
 
   if (! initialized)
     {
+      /**
+       * GtkTreeSortable::sort-column-changed:
+       * @sortable: the object on which the signal is emitted
+       *
+       * The ::sort-column-changed signal is emitted when the sort column
+       * or sort order of @sortable is changed. The signal is emitted before
+       * the contents of @sortable are resorted.
+       */
       g_signal_new (I_("sort-column-changed"),
                     GTK_TYPE_TREE_SORTABLE,
                     G_SIGNAL_RUN_LAST,
@@ -78,8 +86,8 @@ gtk_tree_sortable_base_init (gpointer g_class)
  * gtk_tree_sortable_sort_column_changed:
  * @sortable: A #GtkTreeSortable
  * 
- * Emits a GtkTreeSortable::sort_column_changed signal on 
- **/
+ * Emits a #GtkTreeSortable::sort-column-changed signal on @sortable.
+ */
 void
 gtk_tree_sortable_sort_column_changed (GtkTreeSortable *sortable)
 {
@@ -95,7 +103,7 @@ gtk_tree_sortable_sort_column_changed (GtkTreeSortable *sortable)
  * @order: The #GtkSortType to be filled in
  * 
  * Fills in @sort_column_id and @order with the current sort column and the
- * order.  It returns %TRUE unless the @sort_column_id is 
+ * order. It returns %TRUE unless the @sort_column_id is 
  * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or 
  * %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID.
  * 
@@ -125,12 +133,21 @@ gtk_tree_sortable_get_sort_column_id (GtkTreeSortable  *sortable,
  * @sort_column_id: the sort column id to set
  * @order: The sort order of the column
  * 
- * Sets the current sort column to be @sort_column_id.  The @sortable will
+ * Sets the current sort column to be @sort_column_id. The @sortable will
  * resort itself to reflect this change, after emitting a
- * GtkTreeSortable::sort_column_changed signal.  If @sort_column_id is
- * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the default sort function
- * will be used, if it is set.
- **/
+ * #GtkTreeSortable::sort-column-changed signal. @sortable may either be 
+ * a regular column id, or one of the following special values:
+ * <variablelist>
+ * <varlistentry>
+ *   <term>%GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</term>
+ *   <listitem>the default sort function will be used, if it is set</listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>%GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID</term>
+ *   <listitem>no sorting will occur</listitem>
+ * </varlistentry>
+ * </variablelist>
+ */
 void
 gtk_tree_sortable_set_sort_column_id (GtkTreeSortable  *sortable,
                                      gint              sort_column_id,
@@ -156,10 +173,10 @@ gtk_tree_sortable_set_sort_column_id (GtkTreeSortable  *sortable,
  * @user_data: User data to pass to @sort_func, or %NULL
  * @destroy: Destroy notifier of @user_data, or %NULL
  * 
- * Sets the comparison function used when sorting to be @sort_func.  If the
- * current sort column id of @sortable is the same as @sort_column_id, then the
- * model will sort using this function.
- **/
+ * Sets the comparison function used when sorting to be @sort_func. If the
+ * current sort column id of @sortable is the same as @sort_column_id, then 
+ * the model will sort using this function.
+ */
 void
 gtk_tree_sortable_set_sort_func (GtkTreeSortable        *sortable,
                                 gint                    sort_column_id,
@@ -195,9 +212,9 @@ gtk_tree_sortable_set_sort_func (GtkTreeSortable        *sortable,
  *
  * If @sort_func is %NULL, then there will be no default comparison function.
  * This means that once the model  has been sorted, it can't go back to the
- * default state. In this case, when the current sort column id of @sortable is
- * GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted.
- **/
+ * default state. In this case, when the current sort column id of @sortable 
+ * is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted.
+ */
 void
 gtk_tree_sortable_set_default_sort_func (GtkTreeSortable        *sortable,
                                         GtkTreeIterCompareFunc  sort_func,
@@ -220,12 +237,12 @@ gtk_tree_sortable_set_default_sort_func (GtkTreeSortable        *sortable,
  * gtk_tree_sortable_has_default_sort_func:
  * @sortable: A #GtkTreeSortable
  * 
- * Returns %TRUE if the model has a default sort function.  This is used
- * primarily by GtkTreeViewColumns in order to determine if a model can go back
- * to the default state, or not.
+ * Returns %TRUE if the model has a default sort function. This is used
+ * primarily by GtkTreeViewColumns in order to determine if a model can 
+ * go back to the default state, or not.
  * 
  * Return value: %TRUE, if the model has a default sort function
- **/
+ */
 gboolean
 gtk_tree_sortable_has_default_sort_func (GtkTreeSortable *sortable)
 {