Glib::NodeTree< T > Class Template Reference

N-ary Trees - trees of data with any number of branches The NodeTree class and its associated functions provide an N-ary tree data structure, in which nodes in the tree can contain arbitrary data. More...

`#include <glibmm/nodetree.h>`

## Public Types

using | TraverseFunc = sigc::slot< bool, NodeTree< T >& >
using | ForeachFunc = sigc::slot< void, NodeTree< T >& >

## Public Member Functions

| NodeTree ()
| NodeTree (const T& the_data)
| NodeTree (const NodeTree< T >& node)
| ~NodeTree ()
| Removes the instance and its children from the tree, freeing any memory allocated. More...
NodeTree< T >& | operator= (const NodeTree< T >& node)
GNode* | gobj ()
| Provides access to the underlying C GObject. More...
const GNode* | gobj () const
| Provides access to the underlying C GObject. More...
NodeTree< T >& | insert (int position, NodeTree< T >& node)
| Inserts a NodeTree beneath the parent at the given position. More...
NodeTree< T >& | insert_before (NodeTree< T >& sibling, NodeTree< T >& node)
| Inserts a NodeTree beneath the parent before the given sibling. More...
NodeTree< T >& | insert_after (NodeTree< T >& sibling, NodeTree< T >& node)
| Inserts a NodeTree beneath the parent after the given sibling. More...
NodeTree< T >& | append (NodeTree< T >& node)
| Inserts a NodeTree as the last child. More...
NodeTree< T >& | prepend (NodeTree< T >& node)
| Inserts a NodeTree as the first child. More...
NodeTree< T >* | insert_data (int position, const T& the_data)
| Inserts a new NodeTree at the given position. More...
NodeTree< T >* | insert_data_before (NodeTree< T >& sibling, const T& the_data)
| Inserts a new NodeTree before the given sibling. More...
NodeTree< T >* | append_data (const T& the_data)
| Inserts a new NodeTree as the last child. More...
NodeTree< T >* | prepend_data (const T& the_data)
| Inserts a new NodeTree as the first child. More...
void | reverse_children ()
| Reverses the order of the children. More...
NodeTree< T >* | get_root ()
| Returns a pointer to the root of the tree. More...
const NodeTree< T >* | get_root () const
void | traverse (const TraverseFunc& func, TraverseType order=TRAVERSE_IN_ORDER, TraverseFlags flags=TRAVERSE_ALL, int max_depth=-1)
| Traverses a tree starting at the current node. More...
void | foreach (const ForeachFunc& func, TraverseFlags flags=TRAVERSE_ALL)
| Calls a function for each of the children of a NodeTree. More...
NodeTree< T >* | find_child (const T& the_data, TraverseFlags flags=TRAVERSE_ALL)
| Finds the first child of a NodeTree with the given data. More...
const NodeTree< T >* | find_child (const T& the_data, TraverseFlags flags=TRAVERSE_ALL) const
| Finds the first child of a NodeTree with the given data. More...
NodeTree< T >* | find (const T& the_data, TraverseType order=TRAVERSE_IN_ORDER, TraverseFlags flags=TRAVERSE_ALL)
| Finds a node in a tree. More...
const NodeTree< T >* | find (const T& the_data, TraverseType order=TRAVERSE_IN_ORDER, TraverseFlags flags=TRAVERSE_ALL) const
| Finds a node in a tree. More...
int | child_index (const T& the_data) const
| Gets the position of the first child which contains the given data. More...
int | child_position (const NodeTree< T >& child) const
| Gets the position with respect to its siblings. More...
NodeTree< T >* | first_child ()
| Gets the first child. More...
const NodeTree< T >* | first_child () const
| Gets the first child. More...
NodeTree< T >* | last_child ()
| Gets the last child. More...
const NodeTree< T >* | last_child () const
| Gets the last child. More...
NodeTree< T >* | nth_child (int n)
| Gets the nth child. More...
const NodeTree< T >* | nth_child (int n) const
| Gets the nth child. More...
NodeTree< T >* | first_sibling ()
| Gets the first sibling. More...
const NodeTree< T >* | first_sibling () const
| Gets the first sibling. More...
NodeTree< T >* | prev_sibling ()
| Gets the previous sibling. More...
const NodeTree< T >* | prev_sibling () const
| Gets the previous sibling. More...
NodeTree< T >* | next_sibling ()
| Gets the next sibling. More...
const NodeTree< T >* | next_sibling () const
| Gets the next sibling. More...
NodeTree< T >* | last_sibling ()
| Gets the last sibling. More...
const NodeTree< T >* | last_sibling () const
| Gets the last sibling. More...
bool | is_leaf () const
| Returns true if this is a leaf node. More...
bool | is_root () const
| Returns true if this is the root node. More...
guint | depth () const
| Gets the depth of this node. More...
guint | node_count (TraverseFlags flags=TRAVERSE_ALL) const
| Gets the number of nodes in a tree. More...
guint | child_count () const
| Gets the number children. More...
bool | is_ancestor (const NodeTree< T >& descendant) const
| Returns true if this is an ancestor of descendant. More...
guint | get_max_height () const
| Gets the maximum height of all branches beneath this node. More...
void | unlink ()
| Unlinks a node from a tree, resulting in two separate trees. More...
T& | data ()
| Accessor for this node's data. More...
const T& | data () const
| Accessor for this node's data. More...
const NodeTree< T >* | parent () const
| Accessor for this node's parent. More...

