specs/Paned.xml

   1 <sect1 id="Paned_Widget">
   2 <title>Paned Widget</title>
   3 <para>
   4 <!-- .LP -->
   5 <!-- .XS -->
   6 <!--    Paned Widget -->
   7 <!-- .XE -->
   8 <!-- .IN "Paned widget" "" "@DEF@" -->
   9 <literallayout class="monospaced">
  10 <!-- .TA 2.0i -->
  11 <!-- .ta 2.0i -->
  12 <!-- .sp -->
  13 Application Header file &lt;X11/Xaw/Paned.h&gt;
  14 <!-- .IN "Paned.h" "" -->
  15 Class Header file       &lt;X11/Xaw/PanedP.h&gt;
  16 <!-- .IN "PanedP.h" "" -->
  17 Class           panedWidgetClass
  18 <!-- .IN "panedWidgetClass" "" -->
  19 Class Name      Paned
  20 <!-- .IN "Paned widget" "class name" -->
  21 Superclass      Constraint
  22 <!-- .sp -->
  23 </literallayout>
  24 </para>
  25 <para>
  26 <!-- .LP -->
  27 The Paned widget manages children in a vertically or horizontally
  28 tiled fashion.  The panes may be dynamically resized by the user by
  29 using the <emphasis remap='I'>grips</emphasis> that appear near the right or bottom edge of the
  30 border between two panes.
  31 </para>
  32 <para>
  33 <!-- .LP -->
  34 The Paned widget may accept any widget class as a pane <function>except</function>
  35 Grip.  Grip widgets have a special meaning for the Paned widget, and
  36 adding a Grip as its own pane will confuse the Paned widget.
  37 </para>
  38 <sect2 id="Using_the_Paned_Widget">
  39 <title>Using the Paned Widget</title>
  40 <!-- .IN "Paned widget" "using" -->
  41 <para>
  42 <!-- .LP -->
  43 The grips allow the panes to be resized by the user.  The semantics of
  44 how these panes resize is somewhat complicated, and warrants further
  45 explanation here.  When the mouse pointer is positioned on a grip and
  46 pressed, an arrow is displayed that indicates the pane that is to be to
  47 be resized.  While keeping the mouse button down, the user can move the
  48 grip up and down (or left and right).  This, in turn, changes the size
  49 of the pane.  The size of the Paned widget will not change.   Instead,
  50 it chooses another pane (or panes) to resize. For more details on which
  51 pane it chooses to resize, see <function>Layout Semantics</function>.
  52 </para>
  53 <para>
  54 <!-- .LP -->
  55 One pointer binding allows the border between two panes to be moved,
  56 without affecting any of the other panes.  When this occurs the pointer
  57 will change to an arrow that points along the pane border.
  58 </para>
  59 <para>
  60 <!-- .LP -->
  61 The default bindings for the Paned widget's grips are:
  62 <informaltable>
  63   <tgroup cols='3' align='center'>
  64   <colspec colname='c1'/>
  65   <colspec colname='c2'/>
  66   <colspec colname='c3'/>
  67   <thead>
  68     <row>
  69       <entry>Mouse button</entry>
  70       <entry>Pane to Resize - Vertical</entry>
  71       <entry>Pane to Resize - Horizontal</entry>
  72     </row>
  73   </thead>
  74   <tbody>
  75     <row>
  76       <entry>1 (left)</entry>
  77       <entry>above the grip</entry>
  78       <entry>left of the grip</entry>
  79     </row>
  80     <row>
  81       <entry>2 (middle)</entry>
  82       <entry>adjust border</entry>
  83       <entry>adjust border</entry>
  84     </row>
  85     <row>
  86       <entry>3 (right)</entry>
  87       <entry>below the grip</entry>
  88       <entry>right of the grip</entry>
  89     </row>
  90     <row>
  91       <entry>_</entry>
  92     </row>
  93   </tbody>
  94   </tgroup>
  95 </informaltable>
  96 </para>
  97 </sect2>
  98 <sect2 id='Paned::Resources'>
  99 <title>Resources</title>
 100 <para>
 101 <!-- .LP -->
 102 When creating a Paned widget instance, the following resources are
 103 retrieved from the argument list or the resource database:
 104 </para>
 105 <para>
 106 <!-- .LP -->
 107 <!-- .IN "Paned widget" "resources" -->
 108 <informaltable>
 109   <tgroup cols='5' align='center'>
 110   <colspec colname='c1'/>
 111   <colspec colname='c2'/>
 112   <colspec colname='c3'/>
 113   <colspec colname='c4'/>
 114   <colspec colname='c5'/>
 115   <thead>
 116     <row>
 117       <entry>Name</entry>
 118       <entry>Class</entry>
 119       <entry>Type</entry>
 120       <entry>Notes</entry>
 121       <entry>Default Value</entry>
 122     </row>
 123   </thead>
 124   <tbody>
 125     <row>
 126       <entry>accelerators</entry>
 127       <entry>Accelerators</entry>
 128       <entry>AcceleratorTable</entry>
 129       <entry></entry>
 130       <entry>NULL</entry>
 131     </row>
 132     <row>
 133       <entry>ancestorSensitive</entry>
 134       <entry>AncestorSensitive</entry>
 135       <entry>Boolean</entry>
 136       <entry>D</entry>
 137       <entry>True</entry>
 138     </row>
 139     <row>
 140       <entry>background</entry>
 141       <entry>Background</entry>
 142       <entry>Pixel</entry>
 143       <entry></entry>
 144       <entry>XtDefaultBackground</entry>
 145     </row>
 146     <row>
 147       <entry>backgroundPixmap</entry>
 148       <entry>Pixmap</entry>
 149       <entry>Pixmap</entry>
 150       <entry></entry>
 151       <entry>XtUnspecifiedPixmap</entry>
 152     </row>
 153     <row>
 154       <entry>betweenCursor</entry>
 155       <entry>Cursor</entry>
 156       <entry>Cursor</entry>
 157       <entry>A</entry>
 158       <entry>Depends on orientation</entry>
 159     </row>
 160     <row>
 161       <entry>borderColor</entry>
 162       <entry>BorderColor</entry>
 163       <entry>Pixel</entry>
 164       <entry></entry>
 165       <entry>XtDefaultForeground</entry>
 166     </row>
 167     <row>
 168       <entry>borderPixmap</entry>
 169       <entry>Pixmap</entry>
 170       <entry>Pixmap</entry>
 171       <entry></entry>
 172       <entry>XtUnspecifiedPixmap</entry>
 173     </row>
 174     <row>
 175       <entry>borderWidth</entry>
 176       <entry>BorderWidth</entry>
 177       <entry>Dimension</entry>
 178       <entry></entry>
 179       <entry>1</entry>
 180     </row>
 181     <row>
 182       <entry>children</entry>
 183       <entry>ReadOnly</entry>
 184       <entry>WidgetList</entry>
 185       <entry>R</entry>
 186       <entry>NULL</entry>
 187     </row>
 188     <row>
 189       <entry>colormap</entry>
 190       <entry>Colormap</entry>
 191       <entry>Colormap</entry>
 192       <entry></entry>
 193       <entry>Parent's Colormap</entry>
 194     </row>
 195     <row>
 196       <entry>cursor</entry>
 197       <entry>Cursor</entry>
 198       <entry>Cursor</entry>
 199       <entry></entry>
 200       <entry>None</entry>
 201     </row>
 202     <row>
 203       <entry>depth</entry>
 204       <entry>Depth</entry>
 205       <entry>int</entry>
 206       <entry>C</entry>
 207       <entry>Parent's Depth</entry>
 208     </row>
 209     <row>
 210       <entry>destroyCallback</entry>
 211       <entry>Callback</entry>
 212       <entry>XtCallbackList</entry>
 213       <entry></entry>
 214       <entry>NULL</entry>
 215     </row>
 216     <row>
 217       <entry>gripCursor</entry>
 218       <entry>Cursor</entry>
 219       <entry>Cursor</entry>
 220       <entry>A</entry>
 221       <entry>Depends on orientation</entry>
 222     </row>
 223     <row>
 224       <entry>gripIndent</entry>
 225       <entry>GripIndent</entry>
 226       <entry>Position</entry>
 227       <entry></entry>
 228       <entry>10</entry>
 229     </row>
 230     <row>
 231       <entry>gripTranslations</entry>
 232       <entry>Translations</entry>
 233       <entry>TranslationTable</entry>
 234       <entry></entry>
 235       <entry>see below</entry>
 236     </row>
 237     <row>
 238       <entry>height</entry>
 239       <entry>Height</entry>
 240       <entry>Dimension</entry>
 241       <entry>A</entry>
 242       <entry>Depends on orientation</entry>
 243     </row>
 244     <row>
 245       <entry>horizontalBetweenCursor</entry>
 246       <entry>Cursor</entry>
 247       <entry>Cursor</entry>
 248       <entry></entry>
 249       <entry>sb_up_arrow</entry>
 250     </row>
 251     <row>
 252       <entry>horizontalGripCursor</entry>
 253       <entry>Cursor</entry>
 254       <entry>Cursor</entry>
 255       <entry></entry>
 256       <entry>sb_h_double_arrow</entry>
 257     </row>
 258     <row>
 259       <entry>internalBorderColor</entry>
 260       <entry>BorderColor</entry>
 261       <entry>Pixel</entry>
 262       <entry></entry>
 263       <entry>XtDefaultForeground</entry>
 264     </row>
 265     <row>
 266       <entry>internalBorderWidth</entry>
 267       <entry>BorderWidth</entry>
 268       <entry>Dimension</entry>
 269       <entry></entry>
 270       <entry>1</entry>
 271     </row>
 272     <row>
 273       <entry>leftCursor</entry>
 274       <entry>Cursor</entry>
 275       <entry>Cursor</entry>
 276       <entry></entry>
 277       <entry>sb_left_arrow</entry>
 278     </row>
 279     <row>
 280       <entry>lowerCursor</entry>
 281       <entry>Cursor</entry>
 282       <entry>Cursor</entry>
 283       <entry></entry>
 284       <entry>sb_down_arrow</entry>
 285     </row>
 286     <row>
 287       <entry>mappedWhenManaged</entry>
 288       <entry>MappedWhenManaged</entry>
 289       <entry>Boolean</entry>
 290       <entry></entry>
 291       <entry>True</entry>
 292     </row>
 293     <row>
 294       <entry>numChildren</entry>
 295       <entry>ReadOnly</entry>
 296       <entry>Cardinal</entry>
 297       <entry>R</entry>
 298       <entry>0</entry>
 299     </row>
 300     <row>
 301       <entry>orientation</entry>
 302       <entry>Orientation</entry>
 303       <entry>Orientation</entry>
 304       <entry></entry>
 305       <entry>XtorientVertical</entry>
 306     </row>
 307     <row>
 308       <entry>refigureMode</entry>
 309       <entry>Boolean</entry>
 310       <entry>Boolean</entry>
 311       <entry></entry>
 312       <entry>True</entry>
 313     </row>
 314     <row>
 315       <entry>rightCursor</entry>
 316       <entry>Cursor</entry>
 317       <entry>Cursor</entry>
 318       <entry></entry>
 319       <entry>sb_right_arrow</entry>
 320     </row>
 321     <row>
 322       <entry>screen</entry>
 323       <entry>Screen</entry>
 324       <entry>Screen</entry>
 325       <entry>R</entry>
 326       <entry>Parent's Screen</entry>
 327     </row>
 328     <row>
 329       <entry>sensitive</entry>
 330       <entry>Sensitive</entry>
 331       <entry>Boolean</entry>
 332       <entry></entry>
 333       <entry>True</entry>
 334     </row>
 335     <row>
 336       <entry>translations</entry>
 337       <entry>Translations</entry>
 338       <entry>TranslationTable</entry>
 339       <entry></entry>
 340       <entry>NULL</entry>
 341     </row>
 342     <row>
 343       <entry>upperCursor</entry>
 344       <entry>Cursor</entry>
 345       <entry>Cursor</entry>
 346       <entry></entry>
 347       <entry>sb_up_arrow</entry>
 348     </row>
 349     <row>
 350       <entry>verticalBetweenCursor</entry>
 351       <entry>Cursor</entry>
 352       <entry>Cursor</entry>
 353       <entry></entry>
 354       <entry>sb_left_arrow</entry>
 355     </row>
 356     <row>
 357       <entry>verticalGripCursor</entry>
 358       <entry>Cursor</entry>
 359       <entry>Cursor</entry>
 360       <entry></entry>
 361       <entry>sb_v_double_arrow</entry>
 362     </row>
 363     <row>
 364       <entry>width</entry>
 365       <entry>Width</entry>
 366       <entry>Dimension</entry>
 367       <entry>A</entry>
 368       <entry>Depends on orientation</entry>
 369     </row>
 370     <row>
 371       <entry>x</entry>
 372       <entry>Paned</entry>
 373       <entry>Position</entry>
 374       <entry></entry>
 375       <entry>0</entry>
 376     </row>
 377     <row>
 378       <entry>y</entry>
 379       <entry>Paned</entry>
 380       <entry>Position</entry>
 381       <entry></entry>
 382       <entry>0</entry>
 383     </row>
 384     <row>
 385       <entry>_</entry>
 386     </row>
 387   </tbody>
 388   </tgroup>
 389 </informaltable>
 390 <!-- .Ac -->
 391 <!-- .As -->
 392 <!-- .Bg -->
 393 <!-- .Gp -->
 394 <!-- .Bc -->
 395 <!-- .Bp -->
 396 <!-- .Bw -->
 397 <!-- .Ch -->
 398 <!-- .Cm -->
 399 <variablelist>
 400   <varlistentry>
 401     <term>
 402       <function>cursor</function>
 403     </term>
 404     <listitem>
 405       <para>
 406 The cursor to use when the mouse pointer is over the Paned widget, but
 407 not in any of its children (children may also inherit this cursor).  It
 408 should be noted that the internal borders are actually part of the Paned
 409 widget, not the children.
 410 <!-- .Dp -->
 411 <!-- .Dc -->
 412       </para>
 413     </listitem>
 414   </varlistentry>
 415   <varlistentry>
 416     <term>
 417       <function>gripCursor</function>
 418     </term>
 419     <listitem>
 420       <para>
 421 The cursor to use when the grips are not active.  The default value is
 422 <function>verticalGripCursor</function> or <function>horizontalGripCursor</function> depending on
 423 the orientation of the Paned widget.
 424       </para>
 425     </listitem>
 426   </varlistentry>
 427   <varlistentry>
 428     <term>
 429       <function>gripIndent</function>
 430     </term>
 431     <listitem>
 432       <para>
 433 The amount of space left between the right (or bottom) edge of the
 434 Paned widget and all the grips.
 435       </para>
 436     </listitem>
 437   </varlistentry>
 438   <varlistentry>
 439     <term>
 440       <function>gripTranslation</function>
 441     </term>
 442     <listitem>
 443       <para>
 444 Translation table that will be applied to all grips.
 445 <!-- .Hw -->
 446       </para>
 447     </listitem>
 448   </varlistentry>
 449   <varlistentry>
 450     <term>
 451       <function>horizontalBetweenCursor</function>
 452     </term>
 453     <listitem>
 454       <para>
 455 <!-- .br -->
 456 <!-- .ns -->
 457       </para>
 458     </listitem>
 459   </varlistentry>
 460   <varlistentry>
 461     <term>
 462       <function>verticalBetweenCursor</function>
 463     </term>
 464     <listitem>
 465       <para>
 466 The cursor to be used for the grip when changing the boundary between
 467 two panes.  These resources allow the cursors to be different
 468 depending on the orientation of the Paned widget.
 469       </para>
 470     </listitem>
 471   </varlistentry>
 472   <varlistentry>
 473     <term>
 474       <function>horizontalGripCursor</function>
 475     </term>
 476     <listitem>
 477       <para>
 478 <!-- .br -->
 479 <!-- .ns -->
 480       </para>
 481     </listitem>
 482   </varlistentry>
 483   <varlistentry>
 484     <term>
 485       <function>verticalGripCursor</function>
 486     </term>
 487     <listitem>
 488       <para>
 489 The cursor to be used for the grips when they are not active. These
 490 resources allow the cursors to be different depending on the
 491 orientation of the Paned widget.
 492       </para>
 493     </listitem>
 494   </varlistentry>
 495   <varlistentry>
 496     <term>
 497       <function>internalBorderColor</function>
 498     </term>
 499     <listitem>
 500       <para>
 501 A pixel value which indexes the widget's colormap to derive the internal
 502 border color of the widget's window.  The class name of this resource
 503 allows <emphasis remap='I'>Paned*BorderColor: blue</emphasis> to set the internal border color
 504 for the Paned widget.  An optimization is invoked if
 505 <function>internalBorderColor</function> and <function>background</function> are the same, and the
 506 internal borders are not drawn.  <function>internalBorderWidth</function> is still left
 507 between the panes, however.
 508       </para>
 509     </listitem>
 510   </varlistentry>
 511   <varlistentry>
 512     <term>
 513       <function>internalBorderWidth</function>
 514     </term>
 515     <listitem>
 516       <para>
 517 The width of the internal borders.  This is the amount of space left
 518 between the panes.  The class name of this resource allows
 519 <emphasis remap='I'>Paned*BorderWidth: 3</emphasis> to set the internal border width for the
 520 Paned widget.
 521       </para>
 522     </listitem>
 523   </varlistentry>
 524   <varlistentry>
 525     <term>
 526       <function>leftCursor</function>
 527     </term>
 528     <listitem>
 529       <para>
 530 <!-- .br -->
 531 <!-- .ns -->
 532       </para>
 533     </listitem>
 534   </varlistentry>
 535   <varlistentry>
 536     <term>
 537       <function>rightCursor</function>
 538     </term>
 539     <listitem>
 540       <para>
 541 The cursor used to indicate which is the <emphasis remap='I'>important</emphasis> pane to resize
 542 when the Paned widget is oriented horizontally.
 543       </para>
 544     </listitem>
 545   </varlistentry>
 546   <varlistentry>
 547     <term>
 548       <function>lowerCursor</function>
 549     </term>
 550     <listitem>
 551       <para>
 552 <!-- .br -->
 553 <!-- .ns -->
 554       </para>
 555     </listitem>
 556   </varlistentry>
 557   <varlistentry>
 558     <term>
 559       <function>upperCursor</function>
 560     </term>
 561     <listitem>
 562       <para>
 563 The cursor used to indicate which is the <emphasis remap='I'>important</emphasis> pane to resize
 564 when the Paned widget is oriented vertically.
 565 <!-- .Mm -->
 566 <!-- .Nc -->
 567 This is not the same as the number of panes, since this also contains a
 568 grip for some of the panes, use <xref linkend='XawPanedGetNumSub' xrefstyle='select: title'/> to retrieve the
 569 number of panes.
 570       </para>
 571     </listitem>
 572   </varlistentry>
 573   <varlistentry>
 574     <term>
 575       <function>orientation</function>
 576     </term>
 577     <listitem>
 578       <para>
 579 The orientation to stack the panes.  This value can be either
 580 <function>XtorientVertical</function> or <function>XtorientHorizontal</function>.
 581 <!-- .IN "XtorientVertical" "" -->
 582 <!-- .IN "XtorientHorizontal" "" -->
 583 <!-- .IN "conversions" "Orientation" -->
 584 <!-- .Rs "vertical \fPand\fB horizontal" -->
 585       </para>
 586     </listitem>
 587   </varlistentry>
 588   <varlistentry>
 589     <term>
 590       <function>refigureMode</function>
 591     </term>
 592     <listitem>
 593       <para>
 594 This resource allows pane layout to be suspended.  If this value is
 595 <function>False</function>, then no layout actions will be taken.  This may improve
 596 efficiency when adding or removing more than one pane from the Paned
 597 widget.
 598 <!-- .Sc -->
 599 <!-- .Se -->
 600 <!-- .Tr -->
 601 <!-- .Xy -->
 602     </para>
 603   </listitem>
 604   </varlistentry>
 605 </variablelist>
 606 </para>
 607 </sect2>
 608 <sect2 id='Paned::Constraint_Resources'>
 609 <title>Constraint Resources</title>
 610 <para>
 611 <!-- .LP -->
 612 <!-- .IN "Paned widget" "constraint resources" -->
 613 Each child of the Paned widget may request special layout resources
 614 be applied to it.  These <emphasis remap='I'>constraint</emphasis> resources allow the Paned
 615 widget's children to specify individual layout requirements.
 616 </para>
 617 <para>
 618 <!-- .LP -->
 619 <informaltable>
 620   <tgroup cols='5' align='center'>
 621   <colspec colname='c1'/>
 622   <colspec colname='c2'/>
 623   <colspec colname='c3'/>
 624   <colspec colname='c4'/>
 625   <colspec colname='c5'/>
 626   <thead>
 627     <row>
 628       <entry>Name</entry>
 629       <entry>Class</entry>
 630       <entry>Type</entry>
 631       <entry>Notes</entry>
 632       <entry>Default Value</entry>
 633     </row>
 634   </thead>
 635   <tbody>
 636     <row>
 637       <entry>allowResize</entry>
 638       <entry>Boolean</entry>
 639       <entry>Boolean</entry>
 640       <entry></entry>
 641       <entry>False</entry>
 642     </row>
 643     <row>
 644       <entry>max</entry>
 645       <entry>Max</entry>
 646       <entry>Dimension</entry>
 647       <entry></entry>
 648       <entry>Infinity</entry>
 649     </row>
 650     <row>
 651       <entry>min</entry>
 652       <entry>Min</entry>
 653       <entry>Dimension</entry>
 654       <entry></entry>
 655       <entry>Height of Grips</entry>
 656     </row>
 657     <row>
 658       <entry>preferredPaneSize</entry>
 659       <entry>PreferredPaneSize</entry>
 660       <entry>Dimension</entry>
 661       <entry></entry>
 662       <entry>ask child</entry>
 663     </row>
 664     <row>
 665       <entry>resizeToPreferred</entry>
 666       <entry>Boolean</entry>
 667       <entry>Boolean</entry>
 668       <entry></entry>
 669       <entry>False</entry>
 670     </row>
 671     <row>
 672       <entry>showGrip</entry>
 673       <entry>ShowGrip</entry>
 674       <entry>Boolean</entry>
 675       <entry></entry>
 676       <entry>True</entry>
 677     </row>
 678     <row>
 679       <entry>skipAdjust</entry>
 680       <entry>Boolean</entry>
 681       <entry>Boolean</entry>
 682       <entry></entry>
 683       <entry>False</entry>
 684     </row>
 685     <row>
 686       <entry>_</entry>
 687     </row>
 688   </tbody>
 689   </tgroup>
 690 </informaltable>
 691 <variablelist>
 692   <varlistentry>
 693     <term>
 694       <function>allowResize</function>
 695     </term>
 696     <listitem>
 697       <para>
 698 If this value is <function>False</function> the the Paned widget will disallow all
 699 geometry requests from this child.
 700       </para>
 701     </listitem>
 702   </varlistentry>
 703   <varlistentry>
 704     <term>
 705       <function>max</function>
 706     </term>
 707     <listitem>
 708       <para>
 709 <!-- .br -->
 710 <!-- .ns -->
 711       </para>
 712     </listitem>
 713   </varlistentry>
 714   <varlistentry>
 715     <term>
 716       <function>min</function>
 717     </term>
 718     <listitem>
 719       <para>
 720 The absolute maximum or minimum size for this pane.  These values will
 721 never be overridden by the Paned widget.  This may cause some panes to be
 722 pushed off the bottom (or right) edge of the paned widget.
 723       </para>
 724     </listitem>
 725   </varlistentry>
 726   <varlistentry>
 727     <term>
 728       <function>preferredPaneSize</function>
 729     </term>
 730     <listitem>
 731       <para>
 732 Normally the paned widget makes a QueryGeometry call on a child to
 733 determine the preferred size of the child's pane.  There are times
 734 when the application programmer or the user has a better idea of the
 735 preferred size of a pane.  Setting this resource causes the value
 736 passed to be interpreted as the preferred size, in pixels, of this pane.
 737       </para>
 738     </listitem>
 739   </varlistentry>
 740   <varlistentry>
 741     <term>
 742       <function>resizeToPreferred</function>
 743     </term>
 744     <listitem>
 745       <para>
 746 Determines whether or not to resize each pane to its preferred size
 747 when the Paned widget is resized.  See <function>Layout Semantics</function> for details.
 748       </para>
 749     </listitem>
 750   </varlistentry>
 751   <varlistentry>
 752     <term>
 753       <function>showGrip</function>
 754     </term>
 755     <listitem>
 756       <para>
 757 If <function>True</function> then a grip will be shown for this pane.  The grip
 758 associated with a pane is either below or to the right of the pane.  No
 759 grip is ever shown for the last pane.
 760       </para>
 761     </listitem>
 762   </varlistentry>
 763   <varlistentry>
 764     <term>
 765       <function>skipAdjust</function>
 766     </term>
 767     <listitem>
 768       <para>
 769 This resource is used to determine which pane is forced to be resized.
 770 Setting this value to <function>True</function> makes this pane less likely to be
 771 forced to be resized.  See <function>Layout Semantics</function> for details.
 772     </para>
 773   </listitem>
 774   </varlistentry>
 775 </variablelist>
 776 </para>
 777 </sect2>
 778 <sect2 id='Paned::Layout_Semantics'>
 779 <title>Layout Semantics</title>
 780 <para>
 781 <!-- .LP -->
 782 <!-- .IN "Paned widget" "layout semantics" -->
 783 In order to make effective use of the Paned widget it is helpful to know
 784 the rules it uses to determine which child will be resized in any given
 785 situation.  There are three rules used to determine which child is
 786 resized.  While these rules are always the same, the panes that are
 787 searched can change depending upon what caused the relayout.
 788 </para>
 789 <para>
 790 <!-- .LP -->
 791 <!-- .sp -->
 792 <function>Layout Rules</function>
 793 <variablelist>
 794   <varlistentry>
 795     <term>
 796       <function>1</function>
 797     </term>
 798     <listitem>
 799       <para>
 800 Do not let a pane grow larger than its <function>max</function> or smaller than its
 801 <function>min</function>.
 802       </para>
 803     </listitem>
 804   </varlistentry>
 805   <varlistentry>
 806     <term>
 807       <function>2</function>
 808     </term>
 809     <listitem>
 810       <para>
 811 Do not adjust panes with <function>skipAdjust</function> set.
 812       </para>
 813     </listitem>
 814   </varlistentry>
 815   <varlistentry>
 816     <term>
 817       <function>3</function>
 818     </term>
 819     <listitem>
 820       <para>
 821 Do not adjust panes away from their preferred size, although moving one
 822 closer to its preferred size is fine.
 823     </para>
 824   </listitem>
 825   </varlistentry>
 826 </variablelist>
 827 </para>
 828 <para>
 829 <!-- .LP -->
 830 When searching the children the Paned widget looks for panes that
 831 satisfy all the rules, and if unsuccessful then it eliminates rule 3
 832 and then 2.  Rule 1 is always enforced.
 833 </para>
 834 <para>
 835 <!-- .LP -->
 836 If the relayout is due to a resize or change in management then the
 837 panes are searched from bottom to top.  If the relayout is due to grip
 838 movement then they are searched from the grip selected in the direction
 839 opposite the pane selected.
 840 </para>
 841 <sect3 id="Resizing_Panes_from_a_Grip_Action">
 842 <title>Resizing Panes from a Grip Action</title>
 843 <para>
 844 <!-- .LP -->
 845 The pane above the grip is resized by invoking the GripAction with
 846 <function>UpLeftPane</function> specified.  The panes below the grip are each checked
 847 against all rules, then rules 2 and 1 and finally against rule 1 only.
 848 No pane above the chosen pane will ever be resized.
 849 </para>
 850 <para>
 851 <!-- .LP -->
 852 The pane below the grip is resized by invoking the GripAction with
 853 <function>LowRightPane</function> specified.  The panes above the grip are each
 854 checked in this case.  No pane below the chosen pane will ever be resized.
 855 </para>
 856 <para>
 857 <!-- .LP -->
 858 Invoking GripAction with <function>ThisBorderOnly</function> specified just moves the
 859 border between the panes.  No other panes are ever resized.
 860 </para>
 861 </sect3>
 862 <sect3 id='Resizing_Panes_after_the_Paned_widget_is_resized'>
 863 <title>Resizing Panes after the Paned widget is resized.</title>
 864 <para>
 865 <!-- .LP -->
 866 When the Pane widget is resized it must determine a new size for each
 867 pane.  There are two methods of doing this.  The Paned widget can either
 868 give each pane its preferred size and then resize the panes to fit, or
 869 it can use the current sizes and then resize the panes to fit.  The
 870 <function>resizeToPreferred</function> resource allows the application to tell the
 871 Paned widget whether to query the child about its preferred size
 872 (subject to the the <function>preferredPaneSize</function>) or to use the current size
 873 when refiguring the pane locations after the pane has been resized.
 874 </para>
 875 <para>
 876 <!-- .LP -->
 877 There is one special case.  All panes assume they should resize to
 878 their preferred size until the Paned widget becomes visible to the user.
 879 </para>
 880 </sect3>
 881 <sect3 id="Managing_Children_and_Geometry_Management">
 882 <title>Managing Children and Geometry Management</title>
 883 <para>
 884 <!-- .LP -->
 885 The Paned widget always resizes its children to their preferred sizes when
 886 a new child is managed, or a geometry management request is honored.
 887 The Paned widget will first attempt to resize itself to contain its
 888 panes exactly.  If this is not possible then it will hunt through the
 889 children, from bottom to top (right to left), for a pane to resize.
 890 </para>
 891 </sect3>
 892 <sect3 id='Paned::Special_Considerations'>
 893 <title>Special Considerations</title>
 894 <para>
 895 <!-- .LP -->
 896 When a user resizes a pane with the grips, the Paned widget assumes that
 897 this new size is the preferred size of the pane.
 898 </para>
 899 </sect3>
 900 </sect2>
 901 <sect2 id="Grip_Translations">
 902 <title>Grip Translations</title>
 903 <para>
 904 <!-- .LP -->
 905 The Paned widget has no action routines of its own, as all actions are
 906 handled through the grips.  The grips are each assigned a default
 907 Translation table.
 908 </para>
 909 <para>
 910 <!-- .LP -->
 911 <!-- .sp -->
 912 <literallayout class="monospaced">
 913 <!-- .TA .5i 2.25i -->
 914 <!-- .ta .5i 2.25i -->
 915         &lt;Btn1Down&gt;:       GripAction(Start, UpLeftPane)
 916 <!-- .IN "GripAction" "" -->
 917         &lt;Btn2Down&gt;:       GripAction(Start, ThisBorderOnly)
 918         &lt;Btn3Down&gt;:       GripAction(Start, LowRightPane)
 919         &lt;Btn1Motion&gt;:     GripAction(Move, UpLeftPane)
 920         &lt;Btn2Motion&gt;:     GripAction(Move, ThisBorderOnly)
 921         &lt;Btn3Motion&gt;:     GripAction(Move, LowRightPane)
 922         Any&lt;BtnUp&gt;:       GripAction(Commit)
 923 </literallayout>
 924 <!-- .sp -->
 925 </para>
 926 <para>
 927 <!-- .LP -->
 928 The Paned widget interprets the <function>GripAction</function> as taking two arguments.
 929 <!-- .IN "GripAction" "" -->
 930 The first argument may be any of the following:
 931 <variablelist>
 932   <varlistentry>
 933     <term>
 934       <function>Start</function>
 935     </term>
 936     <listitem>
 937       <para>
 938 Sets up the Paned widget for resizing and changes the cursor of the
 939 grip.  The second argument determines which pane will be resized, and
 940 can take on any of the three values shown above.
 941       </para>
 942     </listitem>
 943   </varlistentry>
 944   <varlistentry>
 945     <term>
 946       <function>Move</function>
 947     </term>
 948     <listitem>
 949       <para>
 950 The internal borders are drawn over the current pane locations to
 951 animate where the borders would actually be placed if you were to move
 952 this border as shown.  The second argument must match the second argument
 953 that was passed to the <function>Start</function> action, that began this process.  If
 954 these arguments are not passed, the behavior is undefined.
 955       </para>
 956     </listitem>
 957   </varlistentry>
 958   <varlistentry>
 959     <term>
 960       <function>Commit</function>
 961     </term>
 962     <listitem>
 963       <para>
 964 This argument causes the Paned widget to commit the changes selected
 965 by the previously started action.  The cursor is changed back to the
 966 grip's inactive cursor.  No second argument is needed in this case.
 967     </para>
 968   </listitem>
 969   </varlistentry>
 970 </variablelist>
 971 </para>
 972 </sect2>
 973 <sect2 id='Paned::Convenience_Routines'>
 974 <title>Convenience Routines</title>
 975 <para>
 976 <!-- .LP -->
 977 <!-- .IN "Paned widget" "enable pane resizing" -->
 978 <!-- .IN "Paned widget" "disable pane resizing" -->
 979 To enable or disable a child's request for pane resizing,
 980 use
 981 <function>XawPanedAllowResize :</function>
 982 <!-- .IN "XawPanedAllowResize" "" "@DEF@" -->
 983 <funcsynopsis id='XawPanedAllowResize'>
 984 <funcprototype>
 985   <funcdef>void<function> XawPanedAllowResize</function></funcdef>
 986   <paramdef>Widget<parameter> w</parameter></paramdef>
 987   <paramdef>Boolean<parameter> allow_resize</parameter></paramdef>
 988 </funcprototype>
 989 </funcsynopsis>
 990 <!-- .FN -->
 991 <variablelist>
 992   <varlistentry>
 993     <term>
 994       <emphasis remap='I'>w</emphasis>
 995     </term>
 996     <listitem>
 997       <para>
 998 Specifies the child pane.
 999       </para>
