1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gtk.TreeModelSort;
26 
27 private import glib.ConstructionException;
28 private import glib.MemorySlice;
29 private import gobject.ObjectG;
30 private import gtk.TreeDragSourceIF;
31 private import gtk.TreeDragSourceT;
32 private import gtk.TreeIter;
33 private import gtk.TreeModelIF;
34 private import gtk.TreeModelT;
35 private import gtk.TreePath;
36 private import gtk.TreeSortableIF;
37 private import gtk.TreeSortableT;
38 private import gtk.c.functions;
39 public  import gtk.c.types;
40 public  import gtkc.gtktypes;
41 
42 
43 /**
44  * The #GtkTreeModelSort is a model which implements the #GtkTreeSortable
45  * interface.  It does not hold any data itself, but rather is created with
46  * a child model and proxies its data.  It has identical column types to
47  * this child model, and the changes in the child are propagated.  The
48  * primary purpose of this model is to provide a way to sort a different
49  * model without modifying it. Note that the sort function used by
50  * #GtkTreeModelSort is not guaranteed to be stable.
51  * 
52  * The use of this is best demonstrated through an example.  In the
53  * following sample code we create two #GtkTreeView widgets each with a
54  * view of the same data.  As the model is wrapped here by a
55  * #GtkTreeModelSort, the two #GtkTreeViews can each sort their
56  * view of the data without affecting the other.  By contrast, if we
57  * simply put the same model in each widget, then sorting the first would
58  * sort the second.
59  * 
60  * ## Using a #GtkTreeModelSort
61  * 
62  * |[<!-- language="C" -->
63  * {
64  * GtkTreeView *tree_view1;
65  * GtkTreeView *tree_view2;
66  * GtkTreeModel *sort_model1;
67  * GtkTreeModel *sort_model2;
68  * GtkTreeModel *child_model;
69  * 
70  * // get the child model
71  * child_model = get_my_model ();
72  * 
73  * // Create the first tree
74  * sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
75  * tree_view1 = gtk_tree_view_new_with_model (sort_model1);
76  * 
77  * // Create the second tree
78  * sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
79  * tree_view2 = gtk_tree_view_new_with_model (sort_model2);
80  * 
81  * // Now we can sort the two models independently
82  * gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
83  * COLUMN_1, GTK_SORT_ASCENDING);
84  * gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
85  * COLUMN_1, GTK_SORT_DESCENDING);
86  * }
87  * ]|
88  * 
89  * To demonstrate how to access the underlying child model from the sort
90  * model, the next example will be a callback for the #GtkTreeSelection
91  * #GtkTreeSelection::changed signal.  In this callback, we get a string
92  * from COLUMN_1 of the model.  We then modify the string, find the same
93  * selected row on the child model, and change the row there.
94  * 
95  * ## Accessing the child model of in a selection changed callback
96  * 
97  * |[<!-- language="C" -->
98  * void
99  * selection_changed (GtkTreeSelection *selection, gpointer data)
100  * {
101  * GtkTreeModel *sort_model = NULL;
102  * GtkTreeModel *child_model;
103  * GtkTreeIter sort_iter;
104  * GtkTreeIter child_iter;
105  * char *some_data = NULL;
106  * char *modified_data;
107  * 
108  * // Get the current selected row and the model.
109  * if (! gtk_tree_selection_get_selected (selection,
110  * &sort_model,
111  * &sort_iter))
112  * return;
113  * 
114  * // Look up the current value on the selected row and get
115  * // a new value to change it to.
116  * gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
117  * COLUMN_1, &some_data,
118  * -1);
119  * 
120  * modified_data = change_the_data (some_data);
121  * g_free (some_data);
122  * 
123  * // Get an iterator on the child model, instead of the sort model.
124  * gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
125  * &child_iter,
126  * &sort_iter);
127  * 
128  * // Get the child model and change the value of the row. In this
129  * // example, the child model is a GtkListStore. It could be any other
130  * // type of model, though.
131  * child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
132  * gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
133  * COLUMN_1, &modified_data,
134  * -1);
135  * g_free (modified_data);
136  * }
137  * ]|
138  */
139 public class TreeModelSort : ObjectG, TreeDragSourceIF, TreeModelIF, TreeSortableIF
140 {
141 	/** the main Gtk struct */
142 	protected GtkTreeModelSort* gtkTreeModelSort;
143 
144 	/** Get the main Gtk struct */
145 	public GtkTreeModelSort* getTreeModelSortStruct(bool transferOwnership = false)
146 	{
147 		if (transferOwnership)
148 			ownedRef = false;
149 		return gtkTreeModelSort;
150 	}
151 
152 	/** the main Gtk struct as a void* */
153 	protected override void* getStruct()
154 	{
155 		return cast(void*)gtkTreeModelSort;
156 	}
157 
158 	protected override void setStruct(GObject* obj)
159 	{
160 		gtkTreeModelSort = cast(GtkTreeModelSort*)obj;
161 		super.setStruct(obj);
162 	}
163 
164 	/**
165 	 * Sets our main struct and passes it to the parent class.
166 	 */
167 	public this (GtkTreeModelSort* gtkTreeModelSort, bool ownedRef = false)
168 	{
169 		this.gtkTreeModelSort = gtkTreeModelSort;
170 		super(cast(GObject*)gtkTreeModelSort, ownedRef);
171 	}
172 
173 	// add the TreeDragSource capabilities
174 	mixin TreeDragSourceT!(GtkTreeModelSort);
175 
176 	// add the TreeModel capabilities
177 	mixin TreeModelT!(GtkTreeModelSort);
178 
179 	// add the TreeSortable capabilities
180 	mixin TreeSortableT!(GtkTreeModelSort);
181 
182 
183 	/** */
184 	public static GType getType()
185 	{
186 		return gtk_tree_model_sort_get_type();
187 	}
188 
189 	/**
190 	 * This function should almost never be called.  It clears the @tree_model_sort
191 	 * of any cached iterators that haven’t been reffed with
192 	 * gtk_tree_model_ref_node().  This might be useful if the child model being
193 	 * sorted is static (and doesn’t change often) and there has been a lot of
194 	 * unreffed access to nodes.  As a side effect of this function, all unreffed
195 	 * iters will be invalid.
196 	 */
197 	public void clearCache()
198 	{
199 		gtk_tree_model_sort_clear_cache(gtkTreeModelSort);
200 	}
201 
202 	/**
203 	 * Sets @sort_iter to point to the row in @tree_model_sort that corresponds to
204 	 * the row pointed at by @child_iter.  If @sort_iter was not set, %FALSE
205 	 * is returned.  Note: a boolean is only returned since 2.14.
206 	 *
207 	 * Params:
208 	 *     sortIter = An uninitialized #GtkTreeIter.
209 	 *     childIter = A valid #GtkTreeIter pointing to a row on the child model
210 	 *
211 	 * Returns: %TRUE, if @sort_iter was set, i.e. if @sort_iter is a
212 	 *     valid iterator pointer to a visible row in the child model.
213 	 */
214 	public bool convertChildIterToIter(out TreeIter sortIter, TreeIter childIter)
215 	{
216 		GtkTreeIter* outsortIter = sliceNew!GtkTreeIter();
217 
218 		auto p = gtk_tree_model_sort_convert_child_iter_to_iter(gtkTreeModelSort, outsortIter, (childIter is null) ? null : childIter.getTreeIterStruct()) != 0;
219 
220 		sortIter = ObjectG.getDObject!(TreeIter)(outsortIter, true);
221 
222 		return p;
223 	}
224 
225 	/**
226 	 * Converts @child_path to a path relative to @tree_model_sort.  That is,
227 	 * @child_path points to a path in the child model.  The returned path will
228 	 * point to the same row in the sorted model.  If @child_path isn’t a valid
229 	 * path on the child model, then %NULL is returned.
230 	 *
231 	 * Params:
232 	 *     childPath = A #GtkTreePath to convert
233 	 *
234 	 * Returns: A newly allocated #GtkTreePath, or %NULL
235 	 */
236 	public TreePath convertChildPathToPath(TreePath childPath)
237 	{
238 		auto p = gtk_tree_model_sort_convert_child_path_to_path(gtkTreeModelSort, (childPath is null) ? null : childPath.getTreePathStruct());
239 
240 		if(p is null)
241 		{
242 			return null;
243 		}
244 
245 		return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p, true);
246 	}
247 
248 	/**
249 	 * Sets @child_iter to point to the row pointed to by @sorted_iter.
250 	 *
251 	 * Params:
252 	 *     childIter = An uninitialized #GtkTreeIter
253 	 *     sortedIter = A valid #GtkTreeIter pointing to a row on @tree_model_sort.
254 	 */
255 	public void convertIterToChildIter(out TreeIter childIter, TreeIter sortedIter)
256 	{
257 		GtkTreeIter* outchildIter = sliceNew!GtkTreeIter();
258 
259 		gtk_tree_model_sort_convert_iter_to_child_iter(gtkTreeModelSort, outchildIter, (sortedIter is null) ? null : sortedIter.getTreeIterStruct());
260 
261 		childIter = ObjectG.getDObject!(TreeIter)(outchildIter, true);
262 	}
263 
264 	/**
265 	 * Converts @sorted_path to a path on the child model of @tree_model_sort.
266 	 * That is, @sorted_path points to a location in @tree_model_sort.  The
267 	 * returned path will point to the same location in the model not being
268 	 * sorted.  If @sorted_path does not point to a location in the child model,
269 	 * %NULL is returned.
270 	 *
271 	 * Params:
272 	 *     sortedPath = A #GtkTreePath to convert
273 	 *
274 	 * Returns: A newly allocated #GtkTreePath, or %NULL
275 	 */
276 	public TreePath convertPathToChildPath(TreePath sortedPath)
277 	{
278 		auto p = gtk_tree_model_sort_convert_path_to_child_path(gtkTreeModelSort, (sortedPath is null) ? null : sortedPath.getTreePathStruct());
279 
280 		if(p is null)
281 		{
282 			return null;
283 		}
284 
285 		return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p, true);
286 	}
287 
288 	/**
289 	 * Returns the model the #GtkTreeModelSort is sorting.
290 	 *
291 	 * Returns: the "child model" being sorted
292 	 */
293 	public TreeModelIF getModel()
294 	{
295 		auto p = gtk_tree_model_sort_get_model(gtkTreeModelSort);
296 
297 		if(p is null)
298 		{
299 			return null;
300 		}
301 
302 		return ObjectG.getDObject!(TreeModelIF)(cast(GtkTreeModel*) p);
303 	}
304 
305 	/**
306 	 * > This function is slow. Only use it for debugging and/or testing
307 	 * > purposes.
308 	 *
309 	 * Checks if the given iter is a valid iter for this #GtkTreeModelSort.
310 	 *
311 	 * Params:
312 	 *     iter = A #GtkTreeIter.
313 	 *
314 	 * Returns: %TRUE if the iter is valid, %FALSE if the iter is invalid.
315 	 *
316 	 * Since: 2.2
317 	 */
318 	public bool iterIsValid(TreeIter iter)
319 	{
320 		return gtk_tree_model_sort_iter_is_valid(gtkTreeModelSort, (iter is null) ? null : iter.getTreeIterStruct()) != 0;
321 	}
322 
323 	/**
324 	 * This resets the default sort function to be in the “unsorted” state.  That
325 	 * is, it is in the same order as the child model. It will re-sort the model
326 	 * to be in the same order as the child model only if the #GtkTreeModelSort
327 	 * is in “unsorted” state.
328 	 */
329 	public void resetDefaultSortFunc()
330 	{
331 		gtk_tree_model_sort_reset_default_sort_func(gtkTreeModelSort);
332 	}
333 
334 	/**
335 	 * Creates a new #GtkTreeModel, with @child_model as the child model.
336 	 *
337 	 * Params:
338 	 *     childModel = A #GtkTreeModel
339 	 *
340 	 * Returns: A new #GtkTreeModel.
341 	 *
342 	 * Throws: ConstructionException GTK+ fails to create the object.
343 	 */
344 	public this(TreeModelIF childModel)
345 	{
346 		auto p = gtk_tree_model_sort_new_with_model((childModel is null) ? null : childModel.getTreeModelStruct());
347 
348 		if(p is null)
349 		{
350 			throw new ConstructionException("null returned by new_with_model");
351 		}
352 
353 		this(cast(GtkTreeModelSort*) p, true);
354 	}
355 }