## Detailed Description

### template<typename T>
class Glib::NodeTree< T >

N-ary Trees - trees of data with any number of branches The NodeTree class and its associated functions provide an N-ary tree data structure, in which nodes in the tree can contain arbitrary data.

To insert a node into a tree use insert(), insert_before(), append() or prepend().

To create a new node and insert it into a tree use insert_data(), insert_data_before(), append_data() and prepend_data().

To reverse the children of a node use reverse_children().

To find a node use root(), find(), find_child(), index_of(), child_index(), first_child(), last_child(), nth_child(), first_sibling(), prev_sibling(), next_sibling() or last_sibling().

To get information about a node or tree use is_leaf(), is_root(), depth(), node_count(), child_count(), is_ancestor() or max_height().

To traverse a tree, calling a function for each node visited in the traversal, use traverse() or foreach().

To remove a node or subtree from a tree use unlink().

Since glibmm 2.18:

## Member Typedef Documentation

template <typename T >

using Glib::NodeTree< T >::ForeachFunc = sigc::slot<void, NodeTree<T>&>

template <typename T >

using Glib::NodeTree< T >::TraverseFunc = sigc::slot<bool, NodeTree<T>&>

## Constructor & Destructor Documentation

template <typename T >

Glib::NodeTree< T >::NodeTree | ( |  | ) |

inline

template <typename T >

Glib::NodeTree< T >::NodeTree | ( | const T & | the_data | ) |

inline explicit

template <typename T >

Glib::NodeTree< T >::NodeTree | ( | const NodeTree< T >& | node | ) |

inline

template <typename T >

Glib::NodeTree< T >::~NodeTree | ( |  | ) |

inline

Removes the instance and its children from the tree, freeing any memory allocated.

## Member Function Documentation

template <typename T >

NodeTree<T>& Glib::NodeTree< T >::append | ( | NodeTree< T >& | node | ) |

inline

Inserts a NodeTree as the last child.

Parameters

  node | the NodeTree to append

Returns
  the new NodeTree

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::append_data | ( | const T & | the_data | ) |

inline

Inserts a new NodeTree as the last child.

Parameters

  the_data | the data for the new NodeTree

Returns
  the new NodeTree

template <typename T >

guint Glib::NodeTree< T >::child_count | ( |  | ) | const

inline

Gets the number children.

Returns
  The number of children.

template <typename T >

int Glib::NodeTree< T >::child_index | ( | const T & | the_data | ) | const

inline

Gets the position of the first child which contains the given data.

Parameters

  the_data | The data to find.

Returns
  The index of the child which contains data, or -1 if the data is not found.

template <typename T >

int Glib::NodeTree< T >::child_position | ( | const NodeTree< T >& | child | ) | const

inline

Gets the position with respect to its siblings.

child must be a child of node. The first child is numbered 0, the second 1, and so on.

Parameters

  child | A child

Returns
  The position of child with respect to its siblings.

template <typename T >

T& Glib::NodeTree< T >::data | ( |  | ) |

inline

Accessor for this node's data.

template <typename T >

const T& Glib::NodeTree< T >::data | ( |  | ) | const

inline

Accessor for this node's data.

template <typename T >

guint Glib::NodeTree< T >::depth | ( |  | ) | const

inline

Gets the depth of this node.

The root node has a depth of 1. For the children of the root node the depth is 2. And so on.

Returns
  the depth of this node

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::find | ( | const T & | the_data,
|  | TraverseType | order = `TRAVERSE_IN_ORDER`,
|  | TraverseFlags | flags = `TRAVERSE_ALL`
| ) |  |

inline

Finds a node in a tree.

Parameters

  order | The order in which nodes are visited: IN_ORDER, TRAVERSE_PRE_ORDER, TRAVERSE_POST_ORDER, or TRAVERSE_LEVEL_ORDER
  flags | Which types of children are to be visited: one of TRAVERSE_ALL, TRAVERSE_LEAVES and TRAVERSE_NON_LEAVES.
  the_data | The data for which to search.

