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