book.html

gtk_text program sample&eg

</table>
</p>

<p> There are two functions which give you an idea how large the tree     is, shown in Function Listing 2.14.
</p> 

<p>
<table bgcolor="#EEEEFF" width="100%"><caption><b>Function Listing 2.14:</b> Determining the size of a <tt>GTree</tt></caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre>gint
g_tree_nnodes(GTree* tree)</pre></font> </td></tr>
<tr><td> <font color="black"><pre>gint
g_tree_height(GTree* tree)</pre></font> </td></tr>
</table>
</p>

<p> Using <tt>g_tree_traverse()</tt> (Function Listing 2.15) you can walk the entire tree.  To use it, you provide a <tt>GTraverseFunc</tt>, which is passed each key-value pair and a <tt>data</tt> argument you give to <tt>g_tree_traverse()</tt>. Traversal continues as long as the <tt>GTraverseFunc</tt> returns <tt>FALSE</tt>; if it ever returns <tt>TRUE</tt> then traversal stops. You can use this to search the tree by value.  Here is the definition of <tt>GTraverseFunc</tt>:
</p> 

<pre>

typedef gint (*GTraverseFunc)(gpointer key, gpointer value, gpointer data);

</pre>

<p> <tt>GTraverseType</tt> is an enumeration; there are four possible values. Here are their meanings with respect to <tt>GTree</tt>.
</p> 

<ul>
<li> <tt>G_IN_ORDER</tt> first recurses the left child of the node (the "lower" key according to your <tt>GCompareFunc</tt>), then calls the traversal function on the key-value pair of the current node, then recurses the right child. This traversal is in order from lowest to       highest, according to your <tt>GCompareFunc</tt>.
<li> <tt>G_PRE_ORDER</tt> calls the traversal function on the key-value pair of the current node, then recurses the left child, then recurses the right child.
<li> <tt>G_POST_ORDER</tt> recurses the left child, then recurses the right child, and finally calls the traversal function on the current node's key-value pair.
<li> <tt>G_LEVEL_ORDER</tt> is only meaningful for <tt>GNode</tt>, it is not allowed with <tt>GTree</tt>.

</ul>


<p>
<table bgcolor="#EEEEFF" width="100%"><caption><b>Function Listing 2.15:</b> Traversing <tt>GTree</tt></caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre>void
g_tree_traverse(GTree* tree,
                GTraverseFunc traverse_func,
                GTraverseType traverse_type,
                gpointer data)</pre></font> </td></tr>
</table>
</p>

<h4>GNode</h4>

<p> A <tt>GNode</tt> is an N-way tree, implemented as a doubly linked list with parent and child lists. Thus, most list operations have analogues in the <tt>GNode</tt> API.  You can also walk the tree in various ways. Here's the declaration for a node:
</p> 

<pre>

typedef struct _GNode GNode;

struct _GNode
{
  gpointer data;
  GNode   *next;
  GNode   *prev;
  GNode   *parent;
  GNode   *children;
};

</pre>

<p> There are macros to access <tt>GNode</tt> members, shown in  Macro Listing 2.6.  As with <tt>GList</tt>, the <tt>data</tt> member is intended to be used directly. These macros return the <tt>next</tt>, <tt>prev</tt>, and <tt>children</tt> members respectively; they also check whether their argument is <tt>NULL</tt> before dereferencing it, and return <tt>NULL</tt> if it is.
</p> 

<p>
<table bgcolor="#FFEEEE" width="100%"><caption><b>Macro Listing 2.6:</b> Accessing <tt>GNode</tt> members</caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre><tt>g_node_prev_sibling(node)</tt></pre></font> </td></tr>
<tr><td> <font color="black"><pre><tt>g_node_next_sibling(node)</tt></pre></font> </td></tr>
<tr><td> <font color="black"><pre><tt>g_node_first_child(node)</tt></pre></font> </td></tr>
</table>
</p>

<p> To create a node, the usual <tt>_new()</tt> function is provided (Function Listing 2.16).  <tt>g_node_new()</tt> creates a childless and parentless node containing <tt>data</tt>. Typically <tt>g_node_new()</tt> is used only to create the root node; convenience macros are provided which automatically create new nodes as needed.
</p> 

<p>
<table bgcolor="#EEEEFF" width="100%"><caption><b>Function Listing 2.16:</b> Creating a <tt>GNode</tt></caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre>GNode*
g_node_new(gpointer data)</pre></font> </td></tr>
</table>
</p>

<p> To build a tree the fundamental operations shown in     Function Listing 2.17 are used.  Each operation returns the     just-added node, for convenience when writing loops or recursing     the tree. Unlike <tt>GList</tt>, it is safe to ignore the return     value.
</p> 

<p>
<table bgcolor="#EEEEFF" width="100%"><caption><b>Function Listing 2.17:</b> Building a <tt>GNode</tt> tree</caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre>GNode*
g_node_insert(GNode* parent,
              gint position,
              GNode* node)</pre></font> </td></tr>
<tr><td> <font color="black"><pre>GNode*
g_node_insert_before(GNode* parent,
                     GNode* sibling,
                     GNode* node)</pre></font> </td></tr>
<tr><td> <font color="black"><pre>GNode*
g_node_prepend(GNode* parent,
               GNode* node)</pre></font> </td></tr>
</table>
</p>

