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  * Conversion parameters:
26  * inFile  = GtkTreeModel.html
27  * outPack = gtk
28  * outFile = TreePath
29  * strct   = GtkTreePath
30  * realStrct=
31  * ctorStrct=
32  * clss    = TreePath
33  * interf  = 
34  * class Code: Yes
35  * interface Code: No
36  * template for:
37  * extend  = 
38  * implements:
39  * prefixes:
40  * 	- gtk_tree_path_
41  * omit structs:
42  * omit prefixes:
43  * omit code:
44  * 	- gtk_tree_path_new
45  * 	- gtk_tree_path_new_first
46  * omit signals:
47  * 	- row-changed
48  * 	- row-deleted
49  * 	- row-has-child-toggled
50  * 	- row-inserted
51  * 	- rows-reordered
52  * imports:
53  * 	- glib.Str
54  * 	- gtkc.Loader
55  * 	- gtkc.paths
56  * structWrap:
57  * 	- GtkTreePath* -> TreePath
58  * module aliases:
59  * local aliases:
60  * overrides:
61  * 	- toString
62  */
63 
64 module gtk.TreePath;
65 
66 public  import gtkc.gtktypes;
67 
68 private import gtkc.gtk;
69 private import glib.ConstructionException;
70 private import gobject.ObjectG;
71 
72 private import gobject.Signals;
73 public  import gtkc.gdktypes;
74 
75 private import glib.Str;
76 private import gtkc.Loader;
77 private import gtkc.paths;
78 
79 
80 
81 
82 /**
83  * The GtkTreeModel interface defines a generic tree interface for
84  * use by the GtkTreeView widget. It is an abstract interface, and
85  * is designed to be usable with any appropriate data structure. The
86  * programmer just has to implement this interface on their own data
87  * type for it to be viewable by a GtkTreeView widget.
88  *
89  * The model is represented as a hierarchical tree of strongly-typed,
90  * columned data. In other words, the model can be seen as a tree where
91  * every node has different values depending on which column is being
92  * queried. The type of data found in a column is determined by using
93  * the GType system (ie. G_TYPE_INT, GTK_TYPE_BUTTON, G_TYPE_POINTER,
94  * etc). The types are homogeneous per column across all nodes. It is
95  * important to note that this interface only provides a way of examining
96  * a model and observing changes. The implementation of each individual
97  * model decides how and if changes are made.
98  *
99  * In order to make life simpler for programmers who do not need to
100  * write their own specialized model, two generic models are provided
101  * — the GtkTreeStore and the GtkListStore. To use these, the
102  * developer simply pushes data into these models as necessary. These
103  * models provide the data structure as well as all appropriate tree
104  * interfaces. As a result, implementing drag and drop, sorting, and
105  * storing data is trivial. For the vast majority of trees and lists,
106  * these two models are sufficient.
107  *
108  * Models are accessed on a node/column level of granularity. One can
109  * query for the value of a model at a certain node and a certain
110  * column on that node. There are two structures used to reference
111  * a particular node in a model. They are the GtkTreePath and the
112  * GtkTreeIter[4]. Most of the interface
113  * consists of operations on a GtkTreeIter.
114  *
115  * A path is essentially a potential node. It is a location on a model
116  * that may or may not actually correspond to a node on a specific
117  * model. The GtkTreePath struct can be converted into either an
118  * array of unsigned integers or a string. The string form is a list
119  * of numbers separated by a colon. Each number refers to the offset
120  * at that level. Thus, the path “0” refers to the root
121  * node and the path “2:4” refers to the fifth child of
122  * the third node.
123  *
124  * By contrast, a GtkTreeIter is a reference to a specific node on
125  * a specific model. It is a generic struct with an integer and three
126  * generic pointers. These are filled in by the model in a model-specific
127  * way. One can convert a path to an iterator by calling
128  * gtk_tree_model_get_iter(). These iterators are the primary way
129  * of accessing a model and are similar to the iterators used by
130  * GtkTextBuffer. They are generally statically allocated on the
131  * stack and only used for a short time. The model interface defines
132  * a set of operations using them for navigating the model.
133  *
134  * It is expected that models fill in the iterator with private data.
135  * For example, the GtkListStore model, which is internally a simple
136  * linked list, stores a list node in one of the pointers. The
137  * GtkTreeModelSort stores an array and an offset in two of the
138  * pointers. Additionally, there is an integer field. This field is
139  * generally filled with a unique stamp per model. This stamp is for
140  * catching errors resulting from using invalid iterators with a model.
141  *
142  * The lifecycle of an iterator can be a little confusing at first.
143  * Iterators are expected to always be valid for as long as the model
144  * is unchanged (and doesn't emit a signal). The model is considered
145  * to own all outstanding iterators and nothing needs to be done to
146  * free them from the user's point of view. Additionally, some models
147  * guarantee that an iterator is valid for as long as the node it refers
148  * to is valid (most notably the GtkTreeStore and GtkListStore).
149  * Although generally uninteresting, as one always has to allow for
150  * the case where iterators do not persist beyond a signal, some very
151  * important performance enhancements were made in the sort model.
152  * As a result, the GTK_TREE_MODEL_ITERS_PERSIST flag was added to
153  * indicate this behavior.
154  *
155  * To help show some common operation of a model, some examples are
156  * provided. The first example shows three ways of getting the iter at
157  * the location “3:2:5”. While the first method shown is
158  * easier, the second is much more common, as you often get paths from
159  * callbacks.
160  *
161  * $(DDOC_COMMENT example)
162  *
163  * This second example shows a quick way of iterating through a list
164  * and getting a string and an integer from each row. The
165  * populate_model function used below is not
166  * shown, as it is specific to the GtkListStore. For information on
167  * how to write such a function, see the GtkListStore documentation.
168  *
169  * $(DDOC_COMMENT example)
170  *
171  * The GtkTreeModel interface contains two methods for reference
172  * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node().
173  * These two methods are optional to implement. The reference counting
174  * is meant as a way for views to let models know when nodes are being
175  * displayed. GtkTreeView will take a reference on a node when it is
176  * visible, which means the node is either in the toplevel or expanded.
177  * Being displayed does not mean that the node is currently directly
178  * visible to the user in the viewport. Based on this reference counting
179  * scheme a caching model, for example, can decide whether or not to cache
180  * a node based on the reference count. A file-system based model would
181  * not want to keep the entire file hierarchy in memory, but just the
182  * folders that are currently expanded in every current view.
183  *
184  * When working with reference counting, the following rules must be taken
185  * into account:
186  *
187  * Never take a reference on a node without owning a
188  * reference on its parent. This means that all parent nodes of a referenced
189  * node must be referenced as well.
190  *
191  * Outstanding references on a deleted node are not released.
192  * This is not possible because the node has already been deleted by the
193  * time the row-deleted signal is received.
194  *
195  * Models are not obligated to emit a signal on rows of
196  * which none of its siblings are referenced. To phrase this differently,
197  * signals are only required for levels in which nodes are referenced. For
198  * the root level however, signals must be emitted at all times (however the
199  * root level is always referenced when any view is attached).
200  */
201 public class TreePath
202 {
203 	
204 	/** the main Gtk struct */
205 	protected GtkTreePath* gtkTreePath;
206 	
207 	
208 	public GtkTreePath* getTreePathStruct()
209 	{
210 		return gtkTreePath;
211 	}
212 	
213 	
214 	/** the main Gtk struct as a void* */
215 	protected void* getStruct()
216 	{
217 		return cast(void*)gtkTreePath;
218 	}
219 	
220 	/**
221 	 * Sets our main struct and passes it to the parent class
222 	 */
223 	public this (GtkTreePath* gtkTreePath)
224 	{
225 		this.gtkTreePath = gtkTreePath;
226 	}
227 	
228 	/**
229 	 * Creates a new GtkTreePath. This structure refers to a row.
230 	 * Params:
231 	 * firstRow = if true this is the string representation of this path is "0"
232 	 * Throws: ConstructionException GTK+ fails to create the object.
233 	 */
234 	public this (bool firstRow=false)
235 	{
236 		GtkTreePath* p;
237 		
238 		if ( firstRow )
239 		{
240 			// GtkTreePath* gtk_tree_path_new_first (void);
241 			p = cast(GtkTreePath*)gtk_tree_path_new_first();
242 		}
243 		else
244 		{
245 			// GtkTreePath* gtk_tree_path_new (void);
246 			p = cast(GtkTreePath*)gtk_tree_path_new();
247 		}
248 		
249 		if(p is null)
250 		{
251 			throw new ConstructionException("null returned by gtk_tree_path_new()");
252 		}
253 		
254 		this(p);
255 	}
256 	
257 	/**
258 	 * Creates a new path with "indices" as indices.
259 	 */
260 	this (int[] indices ... )
261 	{
262 		this(false);
263 		
264 		foreach( index; indices )
265 		appendIndex(index);
266 	}
267 	
268 	/**
269 	 */
270 	
271 	/**
272 	 * Creates a new GtkTreePath initialized to path.
273 	 * path is expected to be a colon separated list of numbers.
274 	 * For example, the string "10:4:0" would create a path of depth
275 	 * 3 pointing to the 11th child of the root node, the 5th
276 	 * child of that 11th child, and the 1st child of that 5th child.
277 	 * If an invalid path string is passed in, NULL is returned.
278 	 * Params:
279 	 * path = The string representation of a path
280 	 * Throws: ConstructionException GTK+ fails to create the object.
281 	 */
282 	public this (string path)
283 	{
284 		// GtkTreePath * gtk_tree_path_new_from_string (const gchar *path);
285 		auto p = gtk_tree_path_new_from_string(Str.toStringz(path));
286 		if(p is null)
287 		{
288 			throw new ConstructionException("null returned by gtk_tree_path_new_from_string(Str.toStringz(path))");
289 		}
290 		this(cast(GtkTreePath*) p);
291 	}
292 	
293 	/**
294 	 * Generates a string representation of the path.
295 	 * This string is a ':' separated list of numbers.
296 	 * For example, "4:10:0:3" would be an acceptable
297 	 * return value for this string.
298 	 * Returns: A newly-allocated string. Must be freed with g_free().
299 	 */
300 	public override string toString()
301 	{
302 		// gchar * gtk_tree_path_to_string (GtkTreePath *path);
303 		return Str.toString(gtk_tree_path_to_string(gtkTreePath));
304 	}
305 	
306 	/**
307 	 * Appends a new index to a path.
308 	 * As a result, the depth of the path is increased.
309 	 * Params:
310 	 * index = the index
311 	 */
312 	public void appendIndex(int index)
313 	{
314 		// void gtk_tree_path_append_index (GtkTreePath *path,  gint index_);
315 		gtk_tree_path_append_index(gtkTreePath, index);
316 	}
317 	
318 	/**
319 	 * Prepends a new index to a path.
320 	 * As a result, the depth of the path is increased.
321 	 * Params:
322 	 * index = the index
323 	 */
324 	public void prependIndex(int index)
325 	{
326 		// void gtk_tree_path_prepend_index (GtkTreePath *path,  gint index_);
327 		gtk_tree_path_prepend_index(gtkTreePath, index);
328 	}
329 	
330 	/**
331 	 * Returns the current depth of path.
332 	 * Returns: The depth of path
333 	 */
334 	public int getDepth()
335 	{
336 		// gint gtk_tree_path_get_depth (GtkTreePath *path);
337 		return gtk_tree_path_get_depth(gtkTreePath);
338 	}
339 	
340 	/**
341 	 * Returns the current indices of path.
342 	 * This is an array of integers, each representing a node in a tree.
343 	 * This value should not be freed.
344 	 * The length of the array can be obtained with gtk_tree_path_get_depth().
345 	 * Returns: The current indices, or NULL
346 	 */
347 	public int[] getIndices()
348 	{
349 		// gint * gtk_tree_path_get_indices (GtkTreePath *path);
350 		auto p = gtk_tree_path_get_indices(gtkTreePath);
351 		
352 		if(p is null)
353 		{
354 			return null;
355 		}
356 		
357 		return p[0 .. getDepth()];
358 	}
359 	
360 	/**
361 	 * Returns the current indices of path.
362 	 * This is an array of integers, each representing a node in a tree.
363 	 * It also returns the number of elements in the array.
364 	 * The array should not be freed.
365 	 * Returns: The current indices, or NULL. [array length=depth][transfer none] Since 3.0
366 	 */
367 	public int[] getIndicesWithDepth()
368 	{
369 		// gint * gtk_tree_path_get_indices_with_depth  (GtkTreePath *path,  gint *depth);
370 		int depth;
371 		auto p = gtk_tree_path_get_indices_with_depth(gtkTreePath, &depth);
372 		
373 		if(p is null)
374 		{
375 			return null;
376 		}
377 		
378 		return p[0 .. depth];
379 	}
380 	
381 	/**
382 	 * Frees path. If path is NULL, it simply returns.
383 	 */
384 	public void free()
385 	{
386 		// void gtk_tree_path_free (GtkTreePath *path);
387 		gtk_tree_path_free(gtkTreePath);
388 	}
389 	
390 	/**
391 	 * Creates a new GtkTreePath as a copy of path.
392 	 * Returns: a new GtkTreePath
393 	 */
394 	public TreePath copy()
395 	{
396 		// GtkTreePath * gtk_tree_path_copy (const GtkTreePath *path);
397 		auto p = gtk_tree_path_copy(gtkTreePath);
398 		
399 		if(p is null)
400 		{
401 			return null;
402 		}
403 		
404 		return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p);
405 	}
406 	
407 	/**
408 	 * Compares two paths.
409 	 * If a appears before b in a tree, then -1 is returned.
410 	 * If b appears before a, then 1 is returned.
411 	 * If the two nodes are equal, then 0 is returned.
412 	 * Params:
413 	 * a = a GtkTreePath
414 	 * b = a GtkTreePath to compare with
415 	 * Returns: the relative positions of a and b
416 	 */
417 	public int compare(TreePath b)
418 	{
419 		// gint gtk_tree_path_compare (const GtkTreePath *a,  const GtkTreePath *b);
420 		return gtk_tree_path_compare(gtkTreePath, (b is null) ? null : b.getTreePathStruct());
421 	}
422 	
423 	/**
424 	 * Moves the path to point to the next node at the current depth.
425 	 */
426 	public void next()
427 	{
428 		// void gtk_tree_path_next (GtkTreePath *path);
429 		gtk_tree_path_next(gtkTreePath);
430 	}
431 	
432 	/**
433 	 * Moves the path to point to the previous node at the
434 	 * current depth, if it exists.
435 	 * Returns: TRUE if path has a previous node, and the move was made
436 	 */
437 	public int prev()
438 	{
439 		// gboolean gtk_tree_path_prev (GtkTreePath *path);
440 		return gtk_tree_path_prev(gtkTreePath);
441 	}
442 	
443 	/**
444 	 * Moves the path to point to its parent node, if it has a parent.
445 	 * Returns: TRUE if path has a parent, and the move was made
446 	 */
447 	public int up()
448 	{
449 		// gboolean gtk_tree_path_up (GtkTreePath *path);
450 		return gtk_tree_path_up(gtkTreePath);
451 	}
452 	
453 	/**
454 	 * Moves path to point to the first child of the current path.
455 	 */
456 	public void down()
457 	{
458 		// void gtk_tree_path_down (GtkTreePath *path);
459 		gtk_tree_path_down(gtkTreePath);
460 	}
461 	
462 	/**
463 	 * Returns TRUE if descendant is a descendant of path.
464 	 * Params:
465 	 * descendant = another GtkTreePath
466 	 * Returns: TRUE if descendant is contained inside path
467 	 */
468 	public int isAncestor(TreePath descendant)
469 	{
470 		// gboolean gtk_tree_path_is_ancestor (GtkTreePath *path,  GtkTreePath *descendant);
471 		return gtk_tree_path_is_ancestor(gtkTreePath, (descendant is null) ? null : descendant.getTreePathStruct());
472 	}
473 	
474 	/**
475 	 * Returns TRUE if path is a descendant of ancestor.
476 	 * Params:
477 	 * ancestor = another GtkTreePath
478 	 * Returns: TRUE if ancestor contains path somewhere below it
479 	 */
480 	public int isDescendant(TreePath ancestor)
481 	{
482 		// gboolean gtk_tree_path_is_descendant (GtkTreePath *path,  GtkTreePath *ancestor);
483 		return gtk_tree_path_is_descendant(gtkTreePath, (ancestor is null) ? null : ancestor.getTreePathStruct());
484 	}
485 }