CH11.xml revision 9e7bcd65
1<chapter id='Utility_Functions'> 2<title>Utility Functions</title> 3<para> 4The Intrinsics provide a number of utility functions that you can use to 5</para> 6<itemizedlist spacing='compact'> 7 <listitem> 8 <para> 9Determine the number of elements in an array. 10 </para> 11 </listitem> 12 <listitem> 13 <para> 14Translate strings to widget instances. 15 </para> 16 </listitem> 17 <listitem> 18 <para> 19Manage memory usage. 20 </para> 21 </listitem> 22 <listitem> 23 <para> 24Share graphics contexts. 25 </para> 26 </listitem> 27 <listitem> 28 <para> 29Manipulate selections. 30 </para> 31 </listitem> 32 <listitem> 33 <para> 34Merge exposure events into a region. 35 </para> 36 </listitem> 37 <listitem> 38 <para> 39Translate widget coordinates. 40 </para> 41 </listitem> 42 <listitem> 43 <para> 44Locate a widget given a window id. 45 </para> 46 </listitem> 47 <listitem> 48 <para> 49Handle errors. 50 </para> 51 </listitem> 52 <listitem> 53 <para> 54Set the WM_COLORMAP_WINDOWS property. 55 </para> 56 </listitem> 57 <listitem> 58 <para> 59Locate files by name with string substitutions. 60 </para> 61 </listitem> 62 <listitem> 63 <para> 64Register callback functions for external agents. 65 </para> 66 </listitem> 67 <listitem> 68 <para> 69Locate all the displays of an application context. 70 </para> 71 </listitem> 72</itemizedlist> 73 74<sect1 id="Determining_the_Number_of_Elements_in_an_Array"> 75<title>Determining the Number of Elements in an Array</title> 76<para> 77To determine the number of elements in a fixed-size array, use 78<xref linkend='XtNumber' xrefstyle='select: title'/>. 79</para> 80 81<funcsynopsis id='XtNumber'> 82<funcprototype> 83<funcdef>Cardinal <function>XtNumber</function></funcdef> 84 <paramdef>ArrayType <parameter>array</parameter></paramdef> 85</funcprototype> 86</funcsynopsis> 87 88<variablelist> 89 <varlistentry> 90 <term> 91 <emphasis remap='I'>array</emphasis> 92 </term> 93 <listitem> 94 <para> 95Specifies a fixed-size array of arbitrary type. 96 </para> 97 </listitem> 98 </varlistentry> 99</variablelist> 100 101<para> 102The 103<xref linkend='XtNumber' xrefstyle='select: title'/> 104macro returns the number of elements allocated to the array. 105</para> 106</sect1> 107 108<sect1 id="Translating_Strings_to_Widget_Instances"> 109<title>Translating Strings to Widget Instances</title> 110<para> 111To translate a widget name to a widget instance, use 112<xref linkend='XtNameToWidget' xrefstyle='select: title'/>. 113</para> 114 115<funcsynopsis id='XtNameToWidget'> 116<funcprototype> 117<funcdef>Widget <function>XtNameToWidget</function></funcdef> 118 <paramdef>Widget <parameter>reference</parameter></paramdef> 119 <paramdef>String <parameter>names</parameter></paramdef> 120</funcprototype> 121</funcsynopsis> 122 123<variablelist> 124 <varlistentry> 125 <term> 126 <emphasis remap='I'>reference</emphasis> 127 </term> 128 <listitem> 129 <para> 130Specifies the widget from which the search is to start. Must be of class Core or any subclass thereof. 131 </para> 132 </listitem> 133 </varlistentry> 134 <varlistentry> 135 <term> 136 <emphasis remap='I'>names</emphasis> 137 </term> 138 <listitem> 139 <para> 140Specifies the partially qualified name of the desired widget. 141 </para> 142 </listitem> 143 </varlistentry> 144</variablelist> 145 146<para> 147The 148<xref linkend='XtNameToWidget' xrefstyle='select: title'/> 149function searches for a descendant of the <emphasis remap='I'>reference</emphasis> 150widget whose name matches the specified names. The <emphasis remap='I'>names</emphasis> parameter 151specifies a simple object name or a series of simple object name 152components separated by periods or asterisks. 153<xref linkend='XtNameToWidget' xrefstyle='select: title'/> 154returns the descendant with the shortest name matching the specification 155according to the following rules, where child is either a pop-up child 156or a normal child if the widget's class is a subclass of 157Composite : 158</para> 159<itemizedlist spacing='compact'> 160 <listitem> 161 <para> 162Enumerate the object subtree rooted at the reference widget in 163breadth-first order, qualifying the name of each object with the 164names of all its ancestors up to, but not including, the reference 165widget. The ordering between children of a common parent is 166not defined. 167 </para> 168 </listitem> 169 <listitem> 170 <para> 171Return the first object in the enumeration that matches the 172specified name, where each component of <emphasis remap='I'>names</emphasis> matches exactly the 173corresponding component of the qualified object name and asterisk 174matches any series of components, including none. 175 </para> 176 </listitem> 177 <listitem> 178 <para> 179If no match is found, return NULL. 180 </para> 181 </listitem> 182</itemizedlist> 183<para> 184Since breadth-first traversal is specified, the descendant with the 185shortest matching name (i.e., the fewest number of components), if any, 186will always be returned. However, since the order of enumeration of 187children is undefined and since the Intrinsics do not require that all 188children of a widget have unique names, 189<xref linkend='XtNameToWidget' xrefstyle='select: title'/> 190may return any 191child that matches if there are multiple objects in the subtree with 192the same name. Consecutive separators (periods or asterisks) 193including at least one asterisk are treated as a single asterisk. 194Consecutive periods are treated as a single period. 195</para> 196</sect1> 197 198<sect1 id="Managing_Memory_Usage"> 199<title>Managing Memory Usage</title> 200<para> 201The Intrinsics memory management functions provide uniform checking for 202null pointers and error reporting on memory allocation errors. 203These functions are completely compatible with their standard C language 204runtime counterparts 205<function>malloc</function>, 206<function>calloc</function>, 207<function>realloc</function>, 208and 209<function>free</function> 210with the following added functionality: 211</para> 212<itemizedlist spacing='compact'> 213 <listitem> 214 <para> 215<xref linkend='XtMalloc' xrefstyle='select: title'/>, 216<xref linkend='XtCalloc' xrefstyle='select: title'/>, 217and 218<xref linkend='XtRealloc' xrefstyle='select: title'/> 219give an error if there is not enough memory. 220 </para> 221 </listitem> 222 <listitem> 223 <para> 224<xref linkend='XtFree' xrefstyle='select: title'/> 225simply returns if passed a NULL pointer. 226 </para> 227 </listitem> 228 <listitem> 229 <para> 230<xref linkend='XtRealloc' xrefstyle='select: title'/> 231simply allocates new storage if passed a NULL pointer. 232 </para> 233 </listitem> 234</itemizedlist> 235<para> 236See the standard C library documentation on 237<function>malloc</function>, 238<function>calloc</function>, 239<function>realloc</function>, 240and 241<function>free</function> 242for more information. 243</para> 244 245<para> 246To allocate storage, use 247<xref linkend='XtMalloc' xrefstyle='select: title'/>. 248</para> 249 250<funcsynopsis id='XtMalloc'> 251<funcprototype> 252<funcdef>char * <function>XtMalloc</function></funcdef> 253 <paramdef>Cardinal <parameter>size</parameter></paramdef> 254</funcprototype> 255</funcsynopsis> 256 257<variablelist> 258 <varlistentry> 259 <term> 260 <emphasis remap='I'>size</emphasis> 261 </term> 262 <listitem> 263 <para> 264Specifies the number of bytes desired. 265 </para> 266 </listitem> 267 </varlistentry> 268</variablelist> 269 270<para> 271The 272<xref linkend='XtMalloc' xrefstyle='select: title'/> 273function returns a pointer to a block of storage of at least 274the specified <emphasis remap='I'>size</emphasis> bytes. 275If there is insufficient memory to allocate the new block, 276<xref linkend='XtMalloc' xrefstyle='select: title'/> 277calls 278<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. 279</para> 280 281<para> 282To allocate and initialize an array, use 283<xref linkend='XtCalloc' xrefstyle='select: title'/>. 284</para> 285 286<funcsynopsis id='XtCalloc'> 287<funcprototype> 288<funcdef>char * <function>XtCalloc</function></funcdef> 289 <paramdef>Cardinal <parameter>num</parameter></paramdef> 290 <paramdef>Cardinal <parameter>size</parameter></paramdef> 291</funcprototype> 292</funcsynopsis> 293 294<variablelist> 295 <varlistentry> 296 <term> 297 <emphasis remap='I'>num</emphasis> 298 </term> 299 <listitem> 300 <para> 301Specifies the number of array elements to allocate. 302 </para> 303 </listitem> 304 </varlistentry> 305 <varlistentry> 306 <term> 307 <emphasis remap='I'>size</emphasis> 308 </term> 309 <listitem> 310 <para> 311Specifies the size of each array element in bytes. 312 </para> 313 </listitem> 314 </varlistentry> 315</variablelist> 316 317<para> 318The 319<xref linkend='XtCalloc' xrefstyle='select: title'/> 320function allocates space for the specified number of array elements 321of the specified size and initializes the space to zero. 322If there is insufficient memory to allocate the new block, 323<xref linkend='XtCalloc' xrefstyle='select: title'/> 324calls 325<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. 326<xref linkend='XtCalloc' xrefstyle='select: title'/> 327returns the address of the allocated storage. 328</para> 329 330<para> 331To change the size of an allocated block of storage, use 332<xref linkend='XtRealloc' xrefstyle='select: title'/>. 333</para> 334 335<funcsynopsis id='XtRealloc'> 336<funcprototype> 337<funcdef>char *<function>XtRealloc</function></funcdef> 338 <paramdef>char *<parameter>ptr</parameter></paramdef> 339 <paramdef>Cardinal <parameter>num</parameter></paramdef> 340</funcprototype> 341</funcsynopsis> 342 343<variablelist> 344 <varlistentry> 345 <term> 346 <emphasis remap='I'>ptr</emphasis> 347 </term> 348 <listitem> 349 <para> 350Specifies a pointer to the old storage allocated with 351<xref linkend='XtMalloc' xrefstyle='select: title'/>, 352<xref linkend='XtCalloc' xrefstyle='select: title'/>, 353or 354<xref linkend='XtRealloc' xrefstyle='select: title'/>, 355or NULL. 356 </para> 357 </listitem> 358 </varlistentry> 359 <varlistentry> 360 <term> 361 <emphasis remap='I'>num</emphasis> 362 </term> 363 <listitem> 364 <para> 365Specifies number of bytes desired in new storage. 366 </para> 367 </listitem> 368 </varlistentry> 369</variablelist> 370 371<para> 372The 373<xref linkend='XtRealloc' xrefstyle='select: title'/> 374function changes the size of a block of storage, possibly moving it. 375Then it copies the old contents (or as much as will fit) into the new block 376and frees the old block. 377If there is insufficient memory to allocate the new block, 378<xref linkend='XtRealloc' xrefstyle='select: title'/> 379calls 380<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. 381If <emphasis remap='I'>ptr</emphasis> is NULL, 382<xref linkend='XtRealloc' xrefstyle='select: title'/> 383simply calls 384<xref linkend='XtMalloc' xrefstyle='select: title'/>. 385<xref linkend='XtRealloc' xrefstyle='select: title'/> 386then returns the address of the new block. 387</para> 388 389<para> 390To free an allocated block of storage, use 391<xref linkend='XtFree' xrefstyle='select: title'/>. 392</para> 393 394<funcsynopsis id='XtFree'> 395<funcprototype> 396<funcdef>void <function>XtFree</function></funcdef> 397 <paramdef>char *<parameter>ptr</parameter></paramdef> 398</funcprototype> 399</funcsynopsis> 400 401<variablelist> 402 <varlistentry> 403 <term> 404 <emphasis remap='I'>ptr</emphasis> 405 </term> 406 <listitem> 407 <para> 408Specifies a pointer to a block of storage allocated with 409<xref linkend='XtMalloc' xrefstyle='select: title'/>, 410<xref linkend='XtCalloc' xrefstyle='select: title'/>, 411or 412<xref linkend='XtRealloc' xrefstyle='select: title'/>, 413or NULL. 414 </para> 415 </listitem> 416 </varlistentry> 417</variablelist> 418 419<para> 420The 421<xref linkend='XtFree' xrefstyle='select: title'/> 422function returns storage, allowing it to be reused. 423If <emphasis remap='I'>ptr</emphasis> is NULL, 424<xref linkend='XtFree' xrefstyle='select: title'/> 425returns immediately. 426</para> 427 428<para> 429To allocate storage for a new instance of a type, use 430<xref linkend='XtNew' xrefstyle='select: title'/>. 431</para> 432 433 434<funcsynopsis id='XtNew'> 435<funcprototype> 436<funcdef>type <function>XtNew</function></funcdef> 437 <paramdef>type <parameter>t</parameter></paramdef> 438</funcprototype> 439</funcsynopsis> 440 441<variablelist> 442 <varlistentry> 443 <term> 444 <emphasis remap='I'>type</emphasis> 445 </term> 446 <listitem> 447 <para> 448Specifies a previously declared type. 449 </para> 450 </listitem> 451 </varlistentry> 452</variablelist> 453 454<para> 455<xref linkend='XtNew' xrefstyle='select: title'/> 456returns a pointer to the allocated storage. 457If there is insufficient memory to allocate the new block, 458<xref linkend='XtNew' xrefstyle='select: title'/> 459calls 460<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. 461<xref linkend='XtNew' xrefstyle='select: title'/> 462is a convenience macro that calls 463<xref linkend='XtMalloc' xrefstyle='select: title'/> 464with the following arguments specified: 465</para> 466<literallayout > 467((type *) XtMalloc((unsigned) sizeof(type))) 468</literallayout> 469<para> 470The storage allocated by 471<xref linkend='XtNew' xrefstyle='select: title'/> 472should be freed using 473<xref linkend='XtFree' xrefstyle='select: title'/>. 474</para> 475 476<para> 477To copy an instance of a string, use 478<xref linkend='XtNewString' xrefstyle='select: title'/>. 479</para> 480 481<funcsynopsis id='XtNewString'> 482<funcprototype> 483<funcdef>String <function>XtNewString</function></funcdef> 484 <paramdef>String <parameter>string</parameter></paramdef> 485</funcprototype> 486</funcsynopsis> 487 488<variablelist> 489 <varlistentry> 490 <term> 491 <emphasis remap='I'>string</emphasis> 492 </term> 493 <listitem> 494 <para> 495Specifies a previously declared string. 496 </para> 497 </listitem> 498 </varlistentry> 499</variablelist> 500 501<para> 502<xref linkend='XtNewString' xrefstyle='select: title'/> 503returns a pointer to the allocated storage. 504If there is insufficient memory to allocate the new block, 505<xref linkend='XtNewString' xrefstyle='select: title'/> 506calls 507<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. 508<xref linkend='XtNewString' xrefstyle='select: title'/> 509is a convenience macro that calls 510<xref linkend='XtMalloc' xrefstyle='select: title'/> 511with the following arguments specified: 512</para> 513<literallayout > 514(strcpy(XtMalloc((unsigned)strlen(str) + 1), str)) 515</literallayout> 516<para> 517The storage allocated by 518<xref linkend='XtNewString' xrefstyle='select: title'/> 519should be freed using 520<xref linkend='XtFree' xrefstyle='select: title'/>. 521</para> 522</sect1> 523 524<sect1 id="Sharing_Graphics_Contexts"> 525<title>Sharing Graphics Contexts</title> 526<para> 527The Intrinsics provide a mechanism whereby cooperating objects can share a 528graphics context (GC), thereby reducing both the number of GCs 529created and the total number of server calls in any given application. 530The mechanism is a simple caching scheme 531and allows for clients to declare both modifiable and nonmodifiable 532fields of the shared GCs. 533</para> 534 535<para> 536To obtain a shareable GC with modifiable fields, use 537<xref linkend='XtAllocateGC' xrefstyle='select: title'/>. 538</para> 539 540<funcsynopsis id='XtAllocateGC'> 541<funcprototype> 542<funcdef>GC <function>XtAllocateGC</function></funcdef> 543 <paramdef>Widget <parameter>object</parameter></paramdef> 544 <paramdef>Cardinal <parameter>depth</parameter></paramdef> 545 <paramdef>XtGCMask <parameter>value_mask</parameter></paramdef> 546 <paramdef>XGCValues *<parameter>values</parameter></paramdef> 547 <paramdef>XtGCMask <parameter>dynamic_mask</parameter></paramdef> 548 <paramdef>XtGCMask <parameter>unused_mask</parameter></paramdef> 549</funcprototype> 550</funcsynopsis> 551 552<variablelist> 553 <varlistentry> 554 <term> 555 <emphasis remap='I'>object</emphasis> 556 </term> 557 <listitem> 558 <para> 559Specifies an object, giving the screen for which the 560returned GC is valid. Must be of class Object or any subclass thereof. 561 </para> 562 </listitem> 563 </varlistentry> 564 <varlistentry> 565 <term> 566 <emphasis remap='I'>depth</emphasis> 567 </term> 568 <listitem> 569 <para> 570Specifies the depth for which the returned GC is valid, or 0. 571 </para> 572 </listitem> 573 </varlistentry> 574 <varlistentry> 575 <term> 576 <emphasis remap='I'>value_mask</emphasis> 577 </term> 578 <listitem> 579 <para> 580Specifies fields of the GC that are initialized from <emphasis remap='I'>values</emphasis>. 581 </para> 582 </listitem> 583 </varlistentry> 584 <varlistentry> 585 <term> 586 <emphasis remap='I'>values</emphasis> 587 </term> 588 <listitem> 589 <para> 590Specifies the values for the initialized fields. 591 </para> 592 </listitem> 593 </varlistentry> 594 <varlistentry> 595 <term> 596 <emphasis remap='I'>dynamic_mask</emphasis> 597 </term> 598 <listitem> 599 <para> 600Specifies fields of the GC that will be modified by the caller. 601 </para> 602 </listitem> 603 </varlistentry> 604 <varlistentry> 605 <term> 606 <emphasis remap='I'>unused_mask</emphasis> 607 </term> 608 <listitem> 609 <para> 610Specifies fields of the GC that will not be needed by the caller. 611 </para> 612 </listitem> 613 </varlistentry> 614</variablelist> 615 616<para> 617The 618<xref linkend='XtAllocateGC' xrefstyle='select: title'/> 619function returns a shareable GC that may be 620modified by the client. The <emphasis remap='I'>screen</emphasis> field of the specified 621widget or of the nearest widget ancestor of the specified 622object and the specified <emphasis remap='I'>depth</emphasis> argument supply 623the root and drawable depths for which the GC is to be 624valid. If <emphasis remap='I'>depth</emphasis> is zero, the depth is taken from the 625<emphasis remap='I'>depth</emphasis> field of the specified widget or of the nearest 626widget ancestor of the specified object. 627</para> 628 629<para> 630The <emphasis remap='I'>value_mask</emphasis> argument specifies fields of the GC 631that are initialized with the respective member of the 632<emphasis remap='I'>values</emphasis> structure. The <emphasis remap='I'>dynamic_mask</emphasis> argument specifies fields 633that the caller intends to modify during program execution. 634The caller must ensure that the corresponding GC field is set 635prior to each use of the GC. The <emphasis remap='I'>unused_mask</emphasis> argument 636specifies fields of the GC that are of no interest to the 637caller. The caller may make no assumptions about the contents 638of any fields specified in <emphasis remap='I'>unused_mask</emphasis>. The caller may assume 639that at all times all fields not specified in either 640<emphasis remap='I'>dynamic_mask</emphasis> or <emphasis remap='I'>unused_mask</emphasis> have their default value if not 641specified in <emphasis remap='I'>value_mask</emphasis> or the value specified by <emphasis remap='I'>values</emphasis>. 642If a field is specified in both <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>dynamic_mask</emphasis>, 643the effect is as if it were specified only in <emphasis remap='I'>dynamic_mask</emphasis> 644and then immediately set to the value in <emphasis remap='I'>values</emphasis>. If a field 645is set in <emphasis remap='I'>unused_mask</emphasis> and also in either <emphasis remap='I'>value_mask</emphasis> or 646<emphasis remap='I'>dynamic_mask</emphasis>, the specification in <emphasis remap='I'>unused_mask</emphasis> is ignored. 647</para> 648 649<para> 650<xref linkend='XtAllocateGC' xrefstyle='select: title'/> 651tries to minimize the number of unique GCs 652created by comparing the arguments with those of previous 653calls and returning an existing GC when there are no 654conflicts. 655<xref linkend='XtAllocateGC' xrefstyle='select: title'/> 656may modify and return an existing GC if it was allocated with a 657nonzero <emphasis remap='I'>unused_mask</emphasis>. 658</para> 659 660<para> 661To obtain a shareable GC with no modifiable fields, use 662<xref linkend='XtGetGC' xrefstyle='select: title'/>. 663</para> 664 665<funcsynopsis id='XtGetGC'> 666<funcprototype> 667<funcdef>GC <function>XtGetGC</function></funcdef> 668 <paramdef>Widget <parameter>object</parameter></paramdef> 669 <paramdef>XtGCMask <parameter>value_mask</parameter></paramdef> 670 <paramdef>XGCValues *<parameter>values</parameter></paramdef> 671</funcprototype> 672</funcsynopsis> 673 674<variablelist> 675 <varlistentry> 676 <term> 677 <emphasis remap='I'>object</emphasis> 678 </term> 679 <listitem> 680 <para> 681Specifies an object, giving the screen and depth for which the 682returned GC is valid. Must be of class Object or any subclass thereof. 683 </para> 684 </listitem> 685 </varlistentry> 686 <varlistentry> 687 <term> 688 <emphasis remap='I'>value_mask</emphasis> 689 </term> 690 <listitem> 691 <para> 692Specifies which fields of the <emphasis remap='I'>values</emphasis> structure are specified. 693 </para> 694 </listitem> 695 </varlistentry> 696 <varlistentry> 697 <term> 698 <emphasis remap='I'>values</emphasis> 699 </term> 700 <listitem> 701 <para> 702Specifies the actual values for this GC. 703 </para> 704 </listitem> 705 </varlistentry> 706</variablelist> 707 708<para> 709The 710<xref linkend='XtGetGC' xrefstyle='select: title'/> 711function returns a shareable, read-only GC. 712The parameters to this function are the same as those for 713<function>XCreateGC</function> 714except that an Object is passed instead of a Display. 715<xref linkend='XtGetGC' xrefstyle='select: title'/> 716is equivalent to 717<xref linkend='XtAllocateGC' xrefstyle='select: title'/> 718with <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>dynamic_mask</emphasis>, and <emphasis remap='I'>unused_mask</emphasis> all zero. 719</para> 720 721<para> 722<xref linkend='XtGetGC' xrefstyle='select: title'/> 723shares only GCs in which all values in the GC returned by 724<function>XCreateGC</function> 725are the same. 726In particular, it does not use the <emphasis remap='I'>value_mask</emphasis> provided to 727determine which fields of the GC a widget considers relevant. 728The <emphasis remap='I'>value_mask</emphasis> is used only to tell the server which fields should be 729filled in from <emphasis remap='I'>values</emphasis> and which it should fill in with default values. 730</para> 731 732<para> 733To deallocate a shared GC when it is no longer needed, use 734<xref linkend='XtReleaseGC' xrefstyle='select: title'/>. 735</para> 736 737<funcsynopsis id='XtReleaseGC'> 738<funcprototype> 739<funcdef>void <function>XtReleaseGC</function></funcdef> 740 <paramdef>Widget <parameter>object</parameter></paramdef> 741 <paramdef>GC <parameter>gc</parameter></paramdef> 742</funcprototype> 743</funcsynopsis> 744 745<variablelist> 746 <varlistentry> 747 <term> 748 <emphasis remap='I'>object</emphasis> 749 </term> 750 <listitem> 751 <para> 752Specifies any object on the Display for which the GC was created. Must be of class Object or any subclass thereof. 753 </para> 754 </listitem> 755 </varlistentry> 756 <varlistentry> 757 <term> 758 <emphasis remap='I'>gc</emphasis> 759 </term> 760 <listitem> 761 <para> 762Specifies the shared GC obtained with either 763<xref linkend='XtAllocateGC' xrefstyle='select: title'/> 764or 765<xref linkend='XtGetGC' xrefstyle='select: title'/>. 766 </para> 767 </listitem> 768 </varlistentry> 769</variablelist> 770 771<para> 772References to shareable GCs are counted and a free request is generated to the 773server when the last user of a given GC releases it. 774</para> 775</sect1> 776 777<sect1 id="Managing_Selections"> 778<title>Managing Selections</title> 779<para> 780Arbitrary widgets in multiple applications can communicate 781with each other by means of the Intrinsics global selection mechanism, 782which conforms to the specifications in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>. 783The Intrinsics supply functions for providing and receiving selection data in 784one logical piece (atomic transfers) 785or in smaller logical segments (incremental transfers). 786</para> 787 788<para> 789The incremental interface is provided for a selection owner or 790selection requestor that cannot or prefers not to pass the selection 791value to and from the Intrinsics in a single call. For instance, 792either an application that is running on a machine with limited memory 793may not be able to store the entire selection value in memory or a 794selection owner may already have the selection value available in 795discrete chunks, and it would be more efficient not to have to 796allocate additional storage to copy the pieces contiguously. Any 797owner or requestor that prefers to deal with the selection value in 798segments can use the incremental interfaces to do so. 799The transfer between the selection owner or requestor and the Intrinsics is not 800required to match the underlying 801transport protocol between the application and the X server; 802the Intrinsics will break too large a selection 803into smaller pieces for transport if necessary 804and will coalesce a selection transmitted incrementally if the value 805was requested atomically. 806</para> 807 808<sect2 id='Setting_and_Getting_the_Selection_Timeout_Value'> 809<title>Setting and Getting the Selection Timeout Value</title> 810<para> 811To set the Intrinsics selection timeout, use 812<xref linkend='XtAppSetSelectionTimeout' xrefstyle='select: title'/>. 813</para> 814 815<funcsynopsis id='XtAppSetSelectionTimeout'> 816<funcprototype> 817<funcdef>void <function>XtAppSetSelectionTimeout</function></funcdef> 818 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 819 <paramdef>unsigned long <parameter>timeout</parameter></paramdef> 820</funcprototype> 821</funcsynopsis> 822 823<variablelist> 824 <varlistentry> 825 <term> 826 <emphasis remap='I'>app_context</emphasis> 827 </term> 828 <listitem> 829 <para> 830Specifies the application context. 831 </para> 832 </listitem> 833 </varlistentry> 834 <varlistentry> 835 <term> 836 <emphasis remap='I'>timeout</emphasis> 837 </term> 838 <listitem> 839 <para> 840Specifies the selection timeout in milliseconds. 841 </para> 842 </listitem> 843 </varlistentry> 844</variablelist> 845 846<para> 847To get the current selection timeout value, use 848<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/>. 849</para> 850 851<funcsynopsis id='XtAppGetSelectionTimeout'> 852<funcprototype> 853<funcdef>unsigned long <function>XtAppGetSelectionTimeout</function></funcdef> 854 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 855</funcprototype> 856</funcsynopsis> 857 858<variablelist> 859 <varlistentry> 860 <term> 861 <emphasis remap='I'>app_context</emphasis> 862 </term> 863 <listitem> 864 <para> 865Specifies the application context. 866 </para> 867 </listitem> 868 </varlistentry> 869</variablelist> 870 871<para> 872The 873<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/> 874function returns the current selection timeout value in milliseconds. 875The selection timeout is the time within which the two communicating 876applications must respond to one another. 877The initial timeout value is set by the 878selectionTimeout 879application resource as retrieved by 880<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>. 881If 882selectionTimeout 883is not specified, 884the default is five seconds. 885</para> 886</sect2> 887 888<sect2 id="Using_Atomic_Transfers"> 889<title>Using Atomic Transfers</title> 890<para> 891When using atomic transfers, the owner will completely 892process one selection request at a time. 893The owner may consider each request individually, 894since there is no possibility for overlap 895between evaluation of two requests. 896</para> 897 898<sect3 id="Atomic_Transfer_Procedures"> 899<title>Atomic Transfer Procedures</title> 900<para> 901The following procedures are used by the selection owner when 902providing selection data in a single unit. 903</para> 904 905<para> 906The procedure pointer specified by the owner to supply the selection 907data to the Intrinsics is of type 908<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>. 909</para> 910 911<funcsynopsis id='XtConvertSelectionProc'> 912<funcprototype> 913<funcdef>typedef Boolean <function>(*XtConvertSelectionProc)</function></funcdef> 914 <paramdef>Widget <parameter>w</parameter></paramdef> 915 <paramdef>Atom *<parameter>selection</parameter></paramdef> 916 <paramdef>Atom *<parameter>target</parameter></paramdef> 917 <paramdef>Atom *<parameter>type_return</parameter></paramdef> 918 <paramdef>XtPointer *<parameter>value_return</parameter></paramdef> 919 <paramdef>unsigned long *<parameter>length_return</parameter></paramdef> 920 <paramdef>int *<parameter>format_return</parameter></paramdef> 921</funcprototype> 922</funcsynopsis> 923 924<variablelist> 925 <varlistentry> 926 <term> 927 <emphasis remap='I'>w</emphasis> 928 </term> 929 <listitem> 930 <para> 931Specifies the widget that currently owns this selection. 932 </para> 933 </listitem> 934 </varlistentry> 935 <varlistentry> 936 <term> 937 <emphasis remap='I'>selection</emphasis> 938 </term> 939 <listitem> 940 <para> 941Specifies the atom naming the selection requested 942(for example, 943<function>XA_PRIMARY</function> 944or 945<function>XA_SECONDARY ).</function> 946 </para> 947 </listitem> 948 </varlistentry> 949 <varlistentry> 950 <term> 951 <emphasis remap='I'>target</emphasis> 952 </term> 953 <listitem> 954 <para> 955Specifies the target type of the selection that has been requested, 956which indicates the desired information about the selection 957(for example, File Name, Text, Window). 958 </para> 959 </listitem> 960 </varlistentry> 961 <varlistentry> 962 <term> 963 <emphasis remap='I'>type_return</emphasis> 964 </term> 965 <listitem> 966 <para> 967Specifies a pointer to an atom into which the property type of the 968converted value of the selection is to be stored. 969For instance, either File Name or Text might have property type 970<function>XA_STRING</function>. 971 </para> 972 </listitem> 973 </varlistentry> 974 <varlistentry> 975 <term> 976 <emphasis remap='I'>value_return</emphasis> 977 </term> 978 <listitem> 979 <para> 980Specifies a pointer into which a pointer to the converted value of the 981selection is to be stored. 982The selection owner is responsible for allocating this storage. 983If the selection owner has provided an 984<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/> 985for the selection, 986this storage is owned by the selection owner; 987otherwise, it is owned by the Intrinsics selection mechanism, 988which frees it by calling 989<xref linkend='XtFree' xrefstyle='select: title'/> 990when it is done with it. 991 </para> 992 </listitem> 993 </varlistentry> 994 <varlistentry> 995 <term> 996 <emphasis remap='I'>length_return</emphasis> 997 </term> 998 <listitem> 999 <para> 1000Specifies a pointer into which the number of elements in <emphasis remap='I'>value_return</emphasis>, 1001each of size indicated by <emphasis remap='I'>format_return</emphasis>, is to be stored. 1002 </para> 1003 </listitem> 1004 </varlistentry> 1005 <varlistentry> 1006 <term> 1007 <emphasis remap='I'>format_return</emphasis> 1008 </term> 1009 <listitem> 1010 <para> 1011Specifies a pointer into which the size in bits of the data elements 1012of the selection value is to be stored. 1013 </para> 1014 </listitem> 1015 </varlistentry> 1016</variablelist> 1017 1018<para> 1019This procedure is called by the Intrinsics selection mechanism 1020to get the value of a selection as a given type 1021from the current selection owner. 1022It returns 1023<function>True</function> 1024if the owner successfully converted the selection to the target type or 1025<function>False</function> 1026otherwise. 1027If the procedure returns 1028<function>False</function>, 1029the values of the return arguments are undefined. 1030Each 1031<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/> 1032should respond to target value 1033<function>TARGETS</function> 1034by returning a value containing the list of the targets 1035into which it is 1036prepared to convert the selection. 1037The value returned in 1038<emphasis remap='I'>format_return</emphasis> must be one of 8, 16, or 32 to allow the server to 1039byte-swap the data if necessary. 1040</para> 1041 1042<para> 1043This procedure does not need to worry about responding to the 1044MULTIPLE or the TIMESTAMP target values (see 1045<xref linkend='Window_Creation_Convenience_Routine' /> 1046in the <olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>). 1047A selection request with 1048the MULTIPLE target type is transparently transformed into a 1049series of calls to this procedure, one for each target type, and a 1050selection request with the TIMESTAMP target value is answered 1051automatically by the Intrinsics using the time specified in the 1052call to 1053<xref linkend='XtOwnSelection' xrefstyle='select: title'/> 1054or 1055<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>. 1056</para> 1057 1058<para> 1059To retrieve the 1060<function>SelectionRequest</function> 1061event that triggered the 1062<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/> 1063procedure, use 1064<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>. 1065</para> 1066 1067<funcsynopsis id='XtGetSelectionRequest'> 1068<funcprototype> 1069<funcdef>XSelectionRequestEvent *<function>XtGetSelectionRequest</function></funcdef> 1070 <paramdef>Widget <parameter>w</parameter></paramdef> 1071 <paramdef>Atom <parameter>selection</parameter></paramdef> 1072 <paramdef>XtRequestId <parameter>request_id</parameter></paramdef> 1073</funcprototype> 1074</funcsynopsis> 1075 1076<variablelist> 1077 <varlistentry> 1078 <term> 1079 <emphasis remap='I'>w</emphasis> 1080 </term> 1081 <listitem> 1082 <para> 1083Specifies the widget that currently owns this selection. Must be of class Core or any subclass thereof. 1084 </para> 1085 </listitem> 1086 </varlistentry> 1087 <varlistentry> 1088 <term> 1089 <emphasis remap='I'>selection</emphasis> 1090 </term> 1091 <listitem> 1092 <para> 1093Specifies the selection being processed. 1094 </para> 1095 </listitem> 1096 </varlistentry> 1097 <varlistentry> 1098 <term> 1099 <emphasis remap='I'>request_id</emphasis> 1100 </term> 1101 <listitem> 1102 <para> 1103Specifies the requestor id in the case of incremental 1104selections, or NULL in the case of atomic transfers. 1105 </para> 1106 </listitem> 1107 </varlistentry> 1108</variablelist> 1109 1110<para> 1111<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/> 1112may be called only from within an 1113<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/> 1114procedure and returns a pointer to the 1115<function>SelectionRequest</function> 1116event that caused the conversion procedure to be invoked. 1117<emphasis remap='I'>Request_id</emphasis> specifies a unique id for the individual request in the 1118case that multiple incremental transfers are outstanding. For atomic 1119transfers, <emphasis remap='I'>request_id</emphasis> must be specified as NULL. If no 1120<function>SelectionRequest</function> 1121event is being processed for the specified 1122<emphasis remap='I'>widget</emphasis>, <emphasis remap='I'>selection</emphasis>, and <emphasis remap='I'>request_id</emphasis>, 1123<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/> 1124returns NULL. 1125</para> 1126 1127<para> 1128The procedure pointer specified by the owner when it desires 1129notification upon losing ownership is of type 1130<xref linkend='XtLoseSelectionProc' xrefstyle='select: title'/>. 1131</para> 1132 1133<funcsynopsis id='XtLoseSelectionProc'> 1134<funcprototype> 1135<funcdef>typedef void <function>(*XtLoseSelectionProc)</function></funcdef> 1136 <paramdef>Widget <parameter>w</parameter></paramdef> 1137 <paramdef>Atom *<parameter>selection</parameter></paramdef> 1138</funcprototype> 1139</funcsynopsis> 1140 1141<variablelist> 1142 <varlistentry> 1143 <term> 1144 <emphasis remap='I'>w</emphasis> 1145 </term> 1146 <listitem> 1147 <para> 1148Specifies the widget that has lost selection ownership. 1149 </para> 1150 </listitem> 1151 </varlistentry> 1152 <varlistentry> 1153 <term> 1154 <emphasis remap='I'>selection</emphasis> 1155 </term> 1156 <listitem> 1157 <para> 1158Specifies the atom naming the selection. 1159 </para> 1160 </listitem> 1161 </varlistentry> 1162</variablelist> 1163 1164<para> 1165This procedure is called by the Intrinsics selection mechanism 1166to inform the specified widget that it has lost the given selection. 1167Note that this procedure does not ask the widget to relinquish the 1168selection ownership; it is merely informative. 1169</para> 1170 1171<para> 1172The procedure pointer specified by the owner when it desires 1173notification of receipt of the data or when it manages the storage 1174containing the data is of type 1175<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>. 1176</para> 1177 1178<funcsynopsis id='XtSelectionDoneProc'> 1179<funcprototype> 1180<funcdef>typedef void <function>(*XtSelectionDoneProc)</function></funcdef> 1181 <paramdef>Widget <parameter>w</parameter></paramdef> 1182 <paramdef>Atom *<parameter>selection</parameter></paramdef> 1183 <paramdef>Atom *<parameter>target</parameter></paramdef> 1184</funcprototype> 1185</funcsynopsis> 1186 1187<variablelist> 1188 <varlistentry> 1189 <term> 1190 <emphasis remap='I'>w</emphasis> 1191 </term> 1192 <listitem> 1193 <para> 1194Specifies the widget that owns the converted selection. 1195 </para> 1196 </listitem> 1197 </varlistentry> 1198 <varlistentry> 1199 <term> 1200 <emphasis remap='I'>selection</emphasis> 1201 </term> 1202 <listitem> 1203 <para> 1204Specifies the atom naming the selection that was converted. 1205 </para> 1206 </listitem> 1207 </varlistentry> 1208 <varlistentry> 1209 <term> 1210 <emphasis remap='I'>target</emphasis> 1211 </term> 1212 <listitem> 1213 <para> 1214Specifies the target type to which the conversion was done. 1215 </para> 1216 </listitem> 1217 </varlistentry> 1218</variablelist> 1219 1220<para> 1221This procedure is called by the Intrinsics selection mechanism 1222to inform the selection owner that a selection requestor has successfully 1223retrieved a selection value. 1224If the selection owner has registered an 1225<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>, 1226it should expect it to be called once for each conversion that it performs, 1227after the converted value has been successfully transferred 1228to the requestor. 1229If the selection owner has registered an 1230<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>, 1231it also owns the storage containing the converted 1232selection value. 1233</para> 1234</sect3> 1235<sect3 id="Getting_the_Selection_Value"> 1236<title>Getting the Selection Value</title> 1237<para> 1238The procedure pointer specified by the requestor to receive the 1239selection data from the Intrinsics is of type 1240<xref linkend='XtSelectionCallbackProc' xrefstyle='select: title'/>. 1241</para> 1242 1243<funcsynopsis id='XtSelectionCallbackProc'> 1244<funcprototype> 1245<funcdef>typedef void <function>(*XtSelectionCallbackPro)</function></funcdef> 1246 <paramdef>Widget <parameter>w</parameter></paramdef> 1247 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 1248 <paramdef>Atom *<parameter>selection</parameter></paramdef> 1249 <paramdef>Atom *<parameter>type</parameter></paramdef> 1250 <paramdef>XtPointer <parameter>value</parameter></paramdef> 1251 <paramdef>unsigned long *<parameter>length</parameter></paramdef> 1252 <paramdef>int *<parameter>format</parameter></paramdef> 1253</funcprototype> 1254</funcsynopsis> 1255 1256<variablelist> 1257 <varlistentry> 1258 <term> 1259 <emphasis remap='I'>w</emphasis> 1260 </term> 1261 <listitem> 1262 <para> 1263Specifies the widget that requested the selection value. 1264 </para> 1265 </listitem> 1266 </varlistentry> 1267 <varlistentry> 1268 <term> 1269 <emphasis remap='I'>client_data</emphasis> 1270 </term> 1271 <listitem> 1272 <para> 1273Specifies a value passed in by the widget when it requested the 1274selection. 1275 </para> 1276 </listitem> 1277 </varlistentry> 1278 <varlistentry> 1279 <term> 1280 <emphasis remap='I'>selection</emphasis> 1281 </term> 1282 <listitem> 1283 <para> 1284Specifies the name of the selection that was requested. 1285 </para> 1286 </listitem> 1287 </varlistentry> 1288 <varlistentry> 1289 <term> 1290 <emphasis remap='I'>type</emphasis> 1291 </term> 1292 <listitem> 1293 <para> 1294Specifies the representation type of the selection value (for example, 1295<function>XA_STRING ).</function> 1296Note that it is not the target that was requested (which the client 1297must remember for itself), but the type that 1298is used to represent the target. 1299The special symbolic constant 1300<function>XT_CONVERT_FAIL</function> 1301is used to indicate that the selection conversion failed because the 1302selection owner did not respond within the Intrinsics selection timeout 1303interval. 1304 </para> 1305 </listitem> 1306 </varlistentry> 1307 <varlistentry> 1308 <term> 1309 <emphasis remap='I'>value</emphasis> 1310 </term> 1311 <listitem> 1312 <para> 1313Specifies a pointer to the selection value. 1314The requesting client owns this storage and is responsible for freeing it 1315by calling 1316<xref linkend='XtFree' xrefstyle='select: title'/> 1317when it is done with it. 1318 </para> 1319 </listitem> 1320 </varlistentry> 1321 <varlistentry> 1322 <term> 1323 <emphasis remap='I'>length</emphasis> 1324 </term> 1325 <listitem> 1326 <para> 1327Specifies the number of elements in <emphasis remap='I'>value</emphasis>. 1328 </para> 1329 </listitem> 1330 </varlistentry> 1331 <varlistentry> 1332 <term> 1333 <emphasis remap='I'>format</emphasis> 1334 </term> 1335 <listitem> 1336 <para> 1337Specifies the size in bits of the data in each element of <emphasis remap='I'>value</emphasis>. 1338 </para> 1339 </listitem> 1340 </varlistentry> 1341</variablelist> 1342 1343<para> 1344This procedure is called by the Intrinsics selection mechanism to deliver the 1345requested selection to the requestor. 1346</para> 1347 1348<para> 1349If the 1350<function>SelectionNotify</function> 1351event returns a property of 1352<function>None</function>, 1353meaning the conversion has been refused because there is no owner for the 1354specified selection or the owner cannot convert the selection to the 1355requested target for any reason, the procedure is called with a value 1356of NULL and a length of zero. 1357</para> 1358 1359<para> 1360To obtain the selection value in a single logical unit, use 1361<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> 1362or 1363<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>. 1364</para> 1365 1366<funcsynopsis id='XtGetSelectionValue'> 1367<funcprototype> 1368<funcdef>void <function>XtGetSelectionValue</function></funcdef> 1369 <paramdef>Widget <parameter>w</parameter></paramdef> 1370 <paramdef>Atom <parameter>selection</parameter></paramdef> 1371 <paramdef>Atom <parameter>target</parameter></paramdef> 1372 <paramdef>XtSelectionCallbackProc <parameter>callback</parameter></paramdef> 1373 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 1374 <paramdef>Time <parameter>time</parameter></paramdef> 1375</funcprototype> 1376</funcsynopsis> 1377 1378<variablelist> 1379 <varlistentry> 1380 <term> 1381 <emphasis remap='I'>w</emphasis> 1382 </term> 1383 <listitem> 1384 <para> 1385Specifies the widget making the request. Must be of class Core or any subclass thereof. 1386 </para> 1387 </listitem> 1388 </varlistentry> 1389 <varlistentry> 1390 <term> 1391 <emphasis remap='I'>selection</emphasis> 1392 </term> 1393 <listitem> 1394 <para> 1395Specifies the particular selection desired; for example, 1396<function>XA_PRIMARY</function>. 1397 </para> 1398 </listitem> 1399 </varlistentry> 1400 <varlistentry> 1401 <term> 1402 <emphasis remap='I'>target</emphasis> 1403 </term> 1404 <listitem> 1405 <para> 1406Specifies the type of information needed about the selection. 1407 </para> 1408 </listitem> 1409 </varlistentry> 1410 <varlistentry> 1411 <term> 1412 <emphasis remap='I'>callback</emphasis> 1413 </term> 1414 <listitem> 1415 <para> 1416Specifies the procedure to be called when the selection value 1417has been obtained. 1418Note that this is how the selection value is communicated back to the client. 1419 </para> 1420 </listitem> 1421 </varlistentry> 1422 <varlistentry> 1423 <term> 1424 <emphasis remap='I'>client_data</emphasis> 1425 </term> 1426 <listitem> 1427 <para> 1428Specifies additional data to be passed to the specified procedure 1429when it is called. 1430 </para> 1431 </listitem> 1432 </varlistentry> 1433 <varlistentry> 1434 <term> 1435 <emphasis remap='I'>time</emphasis> 1436 </term> 1437 <listitem> 1438 <para> 1439Specifies the timestamp that indicates when the selection request was 1440initiated. 1441This should be the timestamp of the event that triggered this request; 1442the value 1443<function>CurrentTime</function> 1444is not acceptable. 1445 </para> 1446 </listitem> 1447 </varlistentry> 1448</variablelist> 1449 1450<para> 1451The 1452<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> 1453function requests the value of the selection converted to 1454the target type. 1455The specified callback is called at some time after 1456<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> 1457is called, when the selection value is received from the X server. 1458It may be called before or after 1459<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> 1460returns. 1461For more information about <emphasis remap='I'>selection</emphasis>, 1462<emphasis remap='I'>target</emphasis>, and 1463<emphasis remap='I'>time</emphasis>, see 1464<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the 1465<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>. 1466</para> 1467 1468<funcsynopsis id='XtGetSelectionValues'> 1469<funcprototype> 1470<funcdef>void <function>XtGetSelectionValues</function></funcdef> 1471 <paramdef>Widget <parameter>w</parameter></paramdef> 1472 <paramdef>Atom <parameter>selection</parameter></paramdef> 1473 <paramdef>Atom *<parameter>targets</parameter></paramdef> 1474 <paramdef>int <parameter>count</parameter></paramdef> 1475 <paramdef>XtSelectionCallbackProc <parameter>callback</parameter></paramdef> 1476 <paramdef>XtPointer *<parameter>client_data</parameter></paramdef> 1477 <paramdef>Time <parameter>time</parameter></paramdef> 1478</funcprototype> 1479</funcsynopsis> 1480 1481<variablelist> 1482 <varlistentry> 1483 <term> 1484 <emphasis remap='I'>w</emphasis> 1485 </term> 1486 <listitem> 1487 <para> 1488Specifies the widget making the request. Must be of class Core or any subclass thereof. 1489 </para> 1490 </listitem> 1491 </varlistentry> 1492 <varlistentry> 1493 <term> 1494 <emphasis remap='I'>selection</emphasis> 1495 </term> 1496 <listitem> 1497 <para> 1498Specifies the particular selection desired (that is, primary or secondary). 1499 </para> 1500 </listitem> 1501 </varlistentry> 1502 <varlistentry> 1503 <term> 1504 <emphasis remap='I'>targets</emphasis> 1505 </term> 1506 <listitem> 1507 <para> 1508Specifies the types of information needed about the selection. 1509 </para> 1510 </listitem> 1511 </varlistentry> 1512 <varlistentry> 1513 <term> 1514 <emphasis remap='I'>count</emphasis> 1515 </term> 1516 <listitem> 1517 <para> 1518Specifies the length of the <emphasis remap='I'>targets</emphasis> and <emphasis remap='I'>client_data</emphasis> lists. 1519 </para> 1520 </listitem> 1521 </varlistentry> 1522 <varlistentry> 1523 <term> 1524 <emphasis remap='I'>callback</emphasis> 1525 </term> 1526 <listitem> 1527 <para> 1528Specifies the callback procedure 1529to be called with each selection value obtained. 1530Note that this is how the selection values are communicated back to the 1531client. 1532 </para> 1533 </listitem> 1534 </varlistentry> 1535 <varlistentry> 1536 <term> 1537 <emphasis remap='I'>client_data</emphasis> 1538 </term> 1539 <listitem> 1540 <para> 1541Specifies a list of additional data values, one for each target type, 1542that are passed to the callback procedure when it is called for that target. 1543 </para> 1544 </listitem> 1545 </varlistentry> 1546 <varlistentry> 1547 <term> 1548 <emphasis remap='I'>time</emphasis> 1549 </term> 1550 <listitem> 1551 <para> 1552Specifies the timestamp that indicates when the selection request was 1553initiated. 1554This should be the timestamp of the event that triggered this request; 1555the value 1556<function>CurrentTime</function> 1557is not acceptable. 1558 </para> 1559 </listitem> 1560 </varlistentry> 1561</variablelist> 1562 1563<para> 1564The 1565<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/> 1566function is similar to multiple calls to 1567<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> 1568except that it guarantees that no other client can assert ownership 1569between requests and therefore that all the conversions will refer to 1570the same selection value. The callback is invoked once for each 1571target value with the corresponding client data. 1572For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and 1573<emphasis remap='I'>time</emphasis>, see 1574<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>section 2.6</olink> 1575in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>. 1576</para> 1577</sect3> 1578<sect3 id="Setting_the_Selection_Owner"> 1579<title>Setting the Selection Owner</title> 1580<para> 1581To set the selection owner and indicate that the selection value will 1582be provided in one piece, use 1583<xref linkend='XtOwnSelection' xrefstyle='select: title'/>. 1584</para> 1585 1586<funcsynopsis id='XtOwnSelection'> 1587<funcprototype> 1588<funcdef>Boolean <function>XtOwnSelection</function></funcdef> 1589 <paramdef>Widget <parameter>w</parameter></paramdef> 1590 <paramdef>Atom <parameter>selection</parameter></paramdef> 1591 <paramdef>Time <parameter>time</parameter></paramdef> 1592 <paramdef>XtConvertSelectionProc <parameter>convert_proc</parameter></paramdef> 1593 <paramdef>XtLoseSelectionProc <parameter>lose_selection</parameter></paramdef> 1594 <paramdef>XtSelectionDoneProc <parameter>done_proc</parameter></paramdef> 1595</funcprototype> 1596</funcsynopsis> 1597 1598<variablelist> 1599 <varlistentry> 1600 <term> 1601 <emphasis remap='I'>w</emphasis> 1602 </term> 1603 <listitem> 1604 <para> 1605Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. 1606 </para> 1607 </listitem> 1608 </varlistentry> 1609 <varlistentry> 1610 <term> 1611 <emphasis remap='I'>selection</emphasis> 1612 </term> 1613 <listitem> 1614 <para> 1615Specifies the name of the selection (for example, 1616<function>XA_PRIMARY ).</function> 1617 </para> 1618 </listitem> 1619 </varlistentry> 1620 <varlistentry> 1621 <term> 1622 <emphasis remap='I'>time</emphasis> 1623 </term> 1624 <listitem> 1625 <para> 1626Specifies the timestamp that indicates when the ownership request was 1627initiated. 1628This should be the timestamp of the event that triggered ownership; 1629the value 1630<function>CurrentTime</function> 1631is not acceptable. 1632 </para> 1633 </listitem> 1634 </varlistentry> 1635 <varlistentry> 1636 <term> 1637 <emphasis remap='I'>convert_proc</emphasis> 1638 </term> 1639 <listitem> 1640 <para> 1641Specifies the procedure to be called whenever a client requests the 1642current value of the selection. 1643 </para> 1644 </listitem> 1645 </varlistentry> 1646 <varlistentry> 1647 <term> 1648 <emphasis remap='I'>lose_selection</emphasis> 1649 </term> 1650 <listitem> 1651 <para> 1652Specifies the procedure to be called whenever the widget has 1653lost selection ownership, or NULL if the owner is not interested in being 1654called back. 1655 </para> 1656 </listitem> 1657 </varlistentry> 1658 <varlistentry> 1659 <term> 1660 <emphasis remap='I'>done_proc</emphasis> 1661 </term> 1662 <listitem> 1663 <para> 1664Specifies the procedure called 1665after the requestor has received the selection value, or NULL if the 1666owner is not 1667interested in being called back. 1668 </para> 1669 </listitem> 1670 </varlistentry> 1671</variablelist> 1672 1673<para> 1674The 1675<xref linkend='XtOwnSelection' xrefstyle='select: title'/> 1676function informs the Intrinsics selection mechanism that a 1677widget wishes to own a selection. 1678It returns 1679<function>True</function> 1680if the widget successfully becomes the owner and 1681<function>False</function> 1682otherwise. 1683The widget may fail to become the owner if some other widget 1684has asserted ownership at a time later than this widget. 1685The widget can lose selection ownership either 1686because some other widget asserted later ownership of the selection 1687or because the widget voluntarily gave up ownership of the selection. 1688The lose_selection procedure is not called 1689if the widget fails to obtain selection ownership in the first place. 1690</para> 1691 1692<para> 1693If a done_proc is specified, the client owns the storage allocated 1694for passing the value to the Intrinsics. If <emphasis remap='I'>done_proc</emphasis> is NULL, 1695the convert_proc must allocate storage using 1696<xref linkend='XtMalloc' xrefstyle='select: title'/>, 1697<xref linkend='XtRealloc' xrefstyle='select: title'/>, 1698or 1699<xref linkend='XtCalloc' xrefstyle='select: title'/>, 1700and the value specified is freed by the 1701Intrinsics when the transfer is complete. 1702</para> 1703 1704<para> 1705Usually, a selection owner maintains ownership indefinitely until some 1706other widget requests ownership, at which time 1707the Intrinsics selection mechanism informs the previous owner that it 1708has lost ownership of the selection. 1709However, in response to some user actions 1710(for example, when a user deletes the information selected), 1711the application may wish to explicitly inform the Intrinsics 1712by using 1713<xref linkend='XtDisownSelection' xrefstyle='select: title'/> 1714that it no longer is to be the selection owner. 1715</para> 1716 1717<funcsynopsis id='XtDisownSelection'> 1718<funcprototype> 1719<funcdef>void <function>XtDisownSelection</function></funcdef> 1720 <paramdef>Widget <parameter>w</parameter></paramdef> 1721 <paramdef>Atom <parameter>selection</parameter></paramdef> 1722 <paramdef>Time <parameter>time</parameter></paramdef> 1723</funcprototype> 1724</funcsynopsis> 1725 1726<variablelist> 1727 <varlistentry> 1728 <term> 1729 <emphasis remap='I'>w</emphasis> 1730 </term> 1731 <listitem> 1732 <para> 1733Specifies the widget that wishes to relinquish ownership. 1734 </para> 1735 </listitem> 1736 </varlistentry> 1737 <varlistentry> 1738 <term> 1739 <emphasis remap='I'>selection</emphasis> 1740 </term> 1741 <listitem> 1742 <para> 1743Specifies the atom naming the selection being given up. 1744 </para> 1745 </listitem> 1746 </varlistentry> 1747 <varlistentry> 1748 <term> 1749 <emphasis remap='I'>time</emphasis> 1750 </term> 1751 <listitem> 1752 <para> 1753Specifies the timestamp that indicates when the request to 1754relinquish selection ownership was initiated. 1755 </para> 1756 </listitem> 1757 </varlistentry> 1758</variablelist> 1759 1760<para> 1761The 1762<xref linkend='XtDisownSelection' xrefstyle='select: title'/> 1763function informs the Intrinsics selection mechanism that 1764the specified widget is to lose ownership of the selection. 1765If the widget does not currently own the selection, either 1766because it lost the selection 1767or because it never had the selection to begin with, 1768<xref linkend='XtDisownSelection' xrefstyle='select: title'/> 1769does nothing. 1770</para> 1771 1772<para> 1773After a widget has called 1774<xref linkend='XtDisownSelection' xrefstyle='select: title'/>, 1775its convert procedure is not called even if a request arrives later 1776with a timestamp during the period that this widget owned the selection. 1777However, its done procedure is called if a conversion that started 1778before the call to 1779<xref linkend='XtDisownSelection' xrefstyle='select: title'/> 1780finishes after the call to 1781<xref linkend='XtDisownSelection' xrefstyle='select: title'/>. 1782</para> 1783</sect3> 1784</sect2> 1785 1786<sect2 id="Using_Incremental_Transfers"> 1787<title>Using Incremental Transfers</title> 1788<para> 1789When using the incremental interface, an owner may have to process 1790more than one selection request for the same selection, converted to 1791the same target, at the same time. The incremental functions take a 1792<emphasis remap='I'>request_id</emphasis> argument, which is an identifier that is guaranteed to be 1793unique among all incremental requests that are active concurrently. 1794</para> 1795 1796<para> 1797For example, consider the following: 1798</para> 1799<itemizedlist spacing='compact'> 1800 <listitem> 1801 <para> 1802Upon receiving a request for the selection value, the owner sends 1803the first segment. 1804 </para> 1805 </listitem> 1806 <listitem> 1807 <para> 1808While waiting to be called to provide the next segment value but 1809before sending it, the owner receives another request from a 1810different requestor for the same selection value. 1811 </para> 1812 </listitem> 1813 <listitem> 1814 <para> 1815To distinguish between the requests, the owner uses the request_id 1816value. This allows the owner to distinguish between the first 1817requestor, which is asking for the second segment, and the second 1818requestor, which is asking for the first segment. 1819 </para> 1820 </listitem> 1821</itemizedlist> 1822<sect3 id="Incremental_Transfer_Procedures"> 1823<title>Incremental Transfer Procedures</title> 1824<para> 1825The following procedures are used by selection owners who wish to 1826provide the selection data in multiple segments. 1827</para> 1828 1829<para> 1830The procedure pointer specified by the incremental owner to supply the 1831selection data to the Intrinsics is of type 1832<xref linkend='XtConvertSelectionIncrProc' xrefstyle='select: title'/>. 1833</para> 1834<literallayout > 1835typedef XtPointer XtRequestId; 1836</literallayout> 1837 1838<funcsynopsis id='XtConvertSelectionIncrProc'> 1839<funcprototype> 1840<funcdef>typedef Boolean <function>(*XtConvertSelectionIncrProc)</function></funcdef> 1841 <paramdef>Widget <parameter>w</parameter></paramdef> 1842 <paramdef>Atom *<parameter>selection</parameter></paramdef> 1843 <paramdef>Atom *<parameter>target</parameter></paramdef> 1844 <paramdef>Atom *<parameter>type_return</parameter></paramdef> 1845 <paramdef>XtPointer *<parameter>value_return</parameter></paramdef> 1846 <paramdef>unsigned long *<parameter>length_return</parameter></paramdef> 1847 <paramdef>int *<parameter>format_return</parameter></paramdef> 1848 <paramdef>unsigned long *<parameter>max_length</parameter></paramdef> 1849 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 1850 <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef> 1851</funcprototype> 1852</funcsynopsis> 1853 1854<variablelist> 1855 <varlistentry> 1856 <term> 1857 <emphasis remap='I'>w</emphasis> 1858 </term> 1859 <listitem> 1860 <para> 1861Specifies the widget that currently owns this selection. 1862 </para> 1863 </listitem> 1864 </varlistentry> 1865 <varlistentry> 1866 <term> 1867 <emphasis remap='I'>selection</emphasis> 1868 </term> 1869 <listitem> 1870 <para> 1871Specifies the atom that names the selection requested. 1872 </para> 1873 </listitem> 1874 </varlistentry> 1875 <varlistentry> 1876 <term> 1877 <emphasis remap='I'>target</emphasis> 1878 </term> 1879 <listitem> 1880 <para> 1881Specifies the type of information required about the selection. 1882 </para> 1883 </listitem> 1884 </varlistentry> 1885 <varlistentry> 1886 <term> 1887 <emphasis remap='I'>type_return</emphasis> 1888 </term> 1889 <listitem> 1890 <para> 1891Specifies a pointer to an atom into which the property 1892type of the converted value of the selection is to be 1893stored. 1894 </para> 1895 </listitem> 1896 </varlistentry> 1897 <varlistentry> 1898 <term> 1899 <emphasis remap='I'>value_return</emphasis> 1900 </term> 1901 <listitem> 1902 <para> 1903Specifies a pointer into which a pointer to the 1904converted value of the selection is to be stored. 1905The selection owner is responsible for allocating this storage. 1906 </para> 1907 </listitem> 1908 </varlistentry> 1909 <varlistentry> 1910 <term> 1911 <emphasis remap='I'>length_return</emphasis> 1912 </term> 1913 <listitem> 1914 <para> 1915Specifies a pointer into which the number of elements 1916in <emphasis remap='I'>value_return</emphasis>, each of size indicated by 1917<emphasis remap='I'>format_return</emphasis>, is to be stored. 1918 </para> 1919 </listitem> 1920 </varlistentry> 1921 <varlistentry> 1922 <term> 1923 <emphasis remap='I'>format_return</emphasis> 1924 </term> 1925 <listitem> 1926 <para> 1927Specifies a pointer into which the size in bits of the 1928data elements of the selection value is to be stored so that the 1929server may byte-swap the data if necessary. 1930 </para> 1931 </listitem> 1932 </varlistentry> 1933 <varlistentry> 1934 <term> 1935 <emphasis remap='I'>max_length</emphasis> 1936 </term> 1937 <listitem> 1938 <para> 1939Specifies the maximum number of bytes which may be 1940transferred at any one time. 1941 </para> 1942 </listitem> 1943 </varlistentry> 1944 <varlistentry> 1945 <term> 1946 <emphasis remap='I'>client_data</emphasis> 1947 </term> 1948 <listitem> 1949 <para> 1950Specifies the value passed in by the widget when it 1951took ownership of the selection. 1952 </para> 1953 </listitem> 1954 </varlistentry> 1955 <varlistentry> 1956 <term> 1957 <emphasis remap='I'>request_id</emphasis> 1958 </term> 1959 <listitem> 1960 <para> 1961Specifies an opaque identification for a specific request. 1962 </para> 1963 </listitem> 1964 </varlistentry> 1965</variablelist> 1966 1967<para> 1968This procedure is called repeatedly by the Intrinsics selection mechanism to get 1969the next incremental chunk of data from a selection owner who has 1970called 1971<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>. 1972It must return 1973<function>True</function> 1974if the procedure has succeeded in converting the selection data or 1975<function>False</function> 1976otherwise. 1977On the first call with a particular request id, the owner must begin 1978a new incremental transfer for the requested selection and target. On 1979subsequent calls with the same request id, the owner may assume that 1980the previously supplied value is no longer needed by the Intrinsics; 1981that is, a fixed transfer area may be allocated and returned in <emphasis remap='I'>value_return</emphasis> 1982for each segment to be transferred. This procedure should store a 1983non-NULL value in <emphasis remap='I'>value_return</emphasis> and zero in <emphasis remap='I'>length_return</emphasis> to indicate that the 1984entire selection has been delivered. After returning this final 1985segment, the request id may be reused by the Intrinsics to begin a 1986new transfer. 1987</para> 1988 1989<para> 1990To retrieve the 1991<function>SelectionRequest</function> 1992event that triggered the selection conversion procedure, use 1993<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>, 1994described in Section 11.5.2.1. 1995</para> 1996 1997<para> 1998The procedure pointer specified by the incremental selection owner 1999when it desires notification upon no longer having ownership is of 2000type 2001<xref linkend='XtLoseSelectionIncrProc' xrefstyle='select: title'/>. 2002</para> 2003 2004<funcsynopsis id='XtLoseSelectionIncrProc'> 2005<funcprototype> 2006<funcdef>typedef void <function>(*XtLoseSelectionIncrProc)</function></funcdef> 2007 <paramdef>Widget <parameter>w</parameter></paramdef> 2008 <paramdef>Atom *<parameter>selection</parameter></paramdef> 2009 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 2010</funcprototype> 2011</funcsynopsis> 2012 2013<variablelist> 2014 <varlistentry> 2015 <term> 2016 <emphasis remap='I'>w</emphasis> 2017 </term> 2018 <listitem> 2019 <para> 2020Specifies the widget that has lost the selection ownership. 2021 </para> 2022 </listitem> 2023 </varlistentry> 2024 <varlistentry> 2025 <term> 2026 <emphasis remap='I'>selection</emphasis> 2027 </term> 2028 <listitem> 2029 <para> 2030Specifies the atom that names the selection. 2031 </para> 2032 </listitem> 2033 </varlistentry> 2034 <varlistentry> 2035 <term> 2036 <emphasis remap='I'>client_data</emphasis> 2037 </term> 2038 <listitem> 2039 <para> 2040Specifies the value passed in by the widget when it 2041took ownership of the selection. 2042 </para> 2043 </listitem> 2044 </varlistentry> 2045</variablelist> 2046 2047<para> 2048This procedure, which is optional, is called by the Intrinsics to 2049inform the selection owner that it no longer owns the selection. 2050</para> 2051 2052<para> 2053The procedure pointer specified by the incremental selection owner 2054when it desires notification of receipt of the data or when it manages 2055the storage containing the data is of type 2056<xref linkend='XtSelectionDoneIncrProc' xrefstyle='select: title'/>. 2057</para> 2058 2059<funcsynopsis id='XtSelectionDoneIncrProc'> 2060<funcprototype> 2061<funcdef>typedef void <function>(*XtSelectionDoneIncrProc)</function></funcdef> 2062 <paramdef>Widget <parameter>w</parameter></paramdef> 2063 <paramdef>Atom *<parameter>selection</parameter></paramdef> 2064 <paramdef>Atom *<parameter>target</parameter></paramdef> 2065 <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef> 2066 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 2067</funcprototype> 2068</funcsynopsis> 2069 2070<variablelist> 2071 <varlistentry> 2072 <term> 2073 <emphasis remap='I'>w</emphasis> 2074 </term> 2075 <listitem> 2076 <para> 2077Specifies the widget that owns the selection. 2078 </para> 2079 </listitem> 2080 </varlistentry> 2081 <varlistentry> 2082 <term> 2083 <emphasis remap='I'>selection</emphasis> 2084 </term> 2085 <listitem> 2086 <para> 2087Specifies the atom that names the selection being transferred. 2088 </para> 2089 </listitem> 2090 </varlistentry> 2091 <varlistentry> 2092 <term> 2093 <emphasis remap='I'>target</emphasis> 2094 </term> 2095 <listitem> 2096 <para> 2097Specifies the target type to which the conversion was done. 2098 </para> 2099 </listitem> 2100 </varlistentry> 2101 <varlistentry> 2102 <term> 2103 <emphasis remap='I'>request_id</emphasis> 2104 </term> 2105 <listitem> 2106 <para> 2107Specifies an opaque identification for a specific request. 2108 </para> 2109 </listitem> 2110 </varlistentry> 2111 <varlistentry> 2112 <term> 2113 <emphasis remap='I'>client_data</emphasis> 2114 </term> 2115 <listitem> 2116 <para> 2117Specified the value passed in by the widget when it 2118took ownership of the selection. 2119 </para> 2120 </listitem> 2121 </varlistentry> 2122</variablelist> 2123 2124<para> 2125This procedure, which is optional, is called by the Intrinsics after 2126the requestor has retrieved the final (zero-length) segment of the 2127incremental transfer to indicate that the entire transfer is complete. 2128If this procedure is not specified, the Intrinsics will free only the 2129final value returned by the selection owner using 2130<xref linkend='XtFree' xrefstyle='select: title'/>. 2131</para> 2132 2133<para> 2134The procedure pointer specified by the incremental selection owner to 2135notify it if a transfer should be terminated prematurely is of type 2136<xref linkend='XtCancelConvertSelectionProc' xrefstyle='select: title'/>. 2137</para> 2138 2139<funcsynopsis id='XtCancelConvertSelectionProc'> 2140<funcprototype> 2141<funcdef>typedef void <function>(*XtCancelConvertSelectionProc)</function></funcdef> 2142 <paramdef>Widget <parameter>w</parameter></paramdef> 2143 <paramdef>Atom *<parameter>selection</parameter></paramdef> 2144 <paramdef>Atom *<parameter>target</parameter></paramdef> 2145 <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef> 2146 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 2147</funcprototype> 2148</funcsynopsis> 2149 2150<variablelist> 2151 <varlistentry> 2152 <term> 2153 <emphasis remap='I'>w</emphasis> 2154 </term> 2155 <listitem> 2156 <para> 2157Specifies the widget that owns the selection. 2158 </para> 2159 </listitem> 2160 </varlistentry> 2161 <varlistentry> 2162 <term> 2163 <emphasis remap='I'>selection</emphasis> 2164 </term> 2165 <listitem> 2166 <para> 2167Specifies the atom that names the selection being transferred. 2168 </para> 2169 </listitem> 2170 </varlistentry> 2171 <varlistentry> 2172 <term> 2173 <emphasis remap='I'>target</emphasis> 2174 </term> 2175 <listitem> 2176 <para> 2177Specifies the target type to which the conversion was done. 2178 </para> 2179 </listitem> 2180 </varlistentry> 2181 <varlistentry> 2182 <term> 2183 <emphasis remap='I'>request_id</emphasis> 2184 </term> 2185 <listitem> 2186 <para> 2187Specifies an opaque identification for a specific request. 2188 </para> 2189 </listitem> 2190 </varlistentry> 2191 <varlistentry> 2192 <term> 2193 <emphasis remap='I'>client_data</emphasis> 2194 </term> 2195 <listitem> 2196 <para> 2197Specifies the value passed in by the widget when it took ownership of 2198the selection. 2199 </para> 2200 </listitem> 2201 </varlistentry> 2202</variablelist> 2203 2204<para> 2205This procedure is called by the Intrinsics when it has been determined 2206by means of a timeout or other mechanism that any remaining segments 2207of the selection no longer need to be transferred. Upon receiving 2208this callback, the selection request is considered complete and the 2209owner can free the memory and any other resources that have been 2210allocated for the transfer. 2211</para> 2212</sect3> 2213<sect3 id="Getting_the_Selection_Value_Incrementally"> 2214<title>Getting the Selection Value Incrementally</title> 2215<para> 2216To obtain the value of the selection using incremental transfers, use 2217<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> 2218or 2219<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>. 2220</para> 2221 2222<funcsynopsis id='XtGetSelectionValueIncremental'> 2223<funcprototype> 2224<funcdef>void <function>XtGetSelectionValueIncremental</function></funcdef> 2225 <paramdef>Widget <parameter>w</parameter></paramdef> 2226 <paramdef>Atom <parameter>selection</parameter></paramdef> 2227 <paramdef>Atom <parameter>target</parameter></paramdef> 2228 <paramdef>XtSelectionCallbackProc <parameter>selection_callback</parameter></paramdef> 2229 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 2230 <paramdef>Time <parameter>time</parameter></paramdef> 2231</funcprototype> 2232</funcsynopsis> 2233 2234<variablelist> 2235 <varlistentry> 2236 <term> 2237 <emphasis remap='I'>w</emphasis> 2238 </term> 2239 <listitem> 2240 <para> 2241Specifies the widget making the request. Must be of class Core or any subclass thereof. 2242 </para> 2243 </listitem> 2244 </varlistentry> 2245 <varlistentry> 2246 <term> 2247 <emphasis remap='I'>selection</emphasis> 2248 </term> 2249 <listitem> 2250 <para> 2251Specifies the particular selection desired. 2252 </para> 2253 </listitem> 2254 </varlistentry> 2255 <varlistentry> 2256 <term> 2257 <emphasis remap='I'>target</emphasis> 2258 </term> 2259 <listitem> 2260 <para> 2261Specifies the type of information needed 2262about the selection. 2263 </para> 2264 </listitem> 2265 </varlistentry> 2266 <varlistentry> 2267 <term> 2268 <emphasis remap='I'>selection_callback</emphasis> 2269 </term> 2270 <listitem> 2271 <para> 2272Specifies the callback procedure to be 2273called to receive each data segment. 2274 </para> 2275 </listitem> 2276 </varlistentry> 2277 <varlistentry> 2278 <term> 2279 <emphasis remap='I'>client_data</emphasis> 2280 </term> 2281 <listitem> 2282 <para> 2283Specifies client-specific data to be passed to 2284the specified callback procedure when it is invoked. 2285 </para> 2286 </listitem> 2287 </varlistentry> 2288 <varlistentry> 2289 <term> 2290 <emphasis remap='I'>time</emphasis> 2291 </term> 2292 <listitem> 2293 <para> 2294Specifies the timestamp that indicates when the 2295selection request was initiated. This should be the 2296timestamp of the event that triggered this request; 2297the value 2298<function>CurrentTime</function> 2299is not acceptable. 2300 </para> 2301 </listitem> 2302 </varlistentry> 2303</variablelist> 2304 2305<para> 2306The 2307<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> 2308function is similar to 2309<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> 2310except that the selection_callback procedure will 2311be called repeatedly upon delivery of multiple segments of the 2312selection value. The end of the selection value is indicated when 2313<emphasis remap='I'>selection_callback</emphasis> is called with a non-NULL value of length zero, 2314which must still be freed by the client. If the 2315transfer of the selection is aborted in the middle of a transfer 2316(for example, because of a timeout), the selection_callback procedure is 2317called with a type value equal to the symbolic constant 2318<function>XT_CONVERT_FAIL</function> 2319so that the requestor can dispose 2320of the partial selection value it has collected up until that point. 2321Upon receiving 2322<function>XT_CONVERT_FAIL</function>, 2323the requesting client must determine 2324for itself whether or not a partially completed data transfer is meaningful. 2325For more information about <emphasis remap='I'>selection</emphasis>, 2326<emphasis remap='I'>target</emphasis>, and 2327<emphasis remap='I'>time</emphasis>, see 2328<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms' /> in the 2329<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink> 2330</para> 2331 2332<funcsynopsis id='XtGetSelectionValuesIncremental'> 2333<funcprototype> 2334<funcdef>void <function>XtGetSelectionValuesIncremental</function></funcdef> 2335 <paramdef>Widget <parameter>w</parameter></paramdef> 2336 <paramdef>Atom <parameter>selection</parameter></paramdef> 2337 <paramdef>Atom *<parameter>targets</parameter></paramdef> 2338 <paramdef>int <parameter>count</parameter></paramdef> 2339 <paramdef>XtSelectionCallbackProc <parameter>selection_callback</parameter></paramdef> 2340 <paramdef>XtPointer *<parameter>client_data</parameter></paramdef> 2341 <paramdef>Time <parameter>time</parameter></paramdef> 2342</funcprototype> 2343</funcsynopsis> 2344 2345<variablelist> 2346 <varlistentry> 2347 <term> 2348 <emphasis remap='I'>w</emphasis> 2349 </term> 2350 <listitem> 2351 <para> 2352Specifies the widget making the request. Must be of class Core or any subclass thereof. 2353 </para> 2354 </listitem> 2355 </varlistentry> 2356 <varlistentry> 2357 <term> 2358 <emphasis remap='I'>selection</emphasis> 2359 </term> 2360 <listitem> 2361 <para> 2362Specifies the particular selection desired. 2363 </para> 2364 </listitem> 2365 </varlistentry> 2366 <varlistentry> 2367 <term> 2368 <emphasis remap='I'>targets</emphasis> 2369 </term> 2370 <listitem> 2371 <para> 2372Specifies the types of information needed about 2373the selection. 2374 </para> 2375 </listitem> 2376 </varlistentry> 2377 <varlistentry> 2378 <term> 2379 <emphasis remap='I'>count</emphasis> 2380 </term> 2381 <listitem> 2382 <para> 2383Specifies the length of the <emphasis remap='I'>targets</emphasis> and <emphasis remap='I'>client_data</emphasis> lists. 2384 </para> 2385 </listitem> 2386 </varlistentry> 2387 <varlistentry> 2388 <term> 2389 <emphasis remap='I'>selection_callback</emphasis> 2390 </term> 2391 <listitem> 2392 <para> 2393Specifies the callback procedure to be called 2394to receive each selection value. 2395 </para> 2396 </listitem> 2397 </varlistentry> 2398 <varlistentry> 2399 <term> 2400 <emphasis remap='I'>client_data</emphasis> 2401 </term> 2402 <listitem> 2403 <para> 2404Specifies a list of client data (one for each target 2405type) values that are passed to the callback procedure when 2406it is invoked for the corresponding target. 2407 </para> 2408 </listitem> 2409 </varlistentry> 2410 <varlistentry> 2411 <term> 2412 <emphasis remap='I'>time</emphasis> 2413 </term> 2414 <listitem> 2415 <para> 2416Specifies the timestamp that indicates when the 2417selection request was initiated. This should be the 2418timestamp of the event that triggered this request; 2419the value 2420<function>CurrentTime</function> 2421is not acceptable. 2422 </para> 2423 </listitem> 2424 </varlistentry> 2425</variablelist> 2426 2427<para> 2428The 2429<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> 2430function is similar to 2431<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> 2432except that it takes a list of targets and client data. 2433<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> 2434is equivalent to calling 2435<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> 2436successively for each <emphasis remap='I'>target/client_data</emphasis> pair except that 2437<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> 2438does guarantee that all the conversions will use the same selection 2439value because the ownership of the selection cannot change in the 2440middle of the list, as would be possible when calling 2441<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> 2442repeatedly. 2443For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and 2444<emphasis remap='I'>time</emphasis>, see 2445<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the 2446<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink> 2447</para> 2448</sect3> 2449<sect3 id="Setting_the_Selection_Owner_for_Incremental_Transfers"> 2450<title>Setting the Selection Owner for Incremental Transfers</title> 2451<para> 2452To set the selection owner when using incremental transfers, use 2453<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>. 2454</para> 2455 2456<funcsynopsis id='XtOwnSelectionIncremental'> 2457<funcprototype> 2458<funcdef>Boolean <function>XtOwnSelectionIncremental</function></funcdef> 2459 <paramdef>Widget <parameter>w</parameter></paramdef> 2460 <paramdef>Atom <parameter>selection</parameter></paramdef> 2461 <paramdef>Time <parameter>time</parameter></paramdef> 2462 <paramdef>XtConvertSelectionIncrProc <parameter>convert_callback</parameter></paramdef> 2463 <paramdef>XtLoseSelectionIncrProc <parameter>lose_callback</parameter></paramdef> 2464 <paramdef>XtSelectionDoneIncrProc <parameter>done_callback</parameter></paramdef> 2465 <paramdef>XtCancelConvertSelectionProc <parameter>cancel_callback</parameter></paramdef> 2466 <paramdef>XtPointer <parameter>client_data</parameter></paramdef> 2467</funcprototype> 2468</funcsynopsis> 2469 2470<variablelist> 2471 <varlistentry> 2472 <term> 2473 <emphasis remap='I'>w</emphasis> 2474 </term> 2475 <listitem> 2476 <para> 2477Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. 2478 </para> 2479 </listitem> 2480 </varlistentry> 2481 <varlistentry> 2482 <term> 2483 <emphasis remap='I'>selection</emphasis> 2484 </term> 2485 <listitem> 2486 <para> 2487Specifies the atom that names the selection. 2488 </para> 2489 </listitem> 2490 </varlistentry> 2491 <varlistentry> 2492 <term> 2493 <emphasis remap='I'>time</emphasis> 2494 </term> 2495 <listitem> 2496 <para> 2497Specifies the timestamp that indicates when the 2498selection ownership request was initiated. This should be 2499the timestamp of the event that triggered ownership; the value 2500<function>CurrentTime</function> 2501is not acceptable. 2502 </para> 2503 </listitem> 2504 </varlistentry> 2505 <varlistentry> 2506 <term> 2507 <emphasis remap='I'>convert_callback</emphasis> 2508 </term> 2509 <listitem> 2510 <para> 2511Specifies the procedure to be called whenever 2512the current value of the selection is requested. 2513 </para> 2514 </listitem> 2515 </varlistentry> 2516 <varlistentry> 2517 <term> 2518 <emphasis remap='I'>lose_callback</emphasis> 2519 </term> 2520 <listitem> 2521 <para> 2522Specifies the procedure to be called whenever 2523the widget has lost selection ownership, or NULL if the 2524owner is not interested in being notified. 2525 </para> 2526 </listitem> 2527 </varlistentry> 2528 <varlistentry> 2529 <term> 2530 <emphasis remap='I'>done_callback</emphasis> 2531 </term> 2532 <listitem> 2533 <para> 2534Specifies the procedure called after the 2535requestor has received the entire selection, or NULL if 2536the owner is not interested in being notified. 2537 </para> 2538 </listitem> 2539 </varlistentry> 2540 <varlistentry> 2541 <term> 2542 <emphasis remap='I'>cancel_callback</emphasis> 2543 </term> 2544 <listitem> 2545 <para> 2546Specifies the callback procedure to be called 2547when a selection request aborts because a timeout expires, 2548or NULL if the owner is not interested in being notified. 2549 </para> 2550 </listitem> 2551 </varlistentry> 2552 <varlistentry> 2553 <term> 2554 <emphasis remap='I'>client_data</emphasis> 2555 </term> 2556 <listitem> 2557 <para> 2558Specifies the argument to be passed to each of 2559the callback procedures when they are called. 2560 </para> 2561 </listitem> 2562 </varlistentry> 2563</variablelist> 2564 2565<para> 2566The 2567<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/> 2568procedure informs the Intrinsics 2569incremental selection mechanism that the specified widget wishes to 2570own the selection. It returns 2571<function>True</function> 2572if the specified widget successfully becomes the selection owner or 2573<function>False</function> 2574otherwise. 2575For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and 2576<emphasis remap='I'>time</emphasis>, see 2577<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the 2578<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink> 2579</para> 2580 2581<para> 2582If a done_callback procedure is specified, the client owns the storage allocated 2583for passing the value to the Intrinsics. If <emphasis remap='I'>done_callback</emphasis> is NULL, 2584the convert_callback procedure must allocate storage using 2585<xref linkend='XtMalloc' xrefstyle='select: title'/>, 2586<xref linkend='XtRealloc' xrefstyle='select: title'/>, 2587or 2588<xref linkend='XtCalloc' xrefstyle='select: title'/>, 2589and the final value specified is freed by the 2590Intrinsics when the transfer is complete. After a selection transfer 2591has started, only one of the done_callback or cancel_callback 2592procedures is invoked to indicate completion of the transfer. 2593</para> 2594 2595<para> 2596The lose_callback procedure does not indicate completion of any in-progress 2597transfers; it is invoked at the time a 2598<function>SelectionClear</function> 2599event is dispatched regardless of any active transfers, which are still 2600expected to continue. 2601</para> 2602 2603<para> 2604A widget that becomes the selection owner using 2605<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/> 2606may use 2607<xref linkend='XtDisownSelection' xrefstyle='select: title'/> 2608to relinquish selection ownership. 2609</para> 2610</sect3> 2611</sect2> 2612 2613<sect2 id="Setting_and_Retrieving_Selection_Target_Parameters"> 2614<title>Setting and Retrieving Selection Target Parameters</title> 2615<para> 2616To specify target parameters for a selection request with a single target, 2617use 2618<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>. 2619</para> 2620 2621<funcsynopsis id='XtSetSelectionParameters'> 2622<funcprototype> 2623<funcdef>void <function>XtSetSelectionParameters</function></funcdef> 2624 <paramdef>Widget <parameter>requestor</parameter></paramdef> 2625 <paramdef>Atom <parameter>selection</parameter></paramdef> 2626 <paramdef>Atom <parameter>type</parameter></paramdef> 2627 <paramdef>XtPointer <parameter>value</parameter></paramdef> 2628 <paramdef>unsigned long <parameter>length</parameter></paramdef> 2629 <paramdef>int <parameter>format</parameter></paramdef> 2630</funcprototype> 2631</funcsynopsis> 2632 2633<variablelist> 2634 <varlistentry> 2635 <term> 2636 <emphasis remap='I'>requestor</emphasis> 2637 </term> 2638 <listitem> 2639 <para> 2640Specifies the widget making the request. Must be of class Core or any subclass thereof. 2641 </para> 2642 </listitem> 2643 </varlistentry> 2644 <varlistentry> 2645 <term> 2646 <emphasis remap='I'>selection</emphasis> 2647 </term> 2648 <listitem> 2649 <para> 2650Specifies the atom that names the selection. 2651 </para> 2652 </listitem> 2653 </varlistentry> 2654 <varlistentry> 2655 <term> 2656 <emphasis remap='I'>type</emphasis> 2657 </term> 2658 <listitem> 2659 <para> 2660Specifies the type of the property in which the parameters are passed. 2661 </para> 2662 </listitem> 2663 </varlistentry> 2664 <varlistentry> 2665 <term> 2666 <emphasis remap='I'>value</emphasis> 2667 </term> 2668 <listitem> 2669 <para> 2670Specifies a pointer to the parameters. 2671 </para> 2672 </listitem> 2673 </varlistentry> 2674 <varlistentry> 2675 <term> 2676 <emphasis remap='I'>length</emphasis> 2677 </term> 2678 <listitem> 2679 <para> 2680Specifies the number of elements containing data in <emphasis remap='I'>value</emphasis>, 2681each element of a size indicated by <emphasis remap='I'>format</emphasis>. 2682 </para> 2683 </listitem> 2684 </varlistentry> 2685 <varlistentry> 2686 <term> 2687 <emphasis remap='I'>format</emphasis> 2688 </term> 2689 <listitem> 2690 <para> 2691Specifies the size in bits of the data in the elements of <emphasis remap='I'>value</emphasis>. 2692 </para> 2693 </listitem> 2694 </varlistentry> 2695</variablelist> 2696 2697<para> 2698The specified parameters are copied and stored in a new property 2699of the specified type and format on the requestor's window. To initiate 2700a selection request with a target and these parameters, a subsequent 2701call to 2702<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> 2703or to 2704<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> 2705specifying the same requestor widget and selection atom will generate a 2706<function>ConvertSelection</function> 2707request referring to the property containing the parameters. If 2708<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/> 2709is called more than once with the same widget and selection without 2710a call to specify a request, the most recently specified parameters 2711are used in the subsequent request. 2712</para> 2713 2714<para> 2715The possible values of <emphasis remap='I'>format</emphasis> are 8, 16, or 32. If the format is 8, 2716the elements of <emphasis remap='I'>value</emphasis> are assumed to be sizeof(char); 2717if 16, sizeof(short); if 32, sizeof(long). 2718</para> 2719 2720<para> 2721To generate a MULTIPLE 2722target request with parameters for any of the multiple targets of the 2723selection request, precede individual calls to 2724<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> 2725and 2726<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> 2727with corresponding individual calls to 2728<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>, 2729and enclose these all within 2730<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> 2731and 2732<function>XtSendSelectionRequest.</function> 2733<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/> 2734and 2735<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> 2736cannot be used to make selection requests with parameterized targets. 2737</para> 2738 2739<para> 2740To retrieve any target parameters needed to perform a selection conversion, 2741the selection owner calls 2742<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/>. 2743</para> 2744 2745<funcsynopsis id='XtGetSelectionParameters'> 2746<funcprototype> 2747<funcdef>void <function>XtGetSelectionParameters</function></funcdef> 2748 <paramdef>Widget <parameter>owner</parameter></paramdef> 2749 <paramdef>Atom <parameter>selection</parameter></paramdef> 2750 <paramdef>XtRequestId <parameter>request_id</parameter></paramdef> 2751 <paramdef>Atom *<parameter>type_return</parameter></paramdef> 2752 <paramdef>XtPointer *<parameter>value_return</parameter></paramdef> 2753 <paramdef>unsigned long *<parameter>length_return</parameter></paramdef> 2754 <paramdef>int *<parameter>format_return</parameter></paramdef> 2755</funcprototype> 2756</funcsynopsis> 2757 2758<variablelist> 2759 <varlistentry> 2760 <term> 2761 <emphasis remap='I'>owner</emphasis> 2762 </term> 2763 <listitem> 2764 <para> 2765Specifies the widget that owns the specified selection. 2766 </para> 2767 </listitem> 2768 </varlistentry> 2769 <varlistentry> 2770 <term> 2771 <emphasis remap='I'>selection</emphasis> 2772 </term> 2773 <listitem> 2774 <para> 2775Specifies the selection being processed. 2776 </para> 2777 </listitem> 2778 </varlistentry> 2779 <varlistentry> 2780 <term> 2781 <emphasis remap='I'>request_id</emphasis> 2782 </term> 2783 <listitem> 2784 <para> 2785Specifies the requestor id in the case of incremental selections, 2786or NULL in the case of atomic transfers. 2787 </para> 2788 </listitem> 2789 </varlistentry> 2790 <varlistentry> 2791 <term> 2792 <emphasis remap='I'>type_return</emphasis> 2793 </term> 2794 <listitem> 2795 <para> 2796Specifies a pointer to an atom in which the property type 2797of the parameters is stored. 2798 </para> 2799 </listitem> 2800 </varlistentry> 2801 <varlistentry> 2802 <term> 2803 <emphasis remap='I'>value_return</emphasis> 2804 </term> 2805 <listitem> 2806 <para> 2807Specifies a pointer into which a pointer to the parameters is to be stored. 2808A NULL is stored if no parameters accompany the request. 2809 </para> 2810 </listitem> 2811 </varlistentry> 2812 <varlistentry> 2813 <term> 2814 <emphasis remap='I'>length_return</emphasis> 2815 </term> 2816 <listitem> 2817 <para> 2818Specifies a pointer into which the number of data elements 2819in <emphasis remap='I'>value_return</emphasis> of size indicated by <emphasis remap='I'>format_return</emphasis> are stored. 2820 </para> 2821 </listitem> 2822 </varlistentry> 2823 <varlistentry> 2824 <term> 2825 <emphasis remap='I'>format_return</emphasis> 2826 </term> 2827 <listitem> 2828 <para> 2829Specifies a pointer into which the size in bits of the parameter data 2830in the elements of <emphasis remap='I'>value</emphasis> is stored. 2831 </para> 2832 </listitem> 2833 </varlistentry> 2834</variablelist> 2835 2836<para> 2837<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/> 2838may be called only from within an 2839<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/> 2840or from within the first call to an 2841<xref linkend='XtConvertSelectionIncrProc' xrefstyle='select: title'/> 2842with a new request_id. 2843</para> 2844 2845<para> 2846It is the responsibility of the caller to free the returned parameters using 2847<xref linkend='XtFree' xrefstyle='select: title'/> 2848when the parameters are no longer needed. 2849</para> 2850</sect2> 2851 2852<sect2 id="Generating_MULTIPLE_Requests"> 2853<title>Generating MULTIPLE Requests</title> 2854<para> 2855To have the Intrinsics bundle multiple calls to make selection requests into 2856a single request using a <emphasis role='strong'>MULTIPLE</emphasis> target, use 2857<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> 2858and 2859<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>. 2860</para> 2861 2862<funcsynopsis id='XtCreateSelectionRequest'> 2863<funcprototype> 2864<funcdef>void <function>XtCreateSelectionRequest</function></funcdef> 2865 <paramdef>Widget <parameter>requestor</parameter></paramdef> 2866 <paramdef>Atom <parameter>selection</parameter></paramdef> 2867</funcprototype> 2868</funcsynopsis> 2869 2870<variablelist> 2871 <varlistentry> 2872 <term> 2873 <emphasis remap='I'>requestor</emphasis> 2874 </term> 2875 <listitem> 2876 <para> 2877Specifies the widget making the request. Must be of class Core or any subclass thereof. 2878 </para> 2879 </listitem> 2880 </varlistentry> 2881 <varlistentry> 2882 <term> 2883 <emphasis remap='I'>selection</emphasis> 2884 </term> 2885 <listitem> 2886 <para> 2887Specifies the particular selection desired. 2888 </para> 2889 </listitem> 2890 </varlistentry> 2891</variablelist> 2892 2893<para> 2894When 2895<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> 2896is called, subsequent calls to 2897<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>, 2898<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>, 2899<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>, 2900and 2901<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>, 2902with the requestor and selection as specified to 2903<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>, 2904are bundled into a single selection request with 2905multiple targets. The request is made by calling 2906<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>. 2907</para> 2908 2909<funcsynopsis id='XtSendSelectionRequest'> 2910<funcprototype> 2911<funcdef>void <function>XtSendSelectionRequest</function></funcdef> 2912 <paramdef>Widget <parameter>requestor</parameter></paramdef> 2913 <paramdef>Atom <parameter>selection</parameter></paramdef> 2914 <paramdef>Time <parameter>time</parameter></paramdef> 2915</funcprototype> 2916</funcsynopsis> 2917 2918<variablelist> 2919 <varlistentry> 2920 <term> 2921 <emphasis remap='I'>requestor</emphasis> 2922 </term> 2923 <listitem> 2924 <para> 2925Specifies the widget making the request. Must be of class Core or any subclass thereof. 2926 </para> 2927 </listitem> 2928 </varlistentry> 2929 <varlistentry> 2930 <term> 2931 <emphasis remap='I'>selection</emphasis> 2932 </term> 2933 <listitem> 2934 <para> 2935Specifies the particular selection desired. 2936 </para> 2937 </listitem> 2938 </varlistentry> 2939 <varlistentry> 2940 <term> 2941 <emphasis remap='I'>time</emphasis> 2942 </term> 2943 <listitem> 2944 <para> 2945Specifies the timestamp that indicates when the selection request was 2946initiated. The value 2947<function>CurrentTime</function> 2948is not acceptable. 2949 </para> 2950 </listitem> 2951 </varlistentry> 2952</variablelist> 2953 2954<para> 2955When 2956<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/> 2957is called with a value of <emphasis remap='I'>requestor</emphasis> and <emphasis remap='I'>selection</emphasis> matching 2958a previous call to 2959<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>, 2960a selection request is sent to the selection owner. 2961If a single target request is queued, that request is made. 2962If multiple targets are queued, they are bundled into a single request 2963with a target of MULTIPLE using the specified timestamp. 2964As the values are returned, the callbacks specified in 2965<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>, 2966<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>, 2967<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>, 2968and 2969<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> 2970are invoked. 2971</para> 2972 2973<para> 2974Multi-threaded applications should lock the application context before 2975calling 2976<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> 2977and release the lock after calling 2978<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/> 2979to ensure that the thread assembling the request is safe from interference 2980by another thread assembling a different request naming the same widget 2981and selection. 2982</para> 2983 2984<para> 2985To relinquish the composition of a MULTIPLE request without sending it, use 2986<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/>. 2987</para> 2988 2989<funcsynopsis id='XtCancelSelectionRequest'> 2990<funcprototype> 2991<funcdef>void <function>XtCancelSelectionRequest</function></funcdef> 2992 <paramdef>Widget <parameter>requestor</parameter></paramdef> 2993 <paramdef>Atom <parameter>selection</parameter></paramdef> 2994</funcprototype> 2995</funcsynopsis> 2996 2997<variablelist> 2998 <varlistentry> 2999 <term> 3000 <emphasis remap='I'>requestor</emphasis> 3001 </term> 3002 <listitem> 3003 <para> 3004Specifies the widget making the request. Must be of class Core or any subclass thereof. 3005 </para> 3006 </listitem> 3007 </varlistentry> 3008 <varlistentry> 3009 <term> 3010 <emphasis remap='I'>selection</emphasis> 3011 </term> 3012 <listitem> 3013 <para> 3014Specifies the particular selection desired. 3015 </para> 3016 </listitem> 3017 </varlistentry> 3018</variablelist> 3019 3020<para> 3021When 3022<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/> 3023is called, any requests queued since the last call to 3024<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> 3025for the same widget and selection are discarded 3026and any resources reserved are released. 3027A subsequent call to 3028<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/> 3029will not result in any request being made. 3030Subsequent calls to 3031<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>, 3032<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>, 3033<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>, 3034or 3035<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> 3036will not be deferred. 3037</para> 3038</sect2> 3039 3040<sect2 id="Auxiliary_Selection_Properties"> 3041<title>Auxiliary Selection Properties</title> 3042<para> 3043Certain uses of parameterized selections require clients to name 3044other window properties within a selection parameter. To permit 3045reuse of temporary property names in these circumstances and 3046thereby reduce the number of unique atoms created in the server, 3047the Intrinsics provides two interfaces for acquiring temporary property names. 3048</para> 3049 3050<para> 3051To acquire a temporary property name atom for use in a selection 3052request, the client may call 3053<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>. 3054</para> 3055 3056<funcsynopsis id='XtReservePropertyAtom'> 3057<funcprototype> 3058<funcdef>Atom <function>XtReservePropertyAtom</function></funcdef> 3059 <paramdef>Widget <parameter>w</parameter></paramdef> 3060</funcprototype> 3061</funcsynopsis> 3062 3063<variablelist> 3064 <varlistentry> 3065 <term> 3066 <emphasis remap='I'>w</emphasis> 3067 </term> 3068 <listitem> 3069 <para> 3070Specifies the widget making a selection request. 3071 </para> 3072 </listitem> 3073 </varlistentry> 3074</variablelist> 3075 3076<para> 3077<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/> 3078returns an atom that may be used as a property name during selection 3079requests involving the specified widget. 3080As long as the atom remains reserved, it is unique with respect to all 3081other reserved atoms for the widget. 3082</para> 3083 3084<para> 3085To return a temporary property name atom for reuse and to delete 3086the property named by that atom, use 3087<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/>. 3088</para> 3089 3090<funcsynopsis id='XtReleasePropertyAtom'> 3091<funcprototype> 3092<funcdef>void <function>XtReleasePropertyAtom</function></funcdef> 3093 <paramdef>Widget <parameter>w</parameter></paramdef> 3094 <paramdef>Atom <parameter>atom</parameter></paramdef> 3095</funcprototype> 3096</funcsynopsis> 3097 3098<variablelist> 3099 <varlistentry> 3100 <term> 3101 <emphasis remap='I'>w</emphasis> 3102 </term> 3103 <listitem> 3104 <para> 3105Specifies the widget used to reserve the property name atom. 3106 </para> 3107 </listitem> 3108 </varlistentry> 3109 <varlistentry> 3110 <term> 3111 <emphasis remap='I'>atom</emphasis> 3112 </term> 3113 <listitem> 3114 <para> 3115Specifies the property name atom returned by 3116<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/> 3117that is to be released for reuse. 3118 </para> 3119 </listitem> 3120 </varlistentry> 3121</variablelist> 3122 3123<para> 3124<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/> 3125marks the specified property name atom as 3126no longer in use and ensures that any property having that name 3127on the specified widget's window is deleted. If <emphasis remap='I'>atom</emphasis> does not 3128specify a value returned by 3129<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/> 3130for the specified widget, the results are undefined. 3131</para> 3132</sect2> 3133 3134<sect2 id="Retrieving_the_Most_Recent_Timestamp"> 3135<title>Retrieving the Most Recent Timestamp</title> 3136<para> 3137To retrieve the timestamp from the most recent call to 3138<xref linkend='XtDispatchEvent' xrefstyle='select: title'/> 3139that contained a timestamp, use 3140<xref linkend='XtLastTimestampProcessed' xrefstyle='select: title'/>. 3141</para> 3142 3143<funcsynopsis id='XtLastTimestampProcessed'> 3144<funcprototype> 3145<funcdef>Time <function>XtLastTimestampProcessed</function></funcdef> 3146 <paramdef>Display *<parameter>display</parameter></paramdef> 3147</funcprototype> 3148</funcsynopsis> 3149 3150<variablelist> 3151 <varlistentry> 3152 <term> 3153 <emphasis remap='I'>display</emphasis> 3154 </term> 3155 <listitem> 3156 <para> 3157Specifies an open display connection. 3158 </para> 3159 </listitem> 3160 </varlistentry> 3161</variablelist> 3162 3163<para> 3164If no 3165<function>KeyPress</function>, 3166<function>KeyRelease</function>, 3167<function>ButtonPress</function>, 3168<function>ButtonRelease</function>, 3169<function>MotionNotify</function>, 3170<function>EnterNotify</function>, 3171<function>LeaveNotify</function>, 3172<function>PropertyNotify</function>, 3173or 3174<function>SelectionClear</function> 3175event has yet been passed to 3176<xref linkend='XtDispatchEvent' xrefstyle='select: title'/> 3177for the specified display, 3178<xref linkend='XtLastTimestampProcessed' xrefstyle='select: title'/> 3179returns zero. 3180</para> 3181</sect2> 3182 3183<sect2 id="Retrieving_the_Most_Recent_Event"> 3184<title>Retrieving the Most Recent Event</title> 3185<para> 3186To retrieve the event from the most recent call to 3187<xref linkend='XtDispatchEvent' xrefstyle='select: title'/> 3188for a specific display, use 3189<xref linkend='XtLastEventProcessed' xrefstyle='select: title'/>. 3190</para> 3191 3192<funcsynopsis id='XtLastEventProcessed'> 3193<funcprototype> 3194<funcdef>XEvent *<function>XtLastEventProcessed</function></funcdef> 3195 <paramdef>Display *<parameter>display</parameter></paramdef> 3196</funcprototype> 3197</funcsynopsis> 3198 3199<variablelist> 3200 <varlistentry> 3201 <term> 3202 <emphasis remap='I'>display</emphasis> 3203 </term> 3204 <listitem> 3205 <para> 3206Specifies the display connection from which to retrieve the event. 3207 </para> 3208 </listitem> 3209 </varlistentry> 3210</variablelist> 3211 3212<para> 3213Returns the last event passed to 3214<xref linkend='XtDispatchEvent' xrefstyle='select: title'/> 3215for the specified display. Returns NULL if there is no such event. 3216The client must not modify the contents of the returned event. 3217</para> 3218</sect2> 3219</sect1> 3220 3221<sect1 id="Merging_Exposure_Events_into_a_Region"> 3222<title>Merging Exposure Events into a Region</title> 3223<para> 3224The Intrinsics provide an 3225<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/> 3226utility function that merges 3227<function>Expose</function> 3228and 3229<function>GraphicsExpose</function> 3230events into a region for clients to process at once 3231rather than processing individual rectangles. 3232For further information about regions, 3233see <olink targetdoc='libX11' targetptr='Manipulating_Regions' /> 3234in <olink targetdoc='libX11' targetptr='libX11'> 3235Xlib — C Language X Interface.</olink>. 3236</para> 3237 3238<para> 3239To merge 3240<function>Expose</function> 3241and 3242<function>GraphicsExpose</function> 3243events into a region, use 3244<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>. 3245</para> 3246 3247<funcsynopsis id='XtAddExposureToRegion'> 3248<funcprototype> 3249<funcdef>void <function>XtAddExposureToRegion</function></funcdef> 3250 <paramdef>XEvent *<parameter>event</parameter></paramdef> 3251 <paramdef>Region <parameter>region</parameter></paramdef> 3252</funcprototype> 3253</funcsynopsis> 3254 3255<variablelist> 3256 <varlistentry> 3257 <term> 3258 <emphasis remap='I'>event</emphasis> 3259 </term> 3260 <listitem> 3261 <para> 3262Specifies a pointer to the 3263<function>Expose</function> 3264or 3265<function>GraphicsExpose</function> 3266event. 3267 </para> 3268 </listitem> 3269 </varlistentry> 3270 <varlistentry> 3271 <term> 3272 <emphasis remap='I'>region</emphasis> 3273 </term> 3274 <listitem> 3275 <para> 3276Specifies the region object (as defined in 3277<function><X11/Xutil.h></function>). 3278 </para> 3279 </listitem> 3280 </varlistentry> 3281</variablelist> 3282 3283<para> 3284The 3285<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/> 3286function computes the union of the rectangle defined by the exposure 3287event and the specified region. 3288Then it stores the results back in <emphasis remap='I'>region</emphasis>. 3289If the event argument is not an 3290<function>Expose</function> 3291or 3292<function>GraphicsExpose</function> 3293event, 3294<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/> 3295returns without an error and without modifying <emphasis remap='I'>region</emphasis>. 3296</para> 3297 3298<para> 3299This function is used by the exposure compression mechanism; 3300see <xref linkend='Exposure_Compression' /> 3301</para> 3302</sect1> 3303 3304<sect1 id="Translating_Widget_Coordinates"> 3305<title>Translating Widget Coordinates</title> 3306<para> 3307To translate an x-y coordinate pair from widget coordinates to root 3308window absolute coordinates, use 3309<xref linkend='XtTranslateCoords' xrefstyle='select: title'/>. 3310</para> 3311 3312<funcsynopsis id='XtTranslateCoords'> 3313<funcprototype> 3314<funcdef>void <function>XtTranslateCoords</function></funcdef> 3315 <paramdef>Widget <parameter>w</parameter></paramdef> 3316 <paramdef>Position <parameter>x</parameter></paramdef> 3317 <paramdef>Position *<parameter>rootx_return</parameter></paramdef> 3318</funcprototype> 3319</funcsynopsis> 3320 3321<variablelist> 3322 <varlistentry> 3323 <term> 3324 <emphasis remap='I'>w</emphasis> 3325 </term> 3326 <listitem> 3327 <para> 3328Specifies the widget. Must be of class RectObj or any subclass thereof. 3329 </para> 3330 </listitem> 3331 </varlistentry> 3332 <varlistentry> 3333 <term> 3334 <emphasis remap='I'>x</emphasis> 3335 </term> 3336 <listitem> 3337 <para></para> 3338 </listitem> 3339 </varlistentry> 3340 <varlistentry> 3341 <term> 3342 <emphasis remap='I'>y</emphasis> 3343 </term> 3344 <listitem> 3345 <para> 3346Specify the widget-relative x and y coordinates. 3347 </para> 3348 </listitem> 3349 </varlistentry> 3350 <varlistentry> 3351 <term> 3352 <emphasis remap='I'>rootx_return</emphasis> 3353 </term> 3354 <listitem> 3355 <para></para> 3356 </listitem> 3357 </varlistentry> 3358 <varlistentry> 3359 <term> 3360 <emphasis remap='I'>rooty_return</emphasis> 3361 </term> 3362 <listitem> 3363 <para> 3364Return the root-relative x and y coordinates. 3365 </para> 3366 </listitem> 3367 </varlistentry> 3368</variablelist> 3369 3370<para> 3371While 3372<xref linkend='XtTranslateCoords' xrefstyle='select: title'/> 3373is similar to the Xlib 3374<function>XTranslateCoordinates</function> 3375function, it does not generate a server request because all the required 3376information already is in the widget's data structures. 3377</para> 3378</sect1> 3379 3380<sect1 id="Translating_a_Window_to_a_Widget"> 3381<title>Translating a Window to a Widget</title> 3382<para> 3383To translate a given window and display pointer into a widget instance, use 3384<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>. 3385</para> 3386 3387<funcsynopsis id='XtWindowToWidget'> 3388<funcprototype> 3389<funcdef>Widget <function>XtWindowToWidget</function></funcdef> 3390 <paramdef>Display *<parameter>display</parameter></paramdef> 3391 <paramdef>Window <parameter>window</parameter></paramdef> 3392</funcprototype> 3393</funcsynopsis> 3394 3395<variablelist> 3396 <varlistentry> 3397 <term> 3398 <emphasis remap='I'>display</emphasis> 3399 </term> 3400 <listitem> 3401 <para> 3402Specifies the display on which the window is defined. 3403 </para> 3404 </listitem> 3405 </varlistentry> 3406 <varlistentry> 3407 <term> 3408 <emphasis remap='I'>window</emphasis> 3409 </term> 3410 <listitem> 3411 <para> 3412Specifies the drawable for which you want the widget. 3413 </para> 3414 </listitem> 3415 </varlistentry> 3416</variablelist> 3417 3418<para> 3419If there is a realized widget whose window is the specified drawable on 3420the specified <emphasis remap='I'>display</emphasis>, 3421<xref linkend='XtWindowToWidget' xrefstyle='select: title'/> 3422returns that widget. 3423If not and if the drawable has been associated with a widget through 3424<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>, 3425<xref linkend='XtWindowToWidget' xrefstyle='select: title'/> 3426returns the widget associated with the drawable. In other cases it 3427returns NULL. 3428</para> 3429</sect1> 3430 3431<sect1 id="Handling_Errors"> 3432<title>Handling Errors</title> 3433<para> 3434The Intrinsics allow a client to register procedures that are called 3435whenever a fatal or nonfatal error occurs. 3436These facilities are intended for both error reporting and logging 3437and for error correction or recovery. 3438</para> 3439 3440<para> 3441Two levels of interface are provided: 3442</para> 3443<itemizedlist spacing='compact'> 3444 <listitem> 3445 <para> 3446A high-level interface that takes an error 3447name and class and retrieves the error message text from 3448an error resource database. 3449 </para> 3450 </listitem> 3451 <listitem> 3452 <para> 3453A low-level interface that takes a simple string to display. 3454 </para> 3455 </listitem> 3456</itemizedlist> 3457<para> 3458The high-level functions construct a string to pass to the lower-level 3459interface. 3460The strings may be specified in application code and are 3461overridden by the contents of an external systemwide file, 3462the "error database file". The location and name of this file are 3463implementation-dependent. 3464</para> 3465<note> 3466<para> 3467The application-context-specific error handling is not 3468implemented on many systems, although the interfaces are 3469always present. 3470Most implementations will have just one set of error handlers 3471for all application contexts within a process. 3472If they are set for different application contexts, 3473the ones registered last will prevail. 3474</para> 3475</note> 3476 3477<para> 3478To obtain the error database (for example, to merge with 3479an application- or widget-specific database), use 3480<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/>. 3481</para> 3482 3483<funcsynopsis id='XtAppGetErrorDatabase'> 3484<funcprototype> <funcdef>XrmDatabase *<function>XtAppGetErrorDatabase</function></funcdef> 3485 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 3486</funcprototype> 3487</funcsynopsis> 3488 3489<variablelist> 3490 <varlistentry> 3491 <term> 3492 <emphasis remap='I'>app_context</emphasis> 3493 </term> 3494 <listitem> 3495 <para> 3496Specifies the application context. 3497 </para> 3498 </listitem> 3499 </varlistentry> 3500</variablelist> 3501 3502<para> 3503The 3504<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/> 3505function returns the address of the error database. 3506The Intrinsics do a lazy binding of the error database and do not merge in the 3507database file until the first call to 3508<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>. 3509</para> 3510 3511<para> 3512For a complete listing of all errors and warnings 3513that can be generated by the Intrinsics, see <xref linkend='Intrinsics_Error_Messages' /> 3514</para> 3515 3516<para> 3517The high-level error and warning handler procedure pointers are of type 3518<xref linkend='XtErrorMsgHandler' xrefstyle='select: title'/>. 3519</para> 3520 3521<funcsynopsis id='XtErrorMsgHandler'> 3522<funcprototype> 3523<funcdef>typedef void <function>(*XtErrorMsgHandler)</function></funcdef> 3524 <paramdef>String <parameter>name</parameter></paramdef> 3525 <paramdef>String <parameter>type</parameter></paramdef> 3526 <paramdef>String <parameter>class</parameter></paramdef> 3527 <paramdef>String <parameter>defaultp</parameter></paramdef> 3528 <paramdef>String *<parameter>params</parameter></paramdef> 3529 <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> 3530</funcprototype> 3531</funcsynopsis> 3532 3533<variablelist> 3534 <varlistentry> 3535 <term> 3536 <emphasis remap='I'>name</emphasis> 3537 </term> 3538 <listitem> 3539 <para> 3540Specifies the name to be concatenated with the specified type to form 3541the resource name of the error message. 3542 </para> 3543 </listitem> 3544 </varlistentry> 3545 <varlistentry> 3546 <term> 3547 <emphasis remap='I'>type</emphasis> 3548 </term> 3549 <listitem> 3550 <para> 3551Specifies the type to be concatenated with the name to form the 3552resource name of the error message. 3553 </para> 3554 </listitem> 3555 </varlistentry> 3556 <varlistentry> 3557 <term> 3558 <emphasis remap='I'>class</emphasis> 3559 </term> 3560 <listitem> 3561 <para> 3562Specifies the resource class of the error message. 3563 </para> 3564 </listitem> 3565 </varlistentry> 3566 <varlistentry> 3567 <term> 3568 <emphasis remap='I'>defaultp</emphasis> 3569 </term> 3570 <listitem> 3571 <para> 3572Specifies the default message to use if no error database entry is found. 3573 </para> 3574 </listitem> 3575 </varlistentry> 3576 <varlistentry> 3577 <term> 3578 <emphasis remap='I'>params</emphasis> 3579 </term> 3580 <listitem> 3581 <para> 3582Specifies a pointer to a list of parameters to be substituted in the message. 3583 </para> 3584 </listitem> 3585 </varlistentry> 3586 <varlistentry> 3587 <term> 3588 <emphasis remap='I'>num_params</emphasis> 3589 </term> 3590 <listitem> 3591 <para> 3592Specifies the number of entries in <emphasis remap='I'>params</emphasis>. 3593 </para> 3594 </listitem> 3595 </varlistentry> 3596</variablelist> 3597 3598<para> 3599The specified name can be a general kind of error, 3600like "invalidParameters" or "invalidWindow", 3601and the specified type gives extra information 3602such as the name of the routine in which the error was detected. 3603Standard 3604<function>printf</function> 3605notation is used to substitute the parameters into the message. 3606</para> 3607 3608<para> 3609An error message handler can obtain the error database text for an 3610error or a warning by calling 3611<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>. 3612</para> 3613 3614<funcsynopsis id='XtAppGetErrorDatabaseText'> 3615<funcprototype> 3616<funcdef>void <function>XtAppGetErrorDatabaseText</function></funcdef> 3617 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 3618 <paramdef>String <parameter>name</parameter></paramdef> 3619 <paramdef>String <parameter>default</parameter></paramdef> 3620 <paramdef>String <parameter>buffer_return</parameter></paramdef> 3621 <paramdef>int <parameter>nbytes</parameter></paramdef> 3622 <paramdef>XrmDatabase <parameter>database</parameter></paramdef> 3623</funcprototype> 3624</funcsynopsis> 3625 3626<variablelist> 3627 <varlistentry> 3628 <term> 3629 <emphasis remap='I'>app_context</emphasis> 3630 </term> 3631 <listitem> 3632 <para> 3633Specifies the application context. 3634 </para> 3635 </listitem> 3636 </varlistentry> 3637 <varlistentry> 3638 <term> 3639 <emphasis remap='I'>name</emphasis> 3640 </term> 3641 <term> 3642 <emphasis remap='I'>type</emphasis> 3643 </term> 3644 <listitem> 3645 <para> 3646Specify the name and type concatenated to form the resource name 3647of the error message. 3648 </para> 3649 </listitem> 3650 </varlistentry> 3651 <varlistentry> 3652 <term> 3653 <emphasis remap='I'>class</emphasis> 3654 </term> 3655 <listitem> 3656 <para> 3657Specifies the resource class of the error message. 3658 </para> 3659 </listitem> 3660 </varlistentry> 3661 <varlistentry> 3662 <term> 3663 <emphasis remap='I'>default</emphasis> 3664 </term> 3665 <listitem> 3666 <para> 3667Specifies the default message to use if an error database entry is not found. 3668 </para> 3669 </listitem> 3670 </varlistentry> 3671 <varlistentry> 3672 <term> 3673 <emphasis remap='I'>buffer_return</emphasis> 3674 </term> 3675 <listitem> 3676 <para> 3677Specifies the buffer into which the error message is to be returned. 3678 </para> 3679 </listitem> 3680 </varlistentry> 3681 <varlistentry> 3682 <term> 3683 <emphasis remap='I'>nbytes</emphasis> 3684 </term> 3685 <listitem> 3686 <para> 3687Specifies the size of the buffer in bytes. 3688 </para> 3689 </listitem> 3690 </varlistentry> 3691 <varlistentry> 3692 <term> 3693 <emphasis remap='I'>database</emphasis> 3694 </term> 3695 <listitem> 3696 <para> 3697Specifies the name of the alternative database to be used, 3698or NULL if the application context's error database is to be used. 3699 </para> 3700 </listitem> 3701 </varlistentry> 3702</variablelist> 3703 3704<para> 3705The 3706<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/> 3707returns the appropriate message from the error database 3708or returns the specified default message if one is not found in the 3709error database. 3710To form the full resource name and class when querying the database, 3711the <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>type</emphasis> are concatenated with a single "." 3712between them and the <emphasis remap='I'>class</emphasis> is concatenated with itself with a 3713single "." if it does not already contain a ".". 3714</para> 3715 3716<para> 3717To return the application name and class as passed to 3718<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/> 3719for a particular Display, use 3720<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>. 3721</para> 3722 3723<funcsynopsis id='XtGetApplicationNameAndClass'> 3724<funcprototype> 3725<funcdef>void <function>XtGetApplicationNameAndClass</function></funcdef> 3726 <paramdef>Display* <parameter>display</parameter></paramdef> 3727 <paramdef>String* <parameter>name_return</parameter></paramdef> 3728 <paramdef>String* <parameter>class_return</parameter></paramdef> 3729</funcprototype> 3730</funcsynopsis> 3731 3732<variablelist> 3733 <varlistentry> 3734 <term> 3735 <emphasis remap='I'>display</emphasis> 3736 </term> 3737 <listitem> 3738 <para> 3739Specifies an open display connection that has been initialized with 3740<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>. 3741 </para> 3742 </listitem> 3743 </varlistentry> 3744 <varlistentry> 3745 <term> 3746 <emphasis remap='I'>name_return</emphasis> 3747 </term> 3748 <listitem> 3749 <para> 3750Returns the application name. 3751 </para> 3752 </listitem> 3753 </varlistentry> 3754 <varlistentry> 3755 <term> 3756 <emphasis remap='I'>class_return</emphasis> 3757 </term> 3758 <listitem> 3759 <para> 3760Returns the application class. 3761 </para> 3762 </listitem> 3763 </varlistentry> 3764</variablelist> 3765 3766<para> 3767<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/> 3768returns the application name and class passed to 3769<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/> 3770for the specified display. If the display was 3771never initialized or has been closed, the result is undefined. The 3772returned strings are owned by the Intrinsics and must not be modified 3773or freed by the caller. 3774</para> 3775 3776<para> 3777To register a procedure to be called on fatal error conditions, use 3778<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/>. 3779</para> 3780 3781<funcsynopsis id='XtAppSetErrorMsgHandler'> 3782<funcprototype> 3783<funcdef>XtErrorMsgHandler <function>XtAppSetErrorMsgHandler</function></funcdef> 3784 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 3785 <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef> 3786</funcprototype> 3787</funcsynopsis> 3788 3789<variablelist> 3790 <varlistentry> 3791 <term> 3792 <emphasis remap='I'>app_context</emphasis> 3793 </term> 3794 <listitem> 3795 <para> 3796Specifies the application context. 3797 </para> 3798 </listitem> 3799 </varlistentry> 3800 <varlistentry> 3801 <term> 3802 <emphasis remap='I'>msg_handler</emphasis> 3803 </term> 3804 <listitem> 3805 <para> 3806Specifies the new fatal error procedure, which should not return. 3807 </para> 3808 </listitem> 3809 </varlistentry> 3810</variablelist> 3811 3812<para> 3813<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/> 3814returns a pointer to the previously 3815installed high-level fatal error handler. 3816The default high-level fatal error handler provided by the Intrinsics is named 3817<function>_XtDefaultErrorMsg</function> 3818and constructs a string from the error resource database and calls 3819<xref linkend='XtError' xrefstyle='select: title'/>. 3820Fatal error message handlers should not return. 3821If one does, 3822subsequent Intrinsics behavior is undefined. 3823</para> 3824 3825<para> 3826To call the high-level error handler, use 3827<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>. 3828</para> 3829 3830<funcsynopsis id='XtAppErrorMsg'> 3831<funcprototype> 3832<funcdef>void <function>XtAppErrorMsg</function></funcdef> 3833 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 3834 <paramdef>String <parameter>name</parameter></paramdef> 3835 <paramdef>String <parameter>type</parameter></paramdef> 3836 <paramdef>String <parameter>class</parameter></paramdef> 3837 <paramdef>String <parameter>default</parameter></paramdef> 3838 <paramdef>String *<parameter>params</parameter></paramdef> 3839 <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> 3840</funcprototype> 3841</funcsynopsis> 3842 3843<variablelist> 3844 <varlistentry> 3845 <term> 3846 <emphasis remap='I'>app_context</emphasis> 3847 </term> 3848 <listitem> 3849 <para> 3850Specifies the application context. 3851 </para> 3852 </listitem> 3853 </varlistentry> 3854 <varlistentry> 3855 <term> 3856 <emphasis remap='I'>name</emphasis> 3857 </term> 3858 <listitem> 3859 <para> 3860Specifies the general kind of error. 3861 </para> 3862 </listitem> 3863 </varlistentry> 3864 <varlistentry> 3865 <term> 3866 <emphasis remap='I'>type</emphasis> 3867 </term> 3868 <listitem> 3869 <para> 3870Specifies the detailed name of the error. 3871 </para> 3872 </listitem> 3873 </varlistentry> 3874 <varlistentry> 3875 <term> 3876 <emphasis remap='I'>class</emphasis> 3877 </term> 3878 <listitem> 3879 <para> 3880Specifies the resource class. 3881 </para> 3882 </listitem> 3883 </varlistentry> 3884 <varlistentry> 3885 <term> 3886 <emphasis remap='I'>default</emphasis> 3887 </term> 3888 <listitem> 3889 <para> 3890Specifies the default message to use if an error database entry is not found. 3891 </para> 3892 </listitem> 3893 </varlistentry> 3894 <varlistentry> 3895 <term> 3896 <emphasis remap='I'>params</emphasis> 3897 </term> 3898 <listitem> 3899 <para> 3900Specifies a pointer to a list of values to be stored in the message. 3901 </para> 3902 </listitem> 3903 </varlistentry> 3904 <varlistentry> 3905 <term> 3906 <emphasis remap='I'>num_params</emphasis> 3907 </term> 3908 <listitem> 3909 <para> 3910Specifies the number of entries in <emphasis remap='I'>params</emphasis>. 3911 </para> 3912 </listitem> 3913 </varlistentry> 3914</variablelist> 3915 3916<para> 3917The Intrinsics internal errors all have class 3918"XtToolkitError". 3919</para> 3920 3921<para> 3922To register a procedure to be called on nonfatal error conditions, use 3923<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/>. 3924</para> 3925 3926<funcsynopsis id='XtAppSetWarningMsgHandler'> 3927<funcprototype> 3928<funcdef>XtErrorMsgHandler <function>XtAppSetWarningMsgHandler</function></funcdef> 3929 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 3930 <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef> 3931</funcprototype> 3932</funcsynopsis> 3933 3934<variablelist> 3935 <varlistentry> 3936 <term> 3937 <emphasis remap='I'>app_context</emphasis> 3938 </term> 3939 <listitem> 3940 <para> 3941Specifies the application context. 3942 </para> 3943 </listitem> 3944 </varlistentry> 3945 <varlistentry> 3946 <term> 3947 <emphasis remap='I'>msg_handler</emphasis> 3948 </term> 3949 <listitem> 3950 <para> 3951Specifies the new nonfatal error procedure, which usually returns. 3952 </para> 3953 </listitem> 3954 </varlistentry> 3955</variablelist> 3956 3957<para> 3958<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/> 3959returns a pointer to the previously 3960installed high-level warning handler. 3961The default high-level warning handler provided by the Intrinsics is named 3962<function>_XtDefaultWarningMsg</function> 3963and constructs a string 3964from the error resource database and calls 3965<xref linkend='XtWarning' xrefstyle='select: title'/>. 3966</para> 3967 3968<para> 3969To call the installed high-level warning handler, use 3970<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>. 3971</para> 3972 3973<funcsynopsis id='XtAppWarningMsg'> 3974<funcprototype> 3975<funcdef>void <function>XtAppWarningMsg</function></funcdef> 3976 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 3977 <paramdef>String <parameter>name</parameter></paramdef> 3978 <paramdef>String <parameter>type</parameter></paramdef> 3979 <paramdef>String <parameter>class</parameter></paramdef> 3980 <paramdef>String <parameter>default</parameter></paramdef> 3981 <paramdef>String *<parameter>params</parameter></paramdef> 3982 <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> 3983</funcprototype> 3984</funcsynopsis> 3985 3986<variablelist> 3987 <varlistentry> 3988 <term> 3989 <emphasis remap='I'>app_context</emphasis> 3990 </term> 3991 <listitem> 3992 <para> 3993Specifies the application context. 3994 </para> 3995 </listitem> 3996 </varlistentry> 3997 <varlistentry> 3998 <term> 3999 <emphasis remap='I'>name</emphasis> 4000 </term> 4001 <listitem> 4002 <para> 4003Specifies the general kind of error. 4004 </para> 4005 </listitem> 4006 </varlistentry> 4007 <varlistentry> 4008 <term> 4009 <emphasis remap='I'>type</emphasis> 4010 </term> 4011 <listitem> 4012 <para> 4013Specifies the detailed name of the error. 4014 </para> 4015 </listitem> 4016 </varlistentry> 4017 <varlistentry> 4018 <term> 4019 <emphasis remap='I'>class</emphasis> 4020 </term> 4021 <listitem> 4022 <para> 4023Specifies the resource class. 4024 </para> 4025 </listitem> 4026 </varlistentry> 4027 <varlistentry> 4028 <term> 4029 <emphasis remap='I'>default</emphasis> 4030 </term> 4031 <listitem> 4032 <para> 4033Specifies the default message to use if an error database entry is not found. 4034 </para> 4035 </listitem> 4036 </varlistentry> 4037 <varlistentry> 4038 <term> 4039 <emphasis remap='I'>params</emphasis> 4040 </term> 4041 <listitem> 4042 <para> 4043Specifies a pointer to a list of values to be stored in the message. 4044 </para> 4045 </listitem> 4046 </varlistentry> 4047 <varlistentry> 4048 <term> 4049 <emphasis remap='I'>num_params</emphasis> 4050 </term> 4051 <listitem> 4052 <para> 4053Specifies the number of entries in <emphasis remap='I'>params</emphasis>. 4054 </para> 4055 </listitem> 4056 </varlistentry> 4057</variablelist> 4058 4059<para> 4060The Intrinsics internal warnings all have class 4061"XtToolkitError". 4062</para> 4063 4064<para> 4065The low-level error and warning handler procedure pointers are of type 4066<xref linkend='XtErrorHandler' xrefstyle='select: title'/>. 4067</para> 4068 4069<funcsynopsis id='XtErrorHandler'> 4070<funcprototype> 4071<funcdef>typedef void <function>(*XtErrorHandler)</function></funcdef> 4072 <paramdef>String <parameter>message</parameter></paramdef> 4073</funcprototype> 4074</funcsynopsis> 4075 4076<variablelist> 4077 <varlistentry> 4078 <term> 4079 <emphasis remap='I'>message</emphasis> 4080 </term> 4081 <listitem> 4082 <para> 4083Specifies the error message. 4084 </para> 4085 </listitem> 4086 </varlistentry> 4087</variablelist> 4088 4089<para> 4090The error handler should display the message string in some appropriate fashion. 4091</para> 4092 4093<para> 4094To register a procedure to be called on fatal error conditions, use 4095<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/>. 4096</para> 4097 4098<funcsynopsis id='XtAppSetErrorHandler'> 4099<funcprototype> 4100<funcdef>XtErrorHandler <function>XtAppSetErrorHandler</function></funcdef> 4101 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 4102 <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef> 4103</funcprototype> 4104</funcsynopsis> 4105 4106<variablelist> 4107 <varlistentry> 4108 <term> 4109 <emphasis remap='I'>app_context</emphasis> 4110 </term> 4111 <listitem> 4112 <para> 4113Specifies the application context. 4114 </para> 4115 </listitem> 4116 </varlistentry> 4117 <varlistentry> 4118 <term> 4119 <emphasis remap='I'>handler</emphasis> 4120 </term> 4121 <listitem> 4122 <para> 4123Specifies the new fatal error procedure, which should not return. 4124 </para> 4125 </listitem> 4126 </varlistentry> 4127</variablelist> 4128 4129<para> 4130<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/> 4131returns a pointer to the previously installed 4132low-level fatal error handler. 4133The default low-level error handler provided by the Intrinsics is 4134<function>_XtDefaultError</function>. 4135On POSIX-based systems, 4136it prints the message to standard error and terminates the application. 4137Fatal error message handlers should not return. 4138If one does, 4139subsequent Intrinsics behavior is undefined. 4140</para> 4141 4142<para> 4143To call the installed fatal error procedure, use 4144<xref linkend='XtAppError' xrefstyle='select: title'/>. 4145</para> 4146 4147<funcsynopsis id='XtAppError'> 4148<funcprototype> 4149<funcdef>void <function>XtAppError</function></funcdef> 4150 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 4151 <paramdef>String <parameter>message</parameter></paramdef> 4152</funcprototype> 4153</funcsynopsis> 4154 4155<variablelist> 4156 <varlistentry> 4157 <term> 4158 <emphasis remap='I'>app_context</emphasis> 4159 </term> 4160 <listitem> 4161 <para> 4162Specifies the application context. 4163 </para> 4164 </listitem> 4165 </varlistentry> 4166 <varlistentry> 4167 <term> 4168 <emphasis remap='I'>message</emphasis> 4169 </term> 4170 <listitem> 4171 <para> 4172Specifies the message to be reported. 4173 </para> 4174 </listitem> 4175 </varlistentry> 4176</variablelist> 4177 4178<para> 4179Most programs should use 4180<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>, 4181not 4182<xref linkend='XtAppError' xrefstyle='select: title'/>, 4183to provide for customization and internationalization of error messages. 4184</para> 4185 4186<para> 4187To register a procedure to be called on nonfatal error conditions, use 4188<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/>. 4189</para> 4190 4191<funcsynopsis id='XtAppSetWarningHandler'> 4192<funcprototype> 4193<funcdef>XtErrorHandler <function>XtAppSetWarningHandler</function></funcdef> 4194 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 4195 <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef> 4196</funcprototype> 4197</funcsynopsis> 4198 4199<variablelist> 4200 <varlistentry> 4201 <term> 4202 <emphasis remap='I'>app_context</emphasis> 4203 </term> 4204 <listitem> 4205 <para> 4206Specifies the application context. 4207 </para> 4208 </listitem> 4209 </varlistentry> 4210 <varlistentry> 4211 <term> 4212 <emphasis remap='I'>handler</emphasis> 4213 </term> 4214 <listitem> 4215 <para> 4216Specifies the new nonfatal error procedure, which usually returns. 4217 </para> 4218 </listitem> 4219 </varlistentry> 4220</variablelist> 4221 4222<para> 4223<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/> 4224returns a pointer to the previously installed 4225low-level warning handler. 4226The default low-level warning handler provided by the Intrinsics is 4227<function>_XtDefaultWarning</function>. 4228On POSIX-based systems, 4229it prints the message to standard error and returns to the caller. 4230</para> 4231 4232<para> 4233To call the installed nonfatal error procedure, use 4234<xref linkend='XtAppWarning' xrefstyle='select: title'/>. 4235</para> 4236 4237<funcsynopsis id='XtAppWarning'> 4238<funcprototype> 4239<funcdef>void <function>XtAppWarning</function></funcdef> 4240 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 4241 <paramdef>String <parameter>message</parameter></paramdef> 4242</funcprototype> 4243</funcsynopsis> 4244 4245<variablelist> 4246 <varlistentry> 4247 <term> 4248 <emphasis remap='I'>app_context</emphasis> 4249 </term> 4250 <listitem> 4251 <para> 4252Specifies the application context. 4253 </para> 4254 </listitem> 4255 </varlistentry> 4256 <varlistentry> 4257 <term> 4258 <emphasis remap='I'>message</emphasis> 4259 </term> 4260 <listitem> 4261 <para> 4262Specifies the nonfatal error message to be reported. 4263 </para> 4264 </listitem> 4265 </varlistentry> 4266</variablelist> 4267 4268<para> 4269Most programs should use 4270<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>, 4271not 4272<xref linkend='XtAppWarning' xrefstyle='select: title'/>, 4273to provide for customization and internationalization of warning messages. 4274</para> 4275</sect1> 4276 4277<sect1 id="Setting_WM_COLORMAP_WINDOWS"> 4278<title>Setting WM_COLORMAP_WINDOWS</title> 4279<para> 4280A client may set the value of the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> 4281property on a widget's window by calling 4282<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>. 4283</para> 4284 4285<funcsynopsis id='XtSetWMColormapWindows'> 4286<funcprototype> 4287<funcdef>void <function>XtSetWMColormapWindows</function></funcdef> 4288 <paramdef>Widget <parameter>widget</parameter></paramdef> 4289 <paramdef>Widget* <parameter>list</parameter></paramdef> 4290 <paramdef>Cardinal <parameter>count</parameter></paramdef> 4291</funcprototype> 4292</funcsynopsis> 4293 4294<variablelist> 4295 <varlistentry> 4296 <term> 4297 <emphasis remap='I'>widget</emphasis> 4298 </term> 4299 <listitem> 4300 <para> 4301Specifies the widget on whose window the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> 4302property is stored. Must be of class Core or any subclass thereof. 4303 </para> 4304 </listitem> 4305 </varlistentry> 4306 <varlistentry> 4307 <term> 4308 <emphasis remap='I'>list</emphasis> 4309 </term> 4310 <listitem> 4311 <para> 4312Specifies a list of widgets whose windows are potentially to be 4313listed in the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> property. 4314 </para> 4315 </listitem> 4316 </varlistentry> 4317 <varlistentry> 4318 <term> 4319 <emphasis remap='I'>count</emphasis> 4320 </term> 4321 <listitem> 4322 <para> 4323Specifies the number of widgets in <emphasis remap='I'>list</emphasis>. 4324 </para> 4325 </listitem> 4326 </varlistentry> 4327</variablelist> 4328 4329<para> 4330<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> 4331returns immediately if <emphasis remap='I'>widget</emphasis> is not realized or if <emphasis remap='I'>count</emphasis> is 0. 4332Otherwise, 4333<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> 4334constructs an ordered list of windows 4335by examining each widget in <emphasis remap='I'>list</emphasis> in turn and 4336ignoring the widget if it is not realized, or 4337adding the widget's window to the window list if the widget is realized 4338and if its colormap resource is different from the colormap 4339resources of all widgets whose windows are already on the window list. 4340</para> 4341 4342<para> 4343Finally, 4344<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> 4345stores the resulting window list in the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> 4346property on the specified widget's window. 4347Refer to Section 4.1.8 in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis> for details of 4348the semantics of the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> property. 4349</para> 4350</sect1> 4351<!-- FIXME: --> 4352<sect1 id="Finding_File_Names"> 4353<title>Finding File Names</title> 4354<para> 4355The Intrinsics provide procedures to look for a file by name, allowing 4356string substitutions in a list of file specifications. Two 4357routines are provided for this: 4358<xref linkend='XtFindFile' xrefstyle='select: title'/> 4359and 4360<xref linkend='XtResolvePathname' xrefstyle='select: title'/>. 4361<xref linkend='XtFindFile' xrefstyle='select: title'/> 4362uses an arbitrary set of client-specified substitutions, and 4363<xref linkend='XtResolvePathname' xrefstyle='select: title'/> 4364uses a set of standard substitutions corresponding 4365to the <emphasis remap='I'>X/Open Portability Guide</emphasis> language localization conventions. 4366Most applications should use 4367<xref linkend='XtResolvePathname' xrefstyle='select: title'/>. 4368</para> 4369 4370<para> 4371A string substitution is defined by a list of 4372<function>Substitution</function> 4373entries. 4374</para> 4375<literallayout > 4376typedef struct { 4377 char match; 4378 String substitution; 4379} SubstitutionRec, *Substitution; 4380</literallayout> 4381<para> 4382File name evaluation is handled in an operating-system-dependent 4383fashion by an 4384<xref linkend='XtFilePredicate' xrefstyle='select: title'/> 4385procedure. 4386</para> 4387 4388<funcsynopsis id='XtFilePredicate'> 4389<funcprototype> 4390<funcdef>typedef Boolean <function>(*XtFilePredicate)</function></funcdef> 4391 <paramdef>String <parameter>filename</parameter></paramdef> 4392</funcprototype> 4393</funcsynopsis> 4394 4395<variablelist> 4396 <varlistentry> 4397 <term> 4398 <emphasis remap='I'>filename</emphasis> 4399 </term> 4400 <listitem> 4401 <para> 4402Specifies a potential filename. 4403 </para> 4404 </listitem> 4405 </varlistentry> 4406</variablelist> 4407 4408<para> 4409A file predicate procedure is called with a string that is 4410potentially a file name. It should return 4411<function>True</function> 4412if this string specifies a file that is appropriate for the intended use and 4413<function>False</function> 4414otherwise. 4415</para> 4416 4417<para> 4418To search for a file using substitutions in a path list, use 4419<xref linkend='XtFindFile' xrefstyle='select: title'/>. 4420</para> 4421 4422<funcsynopsis id='XtFindFile'> 4423<funcprototype> 4424<funcdef>String <function>XtFindFile</function></funcdef> 4425 <paramdef>String <parameter>path</parameter></paramdef> 4426 <paramdef>Substitution <parameter>substitutions</parameter></paramdef> 4427 <paramdef>Cardinal <parameter>num_substitutions</parameter></paramdef> 4428 <paramdef>XtFilePredicate <parameter>predicate</parameter></paramdef> 4429</funcprototype> 4430</funcsynopsis> 4431 4432<variablelist> 4433 <varlistentry> 4434 <term> 4435 <emphasis remap='I'>path</emphasis> 4436 </term> 4437 <listitem> 4438 <para> 4439Specifies a path of file names, including substitution characters. 4440 </para> 4441 </listitem> 4442 </varlistentry> 4443 <varlistentry> 4444 <term> 4445 <emphasis remap='I'>substitutions</emphasis> 4446 </term> 4447 <listitem> 4448 <para> 4449Specifies a list of substitutions to make into the path. 4450 </para> 4451 </listitem> 4452 </varlistentry> 4453 <varlistentry> 4454 <term> 4455 <emphasis remap='I'>num_substitutions</emphasis> 4456 </term> 4457 <listitem> 4458 <para> 4459Specifies the number of substitutions passed in. 4460 </para> 4461 </listitem> 4462 </varlistentry> 4463 <varlistentry> 4464 <term> 4465 <emphasis remap='I'>predicate</emphasis> 4466 </term> 4467 <listitem> 4468 <para> 4469Specifies a procedure called to judge each potential file name, or NULL. 4470 </para> 4471 </listitem> 4472 </varlistentry> 4473</variablelist> 4474 4475<para> 4476The <emphasis remap='I'>path</emphasis> parameter specifies a string that consists of a series of 4477potential file names delimited by colons. Within each name, the 4478percent character specifies a string substitution selected by the 4479following character. The character sequence "%:" specifies an 4480embedded colon that is not a delimiter; the sequence is replaced by a 4481single colon. The character sequence "%%" specifies a percent 4482character that does not introduce a substitution; the sequence is 4483replaced by a single percent character. If a percent character is 4484followed by any other character, 4485<xref linkend='XtFindFile' xrefstyle='select: title'/> 4486looks through the 4487specified <emphasis remap='I'>substitutions</emphasis> for that character in the <emphasis remap='I'>match</emphasis> field 4488and, if found, 4489replaces the percent and match characters with the string in the 4490corresponding <emphasis remap='I'>substitution</emphasis> field. A <emphasis remap='I'>substitution</emphasis> field entry of NULL 4491is equivalent to a pointer to an empty string. If the operating 4492system does not interpret multiple embedded name separators in the 4493path (i.e., "/" in POSIX) the same way as a single separator, 4494<xref linkend='XtFindFile' xrefstyle='select: title'/> 4495will collapse multiple separators into a single one after performing 4496all string substitutions. Except for collapsing embedded separators, 4497the contents of the string substitutions are not interpreted by 4498<xref linkend='XtFindFile' xrefstyle='select: title'/> 4499and may therefore contain any operating-system-dependent 4500characters, including additional name separators. Each resulting 4501string is passed to the predicate procedure until a string is found for 4502which the procedure returns 4503<function>True</function>; 4504this string is the return value for 4505<xref linkend='XtFindFile' xrefstyle='select: title'/>. 4506If no string yields a 4507<function>True</function> 4508return from the predicate, 4509<xref linkend='XtFindFile' xrefstyle='select: title'/> 4510returns NULL. 4511</para> 4512 4513<para> 4514If the <emphasis remap='I'>predicate</emphasis> parameter is NULL, an internal procedure that checks 4515if the file exists, is readable, and is not a directory is used. 4516</para> 4517 4518<para> 4519It is the responsibility of the caller to free the returned string using 4520<xref linkend='XtFree' xrefstyle='select: title'/> 4521when it is no longer needed. 4522</para> 4523 4524<para> 4525To search for a file using standard substitutions in a path list, use 4526<xref linkend='XtResolvePathname' xrefstyle='select: title'/>. 4527</para> 4528 4529<funcsynopsis id='XtResolvePathname'> 4530<funcprototype> 4531<funcdef>String <function>XtResolvePathname</function></funcdef> 4532 <paramdef>Display *<parameter>display</parameter></paramdef> 4533 <paramdef>String <parameter>type</parameter></paramdef> 4534 <paramdef>Substitution <parameter>substitutions</parameter></paramdef> 4535 <paramdef>Cardinal <parameter>num_substitutions</parameter></paramdef> 4536 <paramdef>XtFilePredicate <parameter>predicate</parameter></paramdef> 4537</funcprototype> 4538</funcsynopsis> 4539 4540<variablelist> 4541 <varlistentry> 4542 <term> 4543 <emphasis remap='I'>display</emphasis> 4544 </term> 4545 <listitem> 4546 <para> 4547Specifies the display to use to find the language for language substitutions. 4548 </para> 4549 </listitem> 4550 </varlistentry> 4551 <varlistentry> 4552 <term> 4553 <emphasis remap='I'>type</emphasis> 4554 </term> 4555 <listitem> 4556 <para></para> 4557 4558 </listitem> 4559 </varlistentry> 4560 <varlistentry> 4561 <term> 4562 <emphasis remap='I'>filename</emphasis> 4563 </term> 4564 <listitem> 4565 <para></para> 4566 </listitem> 4567 </varlistentry> 4568 <varlistentry> 4569 <term> 4570 <emphasis remap='I'>suffix</emphasis> 4571 </term> 4572 <listitem> 4573 <para> 4574Specify values to substitute into the path. 4575 </para> 4576 </listitem> 4577 </varlistentry> 4578 <varlistentry> 4579 <term> 4580 <emphasis remap='I'>path</emphasis> 4581 </term> 4582 <listitem> 4583 <para> 4584Specifies the list of file specifications, or NULL. 4585 </para> 4586 </listitem> 4587 </varlistentry> 4588 <varlistentry> 4589 <term> 4590 <emphasis remap='I'>substitutions</emphasis> 4591 </term> 4592 <listitem> 4593 <para> 4594Specifies a list of additional substitutions to make into the path, or NULL. 4595 </para> 4596 </listitem> 4597 </varlistentry> 4598 <varlistentry> 4599 <term> 4600 <emphasis remap='I'>num_substitutions</emphasis> 4601 </term> 4602 <listitem> 4603 <para> 4604Specifies the number of entries in <emphasis remap='I'>substitutions</emphasis>. 4605 </para> 4606 </listitem> 4607 </varlistentry> 4608 <varlistentry> 4609 <term> 4610 <emphasis remap='I'>predicate</emphasis> 4611 </term> 4612 <listitem> 4613 <para> 4614Specifies a procedure called to judge each potential file name, or NULL. 4615 </para> 4616 </listitem> 4617 </varlistentry> 4618</variablelist> 4619 4620<para> 4621The substitutions specified by 4622<xref linkend='XtResolvePathname' xrefstyle='select: title'/> 4623are determined from the value of the language string retrieved by 4624<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/> 4625for the specified display. 4626To set the 4627language for all applications specify "*xnlLanguage: <emphasis remap='I'>lang</emphasis>" in the 4628resource database. 4629The format and content of the language string are 4630implementation-defined. One suggested syntax is to compose 4631the language string of three parts; a "language part", a 4632"territory part" and a "codeset part". The manner in which 4633this composition is accomplished is implementation-defined, 4634and the Intrinsics make no interpretation of the parts other 4635than to use them in substitutions as described below. 4636</para> 4637 4638 4639<para> 4640<xref linkend='XtResolvePathname' xrefstyle='select: title'/> 4641calls 4642<xref linkend='XtFindFile' xrefstyle='select: title'/> 4643with the following substitutions 4644in addition to any passed by the caller and returns the value returned by 4645<xref linkend='XtFindFile' xrefstyle='select: title'/>: 4646</para> 4647<!-- PROBLEM BELOW HERE --> 4648 4649 4650<variablelist> 4651 <varlistentry> 4652 <term> 4653%N 4654 </term> 4655 <listitem> 4656 <para> 4657The value of the <emphasis remap='I'>filename</emphasis> parameter, or the application's 4658class name if <emphasis remap='I'>filename</emphasis> is NULL. 4659 </para> 4660 </listitem> 4661 </varlistentry> 4662 <varlistentry> 4663 <term> 4664%T 4665 </term> 4666 <listitem> 4667 <para> 4668The value of the <emphasis remap='I'>type</emphasis> parameter. 4669 </para> 4670 </listitem> 4671 </varlistentry> 4672 <varlistentry> 4673 <term> 4674%S 4675 </term> 4676 <listitem> 4677 <para> 4678The value of the <emphasis remap='I'>suffix</emphasis> parameter. 4679 </para> 4680 </listitem> 4681 </varlistentry> 4682 <varlistentry> 4683 <term> 4684%L 4685 </term> 4686 <listitem> 4687 <para> 4688The language string associated with the specified display. 4689 </para> 4690 </listitem> 4691 </varlistentry> 4692 <varlistentry> 4693 <term> 4694%l 4695 </term> 4696 <listitem> 4697 <para> 4698The language part of the display's language string. 4699 </para> 4700 </listitem> 4701 </varlistentry> 4702 <varlistentry> 4703 <term> 4704%t 4705 </term> 4706 <listitem> 4707 <para> 4708The territory part of the display's language string. 4709 </para> 4710 </listitem> 4711 </varlistentry> 4712 <varlistentry> 4713 <term> 4714%c 4715 </term> 4716 <listitem> 4717 <para> 4718The codeset part of the display's language string. 4719 </para> 4720 </listitem> 4721 </varlistentry> 4722 <varlistentry> 4723 <term> 4724%C 4725 </term> 4726 <listitem> 4727 <para> 4728The customization string retrieved from the resource 4729database associated with <emphasis remap='I'>display</emphasis>. 4730 </para> 4731 </listitem> 4732 </varlistentry> 4733 <varlistentry> 4734 <term> 4735%D 4736 </term> 4737 <listitem> 4738 <para> 4739The value of the implementation-specific default path. 4740 </para> 4741 </listitem> 4742 </varlistentry> 4743</variablelist> 4744 4745 4746<!-- PROBLEM ABOVE HERE --> 4747<para> 4748If a path is passed to 4749<xref linkend='XtResolvePathname' xrefstyle='select: title'/>, 4750it is passed along to 4751<xref linkend='XtFindFile' xrefstyle='select: title'/>. 4752If the <emphasis remap='I'>path</emphasis> argument is NULL, the value of the 4753<emphasis role='strong'>XFILESEARCHPATH</emphasis> 4754environment variable is passed to 4755<xref linkend='XtFindFile' xrefstyle='select: title'/>. 4756If <emphasis role='strong'>XFILESEARCHPATH</emphasis> 4757is not defined, an implementation-specific default path is used 4758that contains at least six entries. These entries 4759must contain the following substitutions: 4760</para> 4761 4762 4763<!-- OK PAST HERE --> 4764 4765<literallayout> 47661. %C, %N, %S, %T, %L or %C, %N, %S, %T, %l, %t, %c 47672. %C, %N, %S, %T, %l 47683. %C, %N, %S, %T 47694. %N, %S, %T, %L or %N, %S, %T, %l, %t, %c 47705. %N, %S, %T, %l 47716. %N, %S, %T 4772</literallayout> 4773 4774<para> 4775The order of these six entries within the path must be as given above. 4776The order and use of substitutions within a given entry 4777are implementation-dependent. 4778If the path begins 4779with a colon, it is preceded by %N%S. If the path includes two 4780adjacent colons, <function>%N%S</function> is inserted between them. 4781</para> 4782 4783<para> 4784The <emphasis remap='I'>type</emphasis> parameter is intended to be a category of files, usually 4785being translated into a directory in the pathname. Possible values 4786might include "app-defaults", "help", and "bitmap". 4787</para> 4788 4789<para> 4790The <emphasis remap='I'>suffix</emphasis> parameter is intended to be appended to the file name. 4791Possible values might include ".txt", ".dat", and ".bm". 4792</para> 4793 4794<para> 4795A suggested value for the default path on POSIX-based systems is 4796</para> 4797<literallayout> 4798 /usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\ 4799 /usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\ 4800 /usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S 4801</literallayout> 4802 4803 4804<para> 4805Using this example, if the user has specified a language, it is 4806used as a subdirectory of /usr/lib/X11 that is searched for other 4807files. If the desired file is not found there, the lookup is 4808tried again using just the language part of the specification. If the 4809file is not there, it is looked for in /usr/lib/X11. The <emphasis remap='I'>type</emphasis> 4810parameter is used as a subdirectory of the language directory or of 4811/usr/lib/X11, and <emphasis remap='I'>suffix</emphasis> is appended to the file name. 4812</para> 4813 4814<para> 4815The %D substitution allows the addition of path 4816elements to the implementation-specific default path, typically to 4817allow additional directories to be searched without preventing 4818resources in the system directories from being found. For example, a 4819user installing resource files under a directory called "ourdir" 4820might set 4821<emphasis role='strong'>XFILESEARCHPATH</emphasis> 4822to 4823</para> 4824<literallayout> 4825 %D:ourdir/%T/%N%C:ourdir/%T/%N 4826</literallayout> 4827 4828<para> 4829The customization string is obtained by querying the resource database 4830currently associated with the display (the database returned by 4831<function>XrmGetDatabase</function>) 4832for the resource <emphasis remap='I'>application_name</emphasis>.customization, class 4833<emphasis remap='I'>application_class</emphasis>.Customization, where <emphasis remap='I'>application_name</emphasis> 4834and <emphasis remap='I'>application_class</emphasis> are the values returned by 4835<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>. 4836If no value is specified in the database, the empty string is used. 4837</para> 4838 4839<para> 4840It is the responsibility of the caller to free the returned string using 4841<xref linkend='XtFree' xrefstyle='select: title'/> 4842when it is no longer needed. 4843</para> 4844 4845 4846</sect1> 4847<!-- END OF FIXME --> 4848<sect1 id="Hooks_for_External_Agents"> 4849<title>Hooks for External Agents</title> 4850<para> 4851Applications may register 4852functions that are called at a particular control points in the Intrinsics. 4853These functions are intended to be used to provide notification 4854of an "X Toolkit event", such as widget creation, to an external agent, 4855such as an interactive resource editor, drag-and-drop server, or 4856an aid for physically challenged users. 4857The control points containing such registration hooks are identified 4858in a "hook registration" object. 4859</para> 4860 4861<para> 4862To retrieve the hook registration widget, use 4863<xref linkend='XtHooksOfDisplay' xrefstyle='select: title'/>. 4864</para> 4865 4866<funcsynopsis id='XtHooksOfDisplay'> 4867<funcprototype> 4868<funcdef>Widget <function>XtHooksOfDisplay</function></funcdef> 4869 <paramdef>Display *<parameter>display</parameter></paramdef> 4870</funcprototype> 4871</funcsynopsis> 4872 4873<variablelist> 4874 <varlistentry> 4875 <term> 4876 <emphasis remap='I'>display</emphasis> 4877 </term> 4878 <listitem> 4879 <para> 4880Specifies the desired display. 4881 </para> 4882 </listitem> 4883 </varlistentry> 4884</variablelist> 4885 4886<para> 4887The class of this object is a private, implementation-dependent 4888subclass of 4889<function>Object</function>. 4890The hook object has no parent. The resources of this object are 4891the callback lists for hooks and the read-only resources for getting 4892a list of parentless shells. All of the callback lists are initially 4893empty. When a display is closed, the hook object associated with it 4894is destroyed. 4895</para> 4896 4897<para> 4898The following procedures can be called with the hook registration object 4899as an argument: 4900</para> 4901<itemizedlist spacing='compact'> 4902 <listitem> 4903 <para> 4904<xref linkend='XtAddCallback' xrefstyle='select: title'/>, 4905<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>, 4906<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>, 4907<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>, 4908<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>, 4909<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>, 4910<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>, 4911<xref linkend='XtCallCallbackList' xrefstyle='select: title'/> 4912 </para> 4913 </listitem> 4914 <listitem> 4915 <para> 4916<xref linkend='XtClass' xrefstyle='select: title'/>, 4917<function>XtSuperclass</function>, 4918<xref linkend='XtIsSubclass' xrefstyle='select: title'/>, 4919<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>, 4920<function>XtIsObject</function>, 4921<function>XtIsRectObj</function>, 4922<function>XtIsWidget</function>, 4923<function>XtIsComposite</function>, 4924<function>XtIsConstraint</function>, 4925<function>XtIsShell</function>, 4926<function>XtIsOverrideShell</function>, 4927<function>XtIsWMShell</function>, 4928<function>XtIsVendorShell</function>, 4929<function>XtIsTransientShell</function>, 4930<function>XtIsToplevelShell</function>, 4931<function>XtIsApplicationShell</function>, 4932<function>XtIsSessionShell</function> 4933 </para> 4934 </listitem> 4935 <listitem> 4936 <para> 4937<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/> 4938 </para> 4939 </listitem> 4940 <listitem> 4941 <para> 4942<xref linkend='XtName' xrefstyle='select: title'/>, 4943<function>XtParent</function>, 4944<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>, 4945<xref linkend='XtScreenOfObject' xrefstyle='select: title'/> 4946 </para> 4947 </listitem> 4948 <listitem> 4949 <para> 4950<xref linkend='XtSetValues' xrefstyle='select: title'/>, 4951<xref linkend='XtGetValues' xrefstyle='select: title'/>, 4952<xref linkend='XtVaSetValues' xrefstyle='select: title'/>, 4953<xref linkend='XtVaGetValues' xrefstyle='select: title'/> 4954 </para> 4955 </listitem> 4956</itemizedlist> 4957 4958<sect2 id="Hook_Object_Resources"> 4959<title>Hook Object Resources</title> 4960<para> 4961The resource names, classes, and representation types that are specified 4962in the hook object resource list are: 4963<informaltable frame='topbot'> 4964 <?dbfo keep-together="always" ?> 4965 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 4966 <colspec colwidth='1.0*' colname='c1'/> 4967 <colspec colwidth='1.0*' colname='c2'/> 4968 <colspec colwidth='1.0*' colname='c3'/> 4969 <thead> 4970 <row rowsep='1'> 4971 <entry>Name</entry> 4972 <entry>Class</entry> 4973 <entry>Representation</entry> 4974 </row> 4975 </thead> 4976 <tbody> 4977 <row> 4978 <entry>XtNcreateHook</entry> 4979 <entry>XtCCallback</entry> 4980 <entry>XtRCallback</entry> 4981 </row> 4982 <row> 4983 <entry>XtNchangeHook</entry> 4984 <entry>XtCCallback</entry> 4985 <entry>XtRCallback</entry> 4986 </row> 4987 <row> 4988 <entry>XtNconfigureHook</entry> 4989 <entry>XtCCallback</entry> 4990 <entry>XtRCallback</entry> 4991 </row> 4992 <row> 4993 <entry>XtNgeometryHook</entry> 4994 <entry>XtCCallback</entry> 4995 <entry>XtRCallback</entry> 4996 </row> 4997 <row> 4998 <entry>XtNdestroyHook</entry> 4999 <entry>XtCCallback</entry> 5000 <entry>XtRCallback</entry> 5001 </row> 5002 <row> 5003 <entry>XtNshells</entry> 5004 <entry>XtCReadOnly</entry> 5005 <entry>XtRWidgetList</entry> 5006 </row> 5007 <row> 5008 <entry>XtNnumShells</entry> 5009 <entry>XtCReadOnly</entry> 5010 <entry>XtRCardinal</entry> 5011 </row> 5012 </tbody> 5013 </tgroup> 5014</informaltable> 5015</para> 5016 5017<para> 5018Descriptions of each of these resources: 5019</para> 5020 5021<para> 5022The XtNcreateHook callback list is called from: 5023<xref linkend='XtCreateWidget' xrefstyle='select: title'/>, 5024<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>, 5025<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>, 5026<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>, 5027and their corresponding varargs versions. 5028</para> 5029 5030<para> 5031The <emphasis remap='I'>call_data</emphasis> parameter in a createHook callback may be 5032cast to type 5033<function>XtCreateHookData</function>. 5034</para> 5035<literallayout > 5036typedef struct { 5037 String type; 5038 Widget widget; 5039 ArgList args; 5040 Cardinal num_args; 5041} XtCreateHookDataRec, *XtCreateHookData; 5042</literallayout> 5043<para> 5044The <emphasis remap='I'>type</emphasis> is set to 5045<function>XtHcreate</function>, 5046<emphasis remap='I'>widget</emphasis> is the newly created widget, and <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> 5047are the arguments passed to the create function. The callbacks are 5048called before returning from the create function. 5049</para> 5050 5051<para> 5052The XtNchangeHook callback list is called from: 5053</para> 5054<itemizedlist spacing='compact'> 5055 <listitem> 5056 <para> 5057<xref linkend='XtSetValues' xrefstyle='select: title'/>, 5058<xref linkend='XtVaSetValues' xrefstyle='select: title'/> 5059 </para> 5060 </listitem> 5061 <listitem> 5062 <para> 5063<xref linkend='XtManageChild' xrefstyle='select: title'/>, 5064<xref linkend='XtManageChildren' xrefstyle='select: title'/>, 5065<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>, 5066<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/> 5067 </para> 5068 </listitem> 5069 <listitem> 5070 <para> 5071<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>, 5072<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/> 5073 </para> 5074 </listitem> 5075 <listitem> 5076 <para> 5077<xref linkend='XtAddCallback' xrefstyle='select: title'/>, 5078<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>, 5079<function>XtAddCallbacks,</function> 5080<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>, 5081<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/> 5082 </para> 5083 </listitem> 5084 <listitem> 5085 <para> 5086<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>, 5087<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>, 5088<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/> 5089 </para> 5090 </listitem> 5091 <listitem> 5092 <para> 5093<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>, 5094<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> 5095 </para> 5096 </listitem> 5097 <listitem> 5098 <para> 5099<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>, 5100<xref linkend='XtMapWidget' xrefstyle='select: title'/>, 5101<xref linkend='XtUnmapWidget' xrefstyle='select: title'/> 5102 </para> 5103 </listitem> 5104 <listitem> 5105 <para> 5106<xref linkend='XtPopup' xrefstyle='select: title'/>, 5107<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>, 5108<xref linkend='XtPopdown' xrefstyle='select: title'/> 5109 </para> 5110 </listitem> 5111</itemizedlist> 5112 5113<para> 5114The <emphasis remap='I'>call_data</emphasis> parameter in a changeHook callback may 5115be cast to type 5116<function>XtChangeHookData</function>. 5117</para> 5118<literallayout > 5119typedef struct { 5120 String type; 5121 Widget widget; 5122 XtPointer event_data; 5123 Cardinal num_event_data; 5124} XtChangeHookDataRec, *XtChangeHookData; 5125</literallayout> 5126<para> 5127When the changeHook callbacks are called as a result of a call to 5128<xref linkend='XtSetValues' xrefstyle='select: title'/> 5129or 5130<xref linkend='XtVaSetValues' xrefstyle='select: title'/>, 5131<emphasis remap='I'>type</emphasis> is set to 5132<function>XtHsetValues</function>, 5133<emphasis remap='I'>widget</emphasis> is the new widget passed to the set_values procedure, and 5134<emphasis remap='I'>event_data</emphasis> may be cast to type 5135<function>XtChangeHookSetValuesData</function>. 5136</para> 5137<literallayout > 5138typedef struct { 5139 Widget old, req; 5140 ArgList args; 5141 Cardinal num_args; 5142} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData; 5143</literallayout> 5144<para> 5145The <emphasis remap='I'>old</emphasis>, <emphasis remap='I'>req</emphasis>, <emphasis remap='I'>args</emphasis>, and <emphasis remap='I'>num_args</emphasis> are the 5146parameters passed to the set_values procedure. The callbacks are called 5147after the set_values and constraint set_values procedures have been called. 5148</para> 5149 5150<para> 5151When the changeHook callbacks are called as a result of a call to 5152<xref linkend='XtManageChild' xrefstyle='select: title'/> 5153or 5154<xref linkend='XtManageChildren' xrefstyle='select: title'/>, 5155<emphasis remap='I'>type</emphasis> is set to 5156<function>XtHmanageChildren</function>, 5157<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type 5158WidgetList and is the list of children being managed, and 5159<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list. 5160The callbacks are called after the children have been managed. 5161</para> 5162 5163<para> 5164When the changeHook callbacks are called as a result of a call to 5165<xref linkend='XtUnmanageChild' xrefstyle='select: title'/> 5166or 5167<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>, 5168<emphasis remap='I'>type</emphasis> is set to 5169<function>XtHunmanageChildren</function>, 5170<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type 5171WidgetList and is a list of the children being unmanaged, and 5172<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list. 5173The callbacks are called after the children have been unmanaged. 5174</para> 5175 5176<para> 5177The changeHook callbacks are called twice as a result of a call to 5178<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>, 5179once after unmanaging and again after managing. 5180When the callbacks are called the first time, <emphasis remap='I'>type</emphasis> is set to 5181<function>XtHunmanageSet</function>, 5182<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type 5183WidgetList and is a list of the children being unmanaged, and 5184<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list. 5185When the callbacks are called the second time, the <emphasis remap='I'>type</emphasis> is set to 5186<function>XtHmanageSet</function>, 5187<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type 5188WidgetList and is a list of the children being managed, and 5189<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list. 5190</para> 5191 5192<para> 5193When the changeHook callbacks are called as a result of a call to 5194<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>, 5195the <emphasis remap='I'>type</emphasis> is set to 5196<function>XtHrealizeWidget</function> 5197and <emphasis remap='I'>widget</emphasis> is the widget being realized. 5198The callbacks are called after the widget has been realized. 5199</para> 5200 5201<para> 5202When the changeHook callbacks are called as a result of a call to 5203<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>, 5204the <emphasis remap='I'>type</emphasis> is set to 5205<function>XtHunrealizeWidget</function>, 5206and <emphasis remap='I'>widget</emphasis> is the widget being unrealized. 5207The callbacks are called after the widget has been unrealized. 5208</para> 5209 5210<para> 5211When the changeHook callbacks are called as a result of a call to 5212<xref linkend='XtAddCallback' xrefstyle='select: title'/>, 5213<emphasis remap='I'>type</emphasis> is set to 5214<function>XtHaddCallback</function>, 5215<emphasis remap='I'>widget</emphasis> is the widget to which the callback is being added, and 5216<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the 5217callback being added. 5218The callbacks are called after the callback has been added to the widget. 5219</para> 5220 5221<para> 5222When the changeHook callbacks are called as a result of a call to 5223<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>, 5224the <emphasis remap='I'>type</emphasis> is set to 5225<function>XtHaddCallbacks</function>, 5226<emphasis remap='I'>widget</emphasis> is the widget to which the callbacks are being added, and 5227<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the 5228callbacks being added. 5229The callbacks are called after the callbacks have been added to the widget. 5230</para> 5231 5232<para> 5233When the changeHook callbacks are called as a result of a call to 5234<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>, 5235the <emphasis remap='I'>type</emphasis> is set to 5236<function>XtHremoveCallback</function>, 5237<emphasis remap='I'>widget</emphasis> is the widget from which the callback is being removed, and 5238<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of 5239the callback being removed. The callbacks are called after the callback 5240has been removed from the widget. 5241</para> 5242 5243<para> 5244When the changeHook callbacks are called as a result of a call to 5245<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>, 5246the <emphasis remap='I'>type</emphasis> is set to 5247<function>XtHremoveCallbacks</function>, 5248<emphasis remap='I'>widget</emphasis> is the widget from which the callbacks are being removed, and 5249<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the 5250callbacks being removed. The callbacks are called after the callbacks 5251have been removed from the widget. 5252</para> 5253 5254<para> 5255When the changeHook callbacks are called as a result of a call to 5256<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>, 5257the <emphasis remap='I'>type</emphasis> is set to 5258<function>XtHremoveAllCallbacks</function> 5259and <emphasis remap='I'>widget</emphasis> is the widget from which the callbacks are being removed. 5260The callbacks are called after the callbacks have been removed from the 5261widget. 5262</para> 5263 5264<para> 5265When the changeHook callbacks are called as a result of a call to 5266<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>, 5267the <emphasis remap='I'>type</emphasis> is set to 5268<function>XtHaugmentTranslations</function> 5269and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being modified. 5270The callbacks are called after the widget's translations have been 5271modified. 5272</para> 5273 5274<para> 5275When the changeHook callbacks are called as a result of a call to 5276<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>, 5277the <emphasis remap='I'>type</emphasis> is set to 5278<function>XtHoverrideTranslations</function> 5279and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being modified. 5280The callbacks are called after the widget's translations have been 5281modified. 5282</para> 5283 5284<para> 5285When the changeHook callbacks are called as a result of a call to 5286<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>, 5287The <emphasis remap='I'>type</emphasis> is 5288<function>XtHuninstallTranslations</function> 5289and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being uninstalled. 5290The callbacks are called after the widget's translations have been 5291uninstalled. 5292</para> 5293 5294<para> 5295When the changeHook callbacks are called as a result of a call to 5296<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>, 5297the <emphasis remap='I'>type</emphasis> is set to 5298<function>XtHsetKeyboardFocus</function> 5299and <emphasis remap='I'>event_data</emphasis> may be cast to type Widget and is the value of 5300the descendant argument passed to <xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>. The 5301callbacks are called before returning from <xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>. 5302</para> 5303 5304<para> 5305When the changeHook callbacks are called as a result of a call to 5306<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>, 5307<emphasis remap='I'>type</emphasis> is set to 5308<function>XtHsetWMColormapWindows</function>, 5309<emphasis remap='I'>event_data</emphasis> may be cast to type WidgetList and is the value of 5310the list argument passed to <xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>, and 5311<emphasis remap='I'>num_event_data</emphasis> is the length of the list. The callbacks are 5312called before returning from <xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>. 5313</para> 5314 5315<para> 5316When the changeHook callbacks are called as a result of a call to 5317<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>, 5318the <emphasis remap='I'>type</emphasis> is set to 5319<function>XtHsetMappedWhenManaged</function> 5320and <emphasis remap='I'>event_data</emphasis> may be cast to type Boolean and is the value of 5321the mapped_when_managed argument passed to <xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>. 5322The callbacks are called after setting the widget's mapped_when_managed 5323field and before realizing or unrealizing the widget. 5324</para> 5325 5326<para> 5327When the changeHook callbacks are called as a result of a call to 5328<xref linkend='XtMapWidget' xrefstyle='select: title'/>, 5329the <emphasis remap='I'>type </emphasis> is set to 5330<function>XtHmapWidget</function> 5331and <emphasis remap='I'>widget</emphasis> is the widget being mapped. 5332The callbacks are called after mapping the widget. 5333</para> 5334 5335<para> 5336When the changeHook callbacks are called as a result of a call to 5337<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>, 5338the <emphasis remap='I'>type </emphasis> is set to 5339<function>XtHunmapWidget</function> 5340and <emphasis remap='I'>widget</emphasis> is the widget being unmapped. 5341The callbacks are called after unmapping the widget. 5342</para> 5343 5344<para> 5345When the changeHook callbacks are called as a result of a call to 5346<xref linkend='XtPopup' xrefstyle='select: title'/>, 5347the <emphasis remap='I'>type</emphasis> is set to 5348<function>XtHpopup</function>, 5349<emphasis remap='I'>widget</emphasis> is the widget being popped up, and <emphasis remap='I'>event_data</emphasis> may 5350be cast to type XtGrabKind and is the value of the grab_kind argument 5351passed to <xref linkend='XtPopup' xrefstyle='select: title'/>. 5352The callbacks are called before returning from <xref linkend='XtPopup' xrefstyle='select: title'/>. 5353</para> 5354 5355<para> 5356When the changeHook callbacks are called as a result of a call to 5357<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>, 5358the <emphasis remap='I'>type</emphasis> is set to 5359<function>XtHpopupSpringLoaded</function> 5360and <emphasis remap='I'>widget</emphasis> is the widget being popped up. 5361The callbacks are called 5362before returning from <xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>. 5363</para> 5364 5365<para> 5366When the changeHook callbacks are called as a result of a call to 5367<xref linkend='XtPopdown' xrefstyle='select: title'/>, 5368the <emphasis remap='I'>type</emphasis> is set to 5369<function>XtHpopdown</function> 5370and <emphasis remap='I'>widget</emphasis> is the widget being popped down. 5371The callbacks are called 5372before returning from <xref linkend='XtPopdown' xrefstyle='select: title'/>. 5373</para> 5374 5375<para> 5376A widget set that exports interfaces that change application state 5377without employing the Intrinsics library should invoke the change hook 5378itself. This is done by: 5379</para> 5380 5381<literallayout > 5382 XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data); 5383</literallayout> 5384<para> 5385The XtNconfigureHook callback list is called any time the Intrinsics 5386move, resize, or configure a widget and when 5387<xref linkend='XtResizeWindow' xrefstyle='select: title'/> 5388is called. 5389</para> 5390 5391<para> 5392The <emphasis remap='I'>call_data</emphasis> parameter may be cast to type 5393<function>XtConfigureHookData.</function> 5394</para> 5395<literallayout > 5396typedef struct { 5397 String type; 5398 Widget widget; 5399 XtGeometryMask changeMask; 5400 XWindowChanges changes; 5401} XtConfigureHookDataRec, *XtConfigureHookData; 5402</literallayout> 5403<para> 5404When the configureHook callbacks are called, the <emphasis remap='I'>type</emphasis> is 5405<function>XtHconfigure</function>, 5406<emphasis remap='I'>widget</emphasis> is the widget being configured, and <emphasis remap='I'>changeMask</emphasis> and 5407<emphasis remap='I'>changes</emphasis> reflect the changes made to the widget. The callbacks 5408are called after changes have been made to the widget. 5409</para> 5410 5411<para> 5412The XtNgeometryHook callback list is called from 5413<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/> 5414and 5415<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/> 5416once before and once after geometry negotiation occurs. 5417</para> 5418 5419<para> 5420The <emphasis remap='I'>call_data</emphasis> parameter may be cast to type 5421<function>XtGeometryHookData</function>. 5422</para> 5423 5424<literallayout > 5425typedef struct { 5426 String type; 5427 Widget widget; 5428 XtWidgetGeometry* request; 5429 XtWidgetGeometry* reply; 5430 XtGeometryResult result; 5431} XtGeometryHookDataRec, *XtGeometryHookData; 5432</literallayout> 5433<para> 5434When the geometryHook callbacks are called prior to geometry negotiation, 5435the <emphasis remap='I'>type</emphasis> is 5436<function>XtHpreGeometry</function>, 5437<emphasis remap='I'>widget</emphasis> is the widget for which the request is being made, and 5438<emphasis remap='I'>request</emphasis> is the requested geometry. 5439When the geometryHook callbacks 5440are called after geometry negotiation, the <emphasis remap='I'>type</emphasis> is 5441<function>XtHpostGeometry</function>, 5442<emphasis remap='I'>widget</emphasis> is the widget for which the request was made, <emphasis remap='I'>request</emphasis> 5443is the requested geometry, <emphasis remap='I'>reply</emphasis> is the resulting geometry granted, 5444and <emphasis remap='I'>result</emphasis> is the value returned from the geometry negotiation. 5445</para> 5446 5447<para> 5448The XtNdestroyHook callback list is called when a widget is destroyed. 5449The <emphasis remap='I'>call_data parameter</emphasis> may be cast to type 5450<function>XtDestroyHookData</function>. 5451</para> 5452<literallayout > 5453typedef struct { 5454 String type; 5455 Widget widget; 5456} XtDestroyHookDataRec, *XtDestroyHookData; 5457</literallayout> 5458<para> 5459When the destroyHook callbacks are called as a result of a call to 5460<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>, 5461the <emphasis remap='I'>type</emphasis> is 5462<function>XtHdestroy</function> 5463and <emphasis remap='I'>widget</emphasis> is the widget being destroyed. The callbacks are 5464called upon completion of phase one destroy for a widget. 5465</para> 5466 5467<para> 5468The XtNshells and XtnumShells are read-only resources that report a 5469list of all parentless shell widgets associated with a display. 5470</para> 5471 5472<para> 5473Clients who use these hooks must exercise caution in calling Intrinsics 5474functions in order to avoid recursion. 5475</para> 5476</sect2> 5477 5478<sect2 id="Querying_Open_Displays"> 5479<title>Querying Open Displays</title> 5480<para> 5481To retrieve a list of the Displays associated with an application context, 5482use 5483<xref linkend='XtGetDisplays' xrefstyle='select: title'/>. 5484</para> 5485 5486<funcsynopsis id='XtGetDisplays'> 5487<funcprototype> 5488<funcdef>void <function>XtGetDisplays</function></funcdef> 5489 <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> 5490 <paramdef>Display ***<parameter>dpy_return</parameter></paramdef> 5491 <paramdef>Cardinal *<parameter>num_dpy_return</parameter></paramdef> 5492</funcprototype> 5493</funcsynopsis> 5494 5495<variablelist> 5496 <varlistentry> 5497 <term> 5498 <emphasis remap='I'>app_context</emphasis> 5499 </term> 5500 <listitem> 5501 <para> 5502Specifies the application context. 5503 </para> 5504 </listitem> 5505 </varlistentry> 5506 <varlistentry> 5507 <term> 5508 <emphasis remap='I'>dpy_return</emphasis> 5509 </term> 5510 <listitem> 5511 <para> 5512Returns a list of open Display connections in the specified application 5513context. 5514 </para> 5515 </listitem> 5516 </varlistentry> 5517 <varlistentry> 5518 <term> 5519 <emphasis remap='I'>num_dpy_return</emphasis> 5520 </term> 5521 <listitem> 5522 <para> 5523Returns the count of open Display connections in <emphasis remap='I'>dpy_return</emphasis>. 5524 </para> 5525 </listitem> 5526 </varlistentry> 5527</variablelist> 5528 5529<para> 5530<xref linkend='XtGetDisplays' xrefstyle='select: title'/> may be used by an external agent to query the 5531list of open displays that belong to an application context. To free 5532the list of displays, use 5533<xref linkend='XtFree' xrefstyle='select: title'/>. 5534</para> 5535</sect2> 5536</sect1> 5537 5538</chapter> 5539