specs/Dialog.xml

   1 <sect1 id="Dialog_Widget">
   2 <title>Dialog Widget</title>
   3 <para>
   4 <!-- .LP -->
   5 <!-- .XS -->
   6 <!--    Dialog Widget -->
   7 <!-- .XE -->
   8 <!-- .IN "Dialog widget" "" "@DEF@" -->
   9 <literallayout class="monospaced">
  10 <!-- .TA 2.0i -->
  11 <!-- .ta 2.0i -->
  12 <!-- .sp -->
  13 Application Header file &lt;X11/Xaw/Dialog.h&gt;
  14 <!-- .IN "Dialog.h" "" -->
  15 Class Header file       &lt;X11/Xaw/DialogP.h&gt;
  16 <!-- .IN "DialogP.h" "" -->
  17 Class           dialogWidgetClass
  18 <!-- .IN "dialogWidgetClass" "" -->
  19 Class Name      Dialog
  20 <!-- .IN "Dialog widget" "class name" -->
  21 Superclass      Form
  22 <!-- .sp -->
  23 </literallayout>
  24 </para>
  25 <para>
  26 <!-- .LP -->
  27 The Dialog widget implements a commonly used interaction semantic to
  28 prompt for auxiliary input from a user.  For example, you can use a
  29 Dialog widget when an application requires a small piece of information,
  30 such as a filename, from the user.  A Dialog widget, which is simply a
  31 special case of the Form widget, provides a convenient way to create a
  32 preconfigured form.
  33 </para>
  34 <para>
  35 <!-- .LP -->
  36 The typical Dialog widget contains three areas.  The first line
  37 contains a description of the function of the Dialog widget, for
  38 example, the string <emphasis remap='I'>Filename:</emphasis>.  The second line contains an area
  39 into which the user types input.  The third line can contain buttons
  40 that let the user confirm or cancel the Dialog input.  Any of these
  41 areas may be omitted by the application.
  42 </para>
  43 <sect2 id="dialog_resources">
  44 <title>Resources</title>
  45 <para>
  46 <!-- .LP -->
  47 When creating a Dialog widget instance, the following resources are
  48 retrieved from the argument list or the resource database:
  49 <!-- .IN "Dialog widget" "resources" -->
  50 <informaltable>
  51   <tgroup cols='5' align='center'>
  52   <colspec colname='c1'/>
  53   <colspec colname='c2'/>
  54   <colspec colname='c3'/>
  55   <colspec colname='c4'/>
  56   <colspec colname='c5'/>
  57   <thead>
  58     <row>
  59       <entry>Name</entry>
  60       <entry>Class</entry>
  61       <entry>Type</entry>
  62       <entry>Notes</entry>
  63       <entry>Default Value</entry>
  64     </row>
  65   </thead>
  66   <tbody>
  67     <row>
  68       <entry>accelerators</entry>
  69       <entry>Accelerators</entry>
  70       <entry>AcceleratorTable</entry>
  71       <entry></entry>
  72       <entry>NULL</entry>
  73     </row>
  74     <row>
  75       <entry>ancestorSensitive</entry>
  76       <entry>AncestorSensitive</entry>
  77       <entry>Boolean</entry>
  78       <entry>D</entry>
  79       <entry>True</entry>
  80     </row>
  81     <row>
  82       <entry>background</entry>
  83       <entry>Background</entry>
  84       <entry>Pixel</entry>
  85       <entry></entry>
  86       <entry>XtDefaultBackground</entry>
  87     </row>
  88     <row>
  89       <entry>backgroundPixmap</entry>
  90       <entry>Pixmap</entry>
  91       <entry>Pixmap</entry>
  92       <entry></entry>
  93       <entry>XtUnspecifiedPixmap</entry>
  94     </row>
  95     <row>
  96       <entry>borderColor</entry>
  97       <entry>BorderColor</entry>
  98       <entry>Pixel</entry>
  99       <entry></entry>
 100       <entry>XtDefaultForeground</entry>
 101     </row>
 102     <row>
 103       <entry>borderPixmap</entry>
 104       <entry>Pixmap</entry>
 105       <entry>Pixmap</entry>
 106       <entry></entry>
 107       <entry>XtUnspecifiedPixmap</entry>
 108     </row>
 109     <row>
 110       <entry>borderWidth</entry>
 111       <entry>BorderWidth</entry>
 112       <entry>Dimension</entry>
 113       <entry></entry>
 114       <entry>1</entry>
 115     </row>
 116     <row>
 117       <entry>children</entry>
 118       <entry>ReadOnly</entry>
 119       <entry>WidgetList</entry>
 120       <entry>R</entry>
 121       <entry>NULL</entry>
 122     </row>
 123     <row>
 124       <entry>colormap</entry>
 125       <entry>Colormap</entry>
 126       <entry>Colormap</entry>
 127       <entry></entry>
 128       <entry>Parent's Colormap</entry>
 129     </row>
 130     <row>
 131       <entry>defaultDistance</entry>
 132       <entry>Thickness</entry>
 133       <entry>int</entry>
 134       <entry></entry>
 135       <entry>4</entry>
 136     </row>
 137     <row>
 138       <entry>depth</entry>
 139       <entry>Depth</entry>
 140       <entry>int</entry>
 141       <entry>C</entry>
 142       <entry>Parent's Depth</entry>
 143     </row>
 144     <row>
 145       <entry>destroyCallback</entry>
 146       <entry>Callback</entry>
 147       <entry>XtCallbackList</entry>
 148       <entry></entry>
 149       <entry>NULL</entry>
 150     </row>
 151     <row>
 152       <entry>height</entry>
 153       <entry>Height</entry>
 154       <entry>Dimension</entry>
 155       <entry>A</entry>
 156       <entry>Enough space to contain all children</entry>
 157     </row>
 158     <row>
 159       <entry>icon</entry>
 160       <entry>Icon</entry>
 161       <entry>Bitmap</entry>
 162       <entry></entry>
 163       <entry>None</entry>
 164     </row>
 165     <row>
 166       <entry>label</entry>
 167       <entry>Label</entry>
 168       <entry>String</entry>
 169       <entry></entry>
 170       <entry>"label"</entry>
 171     </row>
 172     <row>
 173       <entry>mappedWhenManaged</entry>
 174       <entry>MappedWhenManaged</entry>
 175       <entry>Boolean</entry>
 176       <entry></entry>
 177       <entry>True</entry>
 178     </row>
 179     <row>
 180       <entry>numChildren</entry>
 181       <entry>ReadOnly</entry>
 182       <entry>Cardinal</entry>
 183       <entry>R</entry>
 184       <entry>0</entry>
 185     </row>
 186     <row>
 187       <entry>screen</entry>
 188       <entry>Screen</entry>
 189       <entry>Screen</entry>
 190       <entry>R</entry>
 191       <entry>Parent's Screen</entry>
 192     </row>
 193     <row>
 194       <entry>sensitive</entry>
 195       <entry>Sensitive</entry>
 196       <entry>Boolean</entry>
 197       <entry></entry>
 198       <entry>True</entry>
 199     </row>
 200     <row>
 201       <entry>translations</entry>
 202       <entry>Translations</entry>
 203       <entry>TranslationTable</entry>
 204       <entry></entry>
 205       <entry>NULL</entry>
 206     </row>
 207     <row>
 208       <entry>value</entry>
 209       <entry>Value</entry>
 210       <entry>String</entry>
 211       <entry></entry>
 212       <entry>no value widget</entry>
 213     </row>
 214     <row>
 215       <entry>width</entry>
 216       <entry>Width</entry>
 217       <entry>Dimension</entry>
 218       <entry>A</entry>
 219       <entry>Enough space to contain all children</entry>
 220     </row>
 221     <row>
 222       <entry>x</entry>
 223       <entry>Position</entry>
 224       <entry>Position</entry>
 225       <entry></entry>
 226       <entry>0</entry>
 227     </row>
 228     <row>
 229       <entry>y</entry>
 230       <entry>Position</entry>
 231       <entry>Position</entry>
 232       <entry></entry>
 233       <entry>0</entry>
 234     </row>
 235     <row>
 236       <entry>_</entry>
 237     </row>
 238   </tbody>
 239   </tgroup>
 240 </informaltable>
 241 <!-- .Ac -->
 242 <!-- .As -->
 243 <!-- .Bg -->
 244 <!-- .Gp -->
 245 <!-- .Bc -->
 246 <!-- .Bp -->
 247 <!-- .Bw -->
 248 <!-- .Ch -->
 249 <!-- .Cm -->
 250 <!-- .Dd -->
 251 <!-- .Dp -->
 252 <!-- .Dc -->
 253 <!-- .Hw -->
 254 <variablelist>
 255   <varlistentry>
 256     <term>
 257       <function>icon</function>
 258     </term>
 259     <listitem>
 260       <para>
 261 A pixmap image to be displayed immediately to the left of the
 262 Dialog widget's label.
 263       </para>
 264     </listitem>
 265   </varlistentry>
 266   <varlistentry>
 267     <term>
 268       <function>label</function>
 269     </term>
 270     <listitem>
 271       <para>
 272 A string to be displayed at the top of the Dialog widget.
 273 <!-- .Mm -->
 274 <!-- .Nc -->
 275 <!-- .Sc -->
 276 <!-- .Se -->
 277 <!-- .Tr -->
 278       </para>
 279     </listitem>
 280   </varlistentry>
 281   <varlistentry>
 282     <term>
 283       <function>value</function>
 284     </term>
 285     <listitem>
 286       <para>
 287 An initial value for the string field that the user will enter text
 288 into.  By default, no text entry field is available to the user.
 289 Specifying an initial value for <function>value</function> activates the text entry
 290 field.  If string input is desired, but no initial value is to be
 291 specified then set this resource to "" (empty string).
 292 <!-- .Xy -->
 293     </para>
 294   </listitem>
 295   </varlistentry>
 296 </variablelist>
 297 </para>
 298 </sect2>
 299 <sect2 id="Constraint_Resources">
 300 <title>Constraint Resources</title>
 301 <para>
 302 <!-- .LP -->
 303 <!-- .IN "Dialog widget" "constraint resources" -->
 304 Each child of the Dialog widget may request special layout resources
 305 be applied to it.  These <emphasis remap='I'>constraint</emphasis> resources allow the Dialog
 306 widget's children to specify individual layout requirements.
 307 </para>
 308 <para>
 309 <!-- .LP -->
 310 <informaltable>
 311   <tgroup cols='5' align='center'>
 312   <colspec colname='c1'/>
 313   <colspec colname='c2'/>
 314   <colspec colname='c3'/>
 315   <colspec colname='c4'/>
 316   <colspec colname='c5'/>
 317   <thead>
 318     <row>
 319       <entry>Name</entry>
 320       <entry>Class</entry>
 321       <entry>Type</entry>
 322       <entry>Notes</entry>
 323       <entry>Default Value</entry>
 324     </row>
 325   </thead>
 326   <tbody>
 327     <row>
 328       <entry>bottom</entry>
 329       <entry>Edge</entry>
 330       <entry>XawEdgeType</entry>
 331       <entry></entry>
 332       <entry>XawRubber</entry>
 333     </row>
 334     <row>
 335       <entry>fromHoriz</entry>
 336       <entry>Widget</entry>
 337       <entry>Widget</entry>
 338       <entry></entry>
 339       <entry>NULL (left edge of Dialog)</entry>
 340     </row>
 341     <row>
 342       <entry>fromVert</entry>
 343       <entry>Widget</entry>
 344       <entry>Widget </entry>
 345       <entry></entry>
 346       <entry>NULL (top edge of Dialog)</entry>
 347     </row>
 348     <row>
 349       <entry>horizDistance</entry>
 350       <entry>Thickness</entry>
 351       <entry>int</entry>
 352       <entry></entry>
 353       <entry><function>defaultDistance</function> resource</entry>
 354     </row>
 355     <row>
 356       <entry>left</entry>
 357       <entry>Edge</entry>
 358       <entry>XawEdgeType</entry>
 359       <entry></entry>
 360       <entry>XawRubber</entry>
 361     </row>
 362     <row>
 363       <entry>resizable</entry>
 364       <entry>Boolean</entry>
 365       <entry>Boolean</entry>
 366       <entry></entry>
 367       <entry>FALSE</entry>
 368     </row>
 369     <row>
 370       <entry>right</entry>
 371       <entry>Edge</entry>
 372       <entry>XawEdgeType</entry>
 373       <entry></entry>
 374       <entry>XawRubber</entry>
 375     </row>
 376     <row>
 377       <entry>top</entry>
 378       <entry>Edge</entry>
 379       <entry>XawEdgeType</entry>
 380       <entry></entry>
 381       <entry>XawRubber</entry>
 382     </row>
 383     <row>
 384       <entry>vertDistance</entry>
 385       <entry>Thickness</entry>
 386       <entry>int</entry>
 387       <entry></entry>
 388       <entry><function>defaultDistance</function> resource</entry>
 389     </row>
 390   </tbody>
 391   </tgroup>
 392 </informaltable>
 393
 394 <literallayout class="monospaced">
 395 bottom
 396 left
 397 right
 398 top            What to do with this edge of the child when
 399                the parent is resized.  This resource may be
 400                any edgeType.  See Layout Semantics for
 401                details.
 402
 403 fromHoriz
 404 fromVert       Which widget this child should be placed
 405                underneath (or to the right of).  If a value
 406                of NULL is specified then this widget will be
 407                positioned relative to the edge of the par-
 408                ent.
 409
 410 horizDistance
 411 vertDistance   The amount of space, in pixels, between this
 412                child and its left or upper neighbor.
 413
 414 resizable      If this resource is False then the parent
 415                widget will ignore all geometry request made
 416                by this child.  The parent may still resize
 417                this child itself, however.
 418 </literallayout>
 419 <!-- .Bt -->
 420 <!-- .Fh -->
 421 <!-- .Hd -->
 422 <!-- .Rl -->
 423 </para>
 424 </sect2>
 425 <sect2 id="dialog_layout_semantics">
 426 <title>Layout Semantics</title>
 427 <!-- .IN "Dialog widget" "layout semantics" -->
 428 <para>
 429 The Dialog widget uses two different sets of layout seman-
 430 tics.  One is used when initially laying out the children.
 431 The other is used when the Dialog is resized.
 432 </para>
 433 <para>
 434 The first layout method uses the <function>fromVert</function> mand <function>fromHoriz</function>
 435 resources to place the children of the Dialog.  A single
 436 pass is made through the Dialog widget's children in the
 437 order that they were created.  Each child is then placed in
 438 the Dialog widget below or to the right of the widget speci-
 439 fied by the <function>fromVert</function> mand <function>fromHoriz</function> mresources.  The distance
 440 the new child is placed from its left or upper neighbor is
 441 determined by the <function>horizDistance</function> mand <function>vertDistance</function> mresources.
 442 This implies some things about how the order of creation
 443 affects the possible placement of the children.  The Form
 444 widget registers a string to widget converter which does not
 445 postpone conversion and does not cache conversion results.
 446 </para>
 447 <para>
 448
 449 The second layout method is used when the Dialog is resized.
 450 It does not matter what causes this resize, and it is possi-
 451 ble for a resize to happen before the widget becomes visible
 452 (due to constraints imposed by the parent of the Dialog).
 453 This layout method uses the <function>bottom</function> ,
 454 <function>top</function> , <function>left</function> , and
 455 <function>right</function>
 456 resources.  These resources are used to determine what will
 457 happen to each edge of the child when the Dialog is resized.
 458 If a value of <function>XawChain</function>
 459 <emphasis remap='I'>&lt;something&gt;</emphasis>
 460  is specified, the the edge
 461 of the child will remain a fixed distance from the <emphasis remap='I'>chain</emphasis>
 462 edge of the Dialog.  For example if <function>XawChainLeft</function>
 463 mis specified for the <function>right</function> mresource of a child
 464 then the right edge
 465 of that child will remain a fixed distance from the left
 466 edge of the Dialog widget.  If a value of <function>XawRubber</function> mis spec-
 467 ified, that edge will grow by the same percentage that the
 468 Dialog grew.  For instance if the Dialog grows by 50% the
 469 left edge of the child (if specified as <function>XawRubber</function> mwill be
 470 50% farther from the left edge of the Dialog).  One must be
 471 very careful when specifying these resources, for when they
 472 are specified incorrectly children may overlap or completely
 473 occlude other children when the Dialog widget is resized.
 474 </para>
 475
 476 <para>
 477 <!-- .LP -->
 478 <informaltable>
 479   <tgroup cols='3' align='center'>
 480   <colspec colname='c1'/>
 481   <colspec colname='c2'/>
 482   <colspec colname='c3'/>
 483   <thead>
 484     <row>
 485       <entry>Edge Type</entry>
 486       <entry>Resource Name</entry>
 487       <entry>Description</entry>
 488     </row>
 489   </thead>
 490   <tbody>
 491     <row>
 492       <entry>XawChainBottom</entry>
 493       <entry>ChainBottom</entry>
 494       <entry>Edge remains a fixed distance from bottom of Dialog</entry>
 495     </row>
 496     <row>
 497       <entry>XawChainLeft</entry>
 498       <entry>ChainLeft</entry>
 499       <entry>Edge remains a fixed distance from left of Dialog</entry>
 500     </row>
 501     <row>
 502       <entry>XawChainRight</entry>
 503       <entry>ChainRight</entry>
 504       <entry>Edge remains a fixed distance from right of Dialog</entry>
 505     </row>
 506     <row>
 507       <entry>XawChainTop</entry>
 508       <entry>ChainTop</entry>
 509       <entry>Edge remains a fixed distance from top of Dialog</entry>
 510     </row>
 511     <row>
 512       <entry>XawRubber</entry>
 513       <entry>Rubber</entry>
 514       <entry>Edges will move a proportional distance</entry>
 515     </row>
 516   </tbody>
 517   </tgroup>
 518 </informaltable>
 519 </para>
 520 <sect3 id="Example">
 521 <title>Example</title>
 522 <para>
 523 <!-- .LP -->
 524 If you wish to force the Dialog to never resize one or more of its children
 525 then set <function>left</function> and <function>right</function> to <function>XawChainLeft</function> and
 526 <function>top</function> and <function>bottom</function> to <function>XawChainTop</function>.  This will cause
 527 the child to remain a fixed distance from the top and left
 528 edges of the Dialog, and to never resize.
 529 </para>
 530 </sect3>
 531 <sect3 id="Special_Considerations">
 532 <title>Special Considerations</title>
 533 <!-- .IN "Dialog widget" "special considerations" -->
 534 <para>
 535 <!-- .LP -->
 536 The Dialog widget automatically sets the <function>top</function> and <function>bottom</function>
 537 resources for all Children that are subclasses of the Command widget,
 538 as well as the widget children that are used to contain the <function>label</function>,
 539 <function>value</function>, and <function>icon</function>.  This policy allows the buttons at the
 540 bottom of the Dialog to interact correctly with the predefined children,
 541 and makes it possible for a client to simply create and manage a new
 542 Command button without having to specify its constraints.
 543 </para>
 544 <para>
 545 <!-- .LP -->
 546 The Dialog will also set <function>fromLeft</function> to the last button in the
 547 <!-- .IN "fromLeft" "" -->
 548 Dialog for each new button added to the Dialog widget.
 549 </para>
 550 <para>
 551 <!-- .LP -->
 552 The automatically added constraints cannot be overridden, as they are
 553 policy decisions of the Dialog widget.  If a more flexible Dialog is
 554 desired, the application is free to use the Form widget to create its
 555 own Dialog policy.
 556 </para>
 557 </sect3>
 558 </sect2>
 559 <sect2 id="Automatically_Created_Children_">
 560 <title>Automatically Created Children.</title>
 561 <!-- .IN "Dialog widget" "automatically created children" -->
 562 <para>
 563 <!-- .LP -->
 564 The Dialog uses Label widgets to contain the <function>label</function> and <function>icon</function>.
 565 These widgets are named <emphasis remap='I'>label</emphasis> and <emphasis remap='I'>icon</emphasis> respectively.  The
 566 Dialog <function>value</function> is contained in an AsciiText widget whose name is
 567 <function>value</function>.  Using <function>XtNameToWidget</function> the application can change
 568 <!-- .IN "XtNameToWidget" "" -->
 569 those resources associated with each of these widgets that are not
 570 available through the Dialog widget itself.
 571 </para>
 572 <para>
 573 <!-- .LP -->
 574 </para>
 575 </sect2>
 576 <sect2 id="dialog_convenience_routines">
 577 <title>Convenience Routines</title>
 578 <para>
 579 <!-- .LP -->
 580 To return the character string in the text field, use
 581 <!-- .PN XawDialogGetValueString . -->
 582 <!-- .IN "XawDialogGetValueString" "" "@DEF@" -->
 583 <funcsynopsis>
 584 <funcprototype>
 585   <funcdef>String<function> XawDialogGetValueString</function></funcdef>
 586   <paramdef>Widget<parameter> w</parameter></paramdef>
 587 </funcprototype>
 588 </funcsynopsis>
 589 <!-- .FN -->
 590 <variablelist>
 591   <varlistentry>
 592     <term>
 593       <emphasis remap='I'>w</emphasis>
 594     </term>
 595     <listitem>
 596       <para>
 597 Specifies the Dialog widget.
 598     </para>
 599   </listitem>
 600   </varlistentry>
 601 </variablelist>
 602 </para>
 603 <para>
 604 <!-- .LP -->
 605 This function returns a copy of the value string of the Dialog
 606 widget.  This string is allocated by the AsciiText widget and will
 607 remain valid and unchanged until another call to
 608 <function>XawDialogGetValueString</function> or an <function>XtGetValues</function> call on the
 609 <function>value</function> widget, when the string will be automatically freed, and
 610 a new string is returned.  This string may be freed earlier by calling
 611 the function <function>XawAsciiSourceFreeString</function>.
 612 <!-- .IN "XawAsciiSourceFreeString" "" -->
 613 </para>
 614 <para>
 615 <!-- .LP -->
 616 <!-- .sp -->
 617 To add a new button to the Dialog widget use
 618 <function>XawDialogAddButton</function>.
 619 <!-- .IN "XawDialogAddButton" "" "@DEF@" -->
 620 <funcsynopsis>
 621 <funcprototype>
 622   <funcdef>void<function> XawDialogAddButton</function></funcdef>
 623   <paramdef>Widget<parameter> w</parameter></paramdef>
 624   <paramdef>String<parameter> name</parameter></paramdef>
 625   <paramdef>XtCallbackProc<parameter> func</parameter></paramdef>
 626   <paramdef>XtPointer<parameter> client_data</parameter></paramdef>
 627 </funcprototype>
 628 </funcsynopsis>
 629 <!-- .FN -->
 630 <variablelist>
 631   <varlistentry>
 632     <term>
 633       <emphasis remap='I'>w</emphasis>
 634     </term>
 635     <listitem>
 636       <para>
 637 Specifies the Dialog widget.
 638       </para>
 639     </listitem>
 640   </varlistentry>
 641   <varlistentry>
 642     <term>
 643       <emphasis remap='I'>name</emphasis>
 644     </term>
 645     <listitem>
 646       <para>
 647 Specifies the name of the new Command button to be added to the Dialog.
 648       </para>
 649     </listitem>
 650   </varlistentry>
 651   <varlistentry>
 652     <term>
 653       <emphasis remap='I'>func</emphasis>
 654     </term>
 655     <listitem>
 656       <para>
 657 Specifies a callback function to be called when this button is activated.  If
 658 NULL is specified then no callback is added.
 659       </para>
 660     </listitem>
 661   </varlistentry>
 662   <varlistentry>
 663     <term>
 664       <emphasis remap='I'>client_data</emphasis>
 665     </term>
 666     <listitem>
 667       <para>
 668 Specifies the client_data to be passed to the <emphasis remap='I'>func</emphasis>.
 669     </para>
 670   </listitem>
 671   </varlistentry>
 672 </variablelist>
 673 </para>
 674 <para>
 675 <!-- .LP -->
 676 This function is merely a shorthand for the code sequence:
 677 <!-- .sp -->
 678 <literallayout class="monospaced">
 679 <!-- .SM -->
 680 <!-- .TA 1i 2i -->
 681 <!-- .ta 1i 2i -->
 682 {
 683         Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO);
 684         XtAddCallback(button, XtNcallback, func, client_data);
 685 }
 686 <!-- .NL -->
 687 </literallayout>
 688 <!-- .sp -->
 689
 690 </para>
 691 </sect2>
 692 </sect1>