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

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

gtk/gtktreemodelsort.c

@@ -1318,6 +1318,8 @@ gtk_tree_model_sort_set_sort_column_id (GtkTreeSortable *sortable,
 {
   GtkTreeModelSort *tree_model_sort = (GtkTreeModelSort *)sortable;
 
+  if (sort_column_id != GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID)
+    {
       if (sort_column_id != GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID)
         {
           GtkTreeDataSortHeader *header = NULL;
@@ -1342,6 +1344,7 @@ gtk_tree_model_sort_set_sort_column_id (GtkTreeSortable *sortable,
           else
 	    return;
         }
+    }
 
   tree_model_sort->sort_column_id = sort_column_id;
   tree_model_sort->order = order;
@@ -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;
 

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)
 {
@@ -127,10 +135,19 @@ gtk_tree_sortable_get_sort_column_id (GtkTreeSortable  *sortable,
  * 
  * 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
+ * #GtkTreeSortable::sort-column-changed signal. @sortable may either be 
- * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the default sort function
+ * a regular column id, or one of the following special values:
- * will be used, if it is set.
+ * <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,
@@ -157,9 +174,9 @@ gtk_tree_sortable_set_sort_column_id (GtkTreeSortable  *sortable,
  * @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
+ * current sort column id of @sortable is the same as @sort_column_id, then 
- * model will sort using this function.
+ * 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
+ * default state. In this case, when the current sort column id of @sortable 
- * GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted.
+ * 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,
@@ -221,11 +238,11 @@ gtk_tree_sortable_set_default_sort_func (GtkTreeSortable        *sortable,
  * @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
+ * primarily by GtkTreeViewColumns in order to determine if a model can 
- * to the default state, or not.
+ * 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)
 {