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 glib.Node;
26 
27 private import glib.ConstructionException;
28 private import glib.c.functions;
29 public  import glib.c.types;
30 public  import gtkc.glibtypes;
31 private import gtkd.Loader;
32 
33 
34 /**
35  * The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees].
36  */
37 public final class Node
38 {
39 	/** the main Gtk struct */
40 	protected GNode* gNode;
41 	protected bool ownedRef;
42 
43 	/** Get the main Gtk struct */
44 	public GNode* getNodeStruct(bool transferOwnership = false)
45 	{
46 		if (transferOwnership)
47 			ownedRef = false;
48 		return gNode;
49 	}
50 
51 	/** the main Gtk struct as a void* */
52 	protected void* getStruct()
53 	{
54 		return cast(void*)gNode;
55 	}
56 
57 	/**
58 	 * Sets our main struct and passes it to the parent class.
59 	 */
60 	public this (GNode* gNode, bool ownedRef = false)
61 	{
62 		this.gNode = gNode;
63 		this.ownedRef = ownedRef;
64 	}
65 
66 	~this ()
67 	{
68 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
69 			g_free(gNode);
70 	}
71 
72 
73 	/**
74 	 * contains the actual data of the node.
75 	 */
76 	public @property void* data()
77 	{
78 		return gNode.data;
79 	}
80 
81 	/** Ditto */
82 	public @property void data(void* value)
83 	{
84 		gNode.data = value;
85 	}
86 
87 	/**
88 	 * points to the node's next sibling (a sibling is another
89 	 * #GNode with the same parent).
90 	 */
91 	public @property Node next()
92 	{
93 		return new Node(gNode.next, false);
94 	}
95 
96 	/** Ditto */
97 	public @property void next(Node value)
98 	{
99 		gNode.next = value.getNodeStruct();
100 	}
101 
102 	/**
103 	 * points to the node's previous sibling.
104 	 */
105 	public @property Node prev()
106 	{
107 		return new Node(gNode.prev, false);
108 	}
109 
110 	/** Ditto */
111 	public @property void prev(Node value)
112 	{
113 		gNode.prev = value.getNodeStruct();
114 	}
115 
116 	/**
117 	 * points to the parent of the #GNode, or is %NULL if the
118 	 * #GNode is the root of the tree.
119 	 */
120 	public @property Node parent()
121 	{
122 		return new Node(gNode.parent, false);
123 	}
124 
125 	/** Ditto */
126 	public @property void parent(Node value)
127 	{
128 		gNode.parent = value.getNodeStruct();
129 	}
130 
131 	/**
132 	 * points to the first child of the #GNode.  The other
133 	 * children are accessed by using the @next pointer of each
134 	 * child.
135 	 */
136 	public @property Node children()
137 	{
138 		return new Node(gNode.children, false);
139 	}
140 
141 	/** Ditto */
142 	public @property void children(Node value)
143 	{
144 		gNode.children = value.getNodeStruct();
145 	}
146 
147 	/**
148 	 * Gets the position of the first child of a #GNode
149 	 * which contains the given data.
150 	 *
151 	 * Params:
152 	 *     data = the data to find
153 	 *
154 	 * Returns: the index of the child of @node which contains
155 	 *     @data, or -1 if the data is not found
156 	 */
157 	public int childIndex(void* data)
158 	{
159 		return g_node_child_index(gNode, data);
160 	}
161 
162 	/**
163 	 * Gets the position of a #GNode with respect to its siblings.
164 	 * @child must be a child of @node. The first child is numbered 0,
165 	 * the second 1, and so on.
166 	 *
167 	 * Params:
168 	 *     child = a child of @node
169 	 *
170 	 * Returns: the position of @child with respect to its siblings
171 	 */
172 	public int childPosition(Node child)
173 	{
174 		return g_node_child_position(gNode, (child is null) ? null : child.getNodeStruct());
175 	}
176 
177 	/**
178 	 * Calls a function for each of the children of a #GNode. Note that it
179 	 * doesn't descend beneath the child nodes. @func must not do anything
180 	 * that would modify the structure of the tree.
181 	 *
182 	 * Params:
183 	 *     flags = which types of children are to be visited, one of
184 	 *         %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
185 	 *     func = the function to call for each visited node
186 	 *     data = user data to pass to the function
187 	 */
188 	public void childrenForeach(GTraverseFlags flags, GNodeForeachFunc func, void* data)
189 	{
190 		g_node_children_foreach(gNode, flags, func, data);
191 	}
192 
193 	/**
194 	 * Recursively copies a #GNode (but does not deep-copy the data inside the
195 	 * nodes, see g_node_copy_deep() if you need that).
196 	 *
197 	 * Returns: a new #GNode containing the same data pointers
198 	 */
199 	public Node copy()
200 	{
201 		auto p = g_node_copy(gNode);
202 
203 		if(p is null)
204 		{
205 			return null;
206 		}
207 
208 		return new Node(cast(GNode*) p);
209 	}
210 
211 	/**
212 	 * Recursively copies a #GNode and its data.
213 	 *
214 	 * Params:
215 	 *     copyFunc = the function which is called to copy the data inside each node,
216 	 *         or %NULL to use the original data.
217 	 *     data = data to pass to @copy_func
218 	 *
219 	 * Returns: a new #GNode containing copies of the data in @node.
220 	 *
221 	 * Since: 2.4
222 	 */
223 	public Node copyDeep(GCopyFunc copyFunc, void* data)
224 	{
225 		auto p = g_node_copy_deep(gNode, copyFunc, data);
226 
227 		if(p is null)
228 		{
229 			return null;
230 		}
231 
232 		return new Node(cast(GNode*) p);
233 	}
234 
235 	/**
236 	 * Gets the depth of a #GNode.
237 	 *
238 	 * If @node is %NULL the depth is 0. The root node has a depth of 1.
239 	 * For the children of the root node the depth is 2. And so on.
240 	 *
241 	 * Returns: the depth of the #GNode
242 	 */
243 	public uint depth()
244 	{
245 		return g_node_depth(gNode);
246 	}
247 
248 	/**
249 	 * Removes @root and its children from the tree, freeing any memory
250 	 * allocated.
251 	 */
252 	public void destroy()
253 	{
254 		g_node_destroy(gNode);
255 	}
256 
257 	/**
258 	 * Finds a #GNode in a tree.
259 	 *
260 	 * Params:
261 	 *     order = the order in which nodes are visited - %G_IN_ORDER,
262 	 *         %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER
263 	 *     flags = which types of children are to be searched, one of
264 	 *         %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
265 	 *     data = the data to find
266 	 *
267 	 * Returns: the found #GNode, or %NULL if the data is not found
268 	 */
269 	public Node find(GTraverseType order, GTraverseFlags flags, void* data)
270 	{
271 		auto p = g_node_find(gNode, order, flags, data);
272 
273 		if(p is null)
274 		{
275 			return null;
276 		}
277 
278 		return new Node(cast(GNode*) p);
279 	}
280 
281 	/**
282 	 * Finds the first child of a #GNode with the given data.
283 	 *
284 	 * Params:
285 	 *     flags = which types of children are to be searched, one of
286 	 *         %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
287 	 *     data = the data to find
288 	 *
289 	 * Returns: the found child #GNode, or %NULL if the data is not found
290 	 */
291 	public Node findChild(GTraverseFlags flags, void* data)
292 	{
293 		auto p = g_node_find_child(gNode, flags, data);
294 
295 		if(p is null)
296 		{
297 			return null;
298 		}
299 
300 		return new Node(cast(GNode*) p);
301 	}
302 
303 	/**
304 	 * Gets the first sibling of a #GNode.
305 	 * This could possibly be the node itself.
306 	 *
307 	 * Returns: the first sibling of @node
308 	 */
309 	public Node firstSibling()
310 	{
311 		auto p = g_node_first_sibling(gNode);
312 
313 		if(p is null)
314 		{
315 			return null;
316 		}
317 
318 		return new Node(cast(GNode*) p);
319 	}
320 
321 	/**
322 	 * Gets the root of a tree.
323 	 *
324 	 * Returns: the root of the tree
325 	 */
326 	public Node getRoot()
327 	{
328 		auto p = g_node_get_root(gNode);
329 
330 		if(p is null)
331 		{
332 			return null;
333 		}
334 
335 		return new Node(cast(GNode*) p);
336 	}
337 
338 	/**
339 	 * Inserts a #GNode beneath the parent at the given position.
340 	 *
341 	 * Params:
342 	 *     position = the position to place @node at, with respect to its siblings
343 	 *         If position is -1, @node is inserted as the last child of @parent
344 	 *     node = the #GNode to insert
345 	 *
346 	 * Returns: the inserted #GNode
347 	 */
348 	public Node insert(int position, Node node)
349 	{
350 		auto p = g_node_insert(gNode, position, (node is null) ? null : node.getNodeStruct());
351 
352 		if(p is null)
353 		{
354 			return null;
355 		}
356 
357 		return new Node(cast(GNode*) p);
358 	}
359 
360 	/**
361 	 * Inserts a #GNode beneath the parent after the given sibling.
362 	 *
363 	 * Params:
364 	 *     sibling = the sibling #GNode to place @node after.
365 	 *         If sibling is %NULL, the node is inserted as the first child of @parent.
366 	 *     node = the #GNode to insert
367 	 *
368 	 * Returns: the inserted #GNode
369 	 */
370 	public Node insertAfter(Node sibling, Node node)
371 	{
372 		auto p = g_node_insert_after(gNode, (sibling is null) ? null : sibling.getNodeStruct(), (node is null) ? null : node.getNodeStruct());
373 
374 		if(p is null)
375 		{
376 			return null;
377 		}
378 
379 		return new Node(cast(GNode*) p);
380 	}
381 
382 	/**
383 	 * Inserts a #GNode beneath the parent before the given sibling.
384 	 *
385 	 * Params:
386 	 *     sibling = the sibling #GNode to place @node before.
387 	 *         If sibling is %NULL, the node is inserted as the last child of @parent.
388 	 *     node = the #GNode to insert
389 	 *
390 	 * Returns: the inserted #GNode
391 	 */
392 	public Node insertBefore(Node sibling, Node node)
393 	{
394 		auto p = g_node_insert_before(gNode, (sibling is null) ? null : sibling.getNodeStruct(), (node is null) ? null : node.getNodeStruct());
395 
396 		if(p is null)
397 		{
398 			return null;
399 		}
400 
401 		return new Node(cast(GNode*) p);
402 	}
403 
404 	/**
405 	 * Returns %TRUE if @node is an ancestor of @descendant.
406 	 * This is true if node is the parent of @descendant,
407 	 * or if node is the grandparent of @descendant etc.
408 	 *
409 	 * Params:
410 	 *     descendant = a #GNode
411 	 *
412 	 * Returns: %TRUE if @node is an ancestor of @descendant
413 	 */
414 	public bool isAncestor(Node descendant)
415 	{
416 		return g_node_is_ancestor(gNode, (descendant is null) ? null : descendant.getNodeStruct()) != 0;
417 	}
418 
419 	/**
420 	 * Gets the last child of a #GNode.
421 	 *
422 	 * Returns: the last child of @node, or %NULL if @node has no children
423 	 */
424 	public Node lastChild()
425 	{
426 		auto p = g_node_last_child(gNode);
427 
428 		if(p is null)
429 		{
430 			return null;
431 		}
432 
433 		return new Node(cast(GNode*) p);
434 	}
435 
436 	/**
437 	 * Gets the last sibling of a #GNode.
438 	 * This could possibly be the node itself.
439 	 *
440 	 * Returns: the last sibling of @node
441 	 */
442 	public Node lastSibling()
443 	{
444 		auto p = g_node_last_sibling(gNode);
445 
446 		if(p is null)
447 		{
448 			return null;
449 		}
450 
451 		return new Node(cast(GNode*) p);
452 	}
453 
454 	/**
455 	 * Gets the maximum height of all branches beneath a #GNode.
456 	 * This is the maximum distance from the #GNode to all leaf nodes.
457 	 *
458 	 * If @root is %NULL, 0 is returned. If @root has no children,
459 	 * 1 is returned. If @root has children, 2 is returned. And so on.
460 	 *
461 	 * Returns: the maximum height of the tree beneath @root
462 	 */
463 	public uint maxHeight()
464 	{
465 		return g_node_max_height(gNode);
466 	}
467 
468 	/**
469 	 * Gets the number of children of a #GNode.
470 	 *
471 	 * Returns: the number of children of @node
472 	 */
473 	public uint nChildren()
474 	{
475 		return g_node_n_children(gNode);
476 	}
477 
478 	/**
479 	 * Gets the number of nodes in a tree.
480 	 *
481 	 * Params:
482 	 *     flags = which types of children are to be counted, one of
483 	 *         %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
484 	 *
485 	 * Returns: the number of nodes in the tree
486 	 */
487 	public uint nNodes(GTraverseFlags flags)
488 	{
489 		return g_node_n_nodes(gNode, flags);
490 	}
491 
492 	/**
493 	 * Gets a child of a #GNode, using the given index.
494 	 * The first child is at index 0. If the index is
495 	 * too big, %NULL is returned.
496 	 *
497 	 * Params:
498 	 *     n = the index of the desired child
499 	 *
500 	 * Returns: the child of @node at index @n
501 	 */
502 	public Node nthChild(uint n)
503 	{
504 		auto p = g_node_nth_child(gNode, n);
505 
506 		if(p is null)
507 		{
508 			return null;
509 		}
510 
511 		return new Node(cast(GNode*) p);
512 	}
513 
514 	/**
515 	 * Inserts a #GNode as the first child of the given parent.
516 	 *
517 	 * Params:
518 	 *     node = the #GNode to insert
519 	 *
520 	 * Returns: the inserted #GNode
521 	 */
522 	public Node prepend(Node node)
523 	{
524 		auto p = g_node_prepend(gNode, (node is null) ? null : node.getNodeStruct());
525 
526 		if(p is null)
527 		{
528 			return null;
529 		}
530 
531 		return new Node(cast(GNode*) p);
532 	}
533 
534 	/**
535 	 * Reverses the order of the children of a #GNode.
536 	 * (It doesn't change the order of the grandchildren.)
537 	 */
538 	public void reverseChildren()
539 	{
540 		g_node_reverse_children(gNode);
541 	}
542 
543 	/**
544 	 * Traverses a tree starting at the given root #GNode.
545 	 * It calls the given function for each node visited.
546 	 * The traversal can be halted at any point by returning %TRUE from @func.
547 	 * @func must not do anything that would modify the structure of the tree.
548 	 *
549 	 * Params:
550 	 *     order = the order in which nodes are visited - %G_IN_ORDER,
551 	 *         %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER.
552 	 *     flags = which types of children are to be visited, one of
553 	 *         %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES
554 	 *     maxDepth = the maximum depth of the traversal. Nodes below this
555 	 *         depth will not be visited. If max_depth is -1 all nodes in
556 	 *         the tree are visited. If depth is 1, only the root is visited.
557 	 *         If depth is 2, the root and its children are visited. And so on.
558 	 *     func = the function to call for each visited #GNode
559 	 *     data = user data to pass to the function
560 	 */
561 	public void traverse(GTraverseType order, GTraverseFlags flags, int maxDepth, GNodeTraverseFunc func, void* data)
562 	{
563 		g_node_traverse(gNode, order, flags, maxDepth, func, data);
564 	}
565 
566 	/**
567 	 * Unlinks a #GNode from a tree, resulting in two separate trees.
568 	 */
569 	public void unlink()
570 	{
571 		g_node_unlink(gNode);
572 	}
573 
574 	/**
575 	 * Creates a new #GNode containing the given data.
576 	 * Used to create the first node in a tree.
577 	 *
578 	 * Params:
579 	 *     data = the data of the new node
580 	 *
581 	 * Returns: a new #GNode
582 	 *
583 	 * Throws: ConstructionException GTK+ fails to create the object.
584 	 */
585 	public this(void* data)
586 	{
587 		auto p = g_node_new(data);
588 
589 		if(p is null)
590 		{
591 			throw new ConstructionException("null returned by new");
592 		}
593 
594 		this(cast(GNode*) p);
595 	}
596 }