<sect1 id="Tree_Widget">
<title>Tree Widget</title>
<literallayout class="monospaced">
Application Header file <X11/Xaw/Tree.h>
Class Header file <X11/Xaw/TreeP.h>
Class treeWidgetClass
Class Name Tree
Superclass Constraint
</literallayout>
<para>
The Tree widget provides geometry management of arbitrary widgets arranged
in a directed, acyclic graph (i.e., a tree). The hierarchy is constructed
by attaching a constraint resource called <function>treeParent</function> to each widget
indicating which other node in the tree should be treated as the widget's
superior. The structure of the tree is shown by laying out the nodes
in the standard format for tree diagrams with lines drawn connecting each
node with its children.
</para>
<para>
The Tree sizes itself according to the needs of its children and is not
intended to be resized by its parent. Instead, it should be placed inside
another composite widget (such as the <function>Porthole</function> or <function>Viewport</function>)
that can be used to scroll around in the tree.
</para>
<sect2 id="tree_resources">
<title>Resources</title>
<para>
When creating a Tree widget instance, the following resources are
retrieved from the argument list or from the resource database:
</para>
<informaltable>
<tgroup cols='5' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<colspec colname='c4'/>
<colspec colname='c5'/>
<thead>
<row>
<entry>Name</entry>
<entry>Class</entry>
<entry>Type</entry>
<entry>Notes</entry>
<entry>Default Value</entry>
</row>
</thead>
<tbody>
<row>
<entry>accelerators</entry>
<entry>Accelerators</entry>
<entry>AcceleratorTable</entry>
<entry></entry>
<entry>NULL</entry>
</row>
<row>
<entry>ancestorSensitive</entry>
<entry>AncestorSensitive</entry>
<entry>Boolean</entry>
<entry>D</entry>
<entry>True</entry>
</row>
<row>
<entry>autoReconfigure</entry>
<entry>AutoReconfigure</entry>
<entry>Boolean</entry>
<entry></entry>
<entry>False</entry>
</row>
<row>
<entry>background</entry>
<entry>Background</entry>
<entry>Pixel</entry>
<entry></entry>
<entry>XtDefaultBackground</entry>
</row>
<row>
<entry>backgroundPixmap</entry>
<entry>Pixmap</entry>
<entry>Pixmap</entry>
<entry></entry>
<entry>XtUnspecifiedPixmap</entry>
</row>
<row>
<entry>borderColor</entry>
<entry>BorderColor</entry>
<entry>Pixel</entry>
<entry></entry>
<entry>XtDefaultForeground</entry>
</row>
<row>
<entry>borderPixmap</entry>
<entry>Pixmap</entry>
<entry>Pixmap</entry>
<entry></entry>
<entry>XtUnspecifiedPixmap</entry>
</row>
<row>
<entry>borderWidth</entry>
<entry>BorderWidth</entry>
<entry>Dimension</entry>
<entry></entry>
<entry>1</entry>
</row>
<row>
<entry>children</entry>
<entry>ReadOnly</entry>
<entry>WidgetList</entry>
<entry>R</entry>
<entry>NULL</entry>
</row>
<row>
<entry>colormap</entry>
<entry>Colormap</entry>
<entry>Colormap</entry>
<entry></entry>
<entry>Parent's Colormap</entry>
</row>
<row>
<entry>depth</entry>
<entry>Depth</entry>
<entry>int</entry>
<entry>C</entry>
<entry>Parent's Depth</entry>
</row>
<row>
<entry>destroyCallback</entry>
<entry>Callback</entry>
<entry>XtCallbackList</entry>
<entry></entry>
<entry>NULL</entry>
</row>
<row>
<entry>foreground</entry>
<entry>Foreground</entry>
<entry>Pixel</entry>
<entry></entry>
<entry>XtDefaultForeground</entry>
</row>
<row>
<entry>gravity</entry>
<entry>Gravity</entry>
<entry>XtGravity</entry>
<entry></entry>
<entry>WestGravity</entry>
</row>
<row>
<entry>height</entry>
<entry>Height</entry>
<entry>Dimension</entry>
<entry>A</entry>
<entry>see <function>Layout Semantics</function></entry> <!-- xref -->
</row>
<row>
<entry>hSpace</entry>
<entry>HSpace</entry>
<entry>Dimension</entry>
<entry></entry>
<entry>4</entry>
</row>
<row>
<entry>lineWidth</entry>
<entry>LineWidth</entry>
<entry>Dimension</entry>
<entry></entry>
<entry>0</entry>
</row>
<row>
<entry>mappedWhenManaged</entry>
<entry>MappedWhenManaged</entry>
<entry>Boolean</entry>
<entry></entry>
<entry>True</entry>
</row>
<row>
<entry>numChildren</entry>
<entry>ReadOnly</entry>
<entry>Cardinal</entry>
<entry>R</entry>
<entry>0</entry>
</row>
<row>
<entry>screen</entry>
<entry>Screen</entry>
<entry>Screen</entry>
<entry>R</entry>
<entry>Parent's Screen</entry>
</row>
<row>
<entry>sensitive</entry>
<entry>Sensitive</entry>
<entry>Boolean</entry>
<entry></entry>
<entry>True</entry>
</row>
<row>
<entry>vSpace</entry>
<entry>VSpace</entry>
<entry>Dimension</entry>
<entry></entry>
<entry>4</entry>
</row>
<row>
<entry>translations</entry>
<entry>Translations</entry>
<entry>TranslationTable</entry>
<entry></entry>
<entry>NULL</entry>
</row>
<row>
<entry>width</entry>
<entry>Width</entry>
<entry>Dimension</entry>
<entry>A</entry>
<entry>see <function>Layout Semantics</function></entry> <!-- xref -->
</row>
<row>
<entry>x</entry>
<entry>Position</entry>
<entry>Position</entry>
<entry></entry>
<entry>0</entry>
</row>
<row>
<entry>y</entry>
<entry>Position</entry>
<entry>Position</entry>
<entry></entry>
<entry>0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<variablelist>
<varlistentry>
<term><function>autoReconfigure</function></term>
<listitem>
<para>
Whether or not to layout the tree every time a node is added or removed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>gravity</function></term>
<listitem>
<para>
Specifies the side of the widget from which the tree should grow. Valid
values include <function>WestGravity</function>, <function>NorthGravity</function>, <function>EastGravity</function>, and
<function>SouthGravity</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>hSpace</function></term>
<listitem>
<para>
<!-- .br -->
<!-- .ns -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>vSpace</function></term>
<listitem>
<para>
The amount of space, in pixels, to leave between the children. This
resource specifies the amount of space left between the outermost
children and the edge of the box.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>lineWidth</function></term>
<listitem>
<para>
The width of the lines from nodes that do not have a <function>treeGC</function>
constraint resource to their children.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="tree_constraint_resources">
<title>Constraint Resources</title>
<para>
Each child of the Tree widget must specify its superior node in the tree. In
addition, it may specify a GC to use when drawing a line between it and its
inferior nodes.
</para>
<informaltable>
<tgroup cols='5' align='center'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<colspec colname='c4'/>
<colspec colname='c5'/>
<thead>
<row>
<entry>Name</entry>
<entry>Class</entry>
<entry>Type</entry>
<entry>Notes</entry>
<entry>Default Value</entry>
</row>
</thead>
<tbody>
<row>
<entry>treeGC</entry>
<entry>TreeGC</entry>
<entry>GC</entry>
<entry></entry>
<entry>NULL</entry>
</row>
<row>
<entry>treeParent</entry>
<entry>TreeParent</entry>
<entry>Widget</entry>
<entry></entry>
<entry>NULL</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<variablelist>
<varlistentry>
<term><function>treeGC</function></term>
<listitem>
<para>
This specifies the GC to use when drawing lines between this widget and its
inferiors in the tree. If this resource is not specified, the Tree's
<function>foreground</function> and <function>lineWidth</function> will be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>treeParent</function></term>
<listitem>
<para>
This specifies the superior node in the tree for this widget. The default is
for the node to have no superior (and to therefore be at the top of the tree).
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="tree_layout_semantics">
<title>Layout Semantics</title>
<para>
Each time a child is managed or unmanaged, the Tree widget will attempt
to reposition the remaining children to fix the shape of the tree if the
<!-- .B autoReconfigure -->
resource is set. Children at the top (most superior) of the tree are
drawn at the side specified by the resource.
</para>
<para>
After positioning all children, the Tree widget attempts to shrink its
own size to the minimum dimensions required for the layout.
</para>
</sect2>
<sect2 id="tree_convenience_routines">
<title>Convenience Routines</title>
<para>
The most efficient way to layout a tree is to set
<function>autoReconfigure</function>
to False and then use the
<function> XawTreeForceLayout</function>
routine to arrange the children.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>void<function> XawTreeForceLayout</function></funcdef>
<paramdef>Widget<parameter> w</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<variablelist>
<varlistentry>
<term>w</term>
<listitem>
<para>
Specifies the Tree widget.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>