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