1<sect1 id="Dialog_Widget"> 2<title>Dialog Widget</title> 3<para> 4<!-- .LP --> 5<!-- .XS --> 6<!-- Dialog Widget --> 7<!-- .XE --> 8<indexterm significance="preferred"><primary>Dialog widget</primary></indexterm> 9<literallayout class="monospaced"> 10<!-- .TA 2.0i --> 11<!-- .ta 2.0i --> 12<!-- .sp --> 13Application Header file <X11/Xaw/Dialog.h> 14<indexterm><primary>Dialog.h</primary></indexterm> 15Class Header file <X11/Xaw/DialogP.h> 16<indexterm><primary>DialogP.h</primary></indexterm> 17Class dialogWidgetClass 18<indexterm><primary>dialogWidgetClass</primary></indexterm> 19Class Name Dialog 20<indexterm><primary>Dialog widget</primary><secondary>class name</secondary></indexterm> 21Superclass Form 22<!-- .sp --> 23</literallayout> 24</para> 25<para> 26<!-- .LP --> 27The Dialog widget implements a commonly used interaction semantic to 28prompt for auxiliary input from a user. For example, you can use a 29Dialog widget when an application requires a small piece of information, 30such as a filename, from the user. A Dialog widget, which is simply a 31special case of the Form widget, provides a convenient way to create a 32preconfigured form. 33</para> 34<para> 35<!-- .LP --> 36The typical Dialog widget contains three areas. The first line 37contains a description of the function of the Dialog widget, for 38example, the string <emphasis remap='I'>Filename:</emphasis>. The second line contains an area 39into which the user types input. The third line can contain buttons 40that let the user confirm or cancel the Dialog input. Any of these 41areas may be omitted by the application. 42</para> 43<sect2 id='Dialog::Resources'> 44<title>Resources</title> 45<para> 46<!-- .LP --> 47When creating a Dialog widget instance, the following resources are 48retrieved from the argument list or the resource database: 49<indexterm><primary>Dialog widget</primary><secondary>resources</secondary></indexterm> 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> 261A pixmap image to be displayed immediately to the left of the 262Dialog widget's label. 263 </para> 264 </listitem> 265 </varlistentry> 266 <varlistentry> 267 <term> 268 <function>label</function> 269 </term> 270 <listitem> 271 <para> 272A 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> 287An initial value for the string field that the user will enter text 288into. By default, no text entry field is available to the user. 289Specifying an initial value for <function>value</function> activates the text entry 290field. If string input is desired, but no initial value is to be 291specified 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<indexterm><primary>Dialog widget</primary><secondary>constraint resources</secondary></indexterm> 304Each child of the Dialog widget may request special layout resources 305be applied to it. These <emphasis remap='I'>constraint</emphasis> resources allow the Dialog 306widget'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"> 395bottom 396left 397right 398top 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 403fromHoriz 404fromVert 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 410horizDistance 411vertDistance The amount of space, in pixels, between this 412 child and its left or upper neighbor. 413 414resizable 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<indexterm><primary>Dialog widget</primary><secondary>layout semantics</secondary></indexterm> 428<para> 429The Dialog widget uses two different sets of layout seman- 430tics. One is used when initially laying out the children. 431The other is used when the Dialog is resized. 432</para> 433<para> 434The first layout method uses the <function>fromVert</function> mand <function>fromHoriz</function> 435resources to place the children of the Dialog. A single 436pass is made through the Dialog widget's children in the 437order that they were created. Each child is then placed in 438the Dialog widget below or to the right of the widget specified by the 439<function>fromVert</function> and <function>fromHoriz</function> resources. 440The distance the new child is placed from its left or upper neighbor is 441determined by the <function>horizDistance</function> and 442<function>vertDistance</function> resources. 443This implies some things about how the order of creation 444affects the possible placement of the children. The Form 445widget registers a string to widget converter which does not 446postpone conversion and does not cache conversion results. 447</para> 448<para> 449 450The second layout method is used when the Dialog is resized. 451It does not matter what causes this resize, and it is possi- 452ble for a resize to happen before the widget becomes visible 453(due to constraints imposed by the parent of the Dialog). 454This layout method uses the <function>bottom</function> , 455<function>top</function> , <function>left</function> , and 456<function>right</function> 457resources. These resources are used to determine what will 458happen to each edge of the child when the Dialog is resized. 459If a value of <function>XawChain</function> 460<emphasis remap='I'><something></emphasis> 461 is specified, the the edge 462of the child will remain a fixed distance from the <emphasis remap='I'>chain</emphasis> 463edge of the Dialog. For example if <function>XawChainLeft</function> 464mis specified for the <function>right</function> mresource of a child 465then the right edge 466of that child will remain a fixed distance from the left 467edge of the Dialog widget. If a value of <function>XawRubber</function> mis spec- 468ified, that edge will grow by the same percentage that the 469Dialog grew. For instance if the Dialog grows by 50% the 470left edge of the child (if specified as <function>XawRubber</function> mwill be 47150% farther from the left edge of the Dialog). One must be 472very careful when specifying these resources, for when they 473are specified incorrectly children may overlap or completely 474occlude other children when the Dialog widget is resized. 475</para> 476 477<para> 478<!-- .LP --> 479<informaltable> 480 <tgroup cols='3' align='center'> 481 <colspec colname='c1'/> 482 <colspec colname='c2'/> 483 <colspec colname='c3'/> 484 <thead> 485 <row> 486 <entry>Edge Type</entry> 487 <entry>Resource Name</entry> 488 <entry>Description</entry> 489 </row> 490 </thead> 491 <tbody> 492 <row> 493 <entry>XawChainBottom</entry> 494 <entry>ChainBottom</entry> 495 <entry>Edge remains a fixed distance from bottom of Dialog</entry> 496 </row> 497 <row> 498 <entry>XawChainLeft</entry> 499 <entry>ChainLeft</entry> 500 <entry>Edge remains a fixed distance from left of Dialog</entry> 501 </row> 502 <row> 503 <entry>XawChainRight</entry> 504 <entry>ChainRight</entry> 505 <entry>Edge remains a fixed distance from right of Dialog</entry> 506 </row> 507 <row> 508 <entry>XawChainTop</entry> 509 <entry>ChainTop</entry> 510 <entry>Edge remains a fixed distance from top of Dialog</entry> 511 </row> 512 <row> 513 <entry>XawRubber</entry> 514 <entry>Rubber</entry> 515 <entry>Edges will move a proportional distance</entry> 516 </row> 517 </tbody> 518 </tgroup> 519</informaltable> 520</para> 521<sect3 id="Example"> 522<title>Example</title> 523<para> 524<!-- .LP --> 525If you wish to force the Dialog to never resize one or more of its children 526then set <function>left</function> and <function>right</function> to <function>XawChainLeft</function> and 527<function>top</function> and <function>bottom</function> to <function>XawChainTop</function>. This will cause 528the child to remain a fixed distance from the top and left 529edges of the Dialog, and to never resize. 530</para> 531</sect3> 532<sect3 id="Special_Considerations"> 533<title>Special Considerations</title> 534<indexterm><primary>Dialog widget</primary><secondary>special considerations</secondary></indexterm> 535<para> 536<!-- .LP --> 537The Dialog widget automatically sets the <function>top</function> and <function>bottom</function> 538resources for all Children that are subclasses of the Command widget, 539as well as the widget children that are used to contain the <function>label</function>, 540<function>value</function>, and <function>icon</function>. This policy allows the buttons at the 541bottom of the Dialog to interact correctly with the predefined children, 542and makes it possible for a client to simply create and manage a new 543Command button without having to specify its constraints. 544</para> 545<para> 546<!-- .LP --> 547The Dialog will also set <function>fromLeft</function> to the last button in the 548<indexterm><primary>fromLeft</primary></indexterm> 549Dialog for each new button added to the Dialog widget. 550</para> 551<para> 552<!-- .LP --> 553The automatically added constraints cannot be overridden, as they are 554policy decisions of the Dialog widget. If a more flexible Dialog is 555desired, the application is free to use the Form widget to create its 556own Dialog policy. 557</para> 558</sect3> 559</sect2> 560<sect2 id='Automatically_Created_Children'> 561<title>Automatically Created Children.</title> 562<indexterm><primary>Dialog widget</primary><secondary>automatically created children</secondary></indexterm> 563<para> 564<!-- .LP --> 565The Dialog uses Label widgets to contain the <function>label</function> and <function>icon</function>. 566These widgets are named <emphasis remap='I'>label</emphasis> and <emphasis remap='I'>icon</emphasis> respectively. The 567Dialog <function>value</function> is contained in an AsciiText widget whose name is 568<function>value</function>. Using <function>XtNameToWidget</function> the application can change 569<indexterm><primary>XtNameToWidget</primary></indexterm> 570those resources associated with each of these widgets that are not 571available through the Dialog widget itself. 572</para> 573<para> 574<!-- .LP --> 575</para> 576</sect2> 577<sect2 id='Dialog::Convenience_Routines'> 578<title>Convenience Routines</title> 579<para> 580<!-- .LP --> 581To return the character string in the text field, use 582<!-- .PN XawDialogGetValueString . --> 583<indexterm significance="preferred"><primary>XawDialogGetValueString</primary></indexterm> 584<funcsynopsis id='XawDialogGetValueString'> 585<funcprototype> 586 <funcdef>String<function> XawDialogGetValueString</function></funcdef> 587 <paramdef>Widget<parameter> w</parameter></paramdef> 588</funcprototype> 589</funcsynopsis> 590<!-- .FN --> 591<variablelist> 592 <varlistentry> 593 <term> 594 <emphasis remap='I'>w</emphasis> 595 </term> 596 <listitem> 597 <para> 598Specifies the Dialog widget. 599 </para> 600 </listitem> 601 </varlistentry> 602</variablelist> 603</para> 604<para> 605<!-- .LP --> 606This function returns a copy of the value string of the Dialog 607widget. This string is allocated by the AsciiText widget and will 608remain valid and unchanged until another call to 609<xref linkend='XawDialogGetValueString' xrefstyle='select: title'/> or an <xref linkend='XtGetValues' xrefstyle='select: title'/> call on the 610<function>value</function> widget, when the string will be automatically freed, and 611a new string is returned. This string may be freed earlier by calling 612the function <xref linkend='XawAsciiSourceFreeString' xrefstyle='select: title'/>. 613<indexterm><primary>XawAsciiSourceFreeString</primary></indexterm> 614</para> 615<para> 616<!-- .LP --> 617<!-- .sp --> 618To add a new button to the Dialog widget use 619<xref linkend='XawDialogAddButton' xrefstyle='select: title'/>. 620<indexterm significance="preferred"><primary>XawDialogAddButton</primary></indexterm> 621<funcsynopsis id='XawDialogAddButton'> 622<funcprototype> 623 <funcdef>void<function> XawDialogAddButton</function></funcdef> 624 <paramdef>Widget<parameter> w</parameter></paramdef> 625 <paramdef>String<parameter> name</parameter></paramdef> 626 <paramdef>XtCallbackProc<parameter> func</parameter></paramdef> 627 <paramdef>XtPointer<parameter> client_data</parameter></paramdef> 628</funcprototype> 629</funcsynopsis> 630<!-- .FN --> 631<variablelist> 632 <varlistentry> 633 <term> 634 <emphasis remap='I'>w</emphasis> 635 </term> 636 <listitem> 637 <para> 638Specifies the Dialog widget. 639 </para> 640 </listitem> 641 </varlistentry> 642 <varlistentry> 643 <term> 644 <emphasis remap='I'>name</emphasis> 645 </term> 646 <listitem> 647 <para> 648Specifies the name of the new Command button to be added to the Dialog. 649 </para> 650 </listitem> 651 </varlistentry> 652 <varlistentry> 653 <term> 654 <emphasis remap='I'>func</emphasis> 655 </term> 656 <listitem> 657 <para> 658Specifies a callback function to be called when this button is activated. If 659NULL is specified then no callback is added. 660 </para> 661 </listitem> 662 </varlistentry> 663 <varlistentry> 664 <term> 665 <emphasis remap='I'>client_data</emphasis> 666 </term> 667 <listitem> 668 <para> 669Specifies the client_data to be passed to the <emphasis remap='I'>func</emphasis>. 670 </para> 671 </listitem> 672 </varlistentry> 673</variablelist> 674</para> 675<para> 676<!-- .LP --> 677This function is merely a shorthand for the code sequence: 678<!-- .sp --> 679<literallayout class="monospaced"> 680<!-- .SM --> 681<!-- .TA 1i 2i --> 682<!-- .ta 1i 2i --> 683{ 684 Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO); 685 XtAddCallback(button, XtNcallback, func, client_data); 686} 687<!-- .NL --> 688</literallayout> 689<!-- .sp --> 690 691</para> 692</sect2> 693</sect1> 694