trees-nary.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>parent</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to place <parameter>node</parameter> under.
</entry></row>
<row><entry align="right"><parameter>sibling</parameter>&nbsp;:</entry>
<entry>the sibling <link linkend="GNode">GNode</link> to place <parameter>node</parameter> after. If sibling is <literal>NULL</literal>,
the node is inserted as the first child of <parameter>parent</parameter>.
</entry></row>
<row><entry align="right"><parameter>node</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to insert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the inserted <link linkend="GNode">GNode</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-node-append">g_node_append()</title>
<programlisting>#define     g_node_append(parent, node)</programlisting>
<para>
Inserts a <link linkend="GNode">GNode</link> as the last child of the given parent.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>parent</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to place the new <link linkend="GNode">GNode</link> under.
</entry></row>
<row><entry align="right"><parameter>node</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to insert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the inserted <link linkend="GNode">GNode</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-node-prepend">g_node_prepend ()</title>
<programlisting><link linkend="GNode">GNode</link>*      g_node_prepend                  (<link linkend="GNode">GNode</link> *parent,
                                             <link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Inserts a <link linkend="GNode">GNode</link> as the first child of the given parent.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>parent</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to place the new <link linkend="GNode">GNode</link> under.
</entry></row>
<row><entry align="right"><parameter>node</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to insert.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the inserted <link linkend="GNode">GNode</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-node-insert-data">g_node_insert_data()</title>
<programlisting>#define     g_node_insert_data(parent, position, data)</programlisting>
<para>
Inserts a new <link linkend="GNode">GNode</link> at the given position.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>parent</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to place the new <link linkend="GNode">GNode</link> under.
</entry></row>
<row><entry align="right"><parameter>position</parameter>&nbsp;:</entry>
<entry>the position to place the new <link linkend="GNode">GNode</link> at.
If position is -1, the new <link linkend="GNode">GNode</link> is inserted as the last child of <parameter>parent</parameter>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data for the new <link linkend="GNode">GNode</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GNode">GNode</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-node-insert-data-before">g_node_insert_data_before()</title>
<programlisting>#define     g_node_insert_data_before(parent, sibling, data)</programlisting>
<para>
Inserts a new <link linkend="GNode">GNode</link> before the given sibling.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>parent</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to place the new <link linkend="GNode">GNode</link> under.
</entry></row>
<row><entry align="right"><parameter>sibling</parameter>&nbsp;:</entry>
<entry>the sibling <link linkend="GNode">GNode</link> to place the new <link linkend="GNode">GNode</link> before.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data for the new <link linkend="GNode">GNode</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GNode">GNode</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-node-append-data">g_node_append_data()</title>
<programlisting>#define     g_node_append_data(parent, data)</programlisting>
<para>
Inserts a new <link linkend="GNode">GNode</link> as the last child of the given parent.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>parent</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to place the new <link linkend="GNode">GNode</link> under.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data for the new <link linkend="GNode">GNode</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GNode">GNode</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-node-prepend-data">g_node_prepend_data()</title>
<programlisting>#define     g_node_prepend_data(parent, data)</programlisting>
<para>
Inserts a new <link linkend="GNode">GNode</link> as the first child of the given parent.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>parent</parameter>&nbsp;:</entry>
<entry>the <link linkend="GNode">GNode</link> to place the new <link linkend="GNode">GNode</link> under.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data for the new <link linkend="GNode">GNode</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GNode">GNode</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-node-reverse-children">g_node_reverse_children ()</title>
<programlisting>void        g_node_reverse_children         (<link linkend="GNode">GNode</link> *node);</programlisting>
<para>
Reverses the order of the children of a <link linkend="GNode">GNode</link>.
(It doesn't change the order of the grandchildren.)
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>node</parameter>&nbsp;:</entry>
<entry>a <link linkend="GNode">GNode</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-node-traverse">g_node_traverse ()</title>
<programlisting>void        g_node_traverse                 (<link linkend="GNode">GNode</link> *root,
                                             <link linkend="GTraverseType">GTraverseType</link> order,
                                             <link linkend="GTraverseFlags">GTraverseFlags</link> flags,
                                             <link linkend="gint">gint</link> max_depth,
                                             <link linkend="GNodeTraverseFunc">GNodeTraverseFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Traverses a tree starting at the given root <link linkend="GNode">GNode</link>.
It calls the given function for each node visited.
The traversal can be halted at any point by returning <literal>TRUE</literal> from <parameter>func</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>root</parameter>&nbsp;:</entry>
<entry>the root <link linkend="GNode">GNode</link> of the tree to traverse.
</entry></row>
<row><entry align="right"><parameter>order</parameter>&nbsp;:</entry>
<entry>the order in which nodes are visited - <literal>G_IN_ORDER</literal>, <literal>G_PRE_ORDER</literal>,
<literal>G_POST_ORDER</literal>, or <literal>G_LEVEL_ORDER</literal>.
</entry></row>
<row><entry align="right"><parameter>flags</parameter>&nbsp;:</entry>
<entry>which types of children are to be visited, one of <literal>G_TRAVERSE_ALL</literal>,
<literal>G_TRAVERSE_LEAFS</literal> and <literal>G_TRAVERSE_NON_LEAFS</literal>.
</entry></row>
<row><entry align="right"><parameter>max_depth</parameter>&nbsp;:</entry>
<entry>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 depth is 1, only the root is visited. If depth is 2, the root
and its children are visited. And so on.
</entry></row>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry>the function to call for each visited <link linkend="GNode">GNode</link>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>user data to pass to the function.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GTraverseFlags">enum GTraverseFlags</title>
<programlisting>typedef enum
{
  G_TRAVERSE_LEAFS      = 1 &lt;&lt; 0,
  G_TRAVERSE_NON_LEAFS  = 1 &lt;&lt; 1,
  G_TRAVERSE_ALL        = G_TRAVERSE_LEAFS | G_TRAVERSE_NON_LEAFS,
  G_TRAVERSE_MASK       = 0x03
} GTraverseFlags;
</programlisting>
<para>
Specifies which nodes are visited during several of the tree functions,
including <link linkend="g-node-traverse">g_node_traverse</link>() and <link linkend="g-node-find">g_node_find</link>().
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_TRAVERSE_LEAFS</literal></entry>
<entry>only leaf nodes should be visited.
</entry>
</row>
<row>
<entry><literal>G_TRAVERSE_NON_LEAFS</literal></entry>
<entry>only non-leaf nodes should be visited.
</entry>
</row>
<row>
<entry><literal>G_TRAVERSE_ALL</literal></entry>
<entry>all nodes should be visited.
</entry>
</row>
<row>
<entry><literal>G_TRAVERSE_MASK</literal></entry>
<entry>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GNodeTraverseFunc">GNodeTraverseFunc ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    (*GNodeTraverseFunc)            (<link linkend="GNode">GNode</link> *node,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function passed to <link linkend="g-node-traverse">g_node_traverse</link>().
The function is called with each of the nodes visited, together with the
user data passed to <link linkend="g-node-traverse">g_node_traverse</link>().
If the function returns <literal>TRUE</literal>, then the traversal is stopped.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>