appC.xml revision 9e7bcd65
11.1Skamil<appendix id='Compability_Functions'> 21.1Skamil<title>Compatibility Functions 31.1Skamil<footnote> 41.1Skamil<para> 51.1SkamilThis appendix is part of the formal Intrinsics Specification. 61.1Skamil</para> 71.1Skamil</footnote> 81.1Skamil</title> 91.1Skamil<para> 101.1SkamilIn prototype versions of the X Toolkit 111.1Skamileach widget class 121.1Skamilimplemented an Xt<<emphasis remap='I'>Widget</emphasis>>Create (for example, 131.1Skamil<function>XtLabelCreate</function>) 14function, in which most of the code was identical from widget to widget. 15In the Intrinsics, a single generic 16<xref linkend='XtCreateWidget' xrefstyle='select: title'/> 17performs most of the common work and then calls the initialize procedure 18implemented for the particular widget class. 19</para> 20 21<para> 22Each Composite class also implemented the procedures 23Xt<<emphasis remap='I'>Widget</emphasis>>Add and an Xt<<emphasis remap='I'>Widget</emphasis>>Delete (for example, 24<function>XtButtonBoxAddButton</function> 25and 26<function>XtButtonBoxDeleteButton</function>). 27In the Intrinsics, the Composite generic procedures 28<xref linkend='XtManageChildren' xrefstyle='select: title'/> 29and 30<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/> 31perform error checking and screening out of certain children. 32Then they call the change_managed procedure 33implemented for the widget's Composite class. 34If the widget's parent has not yet been realized, 35the call to the change_managed procedure is delayed until realization time. 36</para> 37 38<para> 39Old-style calls can be implemented in the X Toolkit by defining 40one-line procedures or macros that invoke a generic routine. For example, 41you could define the macro 42<function>XtLabelCreate</function> 43as: 44</para> 45 46<literallayout> 47#define XtLabelCreate(name, parent, args, num_args) \ 48 ((LabelWidget) XtCreateWidget(name, labelWidgetClass, parent, args, num_args)) 49</literallayout> 50 51<para> 52Pop-up shells in some of the prototypes automatically performed an 53<xref linkend='XtManageChild' xrefstyle='select: title'/> 54on their child within their insert_child procedure. 55Creators of pop-up children need to call 56<xref linkend='XtManageChild' xrefstyle='select: title'/> 57themselves. 58</para> 59 60<para> 61<xref linkend='XtAppInitialize' xrefstyle='select: title'/> 62and 63<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/> 64have been replaced by 65<xref linkend='XtOpenApplication' xrefstyle='select: title'/> 66and 67<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/>. 68</para> 69 70<para> 71To initialize the Intrinsics internals, create an application context, 72open and initialize a display, and create the initial application shell 73instance, an application may use 74<xref linkend='XtAppInitialize' xrefstyle='select: title'/> 75or 76<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/>. 77</para> 78 79<funcsynopsis id='XtAppInitialize'> 80<funcprototype> 81<funcdef>Widget <function>XtAppInitialize</function></funcdef> 82 <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef> 83 <paramdef>String <parameter>application_class</parameter></paramdef> 84 <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef> 85 <paramdef>Cardinal <parameter>num_options</parameter></paramdef> 86 <paramdef>int *<parameter>argc_in_out</parameter></paramdef> 87 <paramdef>String *<parameter>argv_in_out</parameter></paramdef> 88 <paramdef>String *<parameter>fallback_resources</parameter></paramdef> 89 <paramdef>ArgList <parameter>args</parameter></paramdef> 90 <paramdef>Cardinal <parameter>num_args</parameter></paramdef> 91</funcprototype> 92</funcsynopsis> 93 94<variablelist> 95 <varlistentry> 96 <term> 97 <emphasis remap='I'>app_context_return</emphasis> 98 </term> 99 <listitem> 100 <para> 101Returns the application context, if non-NULL. 102 </para> 103 </listitem> 104 </varlistentry> 105 <varlistentry> 106 <term> 107 <emphasis remap='I'>application_class</emphasis> 108 </term> 109 <listitem> 110 <para> 111Specifies the class name of the application. 112 </para> 113 </listitem> 114 </varlistentry> 115 <varlistentry> 116 <term> 117 <emphasis remap='I'>options</emphasis> 118 </term> 119 <listitem> 120 <para> 121Specifies the command line options table. 122 </para> 123 </listitem> 124 </varlistentry> 125 <varlistentry> 126 <term> 127 <emphasis remap='I'>num_options</emphasis> 128 </term> 129 <listitem> 130 <para> 131Specifies the number of entries in <emphasis remap='I'>options</emphasis>. 132 </para> 133 </listitem> 134 </varlistentry> 135 <varlistentry> 136 <term> 137 <emphasis remap='I'>argc_in_out</emphasis> 138 </term> 139 <listitem> 140 <para> 141Specifies a pointer to the number of command line arguments. 142 </para> 143 </listitem> 144 </varlistentry> 145 <varlistentry> 146 <term> 147 <emphasis remap='I'>argv_in_out</emphasis> 148 </term> 149 <listitem> 150 <para> 151Specifies a pointer to the command line arguments. 152 </para> 153 </listitem> 154 </varlistentry> 155 <varlistentry> 156 <term> 157 <emphasis remap='I'>fallback_resources</emphasis> 158 </term> 159 <listitem> 160 <para> 161Specifies resource values to be used if the application class resource 162file cannot be opened or read, or NULL. 163 </para> 164 </listitem> 165 </varlistentry> 166 <varlistentry> 167 <term> 168 <emphasis remap='I'>args</emphasis> 169 </term> 170 <listitem> 171 <para> 172Specifies the argument list to override any 173other resource specifications for the created shell widget. 174 </para> 175 </listitem> 176 </varlistentry> 177 <varlistentry> 178 <term> 179 <emphasis remap='I'>num_args</emphasis> 180 </term> 181 <listitem> 182 <para> 183Specifies the number of entries in the argument list. 184 </para> 185 </listitem> 186 </varlistentry> 187</variablelist> 188 189<para> 190The 191<xref linkend='XtAppInitialize' xrefstyle='select: title'/> 192function calls 193<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/> 194followed by 195<xref linkend='XtCreateApplicationContext' xrefstyle='select: title'/>, 196then calls 197<xref linkend='XtOpenDisplay' xrefstyle='select: title'/> 198with <emphasis remap='I'>display_string</emphasis> NULL and 199<emphasis remap='I'>application_name</emphasis> NULL, and finally calls 200<xref linkend='XtAppCreateShell' xrefstyle='select: title'/> 201with <emphasis remap='I'>application_name</emphasis> NULL, <emphasis remap='I'>widget_class</emphasis> 202<function>application\%Shell\%Widget\%Class</function>, 203and the specified <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> 204and returns the created shell. The modified <emphasis remap='I'>argc</emphasis> and <emphasis remap='I'>argv</emphasis> returned by 205<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/> 206are returned in <emphasis remap='I'>argc_in_out</emphasis> and <emphasis remap='I'>argv_in_out</emphasis>. If 207<emphasis remap='I'>app_context_return</emphasis> is not NULL, the created application context is 208also returned. If the display specified by the command line cannot be 209opened, an error message is issued and 210<xref linkend='XtAppInitialize' xrefstyle='select: title'/> 211terminates the application. If <emphasis remap='I'>fallback_resources</emphasis> is non-NULL, 212<xref linkend='XtAppSetFallbackResources' xrefstyle='select: title'/> 213is called with the value prior to calling 214<xref linkend='XtOpenDisplay' xrefstyle='select: title'/>. 215</para> 216 217<funcsynopsis id='XtVaAppInitialize'> 218<funcprototype> 219<funcdef>Widget <function>XtVaAppInitialize</function></funcdef> 220 <paramdef>XtAppContext *<parameter>app_context_return</parameter></paramdef> 221 <paramdef>String <parameter>application_class</parameter></paramdef> 222 <paramdef>XrmOptionDescList <parameter>options</parameter></paramdef> 223 <paramdef>Cardinal <parameter>num_options</parameter></paramdef> 224 <paramdef>int *<parameter>argc_in_out</parameter></paramdef> 225 <paramdef>String *<parameter>argv_in_out</parameter></paramdef> 226 <paramdef>String *<parameter>fallback_resources</parameter></paramdef> 227</funcprototype> 228</funcsynopsis> 229 230<variablelist> 231 <varlistentry> 232 <term> 233 <emphasis remap='I'>app_context_return</emphasis> 234 </term> 235 <listitem> 236 <para> 237Returns the application context, if non-NULL. 238 </para> 239 </listitem> 240 </varlistentry> 241 <varlistentry> 242 <term> 243 <emphasis remap='I'>application_class</emphasis> 244 </term> 245 <listitem> 246 <para> 247Specifies the class name of the application. 248 </para> 249 </listitem> 250 </varlistentry> 251 <varlistentry> 252 <term> 253 <emphasis remap='I'>options</emphasis> 254 </term> 255 <listitem> 256 <para> 257Specifies the command line options table. 258 </para> 259 </listitem> 260 </varlistentry> 261 <varlistentry> 262 <term> 263 <emphasis remap='I'>num_options</emphasis> 264 </term> 265 <listitem> 266 <para> 267Specifies the number of entries in <emphasis remap='I'>options</emphasis>. 268 </para> 269 </listitem> 270 </varlistentry> 271 <varlistentry> 272 <term> 273 <emphasis remap='I'>argc_in_out</emphasis> 274 </term> 275 <listitem> 276 <para> 277Specifies a pointer to the number of command line arguments. 278 </para> 279 </listitem> 280 </varlistentry> 281 <varlistentry> 282 <term> 283 <emphasis remap='I'>argv_in_out</emphasis> 284 </term> 285 <listitem> 286 <para> 287Specifies the command line arguments array. 288 </para> 289 </listitem> 290 </varlistentry> 291 <varlistentry> 292 <term> 293 <emphasis remap='I'>fallback_resources</emphasis> 294 </term> 295 <listitem> 296 <para> 297Specifies resource values to be used if the application class 298resource file cannot be opened, or NULL. 299 </para> 300 </listitem> 301 </varlistentry> 302 <varlistentry> 303 <term> 304 ... 305 </term> 306 <listitem> 307 <para> 308Specifies the variable argument list to override any other 309resource specifications for the created shell. 310 </para> 311 </listitem> 312 </varlistentry> 313</variablelist> 314 315<para> 316The 317<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/> 318procedure is identical in function to 319<xref linkend='XtAppInitialize' xrefstyle='select: title'/> 320with the <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> parameters replaced by a varargs list, 321as described 322in Section 2.5.1. 323</para> 324 325<para> 326As a convenience to people converting from earlier versions of the toolkit 327without application contexts, the following routines exist: 328<xref linkend='XtInitialize' xrefstyle='select: title'/>, 329<xref linkend='XtMainLoop' xrefstyle='select: title'/>, 330<xref linkend='XtNextEvent' xrefstyle='select: title'/>, 331<xref linkend='XtProcessEvent' xrefstyle='select: title'/>, 332<xref linkend='XtPeekEvent' xrefstyle='select: title'/>, 333<xref linkend='XtPending' xrefstyle='select: title'/>, 334<xref linkend='XtAddInput' xrefstyle='select: title'/>, 335<xref linkend='XtAddTimeOut' xrefstyle='select: title'/>, 336<xref linkend='XtAddWorkProc' xrefstyle='select: title'/>, 337<xref linkend='XtCreateApplicationShell' xrefstyle='select: title'/>, 338<xref linkend='XtAddActions' xrefstyle='select: title'/>, 339<xref linkend='XtSetSelectionTimeout' xrefstyle='select: title'/>, 340and 341<xref linkend='XtGetSelectionTimeout' xrefstyle='select: title'/>. 342</para> 343 344<funcsynopsis id='XtInitialize'> 345<funcprototype> 346<funcdef>Widget <function>XtInitialize</function></funcdef> 347 <paramdef>String <parameter>shell_name</parameter></paramdef> 348 <paramdef>String <parameter>application_class</parameter></paramdef> 349 <paramdef>XrmOptionDescRec <parameter>options</parameter></paramdef> 350 <paramdef>Cardinal <parameter>num_options</parameter></paramdef> 351 <paramdef>int *<parameter>argc</parameter></paramdef> 352 <paramdef>String <parameter>argv</parameter></paramdef> 353</funcprototype> 354</funcsynopsis> 355 356<variablelist> 357 <varlistentry> 358 <term> 359 <emphasis remap='I'>shell_name</emphasis> 360 </term> 361 <listitem> 362 <para> 363This parameter is ignored; therefore, you can specify NULL. 364 </para> 365 </listitem> 366 </varlistentry> 367 <varlistentry> 368 <term> 369 <emphasis remap='I'>application_class</emphasis> 370 </term> 371 <listitem> 372 <para> 373Specifies the class name of this application. 374 </para> 375 </listitem> 376 </varlistentry> 377 <varlistentry> 378 <term> 379 <emphasis remap='I'>options</emphasis> 380 </term> 381 <listitem> 382 <para> 383Specifies how to parse the command line for any application-specific resources. 384The <emphasis remap='I'>options</emphasis> argument is passed as a parameter to 385<function>XrmParseCommand</function>. 386 </para> 387 </listitem> 388 </varlistentry> 389 <varlistentry> 390 <term> 391 <emphasis remap='I'>num_options</emphasis> 392 </term> 393 <listitem> 394 <para> 395Specifies the number of entries in the options list. 396 </para> 397 </listitem> 398 </varlistentry> 399 <varlistentry> 400 <term> 401 <emphasis remap='I'>argc</emphasis> 402 </term> 403 <listitem> 404 <para> 405Specifies a pointer to the number of command line parameters. 406 </para> 407 </listitem> 408 </varlistentry> 409 <varlistentry> 410 <term> 411 <emphasis remap='I'>argv</emphasis> 412 </term> 413 <listitem> 414 <para> 415Specifies the command line parameters. 416 </para> 417 </listitem> 418 </varlistentry> 419</variablelist> 420 421<para> 422<xref linkend='XtInitialize' xrefstyle='select: title'/> 423calls 424<xref linkend='XtToolkitInitialize' xrefstyle='select: title'/> 425to initialize the toolkit internals, 426creates a default application context for use by the other convenience 427routines, calls 428<xref linkend='XtOpenDisplay' xrefstyle='select: title'/> 429with <emphasis remap='I'>display_string</emphasis> NULL and <emphasis remap='I'>application_name</emphasis> NULL, and 430finally calls 431<xref linkend='XtAppCreateShell' xrefstyle='select: title'/> 432with <emphasis remap='I'>application_name</emphasis> NULL and 433returns the created shell. 434The semantics of calling 435<xref linkend='XtInitialize' xrefstyle='select: title'/> 436more than once are undefined. 437This routine has been replaced by 438<xref linkend='XtOpenApplication' xrefstyle='select: title'/>. 439</para> 440 441<funcsynopsis id='XtMainLoop'> 442<funcprototype> 443<funcdef>void <function>XtMainLoop</function></funcdef> 444 <paramdef><parameter>void</parameter></paramdef> 445</funcprototype> 446</funcsynopsis> 447 448<para> 449<xref linkend='XtMainLoop' xrefstyle='select: title'/> 450first reads the next alternate input, timer, or X event by calling 451<xref linkend='XtNextEvent' xrefstyle='select: title'/>. 452Then it dispatches this to the appropriate registered procedure by calling 453<xref linkend='XtDispatchEvent' xrefstyle='select: title'/>. 454This routine has been replaced by 455<xref linkend='XtAppMainLoop' xrefstyle='select: title'/>. 456</para> 457 458<funcsynopsis id='XtNextEvent'> 459<funcprototype> 460<funcdef>void <function>XtNextEvent</function></funcdef> 461 <paramdef>XEvent *<parameter>event_return</parameter></paramdef> 462</funcprototype> 463</funcsynopsis> 464 465<variablelist> 466 <varlistentry> 467 <term> 468 <emphasis remap='I'>event_return</emphasis> 469 </term> 470 <listitem> 471 <para> 472Returns the event information to the specified event structure. 473 </para> 474 </listitem> 475 </varlistentry> 476</variablelist> 477 478<para> 479If no input is on the X input queue for the default application context, 480<xref linkend='XtNextEvent' xrefstyle='select: title'/> 481flushes the X output buffer 482and waits for an event while looking at the alternate input sources 483and timeout values and calling any callback procedures triggered by them. 484This routine has been replaced by 485<xref linkend='XtAppNextEvent' xrefstyle='select: title'/>. 486<xref linkend='XtInitialize' xrefstyle='select: title'/> 487must be called before using this routine. 488</para> 489 490<funcsynopsis id='XtProcessEvent'> 491<funcprototype> 492<funcdef>void <function>XtProcessEvent</function></funcdef> 493 <paramdef>XtInputMask <parameter>mask</parameter></paramdef> 494</funcprototype> 495</funcsynopsis> 496 497<variablelist> 498 <varlistentry> 499 <term> 500 <emphasis remap='I'>mask</emphasis> 501 </term> 502 <listitem> 503 <para> 504Specifies the type of input to process. 505 </para> 506 </listitem> 507 </varlistentry> 508</variablelist> 509 510<para> 511<xref linkend='XtProcessEvent' xrefstyle='select: title'/> 512processes one X event, timeout, or alternate input source 513(depending on the value of <emphasis remap='I'>mask</emphasis>), blocking if necessary. 514It has been replaced by 515<xref linkend='XtAppProcessEvent' xrefstyle='select: title'/>. 516<xref linkend='XtInitialize' xrefstyle='select: title'/> 517must be called before using this function. 518</para> 519 520<funcsynopsis id='XtPeekEvent'> 521<funcprototype> 522<funcdef>Boolean <function>XtPeekEvent</function></funcdef> 523 <paramdef>XEvent *<parameter>event_return</parameter></paramdef> 524</funcprototype> 525</funcsynopsis> 526 527<variablelist> 528 <varlistentry> 529 <term> 530 <emphasis remap='I'>event_return</emphasis> 531 </term> 532 <listitem> 533 <para> 534Returns the event information to the specified event structure. 535 </para> 536 </listitem> 537 </varlistentry> 538</variablelist> 539 540<para> 541If there is an event in the queue for the default application context, 542<xref linkend='XtPeekEvent' xrefstyle='select: title'/> 543fills in the event and returns a nonzero value. 544If no X input is on the queue, 545<xref linkend='XtPeekEvent' xrefstyle='select: title'/> 546flushes the output buffer and blocks until input is available, possibly 547calling some timeout callbacks in the process. 548If the input is an event, 549<xref linkend='XtPeekEvent' xrefstyle='select: title'/> 550fills in the event and returns a nonzero value. 551Otherwise, the input is for an alternate input source, and 552<xref linkend='XtPeekEvent' xrefstyle='select: title'/> 553returns zero. 554This routine has been replaced by 555<xref linkend='XtAppPeekEvent' xrefstyle='select: title'/>. 556<xref linkend='XtInitialize' xrefstyle='select: title'/> 557must be called before using this routine. 558</para> 559 560<funcsynopsis id='XtPending'> 561<funcprototype> 562<funcdef>Boolean <function>XtPending</function></funcdef> 563 <paramdef><parameter></parameter></paramdef> 564</funcprototype> 565</funcsynopsis> 566 567<para> 568<xref linkend='XtPending' xrefstyle='select: title'/> 569returns a nonzero value if there are 570events pending from the X server or alternate input sources in the default 571application context. 572If there are no events pending, 573it flushes the output buffer and returns a zero value. 574It has been replaced by 575<xref linkend='XtAppPending' xrefstyle='select: title'/>. 576<xref linkend='XtInitialize' xrefstyle='select: title'/> 577must be called before using this routine. 578</para> 579 580<funcsynopsis id='XtAddInput'> 581<funcprototype> 582<funcdef>XtInputId <function>XtAddInput</function></funcdef> 583 <paramdef>int <parameter>source</parameter></paramdef> 584 <paramdef>XtPointer <parameter>condition</parameter></paramdef> 585 <paramdef>XtInputCallbackProc <parameter>proc</parameter></paramdef> 586 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 587</funcprototype> 588</funcsynopsis> 589 590<variablelist> 591 <varlistentry> 592 <term> 593 <emphasis remap='I'>source</emphasis> 594 </term> 595 <listitem> 596 <para> 597Specifies the source file descriptor on a POSIX-based system 598or other operating-system-dependent device specification. 599 </para> 600 </listitem> 601 </varlistentry> 602 <varlistentry> 603 <term> 604 <emphasis remap='I'>condition</emphasis> 605 </term> 606 <listitem> 607 <para> 608Specifies the mask that indicates either a read, write, or exception condition 609or some operating-system-dependent condition. 610 </para> 611 </listitem> 612 </varlistentry> 613 <varlistentry> 614 <term> 615 <emphasis remap='I'>proc</emphasis> 616 </term> 617 <listitem> 618 <para> 619Specifies the procedure called when input is available. 620 </para> 621 </listitem> 622 </varlistentry> 623 <varlistentry> 624 <term> 625 <emphasis remap='I'>client_data</emphasis> 626 </term> 627 <listitem> 628 <para> 629Specifies the parameter to be passed to <emphasis remap='I'>proc</emphasis> when input is available. 630 </para> 631 </listitem> 632 </varlistentry> 633</variablelist> 634 635<para> 636The 637<xref linkend='XtAddInput' xrefstyle='select: title'/> 638function registers in the default application context a new 639source of events, 640which is usually file input but can also be file output. 641(The word <emphasis remap='I'>file</emphasis> should be loosely interpreted to mean any sink 642or source of data.) 643<xref linkend='XtAddInput' xrefstyle='select: title'/> 644also specifies the conditions under which the source can generate events. 645When input is pending on this source in the default application context, 646the callback procedure is called. 647This routine has been replaced by 648<xref linkend='XtAppAddInput' xrefstyle='select: title'/>. 649<xref linkend='XtInitialize' xrefstyle='select: title'/> 650must be called before using this routine. 651</para> 652 653<funcsynopsis id='XtAddTimeOut'> 654<funcprototype> 655<funcdef>XtIntervalId <function>XtAddTimeOut</function></funcdef> 656 <paramdef>unsigned long <parameter>interval</parameter></paramdef> 657 <paramdef>XtTimerCallbackProc <parameter>proc</parameter></paramdef> 658 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 659</funcprototype> 660</funcsynopsis> 661 662<variablelist> 663 <varlistentry> 664 <term> 665 <emphasis remap='I'>interval</emphasis> 666 </term> 667 <listitem> 668 <para> 669Specifies the time interval in milliseconds. 670 </para> 671 </listitem> 672 </varlistentry> 673 <varlistentry> 674 <term> 675 <emphasis remap='I'>proc</emphasis> 676 </term> 677 <listitem> 678 <para> 679Specifies the procedure to be called when time expires. 680 </para> 681 </listitem> 682 </varlistentry> 683 <varlistentry> 684 <term> 685 <emphasis remap='I'>client_data</emphasis> 686 </term> 687 <listitem> 688 <para> 689Specifies the parameter to be passed to <emphasis remap='I'>proc</emphasis> when it is called. 690 </para> 691 </listitem> 692 </varlistentry> 693</variablelist> 694 695<para> 696The 697<xref linkend='XtAddTimeOut' xrefstyle='select: title'/> 698function creates a timeout in the default application context 699and returns an identifier for it. 700The timeout value is set to <emphasis remap='I'>interval</emphasis>. 701The callback procedure will be called after 702the time interval elapses, after which the timeout is removed. 703This routine has been replaced by 704<xref linkend='XtAppAddTimeOut' xrefstyle='select: title'/>. 705<xref linkend='XtInitialize' xrefstyle='select: title'/> 706must be called before using this routine. 707</para> 708 709<funcsynopsis id='XtAddWorkProc'> 710<funcprototype> 711<funcdef>XtWorkProcId <function>XtAddWorkProc</function></funcdef> 712 <paramdef>XtWorkProc <parameter>proc</parameter></paramdef> 713 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 714</funcprototype> 715</funcsynopsis> 716 717<variablelist> 718 <varlistentry> 719 <term> 720 <emphasis remap='I'>proc</emphasis> 721 </term> 722 <listitem> 723 <para> 724Procedure to call to do the work. 725 </para> 726 </listitem> 727 </varlistentry> 728 <varlistentry> 729 <term> 730 <emphasis remap='I'>client_data</emphasis> 731 </term> 732 <listitem> 733 <para> 734Client data to pass to <emphasis remap='I'>proc</emphasis> when it is called. 735 </para> 736 </listitem> 737 </varlistentry> 738</variablelist> 739 740<para> 741This routine registers a work procedure in the default application context. It has 742been replaced by 743<xref linkend='XtAppAddWorkProc' xrefstyle='select: title'/>. 744<xref linkend='XtInitialize' xrefstyle='select: title'/> 745must be called before using this routine. 746</para> 747 748<funcsynopsis id='XtCreateApplicationShell'> 749<funcprototype> 750<funcdef>Widget <function>XtCreateApplicationShell</function></funcdef> 751 <paramdef>String <parameter>name</parameter></paramdef> 752 <paramdef>WidgetClass <parameter>widget_class</parameter></paramdef> 753 <paramdef>ArgList <parameter>args</parameter></paramdef> 754 <paramdef>Cardinal <parameter>num_args</parameter></paramdef> 755</funcprototype> 756</funcsynopsis> 757 758<variablelist> 759 <varlistentry> 760 <term> 761 <emphasis remap='I'>name</emphasis> 762 </term> 763 <listitem> 764 <para> 765This parameter is ignored; therefore, you can specify NULL. 766 </para> 767 </listitem> 768 </varlistentry> 769 <varlistentry> 770 <term> 771 <emphasis remap='I'>widget_class</emphasis> 772 </term> 773 <listitem> 774 <para> 775Specifies the widget class pointer for the created application shell widget. 776This will usually be 777<function>topLevelShellWidgetClass</function> 778or a subclass thereof. 779 </para> 780 </listitem> 781 </varlistentry> 782 <varlistentry> 783 <term> 784 <emphasis remap='I'>args</emphasis> 785 </term> 786 <listitem> 787 <para> 788Specifies the argument list to override any other resource specifications. 789 </para> 790 </listitem> 791 </varlistentry> 792 <varlistentry> 793 <term> 794 <emphasis remap='I'>num_args</emphasis> 795 </term> 796 <listitem> 797 <para> 798Specifies the number of entries in <emphasis remap='I'>args</emphasis>. 799 </para> 800 </listitem> 801 </varlistentry> 802</variablelist> 803 804<para> 805The procedure 806<xref linkend='XtCreateApplicationShell' xrefstyle='select: title'/> 807calls 808<xref linkend='XtAppCreateShell' xrefstyle='select: title'/> 809with <emphasis remap='I'>application_name</emphasis> NULL, the application class passed to 810<xref linkend='XtInitialize' xrefstyle='select: title'/>, 811and the default application context created by 812<xref linkend='XtInitialize' xrefstyle='select: title'/>. 813This routine has been replaced by 814<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>. 815</para> 816 817<para> 818An old-format resource type converter procedure pointer is of type 819<xref linkend='XtConverter' xrefstyle='select: title'/>. 820</para> 821 822<funcsynopsis id='XtConverter'> 823<funcprototype> 824<funcdef>typedef void <function>(*XtConverter)</function></funcdef> 825 826 <paramdef>XrmValue *<parameter>args</parameter></paramdef> 827 <paramdef>Cardinal *<parameter>num_args</parameter></paramdef> 828 <paramdef>XrmValue *<parameter>from</parameter></paramdef> 829 <paramdef>XrmValue *<parameter>to</parameter></paramdef> 830</funcprototype> 831</funcsynopsis> 832 833<variablelist> 834 <varlistentry> 835 <term> 836 <emphasis remap='I'>args</emphasis> 837 </term> 838 <listitem> 839 <para> 840Specifies a list of additional 841<function>XrmValue</function> 842arguments to the converter if additional context is needed 843to perform the conversion, or NULL. 844 </para> 845 </listitem> 846 </varlistentry> 847 <varlistentry> 848 <term> 849 <emphasis remap='I'>num_args</emphasis> 850 </term> 851 <listitem> 852 <para> 853Specifies the number of entries in <emphasis remap='I'>args</emphasis>. 854 </para> 855 </listitem> 856 </varlistentry> 857 <varlistentry> 858 <term> 859 <emphasis remap='I'>from</emphasis> 860 </term> 861 <listitem> 862 <para> 863Specifies the value to convert. 864 </para> 865 </listitem> 866 </varlistentry> 867 <varlistentry> 868 <term> 869 <emphasis remap='I'>to</emphasis> 870 </term> 871 <listitem> 872 <para> 873Specifies the descriptor to use to return the converted value. 874 </para> 875 </listitem> 876 </varlistentry> 877</variablelist> 878 879<para> 880Type converters should perform the following actions: 881</para> 882<itemizedlist spacing='compact'> 883 <listitem> 884 <para> 885Check to see that the number of arguments passed is correct. 886 </para> 887 </listitem> 888 <listitem> 889 <para> 890Attempt the type conversion. 891 </para> 892 </listitem> 893 <listitem> 894 <para> 895If successful, return the size and pointer to the data in the <emphasis remap='I'>to</emphasis> argument; 896otherwise, call 897<xref linkend='XtWarningMsg' xrefstyle='select: title'/> 898and return without modifying the <emphasis remap='I'>to</emphasis> argument. 899 </para> 900 </listitem> 901</itemizedlist> 902<para> 903Most type converters just take the data described by the specified <emphasis remap='I'>from</emphasis> 904argument and return data by writing into the specified <emphasis remap='I'>to</emphasis> argument. 905A few need other information, which is available in the specified 906argument list. 907A type converter can invoke another type converter, 908which allows differing sources that may convert into a common intermediate 909result to make maximum use of the type converter cache. 910</para> 911 912<para> 913Note that the address returned in <emphasis remap='I'>to->addr</emphasis> cannot be that of a local variable of 914the converter because this is not valid after the converter returns. 915It should be a pointer to a static variable. 916</para> 917 918<para> 919The procedure type 920<xref linkend='XtConverter' xrefstyle='select: title'/> 921has been replaced by 922<xref linkend='XtTypeConverter' xrefstyle='select: title'/>. 923</para> 924 925<para> 926The 927<xref linkend='XtStringConversionWarning' xrefstyle='select: title'/> 928function is a convenience routine for old-format resource converters 929that convert from strings. 930</para> 931 932<funcsynopsis id='XtStringConversionWarning'> 933<funcprototype> 934<funcdef>void <function>XtStringConversionWarning</function></funcdef> 935 <paramdef>String <parameter>src</parameter></paramdef> 936</funcprototype> 937</funcsynopsis> 938 939<variablelist> 940 <varlistentry> 941 <term> 942 <emphasis remap='I'>src</emphasis> 943 </term> 944 <listitem> 945 <para> 946Specifies the string that could not be converted. 947 </para> 948 </listitem> 949 </varlistentry> 950 <varlistentry> 951 <term> 952 <emphasis remap='I'>dst_type</emphasis> 953 </term> 954 <listitem> 955 <para> 956Specifies the name of the type to which the string could not be converted. 957 </para> 958 </listitem> 959 </varlistentry> 960</variablelist> 961 962<para> 963The 964<xref linkend='XtStringConversionWarning' xrefstyle='select: title'/> 965function issues a warning message with name "conversionError", 966type "string", class "XtToolkitError, and the default message string 967"Cannot convert "<emphasis remap='I'>src</emphasis>" to type <emphasis remap='I'>dst_type</emphasis>". This routine 968has been superseded by 969<xref linkend='XtDisplayStringConversionWarning' xrefstyle='select: title'/>. 970</para> 971 972<para> 973To register an old-format converter, use 974<xref linkend='XtAddConverter' xrefstyle='select: title'/> 975or 976<xref linkend='XtAppAddConverter' xrefstyle='select: title'/>. 977</para> 978 979<funcsynopsis id='XtAddConverter'> 980<funcprototype> 981<funcdef>void <function>XtAddConverter</function></funcdef> 982 <paramdef>String <parameter>from_type</parameter></paramdef> 983 <paramdef>String <parameter>to_type</parameter></paramdef> 984 <paramdef>XtConverter <parameter>converter</parameter></paramdef> 985 <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef> 986 <paramdef>Cardinal <parameter>num_args</parameter></paramdef> 987</funcprototype> 988</funcsynopsis> 989 990<variablelist> 991 <varlistentry> 992 <term> 993 <emphasis remap='I'>from_type</emphasis> 994 </term> 995 <listitem> 996 <para> 997Specifies the source type. 998 </para> 999 </listitem> 1000 </varlistentry> 1001 <varlistentry> 1002 <term> 1003 <emphasis remap='I'>to_type</emphasis> 1004 </term> 1005 <listitem> 1006 <para> 1007Specifies the destination type. 1008 </para> 1009 </listitem> 1010 </varlistentry> 1011 <varlistentry> 1012 <term> 1013 <emphasis remap='I'>converter</emphasis> 1014 </term> 1015 <listitem> 1016 <para> 1017Specifies the type converter procedure. 1018 </para> 1019 </listitem> 1020 </varlistentry> 1021 <varlistentry> 1022 <term> 1023 <emphasis remap='I'>convert_args</emphasis> 1024 </term> 1025 <listitem> 1026 <para> 1027Specifies how to compute the additional arguments to the converter, or NULL. 1028 </para> 1029 </listitem> 1030 </varlistentry> 1031 <varlistentry> 1032 <term> 1033 <emphasis remap='I'>num_args</emphasis> 1034 </term> 1035 <listitem> 1036 <para> 1037Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>. 1038 </para> 1039 </listitem> 1040 </varlistentry> 1041</variablelist> 1042 1043<para> 1044<xref linkend='XtAddConverter' xrefstyle='select: title'/> 1045is equivalent in function to 1046<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/> 1047with <emphasis remap='I'>cache_type</emphasis> equal to 1048<function>XtCacheAll</function> 1049for old-format type converters. It has been superseded by 1050<xref linkend='XtSetTypeConverter' xrefstyle='select: title'/>. 1051</para> 1052 1053<funcsynopsis id='XtAppAddConverter'> 1054<funcprototype> 1055<funcdef>void <function>XtAppAddConverter</function></funcdef> 1056 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 1057 <paramdef>String <parameter>from_type</parameter></paramdef> 1058 <paramdef>String <parameter>to_type</parameter></paramdef> 1059 <paramdef>XtConverter <parameter>converter</parameter></paramdef> 1060 <paramdef>XtConvertArgList <parameter>convert_args</parameter></paramdef> 1061 <paramdef>Cardinal <parameter>num_args</parameter></paramdef> 1062</funcprototype> 1063</funcsynopsis> 1064 1065<variablelist> 1066 <varlistentry> 1067 <term> 1068 <emphasis remap='I'>app_context</emphasis> 1069 </term> 1070 <listitem> 1071 <para> 1072Specifies the application context. 1073 </para> 1074 </listitem> 1075 </varlistentry> 1076 <varlistentry> 1077 <term> 1078 <emphasis remap='I'>from_type</emphasis> 1079 </term> 1080 <listitem> 1081 <para> 1082Specifies the source type. 1083 </para> 1084 </listitem> 1085 </varlistentry> 1086 <varlistentry> 1087 <term> 1088 <emphasis remap='I'>to_type</emphasis> 1089 </term> 1090 <listitem> 1091 <para> 1092Specifies the destination type. 1093 </para> 1094 </listitem> 1095 </varlistentry> 1096 <varlistentry> 1097 <term> 1098 <emphasis remap='I'>converter</emphasis> 1099 </term> 1100 <listitem> 1101 <para> 1102Specifies the type converter procedure. 1103 </para> 1104 </listitem> 1105 </varlistentry> 1106 <varlistentry> 1107 <term> 1108 <emphasis remap='I'>convert_args</emphasis> 1109 </term> 1110 <listitem> 1111 <para> 1112Specifies how to compute the additional arguments to the converter, or NULL. 1113 </para> 1114 </listitem> 1115 </varlistentry> 1116 <varlistentry> 1117 <term> 1118 <emphasis remap='I'>num_args</emphasis> 1119 </term> 1120 <listitem> 1121 <para> 1122Specifies the number of entries in <emphasis remap='I'>convert_args</emphasis>. 1123 </para> 1124 </listitem> 1125 </varlistentry> 1126</variablelist> 1127 1128<para> 1129<xref linkend='XtAppAddConverter' xrefstyle='select: title'/> 1130is equivalent in function to 1131<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/> 1132with <emphasis remap='I'>cache_type</emphasis> equal to 1133<function>XtCacheAll</function> 1134for old-format type converters. It has been superseded by 1135<xref linkend='XtAppSetTypeConverter' xrefstyle='select: title'/>. 1136</para> 1137 1138<para> 1139To invoke resource conversions, a client may use 1140<xref linkend='XtConvert' xrefstyle='select: title'/> 1141or, for old-format converters only, 1142<xref linkend='XtDirectConvert' xrefstyle='select: title'/>. 1143</para> 1144 1145<funcsynopsis id='XtConvert'> 1146<funcprototype> 1147<funcdef>void <function>XtConvert</function></funcdef> 1148 <paramdef>Widget <parameter>w</parameter></paramdef> 1149 <paramdef>String <parameter>from_type</parameter></paramdef> 1150 <paramdef>XrmValuePtr <parameter>from</parameter></paramdef> 1151 <paramdef>String <parameter>to_type</parameter></paramdef> 1152 <paramdef>XrmValuePtr <parameter>to_return</parameter></paramdef> 1153</funcprototype> 1154</funcsynopsis> 1155 1156<variablelist> 1157 <varlistentry> 1158 <term> 1159 <emphasis remap='I'>w</emphasis> 1160 </term> 1161 <listitem> 1162 <para> 1163Specifies the widget to use for additional arguments, if any are 1164needed. 1165 </para> 1166 </listitem> 1167 </varlistentry> 1168 <varlistentry> 1169 <term> 1170 <emphasis remap='I'>from_type</emphasis> 1171 </term> 1172 <listitem> 1173 <para> 1174Specifies the source type. 1175 </para> 1176 </listitem> 1177 </varlistentry> 1178 <varlistentry> 1179 <term> 1180 <emphasis remap='I'>from</emphasis> 1181 </term> 1182 <listitem> 1183 <para> 1184Specifies the value to be converted. 1185 </para> 1186 </listitem> 1187 </varlistentry> 1188 <varlistentry> 1189 <term> 1190 <emphasis remap='I'>to_type</emphasis> 1191 </term> 1192 <listitem> 1193 <para> 1194Specifies the destination type. 1195 </para> 1196 </listitem> 1197 </varlistentry> 1198 <varlistentry> 1199 <term> 1200 <emphasis remap='I'>to_return</emphasis> 1201 </term> 1202 <listitem> 1203 <para> 1204Returns the converted value. 1205 </para> 1206 </listitem> 1207 </varlistentry> 1208</variablelist> 1209 1210 1211<funcsynopsis id='XtDirectConvert'> 1212<funcprototype> 1213<funcdef>void <function>XtDirectConvert</function></funcdef> 1214 <paramdef>XtConverter <parameter>converter</parameter></paramdef> 1215 <paramdef>XrmValuePtr <parameter>args</parameter></paramdef> 1216 <paramdef>Cardinal <parameter>num_args</parameter></paramdef> 1217 <paramdef>XrmValuePtr <parameter>from</parameter></paramdef> 1218 <paramdef>XrmValuePtr <parameter>to_return</parameter></paramdef> 1219</funcprototype> 1220</funcsynopsis> 1221 1222<variablelist> 1223 <varlistentry> 1224 <term> 1225 <emphasis remap='I'>converter</emphasis> 1226 </term> 1227 <listitem> 1228 <para> 1229Specifies the conversion procedure to be called. 1230 </para> 1231 </listitem> 1232 </varlistentry> 1233 <varlistentry> 1234 <term> 1235 <emphasis remap='I'>args</emphasis> 1236 </term> 1237 <listitem> 1238 <para> 1239Specifies the argument list that contains the additional arguments 1240needed to perform the conversion (often NULL). 1241 </para> 1242 </listitem> 1243 </varlistentry> 1244 <varlistentry> 1245 <term> 1246 <emphasis remap='I'>num_args</emphasis> 1247 </term> 1248 <listitem> 1249 <para> 1250Specifies the number of entries in <emphasis remap='I'>args</emphasis>. 1251 </para> 1252 </listitem> 1253 </varlistentry> 1254 <varlistentry> 1255 <term> 1256 <emphasis remap='I'>from</emphasis> 1257 </term> 1258 <listitem> 1259 <para> 1260Specifies the value to be converted. 1261 </para> 1262 </listitem> 1263 </varlistentry> 1264 <varlistentry> 1265 <term> 1266 <emphasis remap='I'>to_return</emphasis> 1267 </term> 1268 <listitem> 1269 <para> 1270Returns the converted value. 1271 </para> 1272 </listitem> 1273 </varlistentry> 1274</variablelist> 1275 1276<para> 1277The 1278<xref linkend='XtConvert' xrefstyle='select: title'/> 1279function looks up the type converter registered to convert <emphasis remap='I'>from_type</emphasis> 1280to <emphasis remap='I'>to_type</emphasis>, computes any additional arguments needed, and then calls 1281<xref linkend='XtDirectConvert' xrefstyle='select: title'/> 1282or 1283<xref linkend='XtCallConverter' xrefstyle='select: title'/>. 1284The 1285<xref linkend='XtDirectConvert' xrefstyle='select: title'/> 1286function looks in the converter cache to see if this conversion procedure 1287has been called with the specified arguments. 1288If so, it returns a descriptor for information stored in the cache; 1289otherwise, it calls the converter and enters the result in the cache. 1290</para> 1291 1292<para> 1293Before calling the specified converter, 1294<xref linkend='XtDirectConvert' xrefstyle='select: title'/> 1295sets the return value size to zero and the return value address to NULL. 1296To determine if the conversion was successful, 1297the client should check <emphasis remap='I'>to_return.addr</emphasis> for non-NULL. 1298The data returned by 1299<xref linkend='XtConvert' xrefstyle='select: title'/> 1300must be copied immediately by the caller, 1301as it may point to static data in the type converter. 1302</para> 1303 1304<para> 1305<xref linkend='XtConvert' xrefstyle='select: title'/> 1306has been replaced by 1307<xref linkend='XtConvertAndStore' xrefstyle='select: title'/>, 1308and 1309<xref linkend='XtDirectConvert' xrefstyle='select: title'/> 1310has been superseded by 1311<xref linkend='XtCallConverter' xrefstyle='select: title'/>. 1312</para> 1313 1314<para> 1315To deallocate a shared GC when it is no longer needed, use 1316<xref linkend='XtDestroyGC' xrefstyle='select: title'/>. 1317</para> 1318 1319<funcsynopsis id='XtDestroyGC'> 1320<funcprototype> 1321<funcdef>void <function>XtDestroyGC</function></funcdef> 1322 <paramdef>Widget <parameter>w</parameter></paramdef> 1323 <paramdef>GC <parameter>gc</parameter></paramdef> 1324</funcprototype> 1325</funcsynopsis> 1326 1327<variablelist> 1328 <varlistentry> 1329 <term> 1330 <emphasis remap='I'>w</emphasis> 1331 </term> 1332 <listitem> 1333 <para> 1334Specifies any object on the display for which the shared GC was 1335created. Must be of class Object or any subclass thereof. 1336 </para> 1337 </listitem> 1338 </varlistentry> 1339 <varlistentry> 1340 <term> 1341 <emphasis remap='I'>gc</emphasis> 1342 </term> 1343 <listitem> 1344 <para> 1345Specifies the shared GC to be deallocated. 1346 </para> 1347 </listitem> 1348 </varlistentry> 1349</variablelist> 1350 1351<para> 1352References to sharable GCs are counted and a free request is generated to the 1353server when the last user of a given GC destroys it. 1354Note that some earlier versions of 1355<xref linkend='XtDestroyGC' xrefstyle='select: title'/> 1356had only a <emphasis remap='I'>gc</emphasis> argument. 1357Therefore, this function is not very portable, 1358and you are encouraged to use 1359<xref linkend='XtReleaseGC' xrefstyle='select: title'/> 1360instead. 1361</para> 1362 1363<para> 1364To declare an action table in the default application context 1365and register it with the translation manager, use 1366<xref linkend='XtAddActions' xrefstyle='select: title'/>. 1367</para> 1368 1369<funcsynopsis id='XtAddActions'> 1370<funcprototype> 1371<funcdef>void <function>XtAddActions</function></funcdef> 1372 <paramdef>XtActionList <parameter>actions</parameter></paramdef> 1373 <paramdef>Cardinal <parameter>num_actions</parameter></paramdef> 1374</funcprototype> 1375</funcsynopsis> 1376 1377<variablelist> 1378 <varlistentry> 1379 <term> 1380 <emphasis remap='I'>actions</emphasis> 1381 </term> 1382 <listitem> 1383 <para> 1384Specifies the action table to register. 1385 </para> 1386 </listitem> 1387 </varlistentry> 1388 <varlistentry> 1389 <term> 1390 <emphasis remap='I'>num_actions</emphasis> 1391 </term> 1392 <listitem> 1393 <para> 1394Specifies the number of entries in <emphasis remap='I'>actions</emphasis>. 1395 </para> 1396 </listitem> 1397 </varlistentry> 1398</variablelist> 1399 1400<para> 1401If more than one action is registered with the same name, 1402the most recently registered action is used. 1403If duplicate actions exist in an action table, 1404the first is used. 1405The Intrinsics register an action table for 1406<xref linkend='XtMenuPopup' xrefstyle='select: title'/> 1407and 1408<xref linkend='XtMenuPopdown' xrefstyle='select: title'/> 1409as part of X Toolkit initialization. 1410This routine has been replaced by 1411<xref linkend='XtAppAddActions' xrefstyle='select: title'/>. 1412<xref linkend='XtInitialize' xrefstyle='select: title'/> 1413must be called before using this routine. 1414</para> 1415 1416<para> 1417To set the Intrinsics selection timeout in the default application context, use 1418<xref linkend='XtSetSelectionTimeout' xrefstyle='select: title'/>. 1419</para> 1420 1421<funcsynopsis id='XtSetSelectionTimeout'> 1422<funcprototype> 1423<funcdef>void <function>XtSetSelectionTimeout</function></funcdef> 1424 <paramdef>unsigned long <parameter>timeout</parameter></paramdef> 1425</funcprototype> 1426</funcsynopsis> 1427 1428 1429<variablelist> 1430 <varlistentry> 1431 <term> 1432 <emphasis remap='I'>timeout</emphasis> 1433 </term> 1434 <listitem> 1435 <para> 1436Specifies the selection timeout in milliseconds. 1437This routine has been replaced by 1438<xref linkend='XtAppSetSelectionTimeout' xrefstyle='select: title'/>. 1439<xref linkend='XtInitialize' xrefstyle='select: title'/> 1440must be called before using this routine. 1441 </para> 1442 </listitem> 1443 </varlistentry> 1444</variablelist> 1445 1446 1447<para> 1448To get the current selection timeout value in the default application 1449context, use 1450<xref linkend='XtGetSelectionTimeout' xrefstyle='select: title'/>. 1451</para> 1452 1453<funcsynopsis id='XtGetSelectionTimeout'> 1454<funcprototype> 1455<funcdef>unsigned long <function>XtGetSelectionTimeout</function></funcdef> 1456 <paramdef><parameter></parameter></paramdef> 1457</funcprototype> 1458</funcsynopsis> 1459 1460<para> 1461The selection timeout is the time within which the two communicating 1462applications must respond to one another. 1463If one of them does not respond within this interval, 1464the Intrinsics abort the selection request. 1465</para> 1466 1467<para> 1468This routine has been replaced by 1469<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/>. 1470<xref linkend='XtInitialize' xrefstyle='select: title'/> 1471must be called before using this routine. 1472</para> 1473 1474<para> 1475To obtain the global error database (for example, to merge with 1476an application- or widget-specific database), use 1477<xref linkend='XtGetErrorDatabase' xrefstyle='select: title'/>. 1478</para> 1479 1480<funcsynopsis id='XtGetErrorDatabase'> 1481<funcprototype> 1482<funcdef>XrmDatabase <function>*XtGetErrorDatabase</function></funcdef> 1483 <paramdef><parameter></parameter></paramdef> 1484</funcprototype> 1485</funcsynopsis> 1486 1487<para> 1488The 1489<xref linkend='XtGetErrorDatabase' xrefstyle='select: title'/> 1490function returns the address of the error database. 1491The Intrinsics do a lazy binding of the error database and do not merge in the 1492database file until the first call to 1493<function>XtGetErrorDatbaseText</function>. 1494This routine has been replaced by 1495<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/>. 1496</para> 1497 1498<para> 1499An error message handler can obtain the error database text for an 1500error or a warning by calling 1501<xref linkend='XtGetErrorDatabaseText' xrefstyle='select: title'/>. 1502</para> 1503 1504<funcsynopsis id='XtGetErrorDatabaseText'> 1505<funcprototype> 1506<funcdef>void <function>XtGetErrorDatabaseText</function></funcdef> 1507 <paramdef>String <parameter>name</parameter></paramdef> 1508 <paramdef>String <parameter>default</parameter></paramdef> 1509 <paramdef>String <parameter>buffer_return</parameter></paramdef> 1510 <paramdef>int <parameter>nbytes</parameter></paramdef> 1511</funcprototype> 1512</funcsynopsis> 1513 1514<variablelist> 1515 <varlistentry> 1516 <term> 1517 <emphasis remap='I'>name</emphasis> 1518 </term> 1519 <listitem> 1520 <para></para> 1521 </listitem> 1522 </varlistentry> 1523 <varlistentry> 1524 <term> 1525 <emphasis remap='I'>type</emphasis> 1526 </term> 1527 <listitem> 1528 <para> 1529Specify the name and type that are concatenated to form the resource name 1530of the error message. 1531 </para> 1532 </listitem> 1533 </varlistentry> 1534 <varlistentry> 1535 <term> 1536 <emphasis remap='I'>class</emphasis> 1537 </term> 1538 <listitem> 1539 <para> 1540Specifies the resource class of the error message. 1541 </para> 1542 </listitem> 1543 </varlistentry> 1544 <varlistentry> 1545 <term> 1546 <emphasis remap='I'>default</emphasis> 1547 </term> 1548 <listitem> 1549 <para> 1550Specifies the default message to use if an error database entry is not found. 1551 </para> 1552 </listitem> 1553 </varlistentry> 1554 <varlistentry> 1555 <term> 1556 <emphasis remap='I'>buffer_return</emphasis> 1557 </term> 1558 <listitem> 1559 <para> 1560Specifies the buffer into which the error message is to be returned. 1561 </para> 1562 </listitem> 1563 </varlistentry> 1564 <varlistentry> 1565 <term> 1566 <emphasis remap='I'>nbytes</emphasis> 1567 </term> 1568 <listitem> 1569 <para> 1570Specifies the size of the buffer in bytes. 1571 </para> 1572 </listitem> 1573 </varlistentry> 1574</variablelist> 1575 1576<para> 1577The 1578<xref linkend='XtGetErrorDatabaseText' xrefstyle='select: title'/> 1579returns the appropriate message from the error database 1580associated with the default application context 1581or returns the specified default message if one is not found in the 1582error database. 1583To form the full resource name and class when querying the database, 1584the <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>type</emphasis> are concatenated with a single "." 1585between them and the <emphasis remap='I'>class</emphasis> is concatenated with itself with a 1586single "." if it does not already contain a ".". 1587This routine has been superseded by 1588<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>. 1589</para> 1590 1591<para> 1592To register a procedure to be called on fatal error conditions, use 1593<xref linkend='XtSetErrorMsgHandler' xrefstyle='select: title'/>. 1594</para> 1595 1596<funcsynopsis id='XtSetErrorMsgHandler'> 1597<funcprototype> 1598<funcdef>void <function>XtSetErrorMsgHandler</function></funcdef> 1599 <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef> 1600</funcprototype> 1601</funcsynopsis> 1602 1603<variablelist> 1604 <varlistentry> 1605 <term> 1606 <emphasis remap='I'>msg_handler</emphasis> 1607 </term> 1608 <listitem> 1609 <para> 1610Specifies the new fatal error procedure, which should not return. 1611 </para> 1612 </listitem> 1613 </varlistentry> 1614</variablelist> 1615 1616<para> 1617The default error handler provided by the Intrinsics constructs a 1618string from the error resource database and calls 1619<xref linkend='XtError' xrefstyle='select: title'/>. 1620Fatal error message handlers should not return. 1621If one does, 1622subsequent Intrinsics behavior is undefined. 1623This routine has been superseded by 1624<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/>. 1625</para> 1626 1627<para> 1628To call the high-level error handler, use 1629<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. 1630</para> 1631 1632<funcsynopsis id='XtErrorMsg'> 1633<funcprototype> 1634<funcdef>void <function>XtErrorMsg</function></funcdef> 1635 <paramdef>String <parameter>name</parameter></paramdef> 1636 <paramdef>String <parameter>type</parameter></paramdef> 1637 <paramdef>String <parameter>class</parameter></paramdef> 1638 <paramdef>String <parameter>default</parameter></paramdef> 1639 <paramdef>String *<parameter>params</parameter></paramdef> 1640 <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> 1641</funcprototype> 1642</funcsynopsis> 1643 1644<variablelist> 1645 <varlistentry> 1646 <term> 1647 <emphasis remap='I'>name</emphasis> 1648 </term> 1649 <listitem> 1650 <para> 1651Specifies the general kind of error. 1652 </para> 1653 </listitem> 1654 </varlistentry> 1655 <varlistentry> 1656 <term> 1657 <emphasis remap='I'>type</emphasis> 1658 </term> 1659 <listitem> 1660 <para> 1661Specifies the detailed name of the error. 1662 </para> 1663 </listitem> 1664 </varlistentry> 1665 <varlistentry> 1666 <term> 1667 <emphasis remap='I'>class</emphasis> 1668 </term> 1669 <listitem> 1670 <para> 1671Specifies the resource class. 1672 </para> 1673 </listitem> 1674 </varlistentry> 1675 <varlistentry> 1676 <term> 1677 <emphasis remap='I'>default</emphasis> 1678 </term> 1679 <listitem> 1680 <para> 1681Specifies the default message to use if an error database entry is not found. 1682 </para> 1683 </listitem> 1684 </varlistentry> 1685 <varlistentry> 1686 <term> 1687 <emphasis remap='I'>params</emphasis> 1688 </term> 1689 <listitem> 1690 <para> 1691Specifies a pointer to a list of values to be stored in the message. 1692 </para> 1693 </listitem> 1694 </varlistentry> 1695 <varlistentry> 1696 <term> 1697 <emphasis remap='I'>num_params</emphasis> 1698 </term> 1699 <listitem> 1700 <para> 1701Specifies the number of entries in <emphasis remap='I'>params</emphasis>. 1702 </para> 1703 </listitem> 1704 </varlistentry> 1705</variablelist> 1706 1707<para> 1708This routine has been superseded by 1709<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>. 1710</para> 1711 1712<para> 1713To register a procedure to be called on nonfatal error conditions, use 1714<xref linkend='XtSetWarningMsgHandler' xrefstyle='select: title'/>. 1715</para> 1716 1717<funcsynopsis id='XtSetWarningMsgHandler'> 1718<funcprototype> 1719<funcdef>void <function>XtSetWarningMsgHandler</function></funcdef> 1720 <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef> 1721</funcprototype> 1722</funcsynopsis> 1723 1724<variablelist> 1725 <varlistentry> 1726 <term> 1727 <emphasis remap='I'>msg_handler</emphasis> 1728 </term> 1729 <listitem> 1730 <para> 1731Specifies the new nonfatal error procedure, which usually returns. 1732 </para> 1733 </listitem> 1734 </varlistentry> 1735</variablelist> 1736 1737<para> 1738The default warning handler provided by the Intrinsics constructs a string 1739from the error resource database and calls 1740<xref linkend='XtWarning' xrefstyle='select: title'/>. 1741This routine has been superseded by 1742<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/>. 1743</para> 1744 1745<para> 1746To call the installed high-level warning handler, use 1747<xref linkend='XtWarningMsg' xrefstyle='select: title'/>. 1748</para> 1749 1750<funcsynopsis id='XtWarningMsg'> 1751<funcprototype> 1752<funcdef>void <function>XtWarningMsg</function></funcdef> 1753 <paramdef>String <parameter>name</parameter></paramdef> 1754 <paramdef>String <parameter>type</parameter></paramdef> 1755 <paramdef>String <parameter>class</parameter></paramdef> 1756 <paramdef>String <parameter>default</parameter></paramdef> 1757 <paramdef>String *<parameter>params</parameter></paramdef> 1758 <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> 1759</funcprototype> 1760</funcsynopsis> 1761 1762<variablelist> 1763 <varlistentry> 1764 <term> 1765 <emphasis remap='I'>name</emphasis> 1766 </term> 1767 <listitem> 1768 <para> 1769Specifies the general kind of error. 1770 </para> 1771 </listitem> 1772 </varlistentry> 1773 <varlistentry> 1774 <term> 1775 <emphasis remap='I'>type</emphasis> 1776 </term> 1777 <listitem> 1778 <para> 1779Specifies the detailed name of the error. 1780 </para> 1781 </listitem> 1782 </varlistentry> 1783 <varlistentry> 1784 <term> 1785 <emphasis remap='I'>class</emphasis> 1786 </term> 1787 <listitem> 1788 <para> 1789Specifies the resource class. 1790 </para> 1791 </listitem> 1792 </varlistentry> 1793 <varlistentry> 1794 <term> 1795 <emphasis remap='I'>default</emphasis> 1796 </term> 1797 <listitem> 1798 <para> 1799Specifies the default message to use if an error database entry is not found. 1800 </para> 1801 </listitem> 1802 </varlistentry> 1803 <varlistentry> 1804 <term> 1805 <emphasis remap='I'>params</emphasis> 1806 </term> 1807 <listitem> 1808 <para> 1809Specifies a pointer to a list of values to be stored in the message. 1810 </para> 1811 </listitem> 1812 </varlistentry> 1813 <varlistentry> 1814 <term> 1815 <emphasis remap='I'>num_params</emphasis> 1816 </term> 1817 <listitem> 1818 <para> 1819Specifies the number of entries in <emphasis remap='I'>params</emphasis>. 1820 </para> 1821 </listitem> 1822 </varlistentry> 1823</variablelist> 1824 1825<para> 1826This routine has been superseded by 1827<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>. 1828</para> 1829 1830<para> 1831To register a procedure to be called on fatal error conditions, use 1832<xref linkend='XtSetErrorHandler' xrefstyle='select: title'/>. 1833</para> 1834 1835<funcsynopsis id='XtSetErrorHandler'> 1836<funcprototype> 1837<funcdef>void <function>XtSetErrorHandler</function></funcdef> 1838 <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef> 1839</funcprototype> 1840</funcsynopsis> 1841 1842<variablelist> 1843 <varlistentry> 1844 <term> 1845 <emphasis remap='I'>handler</emphasis> 1846 </term> 1847 <listitem> 1848 <para> 1849Specifies the new fatal error procedure, which should not return. 1850 </para> 1851 </listitem> 1852 </varlistentry> 1853</variablelist> 1854 1855<para> 1856The default error handler provided by the Intrinsics is 1857<function>_XtError</function>. 1858On POSIX-based systems, 1859it prints the message to standard error and terminates the application. 1860Fatal error message handlers should not return. 1861If one does, 1862subsequent X Toolkit behavior is undefined. 1863This routine has been superseded by 1864<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/>. 1865</para> 1866 1867<para> 1868To call the installed fatal error procedure, use 1869<xref linkend='XtError' xrefstyle='select: title'/>. 1870</para> 1871 1872<funcsynopsis id='XtError'> 1873<funcprototype> 1874<funcdef>void <function>XtError</function></funcdef> 1875 <paramdef>String <parameter>message</parameter></paramdef> 1876</funcprototype> 1877</funcsynopsis> 1878 1879<variablelist> 1880 <varlistentry> 1881 <term> 1882 <emphasis remap='I'>message</emphasis> 1883 </term> 1884 <listitem> 1885 <para> 1886Specifies the message to be reported. 1887 </para> 1888 </listitem> 1889 </varlistentry> 1890</variablelist> 1891 1892<para> 1893Most programs should use 1894<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>, 1895not 1896<xref linkend='XtError' xrefstyle='select: title'/>, 1897to provide for customization and internationalization of error 1898messages. This routine has been superseded by 1899<xref linkend='XtAppError' xrefstyle='select: title'/>. 1900</para> 1901 1902<para> 1903To register a procedure to be called on nonfatal error conditions, use 1904<xref linkend='XtSetWarningHandler' xrefstyle='select: title'/>. 1905</para> 1906 1907<funcsynopsis id='XtSetWarningHandler'> 1908<funcprototype> 1909<funcdef>void <function>XtSetWarningHandler</function></funcdef> 1910 <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef> 1911</funcprototype> 1912</funcsynopsis> 1913 1914<variablelist> 1915 <varlistentry> 1916 <term> 1917 <emphasis remap='I'>handler</emphasis> 1918 </term> 1919 <listitem> 1920 <para> 1921Specifies the new nonfatal error procedure, which usually returns. 1922 </para> 1923 </listitem> 1924 </varlistentry> 1925</variablelist> 1926 1927<para> 1928The default warning handler provided by the Intrinsics is 1929<function>_XtWarning</function>. 1930On POSIX-based systems, 1931it prints the message to standard error and returns to the caller. 1932This routine has been superseded by 1933<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/>. 1934</para> 1935 1936<para> 1937To call the installed nonfatal error procedure, use 1938<xref linkend='XtWarning' xrefstyle='select: title'/>. 1939</para> 1940 1941<funcsynopsis id='XtWarning'> 1942<funcprototype> 1943<funcdef>void <function>XtWarning</function></funcdef> 1944 <paramdef>String <parameter>message</parameter></paramdef> 1945</funcprototype> 1946</funcsynopsis> 1947 1948<variablelist> 1949 <varlistentry> 1950 <term> 1951 <emphasis remap='I'>message</emphasis> 1952 </term> 1953 <listitem> 1954 <para> 1955Specifies the nonfatal error message to be reported. 1956 </para> 1957 </listitem> 1958 </varlistentry> 1959</variablelist> 1960 1961<para> 1962Most programs should use 1963<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>, 1964not 1965<xref linkend='XtWarning' xrefstyle='select: title'/>, 1966to provide for customization and internationalization of warning messages. 1967This routine has been superseded by 1968<xref linkend='XtAppWarning' xrefstyle='select: title'/>. 1969</para> 1970</appendix> 1971