1000     </listitem>
1001   </varlistentry>
1002   <varlistentry>
1003     <term>
1004       <emphasis remap='I'>allow_resize</emphasis>
1005     </term>
1006     <listitem>
1007       <para>
1008 Specifies whether or not resizing requests for this child will be
1009 granted by the Paned widget.
1010     </para>
1011   </listitem>
1012   </varlistentry>
1013 </variablelist>
1014 </para>
1015 <para>
1016 <!-- .LP -->
1017 If allow_resize is <function>True</function>, the Paned widget allows geometry
1018 requests from the child to change the pane's height. If allow_resize
1019 is <function>False</function>, the Paned widget ignores geometry requests from the
1020 child to change the pane's height. The default state is <function>True</function>
1021 before the Pane is realized and <function>False</function> after it is realized.
1022 This procedure is equivalent to changing the <function>allowResize</function>
1023 constraint resource for the child.
1024 </para>
1025 <para>
1026 <!-- .LP -->
1027 <!-- .sp -->
1028 <!-- .IN "Paned widget" "change height settings" -->
1029 To change the minimum and maximum height settings for a pane, use
1030 <function>XawPanedSetMinMax :</function>
1031 <!-- .IN "XawPanedSetMinMax" "" "@DEF@" -->
1032 <funcsynopsis id='XawPanedSetMinMax'>
1033 <funcprototype>
1034   <funcdef>void<function> XawPanedSetMinMax</function></funcdef>
1035   <paramdef>Widget<parameter> w</parameter></paramdef>
1036   <paramdef>intmin,<parameter> max</parameter></paramdef>
1037 </funcprototype>
1038 </funcsynopsis>
1039 <!-- .FN -->
1040 <variablelist>
1041   <varlistentry>
1042     <term>
1043       <emphasis remap='I'>w</emphasis>
1044     </term>
1045     <listitem>
1046       <para>
1047 Specifies the child pane.
1048       </para>
1049     </listitem>
1050   </varlistentry>
1051   <varlistentry>
1052     <term>
1053       <emphasis remap='I'>min</emphasis>
1054     </term>
1055     <listitem>
1056       <para>
1057 Specifies the new minimum height of the child, expressed in pixels.
1058       </para>
1059     </listitem>
1060   </varlistentry>
1061   <varlistentry>
1062     <term>
1063       <emphasis remap='I'>max</emphasis>
1064     </term>
1065     <listitem>
1066       <para>
1067 Specifies new maximum height of the child, expressed in pixels.
1068     </para>
1069   </listitem>
1070   </varlistentry>
1071 </variablelist>
1072 </para>
1073 <para>
1074 <!-- .LP -->
1075 This procedure is equivalent to setting the <function>min</function> and <function>max</function>
1076 constraint resources for the child.
1077 </para>
1078 <para>
1079 <!-- .LP -->
1080 <!-- .sp -->
1081 <!-- .IN "Paned widget" "get height settings" -->
1082 To retrieve the minimum and maximum height settings for a pane, use
1083 <function>XawPanedGetMinMax :</function>
1084 <!-- .IN "XawPanedGetMinMax" "" "@DEF@" -->
1085 <funcsynopsis id='XawPanedGetMinMax'>
1086 <funcprototype>
1087   <funcdef>void<function> XawPanedGetMinMax</function></funcdef>
1088   <paramdef>Widget<parameter> w</parameter></paramdef>
1089   <paramdef>int*min_return,<parameter> *max_return</parameter></paramdef>
1090 </funcprototype>
1091 </funcsynopsis>
1092 <!-- .FN -->
1093 <variablelist>
1094   <varlistentry>
1095     <term>
1096       <emphasis remap='I'>w</emphasis>
1097     </term>
1098     <listitem>
1099       <para>
1100 Specifies the child pane.
1101       </para>
1102     </listitem>
1103   </varlistentry>
1104   <varlistentry>
1105     <term>
1106       <emphasis remap='I'>min_return</emphasis>
1107     </term>
1108     <listitem>
1109       <para>
1110 Returns the minimum height of the child, expressed in pixels.
1111       </para>
1112     </listitem>
1113   </varlistentry>
1114   <varlistentry>
1115     <term>
1116       <emphasis remap='I'>max_return</emphasis>
1117     </term>
1118     <listitem>
1119       <para>
1120 Returns the maximum height of the child, expressed in pixels.
1121     </para>
1122   </listitem>
1123   </varlistentry>
1124 </variablelist>
1125 </para>
1126 <para>
1127 <!-- .LP -->
1128 This procedure is equivalent to getting the <function>min</function> and <function>max</function>
1129 resources for this child child.
1130 </para>
1131 <para>
1132 <!-- .LP -->
1133 <!-- .sp -->
1134 <!-- .IN "Paned widget" "enable auto-reconfiguring" -->
1135 <!-- .IN "Paned widget" "disable auto-reconfiguring" -->
1136 To enable or disable automatic recalculation of pane sizes and positions,
1137 use
1138 <function>XawPanedSetRefigureMode :</function>
1139 <!-- .IN "XawPanedSetRefigureMode" "" "@DEF@" -->
1140 <funcsynopsis id='XawPanedSetRefigureMode'>
1141 <funcprototype>
1142   <funcdef>void<function> XawPanedSetRefigureMode</function></funcdef>
1143   <paramdef>Widget<parameter> w</parameter></paramdef>
1144   <paramdef>Boolean<parameter> mode</parameter></paramdef>
1145 </funcprototype>
1146 </funcsynopsis>
1147 <!-- .FN -->
1148 <variablelist>
1149   <varlistentry>
1150     <term>
1151       <emphasis remap='I'>w</emphasis>
1152     </term>
1153     <listitem>
1154       <para>
1155 Specifies the Paned widget.
1156       </para>
1157     </listitem>
1158   </varlistentry>
1159   <varlistentry>
1160     <term>
1161       <emphasis remap='I'>mode</emphasis>
1162     </term>
1163     <listitem>
1164       <para>
1165 Specifies whether the layout of the Paned widget is enabled (<function>True</function>)
1166 or disabled (<function>False</function>).
1167     </para>
1168   </listitem>
1169   </varlistentry>
1170 </variablelist>
1171 </para>
1172 <para>
1173 <!-- .LP -->
1174 When making several changes to the children of a Paned widget
1175 after the Paned has been realized, it is a good idea to disable
1176 relayout until after all changes have been made.
1177 </para>
1178 <para>
1179 <!-- .LP -->
1180 <!-- .sp -->
1181 <!-- .IN "Paned widget" "getting the number of children" -->
1182 To retrieve the number of panes in a paned widget use
1183 <xref linkend='XawPanedGetNumSub' xrefstyle='select: title'/>:
1184 <!-- .IN "XawPanedGetNumSub" "" "@DEF@" -->
1185 <funcsynopsis id='XawPanedGetNumSub'>
1186 <funcprototype>
1187   <funcdef>int<function> XawPanedGetNumSub</function></funcdef>
1188   <paramdef>Widget<parameter> w</parameter></paramdef>
1189 </funcprototype>
1190 </funcsynopsis>
1191 <!-- .FN -->
1192 <variablelist>
1193   <varlistentry>
1194     <term>
1195       <emphasis remap='I'>w</emphasis>
1196     </term>
1197     <listitem>
1198       <para>
1199 Specifies the Paned widget.
1200     </para>
1201   </listitem>
1202   </varlistentry>
1203 </variablelist>
1204 </para>
1205 <para>
1206 <!-- .LP -->
1207 This function returns the number of panes in the Paned widget.  This is
1208 <function>not</function> the same as the number of children, since the grips are also
1209 children of the Paned widget.
1210
1211 </para>
1212 </sect2>
1213 </sect1>