Returns
  The found node, or `nullptr` if the data is not found.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::find | ( | const T & | the_data,
|  | TraverseType | order = `TRAVERSE_IN_ORDER`,
|  | TraverseFlags | flags = `TRAVERSE_ALL`
| ) |  | const

inline

Finds a node in a tree.

Parameters

  order | The order in which nodes are visited.
  flags | Which types of children are to be visited.
  the_data | The data for which to search.

Returns
  The found node, or `nullptr` if the data is not found.

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::find_child | ( | const T & | the_data,
|  | TraverseFlags | flags = `TRAVERSE_ALL`
| ) |  |

inline

Finds the first child of a NodeTree with the given data.

Parameters

  flags | Which types of children are to be visited, one of TRAVERSE_ALL, TRAVERSE_LEAVES and TRAVERSE_NON_LEAVES.
  the_data | The data for which to search.

Returns
  the found child, or `nullptr` if the data is not found

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::find_child | ( | const T & | the_data,
|  | TraverseFlags | flags = `TRAVERSE_ALL`
| ) |  | const

inline

Finds the first child of a NodeTree with the given data.

Parameters

  flags | Which types of children are to be visited, one of TRAVERSE_ALL, TRAVERSE_LEAVES and TRAVERSE_NON_LEAVES.
  the_data | The data for which to search.

Returns
  the found child, or `nullptr` if the data is not found

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::first_child | ( |  | ) |

inline

Gets the first child.

Returns
  The first child, or `nullptr` if the node has no children.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::first_child | ( |  | ) | const

inline

Gets the first child.

Returns
  The first child, or `nullptr` if the node has no children.

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::first_sibling | ( |  | ) |

inline

Gets the first sibling.

Returns
  The first sibling, or `nullptr` if the node has no siblings.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::first_sibling | ( |  | ) | const

inline

Gets the first sibling.

Returns
  The first sibling, or `nullptr` if the node has no siblings.

template <typename T >

void Glib::NodeTree< T >::foreach | ( | const ForeachFunc& | func,
|  | TraverseFlags | flags = `TRAVERSE_ALL`
| ) |  |

inline

Calls a function for each of the children of a NodeTree.

Note that it doesn't descend beneath the child nodes.

Parameters

  flags | Wwhich types of children are to be visited.
  func | The slot to invoke for each visited node.

template <typename T >

guint Glib::NodeTree< T >::get_max_height | ( |  | ) | const

inline

Gets the maximum height of all branches beneath this node.

This is the maximum distance from the node to all leaf nodes. If root has no children, 1 is returned. If root has children, 2 is returned. And so on.

Returns
  The maximum height of all branches.

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::get_root | ( |  | ) |

inline

Returns a pointer to the root of the tree.

Returns
  A pointer to the root of the tree.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::get_root | ( |  | ) | const

inline

template <typename T >

GNode* Glib::NodeTree< T >::gobj | ( |  | ) |

inline

Provides access to the underlying C GObject.

template <typename T >

const GNode* Glib::NodeTree< T >::gobj | ( |  | ) | const

inline

Provides access to the underlying C GObject.

template <typename T >

NodeTree<T>& Glib::NodeTree< T >::insert | ( | int | position,
|  | NodeTree< T >& | node
| ) |  |

inline

Inserts a NodeTree beneath the parent at the given position.

Parameters

  position | the position to place node at, with respect to its siblings If position is -1, node is inserted as the last child of parent
  node | the NodeTree to insert

Returns
  the inserted NodeTree

template <typename T >

NodeTree<T>& Glib::NodeTree< T >::insert_after | ( | NodeTree< T >& | sibling,
|  | NodeTree< T >& | node
| ) |  |

inline

Inserts a NodeTree beneath the parent after the given sibling.

Parameters

  sibling | the sibling NodeTree to place node after.
  node | the NodeTree to insert

Returns
  the inserted NodeTree

template <typename T >

NodeTree<T>& Glib::NodeTree< T >::insert_before | ( | NodeTree< T >& | sibling,
|  | NodeTree< T >& | node
| ) |  |

inline

Inserts a NodeTree beneath the parent before the given sibling.

Parameters

  sibling | the sibling NodeTree to place node before.
  node | the NodeTree to insert

Returns
  the inserted NodeTree

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::insert_data | ( | int | position,
|  | const T & | the_data
| ) |  |

inline

Inserts a new NodeTree at the given position.

Parameters

  position | the position to place the new NodeTree at. If position is -1, the new NodeTree is inserted as the last child of parent
  the_data | the data for the new NodeTree

