Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtktreemodelsort.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkTreeModelSort
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A GtkTreeModel which makes an underlying tree model sortable
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkTreeModelSort is a model which implements the #GtkTreeSortable
  10 interface.  It does not hold any data itself, but rather is created with
  11 a child model and proxies its data.  It has identical column types to
  12 this child model, and the changes in the child are propagated.  The
  13 primary purpose of this model is to provide a way to sort a different
  14 model without modifying it. Note that the sort function used by
  15 #GtkTreeModelSort is not guaranteed to be stable.
  16 </para>
  17 <para>
  18 The use of this is best demonstrated through an example.  In the
  19 following sample code we create two #GtkTreeView widgets each with a
  20 view of the same data.  As the model is wrapped here by a
  21 #GtkTreeModelSort, the two #GtkTreeView<!-- -->s can each sort their
  22 view of the data without affecting the other.  By contrast, if we
  23 simply put the same model in each widget, then sorting the first would
  24 sort the second.
  25 </para>
  26 <para>
  27 <example>
  28 <title>Using a <structname>GtkTreeModelSort</structname></title>
  29 <programlisting>
  30 {
  31   GtkTreeView *tree_view1;
  32   GtkTreeView *tree_view2;
  33   GtkTreeModel *sort_model1;
  34   GtkTreeModel *sort_model2;
  35   GtkTreeModel *child_model;
  36
  37   /* get the child model */
  38   child_model = get_my_model ();
  39
  40   /* Create the first tree */
  41   sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
  42   tree_view1 = gtk_tree_view_new_with_model (sort_model1);
  43
  44   /* Create the second tree */
  45   sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
  46   tree_view2 = gtk_tree_view_new_with_model (sort_model2);
  47
  48   /* Now we can sort the two models independently */
  49   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
  50                                         COLUMN_1, GTK_SORT_ASCENDING);
  51   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
  52                                         COLUMN_1, GTK_SORT_DESCENDING);
  53 }
  54 </programlisting>
  55 </example>
  56 </para>
  57
  58 <para>
  59 To demonstrate how to access the underlying child model from the sort
  60 model, the next example will be a callback for the #GtkTreeSelection
  61 "changed" signal.  In this callback, we get a string from COLUMN_1 of
  62 the model.  We then modify the string, find the same selected row on the
  63 child model, and change the row there.
  64 </para>
  65
  66 <para>
  67 <example>
  68 <title>Accessing the child model of in a selection changed callback</title>
  69 <programlisting>
  70 void
  71 selection_changed (GtkTreeSelection *selection, gpointer data)
  72 {
  73   GtkTreeModel *sort_model = NULL;
  74   GtkTreeModel *child_model;
  75   GtkTreeIter sort_iter;
  76   GtkTreeIter child_iter;
  77   char *some_data = NULL;
  78   char *modified_data;
  79
  80   /* Get the current selected row and the model. */
  81   if (! gtk_tree_selection_get_selected (selection,
  82                                          &amp;sort_model,
  83                                          &amp;sort_iter))
  84     return;
  85
  86
  87   /* Look up the current value on the selected row and get a new value
  88    * to change it to.
  89    */
  90   gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &amp;sort_iter,
  91                       COLUMN_1, &amp;some_data,
  92                       -1);
  93
  94   modified_data = change_the_data (some_data);
  95   g_free (some_data);
  96
  97   /* Get an iterator on the child model, instead of the sort model. */
  98   gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
  99                                                   &amp;child_iter,
 100                                                   &amp;sort_iter);
 101
 102   /* Get the child model and change the value of the row.  In this
 103    * example, the child model is a GtkListStore.  It could be any other
 104    * type of model, though.
 105    */
 106   child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
 107   gtk_list_store_set (GTK_LIST_STORE (child_model), &amp;child_iter,
 108                       COLUMN_1, &amp;modified_data,
 109                       -1);
 110   g_free (modified_data);
 111 }
 112 </programlisting>
 113 </example>
 114 </para>
 115
 116 <!-- ##### SECTION See_Also ##### -->
 117 <para>
 118 #GtkTreeModel, #GtkListStore, #GtkTreeStore, #GtkTreeSortable, #GtkTreeModelFilter
 119 </para>
 120
 121 <!-- ##### SECTION Stability_Level ##### -->
 122
 123
 124 <!-- ##### SECTION Image ##### -->
 125
 126
 127 <!-- ##### STRUCT GtkTreeModelSort ##### -->
 128 <para>
 129 This should not be accessed directly.  Use the accessor functions below.
 130 </para>
 131
 132
 133 <!-- ##### ARG GtkTreeModelSort:model ##### -->
 134 <para>
 135
 136 </para>
 137
 138 <!-- ##### FUNCTION gtk_tree_model_sort_new_with_model ##### -->
 139 <para>
 140
 141 </para>
 142
 143 @child_model:
 144 @Returns:
 145
 146
 147 <!-- ##### FUNCTION gtk_tree_model_sort_get_model ##### -->
 148 <para>
 149
 150 </para>
 151
 152 @tree_model:
 153 @Returns:
 154
 155
 156 <!-- ##### FUNCTION gtk_tree_model_sort_convert_child_path_to_path ##### -->
 157 <para>
 158
 159 </para>
 160
 161 @tree_model_sort:
 162 @child_path:
 163 @Returns:
 164
 165
 166 <!-- ##### FUNCTION gtk_tree_model_sort_convert_child_iter_to_iter ##### -->
 167 <para>
 168
 169 </para>
 170
 171 @tree_model_sort:
 172 @sort_iter:
 173 @child_iter:
 174 @Returns:
 175
 176
 177 <!-- ##### FUNCTION gtk_tree_model_sort_convert_path_to_child_path ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @tree_model_sort:
 183 @sorted_path:
 184 @Returns:
 185
 186
 187 <!-- ##### FUNCTION gtk_tree_model_sort_convert_iter_to_child_iter ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @tree_model_sort:
 193 @child_iter:
 194 @sorted_iter:
 195
 196
 197 <!-- ##### FUNCTION gtk_tree_model_sort_reset_default_sort_func ##### -->
 198 <para>
 199
 200 </para>
 201
 202 @tree_model_sort:
 203
 204
 205 <!-- ##### FUNCTION gtk_tree_model_sort_clear_cache ##### -->
 206 <para>
 207
 208 </para>
 209
 210 @tree_model_sort:
 211
 212
 213 <!-- ##### FUNCTION gtk_tree_model_sort_iter_is_valid ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @tree_model_sort:
 219 @iter:
 220 @Returns:
 221
 222