z29.html

GTK+_ Gnome Application Development

                class="PARAMETER"><i>key</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF">gpointer <tt class= 
                "FUNCTION">g_tree_lookup</tt></code>(GTree* <tt
                class="PARAMETER"><i>tree</i></tt>, gpointer <tt
                class="PARAMETER"><i>key</i></tt>);</code>
              </p>
            </div>
            <p>
              <b>Figure 18. Manipulating <span class="STRUCTNAME">
              GTree</span> contents</b>
            </p>
          </div>
          <p>
            There are two functions which give you an idea how
            large the tree is, shown in <a href= 
            "z29.html#FL-TREESIZE">Figure 19</a>.
          </p>
          <div class="FIGURE">
            <a name="FL-TREESIZE"></a>
            <div class="FUNCSYNOPSIS">
              <a name="FL-TREESIZE.SYNOPSIS"></a>
              <table border="0" bgcolor="#E0E0E0" width="100%">
                <tr>
                  <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;glib.h&gt;
</pre>
                  </td>
                </tr>
              </table>
              <p>
                <code><code class="FUNCDEF">gint <tt class=
                "FUNCTION">g_tree_nnodes</tt></code>(GTree* <tt
                class="PARAMETER"><i>tree</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF">gint <tt class=
                "FUNCTION">g_tree_height</tt></code>(GTree* <tt
                class="PARAMETER"><i>tree</i></tt>);</code>
              </p>
            </div>
            <p>
              <b>Figure 19. Determining the size of a <span class= 
              "STRUCTNAME">GTree</span></b>
            </p>
          </div>
          <p>
            Using <tt class="FUNCTION">g_tree_traverse()</tt> (<a
            href="z29.html#FL-TREETRAVERSE">Figure 20</a>) you can
            walk the entire tree. To use it, you provide a <span
            class="STRUCTNAME">GTraverseFunc</span>, which is
            passed each key-value pair and a <span class=
            "STRUCTNAME">data</span> argument you give to <tt
            class="FUNCTION">g_tree_traverse()</tt>. Traversal
            continues as long as the <span class="STRUCTNAME">
            GTraverseFunc</span> returns <span class="STRUCTNAME">
            FALSE</span>; if it ever returns <span class=
            "STRUCTNAME">TRUE</span> then traversal stops. You can
            use this to search the tree by value. Here is the
            definition of <span class="STRUCTNAME">
            GTraverseFunc</span>:
          </p>
          <table border="0" bgcolor="#E0E0E0" width="100%">
            <tr>
              <td>
<pre class="PROGRAMLISTING">
&#13;typedef gint (*GTraverseFunc)(gpointer key, gpointer value, gpointer data);&#13;
</pre>
              </td>
            </tr>
          </table>
          <p>
            <span class="STRUCTNAME">GTraverseType</span> is an
            enumeration; there are four possible values. Here are
            their meanings with respect to <span class=
            "STRUCTNAME">GTree</span>.
          </p>
          <ul>
            <li>
              <p>
                <span class="STRUCTNAME">G_IN_ORDER</span> first
                recurses the left child of the node (the "lower"
                key according to your <span class="STRUCTNAME">
                GCompareFunc</span>), 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
                <span class="STRUCTNAME">GCompareFunc</span>.&#13;
              </p>
            </li>
            <li>
              <p>
                <span class="STRUCTNAME">G_PRE_ORDER</span> calls
                the traversal function on the key-value pair of the
                current node, then recurses the left child, then
                recurses the right child.&#13;
              </p>
            </li>
            <li>
              <p>
                <span class="STRUCTNAME">G_POST_ORDER</span>
                recurses the left child, then recurses the right
                child, and finally calls the traversal function on
                the current node's key-value pair.&#13;
              </p>
            </li>
            <li>
              <p>
                <span class="STRUCTNAME">G_LEVEL_ORDER</span> is
                only meaningful for <span class="STRUCTNAME">
                GNode</span>, it is not allowed with <span class= 
                "STRUCTNAME">GTree</span>.&#13;
              </p>
            </li>
          </ul>
          <div class="FIGURE">
            <a name="FL-TREETRAVERSE"></a>
            <div class="FUNCSYNOPSIS">
              <a name="FL-TREETRAVERSE.SYNOPSIS"></a>
              <table border="0" bgcolor="#E0E0E0" width="100%">
                <tr>
                  <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;glib.h&gt;
</pre>
                  </td>
                </tr>
              </table>
              <p>
                <code><code class="FUNCDEF">void <tt class=
                "FUNCTION">g_tree_traverse</tt></code>(GTree* <tt
                class="PARAMETER"><i>tree</i></tt>, GTraverseFunc
                <tt class="PARAMETER"><i>traverse_func</i></tt>,
                GTraverseType <tt class="PARAMETER"><i>
                traverse_type</i></tt>, gpointer <tt class= 
                "PARAMETER"><i>data</i></tt>);</code>
              </p>
            </div>
            <p>
              <b>Figure 20. Traversing <span class="STRUCTNAME">
              GTree</span></b>
            </p>
          </div>
        </div>
        <div class="SECT3">
          <h3 class="SECT3">
            <a name="Z33">GNode</a>
          </h3>
          <p>
            A <span class="STRUCTNAME">GNode</span> is an N-way
            tree, implemented as a doubly linked list with parent
            and child lists. Thus, most list operations have
            analogues in the <span class="STRUCTNAME">GNode</span>
            API. You can also walk the tree in various ways. Here's
            the declaration for a node:
          </p>
          <table border="0" bgcolor="#E0E0E0" width="100%">
            <tr>
              <td>
<pre class="PROGRAMLISTING">
&#13;typedef struct _GNode GNode;

struct _GNode
{
  gpointer data;
  GNode   *next;
  GNode   *prev;
  GNode   *parent;
  GNode   *children;
};&#13;
</pre>
              </td>
            </tr>
          </table>
          <p>
            There are macros to access <span class="STRUCTNAME">
            GNode</span> members, shown in <a href= 
            "z29.html#ML-NODEACCESS">Figure 21</a>. As with <span
            class="STRUCTNAME">GList</span>, the <span class= 
            "STRUCTNAME">data</span> member is intended to be used
            directly. These macros return the <span class= 
            "STRUCTNAME">next</span>, <span class="STRUCTNAME">
            prev</span>, and <span class="STRUCTNAME">
            children</span> members respectively; they also check
            whether their argument is <span class="STRUCTNAME">
            NULL</span> before dereferencing it, and return <span
            class="STRUCTNAME">NULL</span> if it is.
          </p>
          <div class="FIGURE">
            <a name="ML-NODEACCESS"></a>
            <div class="FUNCSYNOPSIS">
              <a name="ML-NODEACCESS.SYNOPSIS"></a>
              <table border="0" bgcolor="#E0E0E0" width="100%">
                <tr>
                  <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;glib.h&gt;
</pre>
                  </td>
                </tr>
              </table>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                g_node_prev_sibling</tt></code>(<tt class=
                "PARAMETER"><i>node</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                g_node_next_sibling</tt></code>(<tt class=
                "PARAMETER"><i>node</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                g_node_first_child</tt></code>(<tt class=
                "PARAMETER"><i>node</i></tt>);</code>
              </p>
            </div>
            <p>
              <b>Figure 21. Accessing <span class="STRUCTNAME">
              GNode</span> members</b>
            </p>
          </div>
          <p>
            To create a node, the usual <tt class="FUNCTION">
            _new()</tt> function is provided (<a href= 
            "z29.html#FL-NODENEW">Figure 22</a>). <tt class= 
            "FUNCTION">g_node_new()</tt> creates a childless and
            parentless node containing <span class="STRUCTNAME">
            data</span>. Typically <tt class="FUNCTION">
            g_node_new()</tt> is used only to create the root node;
            convenience macros are provided which automatically
            create new nodes as needed.
          </p>
          <div class="FIGURE">
            <a name="FL-NODENEW"></a>
            <div class="FUNCSYNOPSIS">
              <a name="FL-NODENEW.SYNOPSIS"></a>
              <table border="0" bgcolor="#E0E0E0" width="100%">
                <tr>
                  <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;glib.h&gt;
</pre>
                  </td>
                </tr>
              </table>
              <p>
                <code><code class="FUNCDEF">GNode* <tt class= 
                "FUNCTION">g_node_new</tt></code>(gpointer <tt
                class="PARAMETER"><i>data</i></tt>);</code>
              </p>
            </div>
            <p>
              <b>Figure 22. Creating a <span class="STRUCTNAME">
              GNode</span></b>
            </p>
          </div>
          <p>
            To build a tree the fundamental operations shown in <a
            href="z29.html#FL-NODEBUILD">Figure 23</a> are used.
            Each operation returns the just-added node, for
            convenience when writing loops or recursing the tree.
            Unlike <span class="STRUCTNAME">GList</span>, it is
            safe to ignore the return value.
          </p>
          <div class="FIGURE">
            <a name="FL-NODEBUILD"></a>
            <div class="FUNCSYNOPSIS">
              <a name="FL-NODEBUILD.SYNOPSIS"></a>
              <table border="0" bgcolor="#E0E0E0" width="100%">
                <tr>
                  <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;glib.h&gt;
</pre>
                  </td>
                </tr>
              </table>
              <p>
                <code><code class="FUNCDEF">GNode* <tt class= 
                "FUNCTION">g_node_insert</tt></code>(GNode* <tt
                class="PARAMETER"><i>parent</i></tt>, gint <tt
                class="PARAMETER"><i>position</i></tt>, GNode* <tt
                class="PARAMETER"><i>node</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF">GNode* <tt class= 
                "FUNCTION">g_node_insert_before</tt></code>(GNode*
                <tt class="PARAMETER"><i>parent</i></tt>, GNode*
                <tt class="PARAMETER"><i>sibling</i></tt>, GNode*
                <tt class="PARAMETER"><i>node</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF">GNode* <tt class= 
                "FUNCTION">g_node_prepend</tt></code>(GNode* <tt
                class="PARAMETER"><i>parent</i></tt>, GNode* <tt
                class="PARAMETER"><i>node</i></tt>);</code>
              </p>
            </div>
            <p>
              <b>Figure 23. Building a <span class="STRUCTNAME">
              GNode</span> tree</b>
            </p>
          </div>
          <p>
            The convenience macros shown in <a href= 
            "z29.html#ML-NODECONV">Figure 24</a> are implemented in
            terms of the fundamental operations. <tt class=
            "FUNCTION">g_node_append()</tt> is analagous to <tt
            class="FUNCTION">g_node_prepend()</tt>; the rest take a
            <span class="STRUCTNAME">data</span> argument,
            automatically allocate a node for it, and call the
            corresponding basic operation.
          </p>
          <div class="FIGURE">
            <a name="ML-NODECONV"></a>
            <div class="FUNCSYNOPSIS">
              <a name="ML-NODECONV.SYNOPSIS"></a>
              <table border="0" bgcolor="#E0E0E0" width="100%">
                <tr>
                  <td>
<pre class="FUNCSYNOPSISINFO">