svn merge ^/branches/released .

1 files changed, 404 insertions, 0 deletions

diff --git a/libXaw/specs/Tree.xml b/libXaw/specs/Tree.xml
new file mode 100644
index 000000000..bb51e80d1
--- /dev/null
+++ b/libXaw/specs/Tree.xml
@@ -0,0 +1,404 @@
+<sect1 id="Tree_Widget">
+<title>Tree Widget</title>
+<literallayout class="monospaced">
+Application Header file	&lt;X11/Xaw/Tree.h&gt;
+Class Header file	&lt;X11/Xaw/TreeP.h&gt;
+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>