1<?xml version="1.0" encoding="UTF-8" ?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> 3 4<chapter id='Nonwidget_Objects'> 5<title>Nonwidget Objects</title> 6 7<para> 8Although widget writers are free to treat 9Core 10as the base class of 11the widget hierarchy, there are actually three classes above it. 12These classes are 13Object, 14RectObj 15(Rectangle Object), and (unnamed), 16and members of these classes 17are referred to generically as <emphasis remap='I'>objects</emphasis>. By convention, the term 18<emphasis remap='I'>widget</emphasis> refers only to objects that are a subclass of 19Core, 20and the term <emphasis remap='I'>nonwidget</emphasis> refers to objects that are not a subclass of 21Core. 22In the preceding portion of this specification, the interface 23descriptions indicate explicitly whether the generic <emphasis remap='I'>widget</emphasis> argument 24is restricted to particular subclasses of Object. Sections 12.2.5, 2512.3.5, and 12.5 summarize the permissible classes of the arguments to, and 26return values from, each of the Intrinsics routines. 27</para> 28<sect1 id="Data_Structures"> 29<title>Data Structures</title> 30<para> 31In order not to conflict with previous widget code, the data 32structures used by nonwidget objects do not follow all the same 33conventions as those for widgets. In particular, the class records 34are not composed of parts but instead are complete data structures 35with filler for the widget fields they do not use. This 36allows the static class initializers for existing widgets to remain 37unchanged. 38</para> 39</sect1> 40 41<sect1 id="Object_Objects"> 42<title>Object Objects</title> 43<para> 44The 45Object 46object contains the definitions of fields common to all 47objects. It encapsulates the mechanisms for resource management. 48All objects and widgets are members of subclasses of 49Object, 50which is defined by the 51<function>ObjectClassPart</function> 52and 53<function>ObjectPart</function> 54structures. 55</para> 56<sect2 id="ObjectClassPart_Structure"> 57<title>ObjectClassPart Structure</title> 58<para> 59The common fields for all object classes are defined in the 60<function>ObjectClassPart</function> 61structure. All fields have the same purpose, 62function, and restrictions as the corresponding fields in 63<function>CoreClassPart</function>; 64fields whose 65names are obj<emphasis remap='I'>n</emphasis> for some integer <emphasis remap='I'>n</emphasis> are not 66used for Object, 67but exist to pad the data structure so that it matches Core's class 68record. The class record initialization must fill all 69obj<emphasis remap='I'>n</emphasis> fields with NULL or zero as appropriate to the type. 70</para> 71<programlisting> 72typedef struct _ObjectClassPart { 73 WidgetClass superclass; 74 String class_name; 75 Cardinal widget_size; 76 XtProc class_initialize; 77 XtWidgetClassProc class_part_initialize; 78 XtEnum class_inited; 79 XtInitProc initialize; 80 XtArgsProc initialize_hook; 81 XtProc obj1; 82 XtPointer obj2; 83 Cardinal obj3; 84 XtResourceList resources; 85 Cardinal num_resources; 86 XrmClass xrm_class; 87 Boolean obj4; 88 XtEnum obj5; 89 Boolean obj6; 90 Boolean obj7; 91 XtWidgetProc destroy; 92 XtProc obj8; 93 XtProc obj9; 94 XtSetValuesFunc set_values; 95 XtArgsFunc set_values_hook; 96 XtProc obj10; 97 XtArgsProc get_values_hook; 98 XtProc obj11; 99 XtVersionType version; 100 XtPointer callback_private; 101 String obj12; 102 XtProc obj13; 103 XtProc obj14; 104 XtPointer extension; 105} ObjectClassPart; 106</programlisting> 107<para> 108The extension record defined for 109<function>ObjectClassPart</function> 110with a <emphasis remap='I'>record_type</emphasis> equal to 111<emphasis role='strong'>NULLQUARK</emphasis> 112is 113<function>ObjectClassExtensionRec</function>. 114</para> 115<programlisting> 116typedef struct { 117 XtPointer next_extension; <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation> 118 XrmQuark record_type; <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation> 119 long version; <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation> 120 Cardinal record_size; <lineannotation>See <xref linkend='Class_Extension_Records' /></lineannotation> 121 XtAllocateProc allocate; <lineannotation>See <xref linkend='Widget_Instance_Allocation_The_allocate_Procedure' /></lineannotation> 122 XtDeallocateProc deallocate; <lineannotation>See <xref linkend='Widget_Instance_Deallocation_The_deallocate_Procedure' /></lineannotation> 123} ObjectClassExtensionRec, *ObjectClassExtension; 124</programlisting> 125<para> 126The prototypical 127<function>ObjectClass</function> 128consists of just the 129<function>ObjectClassPart</function>. 130</para> 131<programlisting> 132typedef struct _ObjectClassRec { 133 ObjectClassPart object_class; 134} ObjectClassRec, *ObjectClass; 135</programlisting> 136<para> 137The predefined class record and pointer for 138<function>ObjectClassRec</function> 139are 140</para> 141 142<para> 143In 144<filename class="headerfile">IntrinsicP.h</filename>: 145</para> 146<programlisting> 147extern ObjectClassRec objectClassRec; 148</programlisting> 149<para> 150In 151<filename class="headerfile">Intrinsic.h</filename>: 152</para> 153<programlisting> 154extern WidgetClass objectClass; 155</programlisting> 156<para> 157The opaque types 158<function>Object</function> 159and 160<function>ObjectClass</function> 161and the opaque variable 162<function>objectClass</function> 163are defined for generic actions on objects. 164The symbolic constant for the 165<function>ObjectClassExtension</function> 166version identifier is 167<function>XtObjectExtensionVersion</function> 168(see <xref linkend='Class_Extension_Records' />). 169<filename class="headerfile">Intrinsic.h</filename> 170uses an incomplete structure definition to ensure that the 171compiler catches attempts to access private data: 172</para> 173<programlisting> 174typedef struct _ObjectClassRec* ObjectClass; 175</programlisting> 176 177</sect2> 178 179<sect2 id="ObjectPart_Structure"> 180<title>ObjectPart Structure</title> 181<para> 182The common fields for all object instances are defined in the 183<function>ObjectPart</function> 184structure. All fields have the same meaning as the 185corresponding fields in 186<function>CorePart</function>. 187</para> 188<programlisting> 189typedef struct _ObjectPart { 190 Widget self; 191 WidgetClass widget_class; 192 Widget parent; 193 Boolean being_destroyed; 194 XtCallbackList destroy_callbacks; 195 XtPointer constraints; 196} ObjectPart; 197</programlisting> 198<para> 199All object instances have the 200Object 201fields as their first component. The prototypical type 202<function>Object</function> 203is defined with only this set of fields. 204Various routines can cast object pointers, as needed, to specific 205object types. 206</para> 207 208<para> 209In 210<filename class="headerfile">IntrinsicP.h</filename>: 211</para> 212<programlisting> 213typedef struct _ObjectRec { 214 ObjectPart object; 215} ObjectRec, *Object; 216</programlisting> 217<para> 218In 219<filename class="headerfile">Intrinsic.h</filename>: 220</para> 221<programlisting> 222typedef struct _ObjectRec *Object; 223</programlisting> 224 225</sect2> 226 227<sect2 id="Object_Resources"> 228<title>Object Resources</title> 229<para> 230The resource names, classes, and representation types specified in the 231<function>objectClassRec</function> 232resource list are: 233</para> 234 235<informaltable frame='topbot'> 236 <?dbfo keep-together="always" ?> 237 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 238 <colspec colwidth='1.0*' colname='c1'/> 239 <colspec colwidth='1.0*' colname='c2'/> 240 <colspec colwidth='1.0*' colname='c3'/> 241 <thead> 242 <row rowsep='1'> 243 <entry>Name</entry> 244 <entry>Class</entry> 245 <entry>Representation</entry> 246 </row> 247 </thead> 248 <tbody> 249 <row> 250 <entry>XtNdestroyCallback</entry> 251 <entry>XtCCallback</entry> 252 <entry>XtRCallback</entry> 253 </row> 254 </tbody> 255 </tgroup> 256</informaltable> 257</sect2> 258 259<sect2 id="ObjectPart_Default_Values"> 260<title>ObjectPart Default Values</title> 261<para> 262All fields in 263<function>ObjectPart</function> 264have the same default values as the corresponding fields in 265<function>CorePart</function>. 266</para> 267</sect2> 268 269<sect2 id="Object_Arguments_to_xI_Routines"> 270<title>Object Arguments to Intrinsics Routines</title> 271<para> 272The WidgetClass arguments to the following procedures may be 273<function>objectClass</function> 274or any subclass: 275</para> 276 277<itemizedlist spacing='compact'> 278<listitem> 279<para> 280<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>, 281<xref linkend='XtCreateWidget' xrefstyle='select: title'/>, 282<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/> 283</para> 284</listitem> 285<listitem> 286<para> 287<xref linkend='XtIsSubclass' xrefstyle='select: title'/>, 288<xref linkend='XtCheckSubclass' xrefstyle='select: title'/> 289</para> 290</listitem> 291<listitem> 292<para> 293<xref linkend='XtGetResourceList' xrefstyle='select: title'/>, 294<xref linkend='XtGetConstraintResourceList' xrefstyle='select: title'/> 295</para> 296</listitem> 297</itemizedlist> 298 299<para> 300The Widget arguments to the following procedures may be of class 301Object 302or any subclass: 303</para> 304<itemizedlist spacing='compact'> 305 <listitem> 306 <para> 307<xref linkend='XtCreateWidget' xrefstyle='select: title'/>, 308<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/> 309 </para> 310 </listitem> 311 <listitem> 312 <para> 313<xref linkend='XtAddCallback' xrefstyle='select: title'/>, 314<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>, 315<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>, 316<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>, 317<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>, 318<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>, 319<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>, 320<xref linkend='XtCallCallbackList' xrefstyle='select: title'/> 321 </para> 322 </listitem> 323 <listitem> 324 <para> 325<xref linkend='XtClass' xrefstyle='select: title'/>, 326<function>XtSuperclass</function>, 327<xref linkend='XtIsSubclass' xrefstyle='select: title'/>, 328<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>, 329<function>XtIsObject</function>, 330<function>XtIsRectObj</function>, 331<function>XtIsWidget</function>, 332<function>XtIsComposite</function>, 333<function>XtIsConstraint</function>, 334<function>XtIsShell</function>, 335<function>XtIsOverrideShell</function>, 336<function>XtIsWMShell</function>, 337<function>XtIsVendorShell</function>, 338<function>XtIsTransientShell</function>, 339<function>XtIsTopLevelShell</function>, 340<function>XtIsApplicationShell</function>, 341<function>XtIsSessionShell</function> 342 </para> 343 </listitem> 344 <listitem> 345 <para> 346<xref linkend='XtIsManaged' xrefstyle='select: title'/>, 347<xref linkend='XtIsSensitive' xrefstyle='select: title'/> 348(both will return 349<function>False</function> 350if argument is not a subclass of 351RectObj) 352 </para> 353 </listitem> 354 <listitem> 355 <para> 356<xref linkend='XtIsRealized' xrefstyle='select: title'/> 357(returns the state of the nearest windowed ancestor 358if class of argument is not a subclass of 359Core) 360 </para> 361 </listitem> 362 <listitem> 363 <para> 364<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/> 365 </para> 366 </listitem> 367 <listitem> 368 <para> 369<xref linkend='XtDestroyWidget' xrefstyle='select: title'/> 370 </para> 371 </listitem> 372 <listitem> 373 <para> 374<function>XtParent</function>, 375<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>, 376<xref linkend='XtScreenOfObject' xrefstyle='select: title'/>, 377<xref linkend='XtWindowOfObject' xrefstyle='select: title'/> 378 </para> 379 </listitem> 380 <listitem> 381 <para> 382<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/> 383(descendant) 384 </para> 385 </listitem> 386 <listitem> 387 <para> 388<xref linkend='XtGetGC' xrefstyle='select: title'/>, 389<xref linkend='XtReleaseGC' xrefstyle='select: title'/> 390 </para> 391 </listitem> 392 <listitem> 393 <para> 394<xref linkend='XtName' xrefstyle='select: title'/> 395 </para> 396 </listitem> 397 <listitem> 398 <para> 399<xref linkend='XtSetValues' xrefstyle='select: title'/>, 400<xref linkend='XtGetValues' xrefstyle='select: title'/>, 401<xref linkend='XtVaSetValues' xrefstyle='select: title'/>, 402<xref linkend='XtVaGetValues' xrefstyle='select: title'/> 403 </para> 404 </listitem> 405 <listitem> 406 <para> 407<xref linkend='XtGetSubresources' xrefstyle='select: title'/>, 408<xref linkend='XtGetApplicationResources' xrefstyle='select: title'/>, 409<xref linkend='XtVaGetSubresources' xrefstyle='select: title'/>, 410<xref linkend='XtVaGetApplicationResources' xrefstyle='select: title'/> 411 </para> 412 </listitem> 413 <listitem> 414 <para> 415<xref linkend='XtConvert' xrefstyle='select: title'/>, 416<xref linkend='XtConvertAndStore' xrefstyle='select: title'/> 417 </para> 418 </listitem> 419</itemizedlist> 420<para> 421The return value of the following procedures will be of class 422Object 423or a subclass: 424</para> 425<itemizedlist spacing='compact'> 426 <listitem> 427 <para> 428<xref linkend='XtCreateWidget' xrefstyle='select: title'/>, 429<xref linkend='XtVaCreateWidget' xrefstyle='select: title'/> 430 </para> 431 </listitem> 432 <listitem> 433 <para> 434<function>XtParent</function> 435 </para> 436 </listitem> 437 <listitem> 438 <para> 439<xref linkend='XtNameToWidget' xrefstyle='select: title'/> 440 </para> 441 </listitem> 442</itemizedlist> 443<para> 444The return value of the following procedures will be 445<function>objectClass</function> 446or a subclass: 447</para> 448<itemizedlist spacing='compact'> 449 <listitem> 450 <para> 451<xref linkend='XtClass' xrefstyle='select: title'/>, 452<function>XtSuperclass</function> 453 </para> 454 </listitem> 455</itemizedlist> 456</sect2> 457 458<sect2 id="Use_of_Objects"> 459<title>Use of Objects</title> 460<para> 461The 462Object 463class exists to enable programmers to use the Intrinsics' 464classing and resource-handling mechanisms for things smaller 465and simpler than widgets. 466Objects make obsolete many common uses of subresources as described in 467Sections 9.4, 9.7.2.4, and 9.7.2.5. 468</para> 469 470<para> 471Composite 472widget classes that wish to accept nonwidget children must 473set the <emphasis remap='I'>accepts_objects</emphasis> field in the 474<function>CompositeClassExtension</function> 475structure to 476<function>True</function>. 477<xref linkend='XtCreateWidget' xrefstyle='select: title'/> 478will otherwise generate an error message on an attempt to create a 479nonwidget child. 480</para> 481 482<para> 483Of the classes defined by the Intrinsics, 484ApplicationShell 485and 486SessionShell 487accept nonwidget children, and the class of any nonwidget child 488must not be 489<function>rectObjClass</function> 490or any subclass. The intent of allowing 491Object 492children of 493ApplicationShell 494and 495SessionShell 496is to provide clients a simple mechanism 497for establishing the resource-naming root of an object hierarchy. 498</para> 499</sect2> 500</sect1> 501 502<sect1 id="Rectangle_Objects"> 503<title>Rectangle Objects</title> 504<para> 505The class of rectangle objects is a subclass of 506Object 507that represents 508rectangular areas. It encapsulates the mechanisms for geometry 509management and is called RectObj 510to avoid conflict with the Xlib 511<function>Rectangle</function> 512data type. 513</para> 514<sect2 id="RectObjClassPart_Structure"> 515<title>RectObjClassPart Structure</title> 516<para> 517As with the 518<function>ObjectClassPart</function> 519structure, all fields in the 520<function>RectObjClassPart</function> 521structure have the same 522purpose and function as the corresponding fields in 523<function>CoreClassPart</function>; 524fields whose names are rect<emphasis remap='I'>n</emphasis> for some integer 525<emphasis remap='I'>n</emphasis> are not used for 526RectObj, but exist to pad the data structure so that it matches 527Core's 528class record. The class record initialization must fill all 529rect<emphasis remap='I'>n</emphasis> fields with NULL or zero as appropriate to the type. 530</para> 531<programlisting> 532typedef struct _RectObjClassPart { 533 WidgetClass superclass; 534 String class_name; 535 Cardinal widget_size; 536 XtProc class_initialize; 537 XtWidgetClassProc class_part_initialize; 538 XtEnum class_inited; 539 XtInitProc initialize; 540 XtArgsProc initialize_hook; 541 XtProc rect1; 542 XtPointer rect2; 543 Cardinal rect3; 544 XtResourceList resources; 545 Cardinal num_resources; 546 XrmClass xrm_class; 547 Boolean rect4; 548 XtEnum rect5; 549 Boolean rect6; 550 Boolean rect7; 551 XtWidgetProc destroy; 552 XtWidgetProc resize; 553 XtExposeProc expose; 554 XtSetValuesFunc set_values; 555 XtArgsFunc set_values_hook; 556 XtAlmostProc set_values_almost; 557 XtArgsProc get_values_hook; 558 XtProc rect9; 559 XtVersionType version; 560 XtPointer callback_private; 561 String rect10; 562 XtGeometryHandler query_geometry; 563 XtProc rect11; 564 XtPointer extension; 565} RectObjClassPart; 566</programlisting> 567<para> 568The 569RectObj 570class record consists of just the 571<function>RectObjClassPart</function>. 572</para> 573<programlisting> 574typedef struct _RectObjClassRec { 575 RectObjClassPart rect_class; 576} RectObjClassRec, *RectObjClass; 577</programlisting> 578<para> 579The predefined class record and pointer for 580<function>RectObjClassRec</function> 581are 582</para> 583 584<para> 585In 586<filename class="headerfile">Intrinsic.h</filename>: 587</para> 588<programlisting> 589extern RectObjClassRec rectObjClassRec; 590</programlisting> 591<para> 592In 593<filename class="headerfile">Intrinsic.h</filename>: 594</para> 595<programlisting> 596extern WidgetClass rectObjClass; 597</programlisting> 598<para> 599The opaque types 600<function>RectObj</function> 601and 602<function>RectObjClass</function> 603and the opaque variable 604<function>rectObjClass</function> 605are defined for generic actions on objects 606whose class is RectObj or a subclass of 607RectObj. 608<filename class="headerfile">Intrinsic.h</filename> 609uses an incomplete structure definition to ensure that the compiler 610catches attempts to access private data: 611</para> 612<programlisting> 613typedef struct _RectObjClassRec* RectObjClass; 614</programlisting> 615 616</sect2> 617 618<sect2 id="RectObjPart_Structure"> 619<title>RectObjPart Structure</title> 620<para> 621In addition to the 622<function>ObjectPart</function> 623fields, 624RectObj 625objects have the following fields defined in the 626<function>RectObjPart</function> 627structure. All fields have the same meaning as the corresponding field in 628<function>CorePart</function>. 629</para> 630<programlisting> 631typedef struct _RectObjPart { 632 Position x, y; 633 Dimension width, height; 634 Dimension border_width; 635 Boolean managed; 636 Boolean sensitive; 637 Boolean ancestor_sensitive; 638} RectObjPart; 639</programlisting> 640<para> 641RectObj 642objects have the RectObj fields immediately following the Object fields. 643</para> 644<programlisting> 645typedef struct _RectObjRec { 646 ObjectPart object; 647 RectObjPart rectangle; 648} RectObjRec, *RectObj; 649</programlisting> 650<para> 651In 652<filename class="headerfile">Intrinsic.h</filename>: 653</para> 654<programlisting> 655typedef struct _RectObjRec* RectObj; 656</programlisting> 657 658</sect2> 659 660<sect2 id="RectObj_Resources"> 661<title>RectObj Resources</title> 662<para> 663The resource names, classes, and representation types that are specified in the 664<function>rectObjClassRec</function> 665resource list are: 666<informaltable frame='topbot'> 667 <?dbfo keep-together="always" ?> 668 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 669 <colspec colwidth='1.0*' colname='c1'/> 670 <colspec colwidth='1.0*' colname='c2'/> 671 <colspec colwidth='1.0*' colname='c3'/> 672 <thead> 673 <row rowsep='1'> 674 <entry>Name</entry> 675 <entry>Class</entry> 676 <entry>Representation</entry> 677 </row> 678 </thead> 679 <tbody> 680 <row> 681 <entry>XtNancestorSensitive</entry> 682 <entry>XtCSensitive</entry> 683 <entry>XtRBoolean</entry> 684 </row> 685 <row> 686 <entry>XtNborderWidth</entry> 687 <entry>XtCBorderWidth</entry> 688 <entry>XtRDimension</entry> 689 </row> 690 <row> 691 <entry>XtNheight</entry> 692 <entry>XtCHeight</entry> 693 <entry>XtRDimension</entry> 694 </row> 695 <row> 696 <entry>XtNsensitive</entry> 697 <entry>XtCSensitive</entry> 698 <entry>XtRBoolean</entry> 699 </row> 700 <row> 701 <entry>XtNwidth</entry> 702 <entry>XtCWidth</entry> 703 <entry>XtRDimension</entry> 704 </row> 705 <row> 706 <entry>XtNx</entry> 707 <entry>XtCPosition</entry> 708 <entry>XtRPosition</entry> 709 </row> 710 <row> 711 <entry>XtNy</entry> 712 <entry>XtCPosition</entry> 713 <entry>XtRPosition</entry> 714 </row> 715 </tbody> 716 </tgroup> 717</informaltable> 718</para> 719</sect2> 720 721<sect2 id="RectObjPart_Default_Values"> 722<title>RectObjPart Default Values</title> 723<para> 724All fields in 725<function>RectObjPart</function> 726have the same default values as the corresponding fields in 727<function>CorePart</function>. 728</para> 729</sect2> 730 731<sect2 id="Widget_Arguments_to_xI_Routines"> 732<title>Widget Arguments to Intrinsics Routines</title> 733<para> 734The WidgetClass arguments to the following procedures may be 735<function>rectObjClass</function> 736or any subclass: 737</para> 738<itemizedlist spacing='compact'> 739 <listitem> 740 <para> 741<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>, 742<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/> 743 </para> 744 </listitem> 745</itemizedlist> 746<para> 747The Widget arguments to the following procedures may be of class 748RectObj 749or any subclass: 750</para> 751<itemizedlist spacing='compact'> 752 <listitem> 753 <para> 754<xref linkend='XtConfigureWidget' xrefstyle='select: title'/>, 755<xref linkend='XtMoveWidget' xrefstyle='select: title'/>, 756<xref linkend='XtResizeWidget' xrefstyle='select: title'/> 757 </para> 758 </listitem> 759 <listitem> 760 <para> 761<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/>, 762<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/> 763 </para> 764 </listitem> 765 <listitem> 766 <para> 767<xref linkend='XtManageChildren' xrefstyle='select: title'/>, 768<xref linkend='XtManageChild' xrefstyle='select: title'/>, 769<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>, 770<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>, 771<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/> 772 </para> 773 </listitem> 774 <listitem> 775 <para> 776<xref linkend='XtQueryGeometry' xrefstyle='select: title'/> 777 </para> 778 </listitem> 779 <listitem> 780 <para> 781<xref linkend='XtSetSensitive' xrefstyle='select: title'/> 782 </para> 783 </listitem> 784 <listitem> 785 <para> 786<xref linkend='XtTranslateCoords' xrefstyle='select: title'/> 787 </para> 788 </listitem> 789</itemizedlist> 790<para> 791The return value of the following procedures will be of class 792RectObj 793or a subclass: 794</para> 795<itemizedlist spacing='compact'> 796 <listitem> 797 <para> 798<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>, 799<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/> 800 </para> 801 </listitem> 802</itemizedlist> 803</sect2> 804 805<sect2 id="Use_of_Rectangle_Objects"> 806<title>Use of Rectangle Objects</title> 807<para> 808RectObj 809can be subclassed to provide widgetlike objects (sometimes 810called gadgets) that do not use windows and do not have those 811features that are seldom used in simple widgets. This can save memory 812resources both in the server and in applications 813but requires additional support code in the parent. 814In the following 815discussion, <emphasis remap='I'>rectobj</emphasis> refers only to objects 816whose class is RectObj or a subclass of 817RectObj, 818but not Core or a subclass of 819Core. 820</para> 821 822<para> 823Composite 824widget classes that wish to accept rectobj children must set 825the <emphasis remap='I'>accepts_objects</emphasis> field in the 826<function>CompositeClassExtension</function> 827extension structure to 828<function>True</function>. 829<xref linkend='XtCreateWidget' xrefstyle='select: title'/> 830or 831<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/> 832will otherwise generate an error if called to create a nonwidget child. 833If the composite widget supports only children of class 834RectObj 835or a subclass (i.e., not of the general Object class), it 836must declare an insert_child procedure and check the subclass of each 837new child in that procedure. None of the classes defined by the 838Intrinsics accept rectobj children. 839</para> 840 841<para> 842If gadgets are defined in an object set, the parent is responsible for 843much more than the parent of a widget. The parent must request and handle 844input events that occur for the gadget and is responsible for making 845sure that when it receives an exposure event the gadget children get 846drawn correctly. 847Rectobj children may 848have expose procedures 849specified in their class records, but the parent is free to 850ignore them, instead drawing the contents of the child itself. This 851can potentially save graphics context switching. The precise contents 852of the exposure event and region arguments to the RectObj expose 853procedure are not specified by the Intrinsics; a particular rectangle object is 854free to define the coordinate system origin (self-relative or 855parent-relative) and whether or not the rectangle or region is assumed to 856have been intersected with the visible region of the object. 857</para> 858 859<para> 860In general, it is expected that a composite widget that accepts 861nonwidget children will document those children it is able to handle, 862since a gadget cannot be viewed as a completely self-contained entity, 863as can a widget. Since a particular composite widget class is usually 864designed to handle nonwidget children of only a limited set of classes, it should 865check the classes of newly added children in its insert_child 866procedure to make sure that it can deal with them. 867</para> 868 869<para> 870The Intrinsics will clear areas of a parent window obscured by 871rectobj children, causing exposure events, under the following 872circumstances: 873</para> 874<itemizedlist spacing='compact'> 875 <listitem> 876 <para> 877A rectobj child is managed or unmanaged. 878 </para> 879 </listitem> 880 <listitem> 881 <para> 882In a call to 883<xref linkend='XtSetValues' xrefstyle='select: title'/> 884on a rectobj child, one or more of the set_values procedures returns 885<function>True</function>. 886 </para> 887 </listitem> 888 <listitem> 889 <para> 890In a call to 891<xref linkend='XtConfigureWidget' xrefstyle='select: title'/> 892on a rectobj child, areas will 893be cleared corresponding to both the old and the new child 894geometries, including the border, if the geometry changes. 895 </para> 896 </listitem> 897 <listitem> 898 <para> 899In a call to 900<xref linkend='XtMoveWidget' xrefstyle='select: title'/> 901on a rectobj child, areas will be 902cleared corresponding to both the old and the new child 903geometries, including the border, if the geometry changes. 904 </para> 905 </listitem> 906 <listitem> 907 <para> 908In a call to 909<xref linkend='XtResizeWidget' xrefstyle='select: title'/> 910on a rectobj child, a single 911rectangle will be cleared corresponding to the larger of the 912old and the new child geometries if they are different. 913 </para> 914 </listitem> 915 <listitem> 916 <para> 917In a call to 918<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/> 919(or 920<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/>) 921on a rectobj child with 922<function>XtQueryOnly</function> 923not set, if the manager returns 924<function>XtGeometryYes</function>, 925two rectangles will be cleared corresponding to both the old and 926the new child geometries. 927 </para> 928 </listitem> 929</itemizedlist> 930<para> 931Stacking order is not supported for rectobj children. Composite widgets with 932rectobj children are free to define any semantics desired if the child 933geometries overlap, including making this an error. 934</para> 935 936<para> 937When a rectobj is playing the role of a widget, developers must be 938reminded to avoid making assumptions about the object passed in the 939Widget argument to a callback procedure. 940</para> 941</sect2> 942</sect1> 943 944<sect1 id="Undeclared_Class"> 945<title>Undeclared Class</title> 946<para> 947The Intrinsics define an unnamed class between 948RectObj 949and 950Core 951for possible future use by the X Consortium. The only assumptions that 952may be made about the unnamed class are 953</para> 954<itemizedlist spacing='compact'> 955 <listitem> 956 <para> 957The <emphasis remap='I'>core_class.superclass</emphasis> field of 958<function>coreWidgetClassRec</function> 959contains a pointer to the unnamed class record. 960 </para> 961 </listitem> 962 <listitem> 963 <para> 964A pointer to the unnamed class record when dereferenced as an 965<function>ObjectClass</function> 966will contain a pointer to 967<function>rectObjClassRec</function> 968in its <emphasis remap='I'>object_class.superclass</emphasis> field. 969 </para> 970 </listitem> 971</itemizedlist> 972<para> 973Except for the above, the contents of the class record for this class 974and the result of an attempt to subclass or to create a widget of this 975unnamed class are undefined. 976</para> 977</sect1> 978 979<sect1 id="Widget_Arguments_to_Intrinsics_Routines"> 980<title>Widget Arguments to Intrinsics Routines</title> 981<para> 982The WidgetClass arguments to the following procedures must be of class 983Shell 984or a subclass: 985</para> 986<itemizedlist spacing='compact'> 987 <listitem> 988 <para> 989<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>, 990<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/>, 991<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>, 992<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>, 993<xref linkend='XtOpenApplication' xrefstyle='select: title'/>, 994<xref linkend='XtVaOpenApplication' xrefstyle='select: title'/> 995 </para> 996 </listitem> 997</itemizedlist> 998<para> 999The Widget arguments to the following procedures must be of class 1000Core 1001or any subclass: 1002</para> 1003<itemizedlist spacing='compact'> 1004 <listitem> 1005 <para> 1006<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>, 1007<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/> 1008 </para> 1009 </listitem> 1010 <listitem> 1011 <para> 1012<xref linkend='XtAddEventHandler' xrefstyle='select: title'/>, 1013<xref linkend='XtAddRawEventHandler' xrefstyle='select: title'/>, 1014<xref linkend='XtRemoveEventHandler' xrefstyle='select: title'/>, 1015<xref linkend='XtRemoveRawEventHandler' xrefstyle='select: title'/>, 1016<xref linkend='XtInsertEventHandler' xrefstyle='select: title'/>, 1017<xref linkend='XtInsertRawEventHandler' xrefstyle='select: title'/> 1018<xref linkend='XtInsertEventTypeHandler' xrefstyle='select: title'/>, 1019<xref linkend='XtRemoveEventTypeHandler' xrefstyle='select: title'/>, 1020 </para> 1021 </listitem> 1022 <listitem> 1023 <para> 1024<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/> 1025<xref linkend='XtDispatchEventToWidget' xrefstyle='select: title'/> 1026 </para> 1027 </listitem> 1028 <listitem> 1029 <para> 1030<xref linkend='XtAddGrab' xrefstyle='select: title'/>, 1031<xref linkend='XtRemoveGrab' xrefstyle='select: title'/>, 1032<xref linkend='XtGrabKey' xrefstyle='select: title'/>, 1033<xref linkend='XtGrabKeyboard' xrefstyle='select: title'/>, 1034<xref linkend='XtUngrabKey' xrefstyle='select: title'/>, 1035<xref linkend='XtUngrabKeyboard' xrefstyle='select: title'/>, 1036<xref linkend='XtGrabButton' xrefstyle='select: title'/>, 1037<xref linkend='XtGrabPointer' xrefstyle='select: title'/>, 1038<xref linkend='XtUngrabButton' xrefstyle='select: title'/>, 1039<xref linkend='XtUngrabPointer' xrefstyle='select: title'/> 1040 </para> 1041 </listitem> 1042 <listitem> 1043 <para> 1044<xref linkend='XtBuildEventMask' xrefstyle='select: title'/> 1045 </para> 1046 </listitem> 1047 <listitem> 1048 <para> 1049<xref linkend='XtCreateWindow' xrefstyle='select: title'/>, 1050<function>XtDisplay</function>, 1051<xref linkend='XtScreen' xrefstyle='select: title'/>, 1052<xref linkend='XtWindow' xrefstyle='select: title'/> 1053 </para> 1054 </listitem> 1055 <listitem> 1056 <para> 1057<xref linkend='XtNameToWidget' xrefstyle='select: title'/> 1058 </para> 1059 </listitem> 1060 <listitem> 1061 <para> 1062<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>, 1063<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>, 1064<xref linkend='XtOwnSelection' xrefstyle='select: title'/>, 1065<xref linkend='XtDisownSelection' xrefstyle='select: title'/>, 1066<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>, 1067<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>, 1068<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>, 1069<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/> 1070 </para> 1071 </listitem> 1072 <listitem> 1073 <para> 1074<xref linkend='XtInstallAccelerators' xrefstyle='select: title'/>, 1075<xref linkend='XtInstallAllAccelerators' xrefstyle='select: title'/> 1076(both destination and source) 1077 </para> 1078 </listitem> 1079 <listitem> 1080 <para> 1081<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>, 1082<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>, 1083<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>, 1084<xref linkend='XtCallActionProc' xrefstyle='select: title'/> 1085 </para> 1086 </listitem> 1087 <listitem> 1088 <para> 1089<xref linkend='XtMapWidget' xrefstyle='select: title'/>, 1090<xref linkend='XtUnmapWidget' xrefstyle='select: title'/> 1091 </para> 1092 </listitem> 1093 <listitem> 1094 <para> 1095<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>, 1096<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/> 1097 </para> 1098 </listitem> 1099 <listitem> 1100 <para> 1101<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/> 1102 </para> 1103 </listitem> 1104 <listitem> 1105 <para> 1106<xref linkend='XtCallAcceptFocus' xrefstyle='select: title'/>, 1107<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/> 1108(subtree) 1109 </para> 1110 </listitem> 1111 <listitem> 1112 <para> 1113<xref linkend='XtResizeWindow' xrefstyle='select: title'/> 1114 </para> 1115 </listitem> 1116 <listitem> 1117 <para> 1118<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> 1119 </para> 1120 </listitem> 1121</itemizedlist> 1122<para> 1123The Widget arguments to the following procedures must be of class 1124Composite 1125or any subclass: 1126</para> 1127<itemizedlist spacing='compact'> 1128 <listitem> 1129 <para> 1130<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>, 1131<xref linkend='XtVaCreateManagedWidget' xrefstyle='select: title'/> 1132 </para> 1133 </listitem> 1134</itemizedlist> 1135<para> 1136The Widget arguments to the following procedures must be of a subclass of 1137Shell: 1138</para> 1139<itemizedlist spacing='compact'> 1140 <listitem> 1141 <para> 1142<xref linkend='XtPopdown' xrefstyle='select: title'/>, 1143<xref linkend='XtCallbackPopdown' xrefstyle='select: title'/>, 1144<xref linkend='XtPopup' xrefstyle='select: title'/>, 1145<xref linkend='XtCallbackNone' xrefstyle='select: title'/>, 1146<xref linkend='XtCallbackNonexclusive' xrefstyle='select: title'/>, 1147<xref linkend='XtCallbackExclusive' xrefstyle='select: title'/>, 1148<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/> 1149 </para> 1150 </listitem> 1151</itemizedlist> 1152<para> 1153The return value of the following procedure will be of class 1154Core 1155or a subclass: 1156</para> 1157<itemizedlist spacing='compact'> 1158 <listitem> 1159 <para> 1160<xref linkend='XtWindowToWidget' xrefstyle='select: title'/> 1161 </para> 1162 </listitem> 1163</itemizedlist> 1164<para> 1165The return value of the following procedures will be of a subclass of 1166Shell: 1167</para> 1168<itemizedlist spacing='compact'> 1169 <listitem> 1170 <para> 1171<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>, 1172<xref linkend='XtVaAppCreateShell' xrefstyle='select: title'/>, 1173<xref linkend='XtAppInitialize' xrefstyle='select: title'/>, 1174<xref linkend='XtVaAppInitialize' xrefstyle='select: title'/>, 1175<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>, 1176<xref linkend='XtVaCreatePopupShell' xrefstyle='select: title'/> 1177 </para> 1178 </listitem> 1179</itemizedlist> 1180</sect1> 1181</chapter> 1182