specs/Tree.xml

   1 <sect1 id="Tree_Widget">
   2 <title>Tree Widget</title>
   3 <literallayout class="monospaced">
   4 Application Header file &lt;X11/Xaw/Tree.h&gt;
   5 Class Header file       &lt;X11/Xaw/TreeP.h&gt;
   6 Class           treeWidgetClass
   7 Class Name      Tree
   8 Superclass      Constraint
   9 </literallayout>
  10
  11 <para>
  12 The Tree widget provides geometry management of arbitrary widgets arranged
  13 in a directed, acyclic graph (i.e., a tree).  The hierarchy is constructed
  14 by attaching a constraint resource called <function>treeParent</function> to each widget
  15 indicating which other node in the tree should be treated as the widget's
  16 superior.  The structure of the tree is shown by laying out the nodes
  17 in the standard format for tree diagrams with lines drawn connecting each
  18 node with its children.
  19 </para>
  20
  21 <para>
  22 The Tree sizes itself according to the needs of its children and is not
  23 intended to be resized by its parent.  Instead, it should be placed inside
  24 another composite widget (such as the <function>Porthole</function> or <function>Viewport</function>)
  25 that can be used to scroll around in the tree.
  26 </para>
  27
  28 <sect2 id='Tree::Resources'>
  29 <title>Resources</title>
  30 <para>
  31 When creating a Tree widget instance, the following resources are
  32 retrieved from the argument list or from the resource database:
  33 </para>
  34
  35 <informaltable>
  36   <tgroup cols='5' align='center'>
  37   <colspec colname='c1'/>
  38   <colspec colname='c2'/>
  39   <colspec colname='c3'/>
  40   <colspec colname='c4'/>
  41   <colspec colname='c5'/>
  42   <thead>
  43     <row>
  44       <entry>Name</entry>
  45       <entry>Class</entry>
  46       <entry>Type</entry>
  47       <entry>Notes</entry>
  48       <entry>Default Value</entry>
  49     </row>
  50   </thead>
  51   <tbody>
  52     <row>
  53       <entry>accelerators</entry>
  54       <entry>Accelerators</entry>
  55       <entry>AcceleratorTable</entry>
  56       <entry></entry>
  57       <entry>NULL</entry>
  58     </row>
  59     <row>
  60       <entry>ancestorSensitive</entry>
  61       <entry>AncestorSensitive</entry>
  62       <entry>Boolean</entry>
  63       <entry>D</entry>
  64       <entry>True</entry>
  65     </row>
  66     <row>
  67       <entry>autoReconfigure</entry>
  68       <entry>AutoReconfigure</entry>
  69       <entry>Boolean</entry>
  70       <entry></entry>
  71       <entry>False</entry>
  72     </row>
  73     <row>
  74       <entry>background</entry>
  75       <entry>Background</entry>
  76       <entry>Pixel</entry>
  77       <entry></entry>
  78       <entry>XtDefaultBackground</entry>
  79     </row>
  80     <row>
  81       <entry>backgroundPixmap</entry>
  82       <entry>Pixmap</entry>
  83       <entry>Pixmap</entry>
  84       <entry></entry>
  85       <entry>XtUnspecifiedPixmap</entry>
  86     </row>
  87     <row>
  88       <entry>borderColor</entry>
  89       <entry>BorderColor</entry>
  90       <entry>Pixel</entry>
  91       <entry></entry>
  92       <entry>XtDefaultForeground</entry>
  93     </row>
  94     <row>
  95       <entry>borderPixmap</entry>
  96       <entry>Pixmap</entry>
  97       <entry>Pixmap</entry>
  98       <entry></entry>
  99       <entry>XtUnspecifiedPixmap</entry>
 100     </row>
 101     <row>
 102       <entry>borderWidth</entry>
 103       <entry>BorderWidth</entry>
 104       <entry>Dimension</entry>
 105       <entry></entry>
 106       <entry>1</entry>
 107     </row>
 108     <row>
 109       <entry>children</entry>
 110       <entry>ReadOnly</entry>
 111       <entry>WidgetList</entry>
 112       <entry>R</entry>
 113       <entry>NULL</entry>
 114     </row>
 115     <row>
 116       <entry>colormap</entry>
 117       <entry>Colormap</entry>
 118       <entry>Colormap</entry>
 119       <entry></entry>
 120       <entry>Parent's Colormap</entry>
 121     </row>
 122     <row>
 123       <entry>depth</entry>
 124       <entry>Depth</entry>
 125       <entry>int</entry>
 126       <entry>C</entry>
 127       <entry>Parent's Depth</entry>
 128     </row>
 129     <row>
 130       <entry>destroyCallback</entry>
 131       <entry>Callback</entry>
 132       <entry>XtCallbackList</entry>
 133       <entry></entry>
 134       <entry>NULL</entry>
 135     </row>
 136     <row>
 137       <entry>foreground</entry>
 138       <entry>Foreground</entry>
 139       <entry>Pixel</entry>
 140       <entry></entry>
 141       <entry>XtDefaultForeground</entry>
 142     </row>
 143     <row>
 144       <entry>gravity</entry>
 145       <entry>Gravity</entry>
 146       <entry>XtGravity</entry>
 147       <entry></entry>
 148       <entry>WestGravity</entry>
 149     </row>
 150     <row>
 151       <entry>height</entry>
 152       <entry>Height</entry>
 153       <entry>Dimension</entry>
 154       <entry>A</entry>
 155       <entry>see <function>Layout Semantics</function></entry> <!-- xref -->
 156     </row>
 157     <row>
 158       <entry>hSpace</entry>
 159       <entry>HSpace</entry>
 160       <entry>Dimension</entry>
 161       <entry></entry>
 162       <entry>4</entry>
 163     </row>
 164     <row>
 165       <entry>lineWidth</entry>
 166       <entry>LineWidth</entry>
 167       <entry>Dimension</entry>
 168       <entry></entry>
 169       <entry>0</entry>
 170     </row>
 171     <row>
 172       <entry>mappedWhenManaged</entry>
 173       <entry>MappedWhenManaged</entry>
 174       <entry>Boolean</entry>
 175       <entry></entry>
 176       <entry>True</entry>
 177     </row>
 178     <row>
 179       <entry>numChildren</entry>
 180       <entry>ReadOnly</entry>
 181       <entry>Cardinal</entry>
 182       <entry>R</entry>
 183       <entry>0</entry>
 184     </row>
 185     <row>
 186       <entry>screen</entry>
 187       <entry>Screen</entry>
 188       <entry>Screen</entry>
 189       <entry>R</entry>
 190       <entry>Parent's Screen</entry>
 191     </row>
 192     <row>
 193       <entry>sensitive</entry>
 194       <entry>Sensitive</entry>
 195       <entry>Boolean</entry>
 196       <entry></entry>
 197       <entry>True</entry>
 198     </row>
 199     <row>
 200       <entry>vSpace</entry>
 201       <entry>VSpace</entry>
 202       <entry>Dimension</entry>
 203       <entry></entry>
 204       <entry>4</entry>
 205     </row>
 206     <row>
 207       <entry>translations</entry>
 208       <entry>Translations</entry>
 209       <entry>TranslationTable</entry>
 210       <entry></entry>
 211       <entry>NULL</entry>
 212     </row>
 213     <row>
 214       <entry>width</entry>
 215       <entry>Width</entry>
 216       <entry>Dimension</entry>
 217       <entry>A</entry>
 218       <entry>see <function>Layout Semantics</function></entry> <!-- xref -->
 219     </row>
 220     <row>
 221       <entry>x</entry>
 222       <entry>Position</entry>
 223       <entry>Position</entry>
 224       <entry></entry>
 225       <entry>0</entry>
 226     </row>
 227     <row>
 228       <entry>y</entry>
 229       <entry>Position</entry>
 230       <entry>Position</entry>
 231       <entry></entry>
 232       <entry>0</entry>
 233     </row>
 234   </tbody>
 235   </tgroup>
 236 </informaltable>
 237
 238 <variablelist>
 239   <varlistentry>
 240     <term><function>autoReconfigure</function></term>
 241     <listitem>
 242       <para>
 243 Whether or not to layout the tree every time a node is added or removed.
 244       </para>
 245     </listitem>
 246   </varlistentry>
 247   <varlistentry>
 248     <term><function>gravity</function></term>
 249     <listitem>
 250       <para>
 251 Specifies the side of the widget from which the tree should grow.  Valid
 252 values include <function>WestGravity</function>, <function>NorthGravity</function>, <function>EastGravity</function>, and
 253 <function>SouthGravity</function>.
 254       </para>
 255     </listitem>
 256   </varlistentry>
 257   <varlistentry>
 258     <term><function>hSpace</function></term>
 259     <listitem>
 260       <para>
 261 <!-- .br -->
 262 <!-- .ns -->
 263       </para>
 264     </listitem>
 265   </varlistentry>
 266   <varlistentry>
 267     <term><function>vSpace</function></term>
 268     <listitem>
 269       <para>
 270 The amount of space, in pixels, to leave between the children.  This
 271 resource specifies the amount of space left between the outermost
 272 children and the edge of the box.
 273       </para>
 274     </listitem>
 275   </varlistentry>
 276   <varlistentry>
 277     <term><function>lineWidth</function></term>
 278     <listitem>
 279       <para>
 280 The width of the lines from nodes that do not have a <function>treeGC</function>
 281 constraint resource to their children.
 282       </para>
 283     </listitem>
 284   </varlistentry>
 285 </variablelist>
 286
 287 </sect2>
 288
 289 <sect2 id='Tree::Constraint_Resources'>
 290 <title>Constraint Resources</title>
 291 <para>
 292 Each child of the Tree widget must specify its superior node in the tree.  In
 293 addition, it may specify a GC to use when drawing a line between it and its
 294 inferior nodes.
 295 </para>
 296
 297 <informaltable>
 298   <tgroup cols='5' align='center'>
 299   <colspec colname='c1'/>
 300   <colspec colname='c2'/>
 301   <colspec colname='c3'/>
 302   <colspec colname='c4'/>
 303   <colspec colname='c5'/>
 304   <thead>
 305     <row>
 306       <entry>Name</entry>
 307       <entry>Class</entry>
 308       <entry>Type</entry>
 309       <entry>Notes</entry>
 310       <entry>Default Value</entry>
 311     </row>
 312   </thead>
 313   <tbody>
 314     <row>
 315       <entry>treeGC</entry>
 316       <entry>TreeGC</entry>
 317       <entry>GC</entry>
 318       <entry></entry>
 319       <entry>NULL</entry>
 320     </row>
 321     <row>
 322       <entry>treeParent</entry>
 323       <entry>TreeParent</entry>
 324       <entry>Widget</entry>
 325       <entry></entry>
 326       <entry>NULL</entry>
 327     </row>
 328   </tbody>
 329   </tgroup>
 330 </informaltable>
 331
 332
 333
 334 <variablelist>
 335   <varlistentry>
 336     <term><function>treeGC</function></term>
 337     <listitem>
 338       <para>
 339 This specifies the GC to use when drawing lines between this widget and its
 340 inferiors in the tree.  If this resource is not specified, the Tree's
 341 <function>foreground</function> and <function>lineWidth</function> will be used.
 342       </para>
 343     </listitem>
 344   </varlistentry>
 345   <varlistentry>
 346     <term><function>treeParent</function></term>
 347     <listitem>
 348       <para>
 349 This specifies the superior node in the tree for this widget.  The default is
 350 for the node to have no superior (and to therefore be at the top of the tree).
 351
 352       </para>
 353     </listitem>
 354   </varlistentry>
 355 </variablelist>
 356 </sect2>
 357
 358
 359 <sect2 id='Tree::Layout_Semantics'>
 360 <title>Layout Semantics</title>
 361 <para>
 362 Each time a child is managed or unmanaged, the Tree widget will attempt
 363 to reposition the remaining children to fix the shape of the tree if the
 364 <!-- .B autoReconfigure -->
 365 resource is set.  Children at the top (most superior) of the tree are
 366 drawn at the side specified by the resource.
 367 </para>
 368
 369 <para>
 370 After positioning all children, the Tree widget attempts to shrink its
 371 own size to the minimum dimensions required for the layout.
 372 </para>
 373
 374 </sect2>
 375
 376 <sect2 id='Tree::Convenience_Routines'>
 377 <title>Convenience Routines</title>
 378 <para>
 379 The most efficient way to layout a tree is to set
 380 <function>autoReconfigure</function>
 381 to False and then use the
 382 <xref linkend='XawTreeForceLayout' xrefstyle='select: title'/>
 383 routine to arrange the children.
 384 </para>
 385
 386 <funcsynopsis id='XawTreeForceLayout'>
 387 <funcprototype>
 388   <funcdef>void<function> XawTreeForceLayout</function></funcdef>
 389   <paramdef>Widget<parameter> w</parameter></paramdef>
 390 </funcprototype>
 391 </funcsynopsis>
 392
 393 <variablelist>
 394   <varlistentry>
 395     <term>w</term>
 396     <listitem>
 397       <para>
 398 Specifies the Tree widget.
 399       </para>
 400     </listitem>
 401   </varlistentry>
 402 </variablelist>
 403 </sect2>
 404 </sect1>