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