/src/wrappers/gtk/library/gtk_tree_model_sort.e

  1indexing
  2	description: "GtkTreeModelSort -- a GtkTreeModel which makes an underlying tree model sortable."
  3	copyright: "[
  4					Copyright (C) 2007 $EWLC_developer, $original_copyright_holder
  5					
  6					This library is free software; you can redistribute it and/or
  7					modify it under the terms of the GNU Lesser General Public License
  8					as published by the Free Software Foundation; either version 2.1 of
  9					the License, or (at your option) any later version.
 10					
 11					This library is distributed in the hope that it will be useful, but
 12					WITHOUT ANY WARRANTY; without even the implied warranty of
 13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 14					Lesser General Public License for more details.
 15
 16					You should have received a copy of the GNU Lesser General Public
 17					License along with this library; if not, write to the Free Software
 18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19					02110-1301 USA
 20			]"
 21
 22class GTK_TREE_MODEL_SORT
 23	-- The GtkTreeModelSort is a model which implements the
 24	-- GtkTreeSortable interface. It does not hold any data itself, but
 25	-- rather is created with a child model and proxies its data. It
 26	-- has identical column types to this child model, and the changes
 27	-- in the child are propagated. The primary purpose of this model
 28	-- is to provide a way to sort a different model without modifying
 29	-- it. Note that the sort function used by GtkTreeModelSort is not
 30	-- guaranteed to be stable.
 31
 32	-- The use of this is best demonstrated through an example. In the
 33	-- following sample code we create two GtkTreeView widgets each
 34	-- with a view of the same data. As the model is wrapped here by a
 35	-- GtkTreeModelSort, the two GtkTreeViews can each sort their view
 36	-- of the data without affecting the other. By contrast, if we
 37	-- simply put the same model in each widget, then sorting the first
 38	-- would sort the second.
 39
 40	-- (TODO: Eiffelize) Example 3. Using a GtkTreeModelSort
 41
 42	-- {
 43	--   GtkTreeView *tree_view1;
 44	--   GtkTreeView *tree_view2;
 45	--   GtkTreeModel *sort_model1;
 46	--   GtkTreeModel *sort_model2;
 47	--   GtkTreeModel *child_model;
 48
 49	--   /* get the child model */
 50	--   child_model = get_my_model();
 51
 52	--   /* Create the first tree */
 53	--   sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
 54	--   tree_view1 = gtk_tree_view_new_with_model (sort_model1);
 55
 56	--   /* Create the second tree */
 57	--   sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
 58	--   tree_view2 = gtk_tree_view_new_with_model (sort_model2);
 59
 60	--   /* Now we can sort the two models independently */
 61	--   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
 62	--                                         COLUMN_1, GTK_SORT_ASCENDING);
 63	--   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
 64	--                                         COLUMN_1, GTK_SORT_DESCENDING);
 65	-- }
 66
 67	-- To demonstrate how to access the underlying child model from the
 68	-- sort model, the next example will be a callback for the
 69	-- GtkTreeSelection "changed" signal. In this callback, we get a
 70	-- string from COLUMN_1 of the model. We then modify the string,
 71	-- find the same selected row on the child model, and change the
 72	-- row there.
 73
 74	-- (TODO: Eiffelize) Example 4. Accessing the child model of in a selection changed callback
 75
 76	-- void
 77	-- selection_changed (GtkTreeSelection *selection, gpointer data)
 78	-- {
 79	--   GtkTreeModel *sort_model = NULL;
 80	--   GtkTreeModel *child_model;
 81	--   GtkTreeIter sort_iter;
 82	--   GtkTreeIter child_iter;
 83	--   char *some_data = NULL;
 84	--   char *modified_data;
 85
 86	--   /* Get the current selected row and the model. */
 87	--   if (! gtk_tree_selection_get_selected (selection,
 88	--                                          &sort_model,
 89	--                                          &sort_iter))
 90	--     return;
 91
 92
 93	--   /* Look up the current value on the selected row and get a new value
 94	--    * to change it to.
 95	--    */
 96	--   gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
 97	--                       COLUMN_1, &some_data,
 98	--                       -1);
 99