<p> The convenience macros shown in Macro Listing 2.7 are implemented in terms of the fundamental operations. <tt>g_node_append()</tt> is analagous to <tt>g_node_prepend()</tt>; the rest take a <tt>data</tt> argument, automatically allocate a node for it, and call the corresponding basic operation.
</p> 

<p>
<table bgcolor="#FFEEEE" width="100%"><caption><b>Macro Listing 2.7:</b> Building a <tt>GNode</tt></caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre><tt>g_node_append(parent, node)</tt></pre></font> </td></tr>
<tr><td> <font color="black"><pre><tt>g_node_insert_data(parent, position, data)</tt></pre></font> </td></tr>
<tr><td> <font color="black"><pre><tt>g_node_insert_data_before(parent, sibling, data)</tt></pre></font> </td></tr>
<tr><td> <font color="black"><pre><tt>g_node_prepend_data(parent, data)</tt></pre></font> </td></tr>
<tr><td> <font color="black"><pre><tt>g_node_append_data(parent, data)</tt></pre></font> </td></tr>
</table>
</p>

<p> To remove a node from the tree, there are two functions shown in  Function Listing 2.18. <tt>g_node_destroy()</tt> removes the node from a tree, destroying it and all its children. <tt>g_node_unlink()</tt> removes a node and makes it into a root node; i.e., it converts a subtree into an independent tree.
</p> 

<p>
<table bgcolor="#EEEEFF" width="100%"><caption><b>Function Listing 2.18:</b> Destroying a <tt>GNode</tt></caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre>void
g_node_destroy(GNode* root)</pre></font> </td></tr>
<tr><td> <font color="black"><pre>void
g_node_unlink(GNode* node)</pre></font> </td></tr>
</table>
</p>

<p> There are two macros for detecting the top and bottom of a <tt>GNode</tt> tree, shown in Macro Listing 2.8. A root node is defined as a node with no parent or siblings. A leaf node has no children.
</p> 

<p>
<table bgcolor="#FFEEEE" width="100%"><caption><b>Macro Listing 2.8:</b> Predicates for <tt>GNode</tt></caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre><tt>G_NODE_IS_ROOT(node)</tt></pre></font> </td></tr>
<tr><td> <font color="black"><pre><tt>G_NODE_IS_LEAF(node)</tt></pre></font> </td></tr>
</table>
</p>

<p> You can ask glib to report useful information about a     <tt>GNode</tt>, including the number of nodes it contains, its root     node, its depth, and the node containing a particular data     pointer. These functions are shown in     Function Listing 2.19.
</p> 
<p> <tt>GTraverseType</tt> was introduced earlier, with respect to <tt>GTree</tt>; here are the possible values for <tt>GNode</tt>:
</p> 

<ul>
<li> <tt>G_IN_ORDER</tt> first recurses the leftmost child of the node, then visits the node itself, then recurses the rest of the node's       children. This isn't very useful; mostly it is intended for use       with <tt>GTree</tt>.
<li> <tt>G_PRE_ORDER</tt> visits the current node, then recurses each       child in turn.
<li> <tt>G_POST_ORDER</tt> recurses each child in order, then visits the current node.
<li> <tt>G_LEVEL_ORDER</tt> first visits the node itself; then each of       the node's children; then the children of the children; then the       children of the children of the children; and so on. That is, it       visits each node of depth 0, then each node of depth 1, then       each node of depth 2, etc.

</ul>

<p> <tt>GNode</tt>'s tree-traversal functions have a <tt>GTraverseFlags</tt>   argument. This is a bitfield used to change the nature of the   traversal. Currently there are only three flags---you can visit only   leaf nodes, only non-leaf nodes, or all nodes:
</p> 

<ul>
<li> <tt>G_TRAVERSE_LEAFS</tt> means to traverse only leaf nodes.
<li> <tt>G_TRAVERSE_NON_LEAFS</tt> means to traverse only non-leaf nodes.
<li> <tt>G_TRAVERSE_ALL</tt> is simply a shortcut for       <tt>(G_TRAVERSE_LEAFS | G_TRAVERSE_NON_LEAFS)</tt>.

</ul>


<p>
<table bgcolor="#EEEEFF" width="100%"><caption><b>Function Listing 2.19:</b> <tt>GNode</tt> Properties</caption>
<tr align="right"><td> <font color="black">&nbsp;<tt>#include &lt;glib.h&gt;</tt> </font> </td></tr>
<tr><td> <font color="black"><pre>guint
g_node_n_nodes(GNode* root,
               GTraverseFlags flags)</pre></font> </td></tr>
<tr><td> <font color="black"><pre>GNode*
g_node_get_root(GNode* node)</pre></font> </td></tr>
<tr><td> <font color="black"><pre>gboolean
g_node_is_ancestor(GNode* node,
                   GNode* descendant)</pre></font> </td></tr>
<tr><td> <font color="black"><pre>guint
g_node_depth(GNode* node)</pre></font> </td></tr>
<tr><td> <font color="black"><pre>GNode*
g_node_find(GNode* root,
            GTraverseType order,
            GTraverseFlags flags,
            gpointer data)</pre></font> </td></tr>
</table>
</p>

<p> The remaining <tt>GNode</tt> functions are straightforward; most of them   are simply operations on the node's list of   children. Function Listing 2.20 lists them. There are two   function typedefs unique to <tt>GNode</tt>:
</p> 

<pre>

typedef gboolean (*GNodeTraverseFunc) (GNode* node, gpointer data);
typedef void (*GNodeForeachFunc