← Back to branch summary

~ubuntu-branches/ubuntu/precise/gtk+2.0/precise-updates

« back to all changes in this revision

Viewing changes to docs/reference/gtk/tmpl/gtktreemodelsort.sgml

  • Committer: Package Import Robot
  • Author(s): Ken VanDine
  • Date: 2011-12-01 11:40:06 UTC
  • mfrom: (1.14.11)
  • Revision ID: package-import@ubuntu.com-20111201114006-nrmf6qu3pg512veo
Tags: 2.24.8-0ubuntu1
https://launchpad.net/bugs/189494
https://launchpad.net/bugs/889019
* New upstream release 
  - gtkfilechooser should be more robust to malformed URIs
    in .gtk-bookmarks (LP: #189494)
* debian/patches/010_make_bg_changes_queue_repaint.patch
  - dropped it introduces performance regressions in some gtk2 
    apps (LP: #889019)
* 101_filechooser.patch, 000git_file_chooser.patch: dropped, upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
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