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()
145 	{
146 		return gtkTreeModelSort;
147 	}
148 
149 	/** the main Gtk struct as a void* */
150 	protected override void* getStruct()
151 	{
152 		return cast(void*)gtkTreeModelSort;
153 	}
154 
155 	protected override void setStruct(GObject* obj)
156 	{
157 		gtkTreeModelSort = cast(GtkTreeModelSort*)obj;
158 		super.setStruct(obj);
159 	}
160 
161 	/**
162 	 * Sets our main struct and passes it to the parent class.
163 	 */
164 	public this (GtkTreeModelSort* gtkTreeModelSort, bool ownedRef = false)
165 	{
166 		this.gtkTreeModelSort = gtkTreeModelSort;
167 		super(cast(GObject*)gtkTreeModelSort, ownedRef);
168 	}
169 
170 	// add the TreeDragSource capabilities
171 	mixin TreeDragSourceT!(GtkTreeModelSort);
172 
173 	// add the TreeModel capabilities
174 	mixin TreeModelT!(GtkTreeModelSort);
175 
176 	// add the TreeSortable capabilities
177 	mixin TreeSortableT!(GtkTreeModelSort);
178 
179 	/**
180 	 * Creates a new TreeModel, with childModel as the child model.
181 	 *
182 	 * Params:
183 	 *     childModel = A TreeModel.
184 	 *
185 	 * Throws: A ConstructionException if GTK+ fails to create the object.
186 	 *
187 	 */
188 	public this(TreeModelIF childModel)
189 	{
190 		auto p = gtk_tree_model_sort_new_with_model(childModel.getTreeModelStruct());
191 		
192 		if(p is null)
193 		{
194 			throw new ConstructionException("null returned by gtk_tree_model_sort_new_with_model");
195 		}
196 		
197 		this(cast(GtkTreeModelSort*) p, true);
198 	}
199 
200 	/**
201 	 */
202 
203 	/** */
204 	public static GType getType()
205 	{
206 		return gtk_tree_model_sort_get_type();
207 	}
208 
209 	/**
210 	 * This function should almost never be called.  It clears the @tree_model_sort
211 	 * of any cached iterators that haven’t been reffed with
212 	 * gtk_tree_model_ref_node().  This might be useful if the child model being
213 	 * sorted is static (and doesn’t change often) and there has been a lot of
214 	 * unreffed access to nodes.  As a side effect of this function, all unreffed
215 	 * iters will be invalid.
216 	 */
217 	public void clearCache()
218 	{
219 		gtk_tree_model_sort_clear_cache(gtkTreeModelSort);
220 	}
221 
222 	/**
223 	 * Sets @sort_iter to point to the row in @tree_model_sort that corresponds to
224 	 * the row pointed at by @child_iter.  If @sort_iter was not set, %FALSE
225 	 * is returned.  Note: a boolean is only returned since 2.14.
226 	 *
227 	 * Params:
228 	 *     sortIter = An uninitialized #GtkTreeIter.
229 	 *     childIter = A valid #GtkTreeIter pointing to a row on the child model
230 	 *
231 	 * Return: %TRUE, if @sort_iter was set, i.e. if @sort_iter is a
232 	 *     valid iterator pointer to a visible row in the child model.
233 	 */
234 	public bool convertChildIterToIter(out TreeIter sortIter, TreeIter childIter)
235 	{
236 		GtkTreeIter* outsortIter = gMalloc!GtkTreeIter();
237 		
238 		auto p = gtk_tree_model_sort_convert_child_iter_to_iter(gtkTreeModelSort, outsortIter, (childIter is null) ? null : childIter.getTreeIterStruct()) != 0;
239 		
240 		sortIter = ObjectG.getDObject!(TreeIter)(outsortIter, true);
241 		
242 		return p;
243 	}
244 
245 	/**
246 	 * Converts @child_path to a path relative to @tree_model_sort.  That is,
247 	 * @child_path points to a path in the child model.  The returned path will
248 	 * point to the same row in the sorted model.  If @child_path isn’t a valid
249 	 * path on the child model, then %NULL is returned.
250 	 *
251 	 * Params:
252 	 *     childPath = A #GtkTreePath to convert
253 	 *
254 	 * Return: A newly allocated #GtkTreePath, or %NULL
255 	 */
256 	public TreePath convertChildPathToPath(TreePath childPath)
257 	{
258 		auto p = gtk_tree_model_sort_convert_child_path_to_path(gtkTreeModelSort, (childPath is null) ? null : childPath.getTreePathStruct());
259 		
260 		if(p is null)
261 		{
262 			return null;
263 		}
264 		
265 		return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p, true);
266 	}
267 
268 	/**
269 	 * Sets @child_iter to point to the row pointed to by @sorted_iter.
270 	 *
271 	 * Params:
272 	 *     childIter = An uninitialized #GtkTreeIter
273 	 *     sortedIter = A valid #GtkTreeIter pointing to a row on @tree_model_sort.
274 	 */
275 	public void convertIterToChildIter(out TreeIter childIter, TreeIter sortedIter)
276 	{
277 		GtkTreeIter* outchildIter = gMalloc!GtkTreeIter();
278 		
279 		gtk_tree_model_sort_convert_iter_to_child_iter(gtkTreeModelSort, outchildIter, (sortedIter is null) ? null : sortedIter.getTreeIterStruct());
280 		
281 		childIter = ObjectG.getDObject!(TreeIter)(outchildIter, true);
282 	}
283 
284 	/**
285 	 * Converts @sorted_path to a path on the child model of @tree_model_sort.
286 	 * That is, @sorted_path points to a location in @tree_model_sort.  The
287 	 * returned path will point to the same location in the model not being
288 	 * sorted.  If @sorted_path does not point to a location in the child model,
289 	 * %NULL is returned.
290 	 *
291 	 * Params:
292 	 *     sortedPath = A #GtkTreePath to convert
293 	 *
294 	 * Return: A newly allocated #GtkTreePath, or %NULL
295 	 */
296 	public TreePath convertPathToChildPath(TreePath sortedPath)
297 	{
298 		auto p = gtk_tree_model_sort_convert_path_to_child_path(gtkTreeModelSort, (sortedPath is null) ? null : sortedPath.getTreePathStruct());
299 		
300 		if(p is null)
301 		{
302 			return null;
303 		}
304 		
305 		return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p, true);
306 	}
307 
308 	/**
309 	 * Returns the model the #GtkTreeModelSort is sorting.
310 	 *
311 	 * Return: the "child model" being sorted
312 	 */
313 	public TreeModelIF getModel()
314 	{
315 		auto p = gtk_tree_model_sort_get_model(gtkTreeModelSort);
316 		
317 		if(p is null)
318 		{
319 			return null;
320 		}
321 		
322 		return ObjectG.getDObject!(TreeModel, TreeModelIF)(cast(GtkTreeModel*) p);
323 	}
324 
325 	/**
326 	 * > This function is slow. Only use it for debugging and/or testing
327 	 * > purposes.
328 	 *
329 	 * Checks if the given iter is a valid iter for this #GtkTreeModelSort.
330 	 *
331 	 * Params:
332 	 *     iter = A #GtkTreeIter.
333 	 *
334 	 * Return: %TRUE if the iter is valid, %FALSE if the iter is invalid.
335 	 *
336 	 * Since: 2.2
337 	 */
338 	public bool iterIsValid(TreeIter iter)
339 	{
340 		return gtk_tree_model_sort_iter_is_valid(gtkTreeModelSort, (iter is null) ? null : iter.getTreeIterStruct()) != 0;
341 	}
342 
343 	/**
344 	 * This resets the default sort function to be in the “unsorted” state.  That
345 	 * is, it is in the same order as the child model. It will re-sort the model
346 	 * to be in the same order as the child model only if the #GtkTreeModelSort
347 	 * is in “unsorted” state.
348 	 */
349 	public void resetDefaultSortFunc()
350 	{
351 		gtk_tree_model_sort_reset_default_sort_func(gtkTreeModelSort);
352 	}
353 }