Returns
  the new NodeTree

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::insert_data_before | ( | NodeTree< T >& | sibling,
|  | const T & | the_data
| ) |  |

inline

Inserts a new NodeTree before the given sibling.

Parameters

  sibling | the sibling NodeTree to place node before.
  the_data | the data for the new NodeTree

Returns
  the new NodeTree

template <typename T >

bool Glib::NodeTree< T >::is_ancestor | ( | const NodeTree< T >& | descendant | ) | const

inline

Returns true if this is an ancestor of descendant.

This is true if this is the parent of descendant, or if this is the grandparent of descendant etc.

Parameters

  descendant | A node.

Returns
  true if this is an ancestor of descendant.

template <typename T >

bool Glib::NodeTree< T >::is_leaf | ( |  | ) | const

inline

Returns true if this is a leaf node.

Returns
  true if this is a leaf node.

template <typename T >

bool Glib::NodeTree< T >::is_root | ( |  | ) | const

inline

Returns true if this is the root node.

Returns
  true if this is the root node.

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::last_child | ( |  | ) |

inline

Gets the last child.

Returns
  The last child, or `nullptr` if the node has no children.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::last_child | ( |  | ) | const

inline

Gets the last child.

Returns
  The last child, or `nullptr` if the node has no children.

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::last_sibling | ( |  | ) |

inline

Gets the last sibling.

Returns
  The last sibling, or `nullptr` if the node has no siblings.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::last_sibling | ( |  | ) | const

inline

Gets the last sibling.

Returns
  The last sibling, or `nullptr` if the node has no siblings.

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::next_sibling | ( |  | ) |

inline

Gets the next sibling.

Returns
  The next sibling, or `nullptr` if the node has no siblings.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::next_sibling | ( |  | ) | const

inline

Gets the next sibling.

Returns
  The next sibling, or `nullptr` if the node has no siblings.

template <typename T >

guint Glib::NodeTree< T >::node_count | ( | TraverseFlags | flags = `TRAVERSE_ALL` | ) | const

inline

Gets the number of nodes in a tree.

Parameters

  flags | Which types of children are to be counted: one of TRAVERSE_ALL, TRAVERSE_LEAVES and TRAVERSE_NON_LEAVES

Returns
  The number of nodes in the tree.

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::nth_child | ( | int | n | ) |

inline

Gets the nth child.

Returns
  The nth child, or `nullptr` if n is too large.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::nth_child | ( | int | n | ) | const

inline

Gets the nth child.

Returns
  The nth child, or `nullptr` if n is too large.

template <typename T >

NodeTree<T>& Glib::NodeTree< T >::operator= | ( | const NodeTree< T >& | node | ) |

inline

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::parent | ( |  | ) | const

inline

Accessor for this node's parent.

Returns
  The node's parent.

template <typename T >

NodeTree<T>& Glib::NodeTree< T >::prepend | ( | NodeTree< T >& | node | ) |

inline

Inserts a NodeTree as the first child.

Parameters

  node | the NodeTree to prepend

Returns
  the NodeTree

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::prepend_data | ( | const T & | the_data | ) |

inline

Inserts a new NodeTree as the first child.

Parameters

  the_data | the data for the new NodeTree

Returns
  the new NodeTree

template <typename T >

NodeTree<T>* Glib::NodeTree< T >::prev_sibling | ( |  | ) |

inline

Gets the previous sibling.

Returns
  The previous sibling, or `nullptr` if the node has no siblings.

template <typename T >

const NodeTree<T>* Glib::NodeTree< T >::prev_sibling | ( |  | ) | const

inline

Gets the previous sibling.

Returns
  The previous sibling, or `nullptr` if the node has no siblings.

template <typename T >

void Glib::NodeTree< T >::reverse_children | ( |  | ) |

inline

Reverses the order of the children.

template <typename T >

void Glib::NodeTree< T >::traverse | ( | const TraverseFunc& | func,
|  | TraverseType | order = `TRAVERSE_IN_ORDER`,
|  | TraverseFlags | flags = `TRAVERSE_ALL`,
|  | int | max_depth = `-1`
| ) |  |

inline

Traverses a tree starting at the current node.

It calls the given function for each node visited. The traversal can be halted at any point by returning true from func.

Parameters

  order | The order in which nodes are visited.
  flags | Which types of children are to be visited.
  max_depth | The maximum depth of the traversal. Nodes below this depth will not be visited. If max_depth is -1 all nodes in the tree are visited. If max_depth is 1, only the root is visited. If max_depth is 2, the root and its children are visited. And so on.
  func | the slot to invoke for each visited child

template <typename T >

void Glib::NodeTree< T >::unlink | ( |  | ) |

inline

Unlinks a node from a tree, resulting in two separate trees.