From 1873c20239b4bbc426e804c0798a283c1eb26369 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 3 Jan 2009 06:57:10 +0000 Subject: [PATCH] Improve the docs 2009-01-03 Matthias Clasen * 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 | 7 ++++++ gtk/gtktreemodelsort.c | 46 ++++++++++++++++++++--------------- gtk/gtktreesortable.c | 55 +++++++++++++++++++++++++++--------------- 3 files changed, 69 insertions(+), 39 deletions(-) diff --git a/ChangeLog b/ChangeLog index 825ddf870..064fb7cdd 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2009-01-03 Matthias Clasen + + * gtk/gtktreesortable.c: Improve the docs + + * gtk/gtktreemodelsort.c: Don't assert when using the "unsorted" + sort column id. + 2009-01-02 Matthias Clasen Bug 565998 – configure script doesn't check for cairo-xlib.pc diff --git a/gtk/gtktreemodelsort.c b/gtk/gtktreemodelsort.c index 077b6023e..1dbdda41f 100644 --- 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) - { - GtkTreeDataSortHeader *header = NULL; - - 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); - - if (tree_model_sort->sort_column_id == sort_column_id) + if (sort_column_id != GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID) { if (sort_column_id != GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID) - { - if (tree_model_sort->order == order) - return; - } + { + GtkTreeDataSortHeader *header = NULL; + + 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 - return; + 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) + 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 09bea0095..d6cd4e2d1 100644 --- 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: + * + * + * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID + * the default sort function will be used, if it is set + * + * + * %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID + * no sorting will occur + * + * + */ 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) {