100	--   modified_data = change_the_data (some_data);
101	--   g_free (some_data);
102
103	--   /* Get an iterator on the child model, instead of the sort model. */
104	--   gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
105	--                                                   &child_iter,
106	--                                                   &sort_iter);
107	
108	--   /* Get the child model and change the value of the row.  In this
109	--    * example, the child model is a GtkListStore.  It could be any other
110	--    * type of model, though.
111	--    */
112	--   child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
113	--   gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
114	--                       COLUMN_1, &modified_data,
115	--                       -1);
116	--   g_free (modified_data);
117	-- }
118	
119inherit
120	G_OBJECT
121	GTK_TREE_MODEL
122	GTK_TREE_DRAG_SOURCE
123	GTK_TREE_SORTABLE
124
125creation from_external_pointer
126
127feature {} 
128-- gtk_tree_model_sort_new_with_model ()
129
130-- GtkTreeModel* gtk_tree_model_sort_new_with_model
131--                                             (GtkTreeModel *child_model);
132
133-- Creates a new GtkTreeModel, with child_model as the child model.
134
135-- child_model : 	A GtkTreeModel
136-- Returns : 	A new GtkTreeModel.
137-- gtk_tree_model_sort_get_model ()
138
139-- GtkTreeModel* gtk_tree_model_sort_get_model (GtkTreeModelSort *tree_model);
140
141-- Returns the model the GtkTreeModelSort is sorting.
142
143-- tree_model : 	a GtkTreeModelSort
144-- Returns : 	the "child model" being sorted
145-- gtk_tree_model_sort_convert_child_path_to_path ()
146
147-- GtkTreePath* gtk_tree_model_sort_convert_child_path_to_path
148--                                             (GtkTreeModelSort *tree_model_sort,
149--                                              GtkTreePath *child_path);
150
151-- Converts child_path to a path relative to tree_model_sort. That is, child_path points to a path in the child model. The returned path will point to the same row in the sorted model. If child_path isn't a valid path on the child model, then NULL is returned.
152
153-- tree_model_sort : 	A GtkTreeModelSort
154-- child_path : 	A GtkTreePath to convert
155-- Returns : 	A newly allocated GtkTreePath, or NULL
156-- gtk_tree_model_sort_convert_child_iter_to_iter ()
157
158-- void        gtk_tree_model_sort_convert_child_iter_to_iter
159--                                             (GtkTreeModelSort *tree_model_sort,
160--                                              GtkTreeIter *sort_iter,
161--                                              GtkTreeIter *child_iter);
162
163-- Sets sort_iter to point to the row in tree_model_sort that corresponds to the row pointed at by child_iter.
164
165-- tree_model_sort : 	A GtkTreeModelSort
166-- sort_iter : 	An uninitialized GtkTreeIter.
167-- child_iter : 	A valid GtkTreeIter pointing to a row on the child model
168-- gtk_tree_model_sort_convert_path_to_child_path ()
169
170-- GtkTreePath* gtk_tree_model_sort_convert_path_to_child_path
171--                                             (GtkTreeModelSort *tree_model_sort,
172--                                              GtkTreePath *sorted_path);
173
174-- Converts sorted_path to a path on the child model of tree_model_sort. That is, sorted_path points to a location in tree_model_sort. The returned path will point to the same location in the model not being sorted. If sorted_path does not point to a location in the child model, NULL is returned.
175
176-- tree_model_sort : 	A GtkTreeModelSort
177-- sorted_path : 	A GtkTreePath to convert
178-- Returns : 	A newly allocated GtkTreePath, or NULL
179-- gtk_tree_model_sort_convert_iter_to_child_iter ()
180
181-- void        gtk_tree_model_sort_convert_iter_to_child_iter
182--                                             (GtkTreeModelSort *tree_model_sort,
183--                                              GtkTreeIter *child_iter,
184--                                              GtkTreeIter *sorted_iter);
185
186-- Sets child_iter to point to the row pointed to by sorted_iter.
187
188-- tree_model_sort : 	A GtkTreeModelSort
189-- child_iter : 	An uninitialized GtkTreeIter
190-- sorted_iter : 	A valid GtkTreeIter pointing to a row on tree_model_sort.
191-- gtk_tree_model_sort_reset_default_sort_func ()
192
193-- void        gtk_tree_model_sort_reset_default_sort_func
194--                                             (GtkTreeModelSort *tree_model_sort);
195
196-- This resets the default sort function to be in the 'unsorted' state. That is, it is in the same order as the child model. It will re-sort the model to be in the same order as the child model only if the GtkTreeModelSort is in 'unsorted' state.
197
198-- tree_model_sort : 	A GtkTreeModelSort
199-- gtk_tree_model_sort_clear_cache ()
200
201-- void        gtk_tree_model_sort_clear_cache (GtkTreeModelSort *tree_model_sort);
202
203-- This function should almost never be called. It clears the tree_model_sort of any cached iterators that haven't been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being sorted is static (and doesn't change often) and there has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid.
204
205-- tree_model_sort : 	A GtkTreeModelSort
206-- gtk_tree_model_sort_iter_is_valid ()
207
208-- gboolean    gtk_tree_model_sort_iter_is_valid
209--                                             (GtkTreeModelSort *tree_model_sort,
210--                                              GtkTreeIter *iter);
211
212-- Warning
213
214-- This function is slow. Only use it for debugging and/or testing purposes.
215
216-- Checks if the given iter is a valid iter for this GtkTreeModelSort.
217
218-- tree_model_sort : 	A GtkTreeModelSort.
219-- iter : 	A GtkTreeIter.
220-- Returns : 	TRUE if the iter is valid, FALSE if the iter is invalid.
221
222
223feature -- "model" properties
224
225--   "model"                GtkTreeModel          : Read / Write / Construct Only
226
227-- The model for the TreeModelSort to sort.
228
229feature {} -- External calls
230
231-- #include <gtk/gtk.h>
232
233
234--             GtkTreeModelSort;
235-- GtkTreeModel* gtk_tree_model_sort_new_with_model
236--                                             (GtkTreeModel *child_model);
237-- GtkTreeModel* gtk_tree_model_sort_get_model (GtkTreeModelSort *tree_model);
238-- GtkTreePath* gtk_tree_model_sort_convert_child_path_to_path
239--                                             (GtkTreeModelSort *tree_model_sort,
240--                                              GtkTreePath *child_path);
241-- void        gtk_tree_model_sort_convert_child_iter_to_iter
242--                                             (GtkTreeModelSort *tree_model_sort,
243--                                              GtkTreeIter *sort_iter,
244--                                              GtkTreeIter *child_iter);
245-- GtkTreePath* gtk_tree_model_sort_convert_path_to_child_path
246--                                             (GtkTreeModelSort *tree_model_sort,
247--                                              GtkTreePath *sorted_path);
248-- void        gtk_tree_model_sort_convert_iter_to_child_iter
249--                                             (GtkTreeModelSort *tree_model_sort,
250--                                              GtkTreeIter *child_iter,
251--                                              GtkTreeIter *sorted_iter);
252-- void        gtk_tree_model_sort_reset_default_sort_func
253--                                             (GtkTreeModelSort *tree_model_sort);
254-- void        gtk_tree_model_sort_clear_cache (GtkTreeModelSort *tree_model_sort);
255-- gboolean    gtk_tree_model_sort_iter_is_valid
256--                                             (GtkTreeModelSort *tree_model_sort,
257--                                              GtkTreeIter *iter);
258feature -- size
259	struct_size: INTEGER is
260		external "C inline use <gtk/gtk.h>"
261		alias "sizeof(GtkTreeModel)"
262		end
263
264end -- class GTK_TREE_MODEL_SORT