forked from AuroraMiddleware/gtk
Move documentation to inline comments: GtkTreeModelSort
This commit is contained in:
Javier Jardón
parent
b83a4f2e1d
commit
911ae50956
1
docs/reference/gtk/tmpl/.gitignore
vendored
1
docs/reference/gtk/tmpl/.gitignore
vendored
@ -130,6 +130,7 @@ gtktooltip.sgml
|
||||
gtktreednd.sgml
|
||||
gtktreemodel.sgml
|
||||
gtktreemodelfilter.sgml
|
||||
gtktreemodelsort.sgml
|
||||
gtktreeselection.sgml
|
||||
gtktreesortable.sgml
|
||||
gtktreestore.sgml
|
||||
|
||||
@ -1,222 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
GtkTreeModelSort
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
A GtkTreeModel which makes an underlying tree model sortable
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
The #GtkTreeModelSort is a model which implements the #GtkTreeSortable
|
||||
interface. It does not hold any data itself, but rather is created with
|
||||
a child model and proxies its data. It has identical column types to
|
||||
this child model, and the changes in the child are propagated. The
|
||||
primary purpose of this model is to provide a way to sort a different
|
||||
model without modifying it. Note that the sort function used by
|
||||
#GtkTreeModelSort is not guaranteed to be stable.
|
||||
</para>
|
||||
<para>
|
||||
The use of this is best demonstrated through an example. In the
|
||||
following sample code we create two #GtkTreeView widgets each with a
|
||||
view of the same data. As the model is wrapped here by a
|
||||
#GtkTreeModelSort, the two #GtkTreeView<!-- -->s can each sort their
|
||||
view of the data without affecting the other. By contrast, if we
|
||||
simply put the same model in each widget, then sorting the first would
|
||||
sort the second.
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title>Using a <structname>GtkTreeModelSort</structname></title>
|
||||
<programlisting>
|
||||
{
|
||||
GtkTreeView *tree_view1;
|
||||
GtkTreeView *tree_view2;
|
||||
GtkTreeModel *sort_model1;
|
||||
GtkTreeModel *sort_model2;
|
||||
GtkTreeModel *child_model;
|
||||
|
||||
/* get the child model */
|
||||
child_model = get_my_model ();
|
||||
|
||||
/* Create the first tree */
|
||||
sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
|
||||
tree_view1 = gtk_tree_view_new_with_model (sort_model1);
|
||||
|
||||
/* Create the second tree */
|
||||
sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
|
||||
tree_view2 = gtk_tree_view_new_with_model (sort_model2);
|
||||
|
||||
/* Now we can sort the two models independently */
|
||||
gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
|
||||
COLUMN_1, GTK_SORT_ASCENDING);
|
||||
gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
|
||||
COLUMN_1, GTK_SORT_DESCENDING);
|
||||
}
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To demonstrate how to access the underlying child model from the sort
|
||||
model, the next example will be a callback for the #GtkTreeSelection
|
||||
"changed" signal. In this callback, we get a string from COLUMN_1 of
|
||||
the model. We then modify the string, find the same selected row on the
|
||||
child model, and change the row there.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title>Accessing the child model of in a selection changed callback</title>
|
||||
<programlisting>
|
||||
void
|
||||
selection_changed (GtkTreeSelection *selection, gpointer data)
|
||||
{
|
||||
GtkTreeModel *sort_model = NULL;
|
||||
GtkTreeModel *child_model;
|
||||
GtkTreeIter sort_iter;
|
||||
GtkTreeIter child_iter;
|
||||
char *some_data = NULL;
|
||||
char *modified_data;
|
||||
|
||||
/* Get the current selected row and the model. */
|
||||
if (! gtk_tree_selection_get_selected (selection,
|
||||
&sort_model,
|
||||
&sort_iter))
|
||||
return;
|
||||
|
||||
|
||||
/* Look up the current value on the selected row and get a new value
|
||||
* to change it to.
|
||||
*/
|
||||
gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
|
||||
COLUMN_1, &some_data,
|
||||
-1);
|
||||
|
||||
modified_data = change_the_data (some_data);
|
||||
g_free (some_data);
|
||||
|
||||
/* Get an iterator on the child model, instead of the sort model. */
|
||||
gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
|
||||
&child_iter,
|
||||
&sort_iter);
|
||||
|
||||
/* Get the child model and change the value of the row. In this
|
||||
* example, the child model is a GtkListStore. It could be any other
|
||||
* type of model, though.
|
||||
*/
|
||||
child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
|
||||
gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
|
||||
COLUMN_1, &modified_data,
|
||||
-1);
|
||||
g_free (modified_data);
|
||||
}
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
#GtkTreeModel, #GtkListStore, #GtkTreeStore, #GtkTreeSortable, #GtkTreeModelFilter
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### SECTION Image ##### -->
|
||||
|
||||
|
||||
<!-- ##### STRUCT GtkTreeModelSort ##### -->
|
||||
<para>
|
||||
This should not be accessed directly. Use the accessor functions below.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### ARG GtkTreeModelSort:model ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_new_with_model ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@child_model:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_get_model ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree_model:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_convert_child_path_to_path ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree_model_sort:
|
||||
@child_path:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_convert_child_iter_to_iter ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree_model_sort:
|
||||
@sort_iter:
|
||||
@child_iter:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_convert_path_to_child_path ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree_model_sort:
|
||||
@sorted_path:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_convert_iter_to_child_iter ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree_model_sort:
|
||||
@child_iter:
|
||||
@sorted_iter:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_reset_default_sort_func ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree_model_sort:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_clear_cache ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree_model_sort:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_tree_model_sort_iter_is_valid ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@tree_model_sort:
|
||||
@iter:
|
||||
@Returns:
|
||||
|
||||
|
||||
@ -49,6 +49,113 @@
|
||||
#include "gtktreednd.h"
|
||||
|
||||
|
||||
/**
|
||||
* SECTION:gtktreemodelsort
|
||||
* @Short_description: A GtkTreeModel which makes an underlying tree model sortable
|
||||
* @Title: GtkTreeModelSort
|
||||
* @See_also: #GtkTreeModel, #GtkListStore, #GtkTreeStore, #GtkTreeSortable, #GtkTreeModelFilter
|
||||
*
|
||||
* The #GtkTreeModelSort is a model which implements the #GtkTreeSortable
|
||||
* interface. It does not hold any data itself, but rather is created with
|
||||
* a child model and proxies its data. It has identical column types to
|
||||
* this child model, and the changes in the child are propagated. The
|
||||
* primary purpose of this model is to provide a way to sort a different
|
||||
* model without modifying it. Note that the sort function used by
|
||||
* #GtkTreeModelSort is not guaranteed to be stable.
|
||||
*
|
||||
* The use of this is best demonstrated through an example. In the
|
||||
* following sample code we create two #GtkTreeView widgets each with a
|
||||
* view of the same data. As the model is wrapped here by a
|
||||
* #GtkTreeModelSort, the two #GtkTreeView<!-- -->s can each sort their
|
||||
* view of the data without affecting the other. By contrast, if we
|
||||
* simply put the same model in each widget, then sorting the first would
|
||||
* sort the second.
|
||||
*
|
||||
* <example>
|
||||
* <title>Using a <structname>GtkTreeModelSort</structname></title>
|
||||
* <programlisting>
|
||||
* {
|
||||
* GtkTreeView *tree_view1;
|
||||
* GtkTreeView *tree_view2;
|
||||
* GtkTreeModel *sort_model1;
|
||||
* GtkTreeModel *sort_model2;
|
||||
* GtkTreeModel *child_model;
|
||||
*
|
||||
* // get the child model
|
||||
* child_model = get_my_model ();
|
||||
*
|
||||
* // Create the first tree
|
||||
* sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
|
||||
* tree_view1 = gtk_tree_view_new_with_model (sort_model1);
|
||||
*
|
||||
* // Create the second tree
|
||||
* sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
|
||||
* tree_view2 = gtk_tree_view_new_with_model (sort_model2);
|
||||
*
|
||||
* // Now we can sort the two models independently
|
||||
* gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
|
||||
* COLUMN_1, GTK_SORT_ASCENDING);
|
||||
* gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
|
||||
* COLUMN_1, GTK_SORT_DESCENDING);
|
||||
* }
|
||||
* </programlisting>
|
||||
* </example>
|
||||
*
|
||||
* To demonstrate how to access the underlying child model from the sort
|
||||
* model, the next example will be a callback for the #GtkTreeSelection
|
||||
* #GtkTreeSelection::changed signal. In this callback, we get a string
|
||||
* from COLUMN_1 of the model. We then modify the string, find the same
|
||||
* selected row on the child model, and change the row there.
|
||||
*
|
||||
* <example>
|
||||
* <title>Accessing the child model of in a selection changed callback</title>
|
||||
* <programlisting>
|
||||
* void
|
||||
* selection_changed (GtkTreeSelection *selection, gpointer data)
|
||||
* {
|
||||
* GtkTreeModel *sort_model = NULL;
|
||||
* GtkTreeModel *child_model;
|
||||
* GtkTreeIter sort_iter;
|
||||
* GtkTreeIter child_iter;
|
||||
* char *some_data = NULL;
|
||||
* char *modified_data;
|
||||
*
|
||||
* // Get the current selected row and the model.
|
||||
* if (! gtk_tree_selection_get_selected (selection,
|
||||
* &sort_model,
|
||||
* &sort_iter))
|
||||
* return;
|
||||
*
|
||||
* /<!---->* Look up the current value on the selected row and get a new value
|
||||
* * to change it to.
|
||||
* *<!---->/
|
||||
* gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
|
||||
* COLUMN_1, &some_data,
|
||||
* -1);
|
||||
*
|
||||
* modified_data = change_the_data (some_data);
|
||||
* g_free (some_data);
|
||||
*
|
||||
* // Get an iterator on the child model, instead of the sort model.
|
||||
* gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
|
||||
* &child_iter,
|
||||
* &sort_iter);
|
||||
*
|
||||
* /<!---->* Get the child model and change the value of the row. In this
|
||||
* * example, the child model is a GtkListStore. It could be any other
|
||||
* * type of model, though.
|
||||
* *<!---->/
|
||||
* child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
|
||||
* gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
|
||||
* COLUMN_1, &modified_data,
|
||||
* -1);
|
||||
* g_free (modified_data);
|
||||
* }
|
||||
* </programlisting>
|
||||
* </example>
|
||||
*/
|
||||
|
||||
|
||||
typedef struct _SortElt SortElt;
|
||||
typedef struct _SortLevel SortLevel;
|
||||
typedef struct _SortData SortData;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user