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='Intrinsics_and_Widgets'> 5<title>Intrinsics and Widgets</title> 6<para> 7The Intrinsics are a programming library tailored to the special requirements 8of user interface construction within a network window system, 9specifically the X Window System. 10The Intrinsics and a widget set make up an X Toolkit. 11</para> 12<sect1 id="Intrinsics"> 13<title>Intrinsics</title> 14<para> 15The Intrinsics provide the base mechanism necessary to build 16a wide variety of interoperating widget sets and application environments. 17The Intrinsics are a layer on top of Xlib, the 18C Library X Interface. They extend the 19fundamental abstractions provided by the X Window System while still 20remaining independent of any particular user interface policy or 21style. 22</para> 23 24<para> 25The Intrinsics use object-oriented programming techniques to supply a 26consistent architecture for constructing and composing user interface 27components, known as widgets. This 28allows programmers to extend a widget set in new ways, either by 29deriving new widgets from existing ones (subclassing) or by writing 30entirely new widgets following the established conventions. 31</para> 32 33<para> 34When the Intrinsics were first conceived, the root of the object 35hierarchy was a widget class named 36Core. 37In Release 4 of the 38Intrinsics, three nonwidget superclasses were added above Core. 39These superclasses are described in <xref linkend='Nonwidget_Objects' />. 40The name of the class 41now at the root of the Intrinsics class hierarchy is 42Object. 43The remainder of this 44specification refers uniformly to <emphasis remap='I'>widgets</emphasis> and <emphasis remap='I'>Core</emphasis> 45as if they were the 46base class for all Intrinsics operations. The argument descriptions 47for each Intrinsics procedure and <xref linkend='Nonwidget_Objects' /> 48describe which operations 49are defined for the nonwidget superclasses of Core. The reader may 50determine by context whether a specific reference to <emphasis remap='I'>widget</emphasis> 51actually means “widget” or “object.” 52</para> 53</sect1> 54 55<sect1 id="Languages"> 56<title>Languages</title> 57<para> 58The Intrinsics are intended to be used for two programming purposes. 59Programmers writing widgets will be using most of the facilities 60provided by the 61Intrinsics to construct user interface components from the simple, such 62as buttons and scrollbars, to the complex, such as control panels and 63property sheets. Application programmers will use a much smaller subset of 64the Intrinsics procedures in combination with one or more sets of widgets to 65construct and present complete user interfaces on an X display. The 66Intrinsics 67programming interfaces primarily 68intended for application use are designed to be callable from most 69procedural programming languages. Therefore, most arguments are passed by 70reference rather than by value. The interfaces primarily 71intended for widget programmers are expected to be used principally 72from the C language. In these cases, the usual C programming 73conventions apply. In this specification, the term <emphasis remap='I'>client</emphasis> refers to 74any module, widget, or application that calls an Intrinsics procedure. 75</para> 76 77<para> 78Applications that use the Intrinsics mechanisms 79must include the header files 80<filename class="headerfile"><X11/Intrinsic.h></filename> 81and 82<filename class="headerfile"><X11/StringDefs.h></filename>, 83or their equivalent, 84and they may also include 85<filename class="headerfile"><X11/Xatoms.h></filename> 86and 87<filename class="headerfile"><X11/Shell.h></filename>. 88In addition, widget implementations should include 89<filename class="headerfile"><X11/IntrinsicP.h></filename> 90instead of 91<filename class="headerfile"><X11/Intrinsic.h></filename>. 92</para> 93 94<para> 95The applications must also include the additional header files for 96each widget class that they are to use (for example, 97<filename class="headerfile"><X11/Xaw/Label.h></filename> 98or 99<filename class="headerfile"><X11/Xaw/Scrollbar.h>).</filename> 100On a POSIX-based system, 101the Intrinsics object library file is named 102<filename class="libraryfile">libXt.a</filename> 103and is usually referenced as -lXt when linking the application. 104</para> 105</sect1> 106 107<sect1 id="Procedures_and_Macros"> 108<title>Procedures and Macros</title> 109<para> 110All functions defined in this specification except those specified below 111may be implemented as C macros with arguments. C applications may use 112“#undef” to remove a macro definition and ensure that the actual function 113is referenced. Any such macro will expand to a single expression that 114has the same precedence as a function call and that evaluates each 115of its arguments exactly once, fully protected by parentheses, so that 116arbitrary expressions may be used as arguments. 117</para> 118 119<para> 120The following symbols are macros that do not have function 121equivalents and that may expand their arguments in a manner other 122than that described above: 123<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>, 124<xref linkend='XtNew' xrefstyle='select: title'/>, 125<xref linkend='XtNumber' xrefstyle='select: title'/>, 126<xref linkend='XtOffsetOf' xrefstyle='select: title'/>, 127<xref linkend='XtOffset' xrefstyle='select: title'/>, 128and 129<xref linkend='XtSetArg' xrefstyle='select: title'/>. 130</para> 131</sect1> 132 133<sect1 id="Widgets"> 134<title>Widgets</title> 135<para> 136The fundamental abstraction and data type of the X Toolkit is the widget, 137which is a combination of an X window and its associated 138input and display semantics 139and which is dynamically allocated and contains state information. 140Some widgets display information (for example, text or graphics), 141and others are merely containers for other widgets (for example, a menu box). 142Some widgets are output-only and do not react to pointer or keyboard input, 143and others change their display in response to input 144and can invoke functions that an application has attached to them. 145</para> 146 147<para> 148Every widget belongs to exactly one widget class, which is statically 149allocated and initialized and which contains the operations allowable on 150widgets of that class. 151Logically, a widget class is the procedures and data associated 152with all widgets belonging to that class. 153These procedures and data can be inherited by 154subclasses. 155Physically, a widget class is a pointer to a structure. 156The contents of this structure are constant for all widgets of the widget 157class but will vary from class to class. 158(Here, “constant” means the class structure is initialized at compile time 159and never changed, except for a one-time class initialization 160and in-place compilation of resource lists, 161which takes place when the first widget of the class or subclass is created.) 162For further information, 163see <xref linkend='Creating_Widgets' /> 164</para> 165 166<para> 167The distribution of the declarations and code for a new widget class 168among a public .h file for application programmer use, a private .h file 169for widget programmer use, 170and the implementation .c file is described in <xref linkend='Widget_Classing' /> 171The predefined widget classes adhere to these conventions. 172</para> 173 174<para> 175A widget instance is composed of two parts: 176</para> 177<itemizedlist spacing='compact'> 178 <listitem> 179 <para> 180A data structure which contains instance-specific values. 181 </para> 182 </listitem> 183 <listitem> 184 <para> 185A class structure which contains information that is applicable to 186all widgets of that class. 187 </para> 188 </listitem> 189</itemizedlist> 190<para> 191Much of the input/output of a widget (for example, fonts, colors, sizes, 192or border widths) is customizable by users. 193</para> 194 195<para> 196This chapter discusses the base widget classes, 197Core, Composite, and Constraint, and 198ends with a discussion of widget classing. 199</para> 200<sect2 id="Core_Widgets"> 201<title>Core Widgets</title> 202<para> 203The 204Core 205widget class contains the definitions of fields common to all widgets. 206All widgets classes are subclasses of the 207Core class, 208which is defined by the 209<function>CoreClassPart</function> 210and 211<function>CorePart</function> 212structures. 213</para> 214<sect3 id="CoreClassPart_Structure"> 215<title>CoreClassPart Structure</title> 216<para> 217All widget classes contain the fields defined in the 218<function>CoreClassPart</function> 219structure. 220</para> 221<programlisting> 222typedef struct { 223 WidgetClass superclass; <lineannotation>See <xref linkend="Widget_Classing" xrefstyle='select: title' /></lineannotation> 224 String class_name; <lineannotation>See <xref linkend="Resource_Management" xrefstyle='select: title' /></lineannotation> 225 Cardinal widget_size; <lineannotation>See <xref linkend="Widget_Classing" xrefstyle='select: title' /></lineannotation> 226 XtProc class_initialize; <lineannotation>See <xref linkend="Widget_Classing" xrefstyle='select: title' /></lineannotation> 227 XtWidgetClassProc class_part_initialize; <lineannotation>See <xref linkend="Widget_Classing" xrefstyle='select: title' /></lineannotation> 228 XtEnum class_inited; <lineannotation>See <xref linkend="Widget_Classing" xrefstyle='select: title' /></lineannotation> 229 XtInitProc initialize; <lineannotation>See <xref linkend='Creating_Widgets' xrefstyle='select: title' /></lineannotation> 230 XtArgsProc initialize_hook; <lineannotation>See <xref linkend='Creating_Widgets' xrefstyle='select: title' /></lineannotation> 231 XtRealizeProc realize; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 232 XtActionList actions; <lineannotation>See <xref linkend='Translation_Management' xrefstyle='select: title' /></lineannotation> 233 Cardinal num_actions; <lineannotation>See <xref linkend='Translation_Management' xrefstyle='select: title' /></lineannotation> 234 XtResourceList resources; <lineannotation>See <xref linkend="Resource_Management" xrefstyle='select: title' /></lineannotation> 235 Cardinal num_resources; <lineannotation>See <xref linkend="Resource_Management" xrefstyle='select: title' /></lineannotation> 236 XrmClass xrm_class; <lineannotation>Private to resource manager</lineannotation> 237 Boolean compress_motion; <lineannotation>See <xref linkend='X_Event_Filters' xrefstyle='select: title' /></lineannotation> 238 XtEnum compress_exposure; <lineannotation>See <xref linkend='X_Event_Filters' xrefstyle='select: title' /></lineannotation> 239 Boolean compress_enterleave; <lineannotation>See <xref linkend='X_Event_Filters' xrefstyle='select: title' /></lineannotation> 240 Boolean visible_interest; <lineannotation>See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: title' /></lineannotation> 241 XtWidgetProc destroy; <lineannotation>See <xref linkend='Destroying_Widgets' xrefstyle='select: title' /></lineannotation> 242 XtWidgetProc resize; <lineannotation>See <xref linkend='Geometry_Management' xrefstyle='select: title' /></lineannotation> 243 XtExposeProc expose; <lineannotation>See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: title' /></lineannotation> 244 XtSetValuesFunc set_values; <lineannotation>See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: title' /></lineannotation> 245 XtArgsFunc set_values_hook; <lineannotation>See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: title' /></lineannotation> 246 XtAlmostProc set_values_almost; <lineannotation>See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: title' /></lineannotation> 247 XtArgsProc get_values_hook; <lineannotation>See <xref linkend='Reading_and_Writing_Widget_State' xrefstyle='select: title' /></lineannotation> 248 XtAcceptFocusProc accept_focus; <lineannotation>See <xref linkend='Focusing_Events_on_a_Child' xrefstyle='select: title' /></lineannotation> 249 XtVersionType version; <lineannotation>See <xref linkend="Widget_Classing" xrefstyle='select: title' /></lineannotation> 250 XtPointer callback_private; <lineannotation>Private to callbacks</lineannotation> 251 String tm_table; <lineannotation>See <xref linkend='Translation_Management' xrefstyle='select: title' /></lineannotation> 252 XtGeometryHandler query_geometry; <lineannotation>See <xref linkend ='Geometry_Management' xrefstyle='select: title' /></lineannotation> 253 XtStringProc display_accelerator; <lineannotation>See <xref linkend='Translation_Management' xrefstyle='select: title' /></lineannotation> 254 XtPointer extension; <lineannotation>See <xref linkend="Widget_Classing" xrefstyle='select: title' /></lineannotation> 255} CoreClassPart; 256</programlisting> 257<para> 258All widget classes have the Core class fields as their first component. 259The prototypical 260<function>WidgetClass</function> 261and 262<function>CoreWidgetClass</function> 263are defined with only this set of fields. 264</para> 265<programlisting> 266typedef struct { 267 CoreClassPart core_class; 268} WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass; 269</programlisting> 270<para> 271Various routines can cast widget class pointers, as needed, 272to specific widget class types. 273</para> 274 275<para> 276The single occurrences of the class record and pointer for 277creating instances of Core are 278</para> 279 280<para> 281In 282<filename class="headerfile">IntrinsicP.h</filename>: 283</para> 284<programlisting> 285extern WidgetClassRec widgetClassRec; 286#define coreClassRec widgetClassRec 287</programlisting> 288<para> 289In 290<filename class="headerfile">Intrinsic.h</filename>: 291</para> 292<programlisting> 293extern WidgetClass widgetClass, coreWidgetClass; 294</programlisting> 295<para> 296The opaque types 297<function>Widget</function> 298and 299<function>WidgetClass</function> 300and the opaque variable 301<function>widgetClass</function> 302are defined for generic actions on widgets. 303In order to make these types opaque and ensure that the compiler 304does not allow applications to access private data, the Intrinsics use 305incomplete structure definitions in 306<filename class="headerfile">Intrinsic.h</filename>: 307</para> 308<programlisting> 309typedef struct _WidgetClassRec *WidgetClass, *CoreWidgetClass; 310</programlisting> 311</sect3> 312<sect3 id="CorePart_Structure"> 313<title>CorePart Structure</title> 314<para> 315All widget instances contain the fields defined in the 316<function>CorePart</function> 317structure. 318</para> 319<programlisting> 320typedef struct _CorePart { 321 Widget self; <lineannotation>Described below</lineannotation> 322 WidgetClass widget_class; <lineannotation>See <xref linkend='Widget_Classing' xrefstyle='select: title' /></lineannotation> 323 Widget parent; <lineannotation>See <xref linkend='Creating_Widgets' xrefstyle='select: title' /></lineannotation> 324 Boolean being_destroyed; <lineannotation>See <xref linkend='Destroying_Widgets' xrefstyle='select: title' /></lineannotation> 325 XtCallbackList destroy_callbacks; <lineannotation>See <xref linkend='Destroying_Widgets' xrefstyle='select: title' /></lineannotation> 326 XtPointer constraints; <lineannotation>See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: title' /></lineannotation> 327 Position x; <lineannotation>See <xref linkend='Geometry_Management' xrefstyle='select: title' /></lineannotation> 328 Position y; <lineannotation>See <xref linkend='Geometry_Management' xrefstyle='select: title' /></lineannotation> 329 Dimension width; <lineannotation>See <xref linkend='Geometry_Management' xrefstyle='select: title' /></lineannotation> 330 Dimension height; <lineannotation>See <xref linkend='Geometry_Management' xrefstyle='select: title' /></lineannotation> 331 Dimension border_width; <lineannotation>See <xref linkend='Geometry_Management' xrefstyle='select: title' /></lineannotation> 332 Boolean managed; <lineannotation>See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: title' /></lineannotation> 333 Boolean sensitive; <lineannotation>See <xref linkend='Setting_and_Checking_the_Sensitivity_State_of_a_Widget' xrefstyle='select: title' /></lineannotation> 334 Boolean ancestor_sensitive; <lineannotation>See <xref linkend='Setting_and_Checking_the_Sensitivity_State_of_a_Widget' xrefstyle='select: title' /></lineannotation> 335 XtTranslations accelerators; <lineannotation>See <xref linkend='Translation_Management' xrefstyle='select: title' /></lineannotation> 336 Pixel border_pixel; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 337 Pixmap border_pixmap; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 338 WidgetList popup_list; <lineannotation>See <xref linkend='Pop_Up_Widgets' xrefstyle='select: title' /></lineannotation> 339 Cardinal num_popups; <lineannotation>See <xref linkend='Pop_Up_Widgets' xrefstyle='select: title' /></lineannotation> 340 String name; <lineannotation>See <xref linkend='Resource_Management' xrefstyle='select: title' /></lineannotation> 341 Screen *screen; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 342 Colormap colormap; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 343 Window window; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 344 Cardinal depth; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 345 Pixel background_pixel; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 346 Pixmap background_pixmap; <lineannotation>See <xref linkend='Realizing_Widgets' xrefstyle='select: title' /></lineannotation> 347 Boolean visible; <lineannotation>See <xref linkend='Widget_Exposure_and_Visibility' xrefstyle='select: title' /></lineannotation> 348 Boolean mapped_when_managed; <lineannotation>See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: title' /></lineannotation> 349} CorePart; 350</programlisting> 351<para> 352All widget instances have the Core fields as their first component. 353The prototypical type 354<function>Widget</function> 355is defined with only this set of fields. 356</para> 357<programlisting> 358typedef struct { 359 CorePart core; 360} WidgetRec, *Widget, CoreRec, *CoreWidget; 361</programlisting> 362<para> 363Various routines can cast widget pointers, as needed, 364to specific widget types. 365</para> 366 367<para> 368In order to make these types opaque and ensure that the compiler 369does not allow applications to access private data, the Intrinsics use 370incomplete structure definitions in 371<filename class="headerfile">Intrinsic.h</filename>. 372</para> 373<programlisting> 374typedef struct _WidgetRec *Widget, *CoreWidget; 375</programlisting> 376</sect3> 377<sect3 id="Core_Resources"> 378<title>Core Resources</title> 379<para> 380The resource names, classes, and representation types specified in the 381<function>coreClassRec</function> 382resource list are 383</para> 384 385<informaltable frame='topbot'> 386 <?dbfo keep-together="always" ?> 387 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 388 <colspec colname='c1' colwidth='1.0*'/> 389 <colspec colname='c2' colwidth='1.0*'/> 390 <colspec colname='c3' colwidth='1.0*'/> 391 <thead> 392 <row rowsep='1'> 393 <entry>Name</entry> 394 <entry>Class</entry> 395 <entry>Representation</entry> 396 </row> 397 </thead> 398 <tbody> 399 <row> 400 <entry>XtNaccelerators</entry> 401 <entry>XtCAccelerators</entry> 402 <entry>XtRAcceleratorTable</entry> 403 </row> 404 <row> 405 <entry>XtNbackground</entry> 406 <entry>XtCBackground</entry> 407 <entry>XtRPixel</entry> 408 </row> 409 <row> 410 <entry>XtNbackgroundPixmap</entry> 411 <entry>XtCPixmap</entry> 412 <entry>XtRPixmap</entry> 413 </row> 414 <row> 415 <entry>XtNborderColor</entry> 416 <entry>XtCBorderColor</entry> 417 <entry>XtRPixel</entry> 418 </row> 419 <row> 420 <entry>XtNborderPixmap</entry> 421 <entry>XtCPixmap</entry> 422 <entry>XtRPixmap</entry> 423 </row> 424 <row> 425 <entry>XtNcolormap</entry> 426 <entry>XtCColormap</entry> 427 <entry>XtRColormap</entry> 428 </row> 429 <row> 430 <entry>XtNdepth</entry> 431 <entry>XtCDepth</entry> 432 <entry>XtRInt</entry> 433 </row> 434 <row> 435 <entry>XtNmappedWhenManaged</entry> 436 <entry>XtCMappedWhenManaged</entry> 437 <entry>XtRBoolean</entry> 438 </row> 439 <row> 440 <entry>XtNscreen</entry> 441 <entry>XtCScreen</entry> 442 <entry>XtRScreen</entry> 443 </row> 444 <row> 445 <entry>XtNtranslations</entry> 446 <entry>XtCTranslations</entry> 447 <entry>XtRTranslationTable</entry> 448 </row> 449 </tbody> 450 </tgroup> 451</informaltable> 452<para> 453Additional resources are defined for all widgets via the 454<function>objectClassRec</function> 455and 456<function>rectObjClassRec</function> 457resource lists; see <xref linkend='Object_Objects' /> and <xref linkend='Rectangle_Objects' /> for details. 458</para> 459</sect3> 460<sect3 id="CorePart_Default_Values"> 461<title>CorePart Default Values</title> 462<para> 463The default values for the Core fields, which are filled in by the Intrinsics, 464from the resource lists, and by the initialize procedures, are 465</para> 466<informaltable frame='topbot'> 467 <?dbfo keep-together="always" ?> 468 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 469 <colspec colname='c1' colwidth='0.4*'/> 470 <colspec colname='c2' colwidth='1.0*'/> 471 <thead> 472 <row rowsep='1'> 473 <entry>Field</entry> 474 <entry>Default Value</entry> 475 </row> 476 </thead> 477 <tbody> 478 <row> 479 <entry>self</entry> 480 <entry>Address of the widget structure (may not be changed).</entry> 481 </row> 482 <row> 483 <entry>widget_class</entry> 484 <entry><emphasis remap='I'>widget_class</emphasis> argument to 485 <xref linkend='XtCreateWidget' xrefstyle='select: title'/> 486 (may not be changed).</entry> 487 </row> 488 <row> 489 <entry>parent</entry> 490 <entry><emphasis remap='I'>parent</emphasis> argument to 491 <xref linkend='XtCreateWidget' xrefstyle='select: title'/> 492 (may not be changed).</entry> 493 </row> 494 <row> 495 <entry>being_destroyed</entry> 496 <entry>Parent's <emphasis remap='I'>being_destroyed</emphasis> value.</entry> 497 </row> 498 <row> 499 <entry>destroy_callbacks</entry> 500 <entry>NULL</entry> 501 </row> 502 <row> 503 <entry>constraints</entry> 504 <entry>NULL</entry> 505 </row> 506 <row> 507 <entry>x</entry> 508 <entry>0</entry> 509 </row> 510 <row> 511 <entry>y</entry> 512 <entry>0</entry> 513 </row> 514 <row> 515 <entry>width</entry> 516 <entry>0</entry> 517 </row> 518 <row> 519 <entry>height</entry> 520 <entry>0</entry> 521 </row> 522 <row> 523 <entry>border_width</entry> 524 <entry>1</entry> 525 </row> 526 <row> 527 <entry>managed</entry> 528 <entry><function>False</function></entry> 529 </row> 530 <row> 531 <entry>sensitive</entry> 532 <entry><function>True</function></entry> 533 </row> 534 <row> 535 <entry>ancestor_sensitive</entry> 536 <entry>logical AND of parent's <emphasis remap='I'>sensitive</emphasis> and 537 <emphasis remap='I'>ancestor_sensitive</emphasis> values.</entry> 538 </row> 539 <row> 540 <entry>accelerators</entry> 541 <entry>NULL</entry> 542 </row> 543 <row> 544 <entry>border_pixel</entry> 545 <entry><function>XtDefaultForeground</function></entry> 546 </row> 547 <row> 548 <entry>border_pixmap</entry> 549 <entry><function>XtUnspecifiedPixmap</function></entry> 550 </row> 551 <row> 552 <entry>popup_list</entry> 553 <entry>NULL</entry> 554 </row> 555 <row> 556 <entry>num_popups</entry> 557 <entry>0</entry> 558 </row> 559 <row> 560 <entry>name</entry> 561 <entry><emphasis remap='I'>name</emphasis> argument to 562 <xref linkend='XtCreateWidget' xrefstyle='select: title'/> 563 (may not be changed).</entry> 564 </row> 565 <row> 566 <entry>screen</entry> 567 <entry>Parent's <emphasis remap='I'>screen</emphasis>; top-level widget gets screen from display specifier 568 (may not be changed).</entry> 569 </row> 570 <row> 571 <entry>colormap</entry> 572 <entry>Parent's <emphasis remap='I'>colormap</emphasis> value.</entry> 573 </row> 574 <row> 575 <entry>window</entry> 576 <entry>NULL</entry> 577 </row> 578 <row> 579 <entry>depth</entry> 580 <entry>Parent's <emphasis remap='I'>depth</emphasis>; top-level widget gets root window depth.</entry> 581 </row> 582 <row> 583 <entry>background_pixel</entry> 584 <entry><function>XtDefaultBackground</function></entry> 585 </row> 586 <row> 587 <entry>background_pixmap</entry> 588 <entry><function>XtUnspecifiedPixmap</function></entry> 589 </row> 590 <row> 591 <entry>visible</entry> 592 <entry><function>True</function></entry> 593 </row> 594 <row> 595 <entry>mapped_when_managed</entry> 596 <entry><function>True</function></entry> 597 </row> 598 </tbody> 599 </tgroup> 600</informaltable> 601<para> 602<function>XtUnspecifiedPixmap</function> 603is a symbolic constant guaranteed to be unequal to 604any valid Pixmap id, 605<function>None</function>, 606and 607<function>ParentRelative</function>. 608</para> 609</sect3> 610</sect2> 611 612<sect2 id="Composite_Widgets"> 613<title>Composite Widgets</title> 614<para> 615The Composite 616widget class is a subclass of the 617Core 618widget class (see <xref linkend='Composite_Widgets_and_Their_Children' />). 619Composite widgets are intended to be containers for other widgets. 620The additional data used by composite widgets are defined by the 621<function>CompositeClassPart</function> 622and 623<function>CompositePart</function> 624structures. 625</para> 626<sect3 id="CompositeClassPart_Structure"> 627<title>CompositeClassPart Structure</title> 628<para> 629In addition to the 630Core 631class fields, 632widgets of the Composite class have the following class fields. 633</para> 634<programlisting> 635typedef struct { 636 XtGeometryHandler geometry_manager; <lineannotation>See <xref linkend='Geometry_Management' xrefstyle='select: title' /></lineannotation> 637 XtWidgetProc change_managed; <lineannotation>See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: title' /></lineannotation> 638 XtWidgetProc insert_child; <lineannotation>See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: title' /></lineannotation> 639 XtWidgetProc delete_child; <lineannotation>See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: title' /></lineannotation> 640 XtPointer extension; <lineannotation>See <xref linkend='Widget_Classing' xrefstyle='select: title' /></lineannotation> 641} CompositeClassPart; 642</programlisting> 643<para> 644The extension record defined for 645<function>CompositeClassPart</function> 646with <emphasis remap='I'>record_type</emphasis> 647equal to 648<emphasis role='strong'>NULLQUARK</emphasis> 649is 650<function>CompositeClassExtensionRec</function>. 651</para> 652<programlisting> 653typedef struct { 654 XtPointer next_extension; <lineannotation>See <xref linkend='Class_Extension_Records' xrefstyle='select: title' /></lineannotation> 655 XrmQuark record_type; <lineannotation>See <xref linkend='Class_Extension_Records' xrefstyle='select: title' /></lineannotation> 656 long version; <lineannotation>See <xref linkend='Class_Extension_Records' xrefstyle='select: title' /></lineannotation> 657 Cardinal record_size; <lineannotation>See <xref linkend='Class_Extension_Records' xrefstyle='select: title' /></lineannotation> 658 Boolean accepts_objects; <lineannotation>See <xref linkend='Creating_a_Widget_Instance' xrefstyle='select: title' /></lineannotation> 659 Boolean allows_change_managed_set; <lineannotation>See <xref linkend='Bundling_Changes_to_the_Managed_Set' xrefstyle='select: title' /></lineannotation> 660} CompositeClassExtensionRec, *CompositeClassExtension; 661</programlisting> 662<para> 663Composite 664classes have the Composite class fields immediately following the 665Core class fields. 666</para> 667<programlisting> 668typedef struct { 669 CoreClassPart core_class; 670 CompositeClassPart composite_class; 671} CompositeClassRec, *CompositeWidgetClass; 672</programlisting> 673<para> 674The single occurrences of the class record and pointer for creating 675instances of Composite are 676</para> 677 678<para> 679In 680<filename class="headerfile">IntrinsicP.h</filename>: 681</para> 682<programlisting> 683extern CompositeClassRec compositeClassRec; 684</programlisting> 685<para> 686In 687<filename class="headerfile">Intrinsic.h</filename>: 688</para> 689<programlisting> 690extern WidgetClass compositeWidgetClass; 691</programlisting> 692<para> 693The opaque types 694<function>CompositeWidget</function> 695and 696<function>CompositeWidgetClass</function> 697and the opaque variable 698<function>compositeWidgetClass</function> 699are defined for generic operations on widgets whose class 700is Composite or a subclass of Composite. 701The symbolic constant for the 702<function>CompositeClassExtension</function> 703version identifier is 704<function>XtCompositeExtensionVersion</function> 705(see <xref linkend='Class_Extension_Records' />). 706<filename class="headerfile">Intrinsic.h</filename> 707uses an incomplete structure 708definition to ensure that the compiler catches attempts to access 709private data. 710</para> 711<programlisting> 712typedef struct _CompositeClassRec *CompositeWidgetClass; 713</programlisting> 714</sect3> 715<sect3 id="CompositePart_Structure"> 716<title>CompositePart Structure</title> 717<para> 718In addition to the 719Core instance 720fields, 721widgets of the Composite class have the following 722instance fields defined in the 723<function>CompositePart</function> 724structure. 725</para> 726<programlisting> 727typedef struct { 728 WidgetList children; <lineannotation>See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: title' /></lineannotation> 729 Cardinal num_children; <lineannotation>See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: title' /></lineannotation> 730 Cardinal num_slots; <lineannotation>See <xref linkend='Composite_Widgets_and_Their_Children' xrefstyle='select: title' /></lineannotation> 731 XtOrderProc insert_position; <lineannotation>See <xref linkend='Insertion_Order_of_Children_The_insert_position_Procedure' xrefstyle='select: title' /></lineannotation> 732} CompositePart; 733</programlisting> 734<para> 735Composite 736widgets have the Composite instance fields immediately following the Core 737instance fields. 738</para> 739<programlisting> 740typedef struct { 741 CorePart core; 742 CompositePart composite; 743} CompositeRec, *CompositeWidget; 744</programlisting> 745<para> 746<filename class="headerfile">Intrinsic.h</filename> 747uses an incomplete structure definition to ensure that the 748compiler catches attempts to access private data. 749</para> 750<programlisting> 751typedef struct _CompositeRec *CompositeWidget; 752</programlisting> 753</sect3> 754<sect3 id="Composite_Resources"> 755<title>Composite Resources</title> 756<para> 757The resource names, classes, and representation types 758that are specified in 759the 760<function>compositeClassRec</function> 761resource list are 762</para> 763 764<informaltable frame='topbot'> 765 <?dbfo keep-together="always" ?> 766 <tgroup cols='3' align='left' colsep='0' rowsep='0'> 767 <colspec colname='c1' colwidth='1.0*'/> 768 <colspec colname='c2' colwidth='1.0*'/> 769 <colspec colname='c3' colwidth='1.0*'/> 770 <thead> 771 <row rowsep='1'> 772 <entry>Name</entry> 773 <entry>Class</entry> 774 <entry>Representation</entry> 775 </row> 776 </thead> 777 <tbody> 778 <row> 779 <entry>XtNchildren</entry> 780 <entry>XtCReadOnly</entry> 781 <entry>XtRWidgetList</entry> 782 </row> 783 <row> 784 <entry>XtNinsertPosition</entry> 785 <entry>XtCInsertPosition</entry> 786 <entry>XtRFunction</entry> 787 </row> 788 <row> 789 <entry>XtNnumChildren</entry> 790 <entry>XtCReadOnly</entry> 791 <entry>XtRCardinal</entry> 792 </row> 793 </tbody> 794 </tgroup> 795</informaltable> 796 797</sect3> 798<sect3 id="CompositePart_Default_Values"> 799<title>CompositePart Default Values</title> 800<para> 801The default values for the Composite fields, 802which are filled in from the 803Composite 804resource list and by the 805Composite 806initialize procedure, are 807</para> 808 809<informaltable frame='topbot'> 810 <?dbfo keep-together="always" ?> 811 <?dbfo table-width="50%" ?> 812 <tgroup cols='2' align='left' colsep='0' rowsep='0'> 813 <colspec colname='c1' colwidth='1.0*' colsep='0'/> 814 <colspec colname='c2' colwidth='1.0*' colsep='0'/> 815 <thead> 816 <row rowsep='1'> 817 <entry>Field</entry> 818 <entry>Default Value</entry> 819 </row> 820 </thead> 821 <tbody> 822 <row> 823 <entry>children</entry><entry>NULL</entry> 824 </row> 825 <row> 826 <entry>num_children</entry><entry>0</entry> 827 </row> 828 <row> 829 <entry>num_slots</entry><entry>0</entry> 830 </row> 831 <row> 832 <entry>insert_position</entry><entry>Internal function to insert at end</entry> 833 </row> 834 </tbody> 835 </tgroup> 836</informaltable> 837 838<para> 839The <emphasis remap='I'>children</emphasis>, <emphasis remap='I'>num_children</emphasis>, 840and <emphasis remap='I'>insert_position</emphasis> fields are declared 841as resources; 842XtNinsertPosition 843is a settable resource, 844XtNchildren 845and 846XtNnumChildren 847may be read by any client but should only be modified by the composite 848widget class procedures. 849</para> 850</sect3> 851</sect2> 852 853<sect2 id="Constraint_Widgets"> 854<title>Constraint Widgets</title> 855<para> 856The Constraint 857widget class is a subclass of the 858Composite 859widget class (see <xref linkend='Constrained_Composite_Widgets' />). Constraint 860widgets maintain additional state 861data for each child; for example, client-defined constraints on the child's 862geometry. 863The additional data used by constraint widgets are defined by the 864<function>ConstraintClassPart</function> 865and 866<function>ConstraintPart</function> 867structures. 868</para> 869<sect3 id="ConstraintClassPart_Structure"> 870<title>ConstraintClassPart Structure</title> 871<para> 872In addition to the 873Core 874and 875Composite 876class fields, 877widgets of the Constraint class 878have the following class fields. 879</para> 880<programlisting> 881typedef struct { 882 XtResourceList resources; <lineannotation>See <xref linkend='Resource_Management' xrefstyle='select: title' /></lineannotation> 883 Cardinal num_resources; <lineannotation>See <xref linkend='Resource_Management' xrefstyle='select: title' /></lineannotation> 884 Cardinal constraint_size; <lineannotation>See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: title' /></lineannotation> 885 XtInitProc initialize; <lineannotation>See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: title' /></lineannotation> 886 XtWidgetProc destroy; <lineannotation>See <xref linkend='Constrained_Composite_Widgets' xrefstyle='select: title' /></lineannotation> 887 XtSetValuesFunc set_values; <lineannotation>See <xref linkend='Setting_Widget_State' xrefstyle='select: title' /></lineannotation> 888 XtPointer extension; <lineannotation>See <xref linkend='Widget_Classing' xrefstyle='select: title' /></lineannotation> 889} ConstraintClassPart; 890</programlisting> 891<para> 892The extension record defined for 893<function>ConstraintClassPart</function> 894with <emphasis remap='I'>record_type</emphasis> equal to 895<emphasis role='strong'>NULLQUARK</emphasis> 896is 897<function>ConstraintClassExtensionRec</function>. 898</para> 899<programlisting> 900typedef struct { 901 XtPointer next_extension; <lineannotation>See <xref linkend='Class_Extension_Records' xrefstyle='select: title' /></lineannotation> 902 XrmQuark record_type; <lineannotation>See <xref linkend='Class_Extension_Records' xrefstyle='select: title' /></lineannotation> 903 long version; <lineannotation>See <xref linkend='Class_Extension_Records' xrefstyle='select: title' /></lineannotation> 904 Cardinal record_size; <lineannotation>See <xref linkend='Class_Extension_Records' xrefstyle='select: title' /></lineannotation> 905 XtArgsProc get_values_hook; <lineannotation>See <xref linkend='Obtaining_Widget_State' xrefstyle='select: title' /></lineannotation> 906} ConstraintClassExtensionRec, *ConstraintClassExtension; 907</programlisting> 908<para> 909Constraint 910classes have the Constraint class fields immediately following the 911Composite class fields. 912</para> 913<programlisting> 914typedef struct _ConstraintClassRec { 915 CoreClassPart core_class; 916 CompositeClassPart composite_class; 917 ConstraintClassPart constraint_class; 918} ConstraintClassRec, *ConstraintWidgetClass; 919</programlisting> 920<para> 921The single occurrences of the class record and pointer for creating 922instances of Constraint are 923</para> 924 925<para> 926In 927<filename class="headerfile">IntrinsicP.h</filename>: 928</para> 929<programlisting> 930extern ConstraintClassRec constraintClassRec; 931</programlisting> 932<para> 933In 934<filename class="headerfile">Intrinsic.h</filename>: 935</para> 936<programlisting> 937extern WidgetClass constraintWidgetClass; 938</programlisting> 939<para> 940The opaque types 941<function>ConstraintWidget</function> 942and 943<function>ConstraintWidgetClass</function> 944and the opaque variable 945<function>constraintWidgetClass</function> 946are defined for generic operations on widgets 947whose class is Constraint or a subclass 948of Constraint. 949The symbolic constant for the 950<function>ConstraintClassExtension</function> 951version identifier is 952<function>XtConstraintExtensionVersion</function> 953(see <xref linkend='Class_Extension_Records' />). 954<filename class="headerfile">Intrinsic.h</filename> 955uses an incomplete structure definition to ensure that the 956compiler catches attempts to access private data. 957</para> 958<programlisting> 959typedef struct _ConstraintClassRec *ConstraintWidgetClass; 960</programlisting> 961</sect3> 962<sect3 id="ConstraintPart_Structure"> 963<title>ConstraintPart Structure</title> 964<para> 965In addition to the 966Core 967and 968Composite instance 969fields, 970widgets of the Constraint class have the following unused 971instance fields defined in the 972<function>ConstraintPart</function> 973structure 974</para> 975<programlisting> 976typedef struct { 977 int empty; 978} ConstraintPart; 979</programlisting> 980<para> 981Constraint 982widgets have the Constraint instance fields immediately following the 983Composite instance fields. 984</para> 985<programlisting> 986typedef struct { 987 CorePart core; 988 CompositePart composite; 989 ConstraintPart constraint; 990} ConstraintRec, *ConstraintWidget; 991</programlisting> 992<para> 993<filename class="headerfile">Intrinsic.h</filename> 994uses an incomplete structure definition to ensure that the 995compiler catches attempts to access private data. 996</para> 997<programlisting> 998typedef struct _ConstraintRec *ConstraintWidget; 999</programlisting> 1000</sect3> 1001<sect3 id="Constraint_Resources"> 1002<title>Constraint Resources</title> 1003<para> 1004The 1005<function>constraintClassRec</function> 1006<emphasis remap='I'>core_class</emphasis> and <emphasis remap='I'>constraint_class resources</emphasis> fields are NULL, 1007and the <emphasis remap='I'>num_resources</emphasis> fields are zero; 1008no additional resources beyond those declared by 1009the superclasses 1010are defined for 1011Constraint. 1012</para> 1013</sect3> 1014</sect2> 1015</sect1> 1016 1017<sect1 id="Implementation_Specific_Types"> 1018<title>Implementation-Specific Types</title> 1019<para> 1020To increase the portability of widget and application source code 1021between different system environments, the Intrinsics define several 1022types whose precise representation is explicitly dependent upon, 1023and chosen by, each individual implementation of the Intrinsics. 1024</para> 1025 1026<para> 1027These implementation-defined types are 1028</para> 1029<variablelist> 1030 <varlistentry> 1031 <term> 1032 <emphasis role='strong'>Boolean</emphasis> 1033 </term> 1034 <listitem> 1035 <para> 1036A datum that contains a zero or nonzero value. 1037Unless explicitly stated, clients should not assume 1038that the nonzero value is equal to the symbolic 1039value 1040<function>True</function>. 1041 </para> 1042 </listitem> 1043 </varlistentry> 1044 1045 <varlistentry> 1046 <term> 1047 <emphasis role='strong'>Cardinal</emphasis> 1048 </term> 1049 <listitem> 1050 <para> 1051An unsigned integer datum with a minimum range of [0..2<superscript>16</superscript>-1]. 1052 </para> 1053 </listitem> 1054 </varlistentry> 1055 1056 <varlistentry> 1057 <term> 1058 <emphasis role='strong'>Dimension</emphasis> 1059 </term> 1060 <listitem> 1061 <para> 1062An unsigned integer datum with a minimum range of [0..2<superscript>16</superscript>-1]. 1063 </para> 1064 </listitem> 1065 </varlistentry> 1066 1067 <varlistentry> 1068 <term> 1069 <emphasis role='strong'>Position</emphasis> 1070 </term> 1071 <listitem> 1072 <para> 1073A signed integer datum with a minimum range of [-2<superscript>15</superscript>..2<superscript>15</superscript>-1]. 1074 </para> 1075 </listitem> 1076 </varlistentry> 1077 1078 <varlistentry> 1079 <term> 1080 <emphasis role='strong'>XtPointer</emphasis> 1081 </term> 1082 <listitem> 1083 <para> 1084A datum large enough to contain the largest of a char*, int*, function 1085pointer, structure pointer, or long value. A pointer 1086to any type or function, or a long value may be converted 1087to an 1088<function>XtPointer</function> 1089and back again and the result will 1090compare equal to the original value. In ANSI C 1091environments it is expected that 1092<function>XtPointer</function> 1093will be 1094defined as void*. 1095 </para> 1096 </listitem> 1097 </varlistentry> 1098 1099 <varlistentry> 1100 <term> 1101 <emphasis role='strong'>XtArgVal</emphasis> 1102 </term> 1103 <listitem> 1104 <para> 1105A datum large enough to contain an 1106<function>XtPointer</function>, 1107<function>Cardinal</function>, 1108<function>Dimension</function>, 1109or 1110<function>Position</function> 1111value. 1112 </para> 1113 </listitem> 1114 </varlistentry> 1115 1116 <varlistentry> 1117 <term> 1118 <emphasis role='strong'>XtEnum</emphasis> 1119 </term> 1120 <listitem> 1121 <para> 1122An integer datum large enough to encode at least 128 distinct 1123values, two of which are the symbolic values 1124<function>True</function> 1125and 1126<function>False</function>. 1127The symbolic values 1128<emphasis role='strong'>TRUE</emphasis> 1129and 1130<emphasis role='strong'>FALSE</emphasis> 1131are 1132also defined to be equal to 1133<function>True</function> 1134and 1135<function>False</function>, 1136respectively. 1137 </para> 1138 </listitem> 1139 </varlistentry> 1140</variablelist> 1141 1142<para> 1143In addition to these specific types, the precise order of the 1144fields within the structure declarations for any of the instance 1145part records 1146<function>ObjectPart</function>, 1147<function>RectObjPart</function>, 1148<function>CorePart</function>, 1149<function>CompositePart</function>, 1150<function>ShellPart</function>, 1151<function>WMShellPart</function>, 1152<function>TopLevelShellPart</function>, 1153and 1154<function>ApplicationShellPart</function> 1155is implementation-defined. These 1156structures may also have additional private 1157fields internal to the implementation. 1158The 1159<function>ObjectPart</function>, 1160<function>RectObjPart</function>, 1161and 1162<function>CorePart</function> 1163structures must be defined so that any member with the same name 1164appears at the same offset in 1165<function>ObjectRec</function>, 1166<function>RectObjRec</function>, 1167and 1168<function>CoreRec</function> 1169<function>( WidgetRec ).</function> 1170No other relations between the offsets of any two 1171fields may be assumed. 1172</para> 1173</sect1> 1174 1175<sect1 id="Widget_Classing"> 1176<title>Widget Classing</title> 1177<para> 1178The <emphasis remap='I'>widget_class</emphasis> field of a widget points to its widget class structure, 1179which contains information that is constant across all widgets of that class. 1180As a consequence, 1181widgets usually do not implement directly callable procedures; 1182rather, they implement procedures, called methods, that are available through 1183their widget class structure. 1184These methods are invoked by generic procedures that envelop common actions 1185around the methods implemented by the widget class. 1186Such procedures are applicable to all widgets 1187of that class and also to widgets whose classes are subclasses of that class. 1188</para> 1189 1190<para> 1191All widget classes are a subclass of 1192Core 1193and can be subclassed further. 1194Subclassing reduces the amount of code and declarations 1195necessary to make a 1196new widget class that is similar to an existing class. 1197For example, you do not have to describe every resource your widget uses in an 1198<function>XtResourceList</function>. 1199Instead, you describe only the resources your widget has 1200that its superclass does not. 1201Subclasses usually inherit many of their superclasses' procedures 1202(for example, the expose procedure or geometry handler). 1203</para> 1204 1205<para> 1206Subclassing, however, can be taken too far. 1207If you create a subclass that inherits none of the procedures of its 1208superclass, 1209you should consider whether you have chosen the most 1210appropriate superclass. 1211</para> 1212 1213<para> 1214To make good use of subclassing, 1215widget declarations and naming conventions are highly stylized. 1216A widget consists of three files: 1217</para> 1218<itemizedlist spacing='compact'> 1219 <listitem> 1220 <para> 1221A public .h file, used by client widgets or applications. 1222 </para> 1223 </listitem> 1224 <listitem> 1225 <para> 1226A private .h file, used by widgets whose classes 1227are subclasses of the widget class. 1228 </para> 1229 </listitem> 1230 <listitem> 1231 <para> 1232A .c file, which implements the widget. 1233 </para> 1234 </listitem> 1235</itemizedlist> 1236<sect2 id="Widget_Naming_Conventions"> 1237<title>Widget Naming Conventions</title> 1238<para> 1239The Intrinsics provide a vehicle by which programmers can create 1240new widgets and organize a collection of widgets into an application. 1241To ensure that applications need not deal with as many styles of capitalization 1242and spelling as the number of widget classes it uses, 1243the following guidelines should be followed when writing new widgets: 1244</para> 1245<itemizedlist spacing='compact'> 1246 <listitem> 1247 <para> 1248Use the X library naming conventions that are applicable. 1249For example, a record component name is all lowercase 1250and uses underscores (_) for compound words (for example, background_pixmap). 1251Type and procedure names start with uppercase and use capitalization for 1252compound words (for example, 1253<function>ArgList</function> 1254or 1255<function>XtSetValues ).</function> 1256 </para> 1257 </listitem> 1258 <listitem> 1259 <para> 1260A resource name is spelled identically to the field name 1261except that compound names use capitalization rather than underscore. 1262To let the compiler catch spelling errors, 1263each resource name should have a symbolic identifier prefixed with 1264“XtN”. 1265For example, 1266the <emphasis remap='I'>background_pixmap</emphasis> field has the corresponding identifier 1267XtNbackgroundPixmap, 1268which is defined as the string “backgroundPixmap”. 1269Many predefined names are listed in 1270<filename class="headerfile"><X11/StringDefs.h></filename>. 1271Before you invent a new name, 1272you should make sure there is not already a name that you can use. 1273 </para> 1274 </listitem> 1275 <listitem> 1276 <para> 1277A resource class string starts with a capital letter 1278and uses capitalization for compound names (for example,“BorderWidth”). 1279Each resource class string should have a symbolic identifier prefixed with 1280“XtC” 1281(for example, XtCBorderWidth). 1282Many predefined classes are listed in 1283<filename class="headerfile"><X11/StringDefs.h></filename>. 1284 </para> 1285 </listitem> 1286 <listitem> 1287 <para> 1288A resource representation string is spelled identically to the type name 1289(for example, “TranslationTable”). 1290Each representation string should have a symbolic identifier prefixed with 1291“XtR” 1292(for example, XtRTranslationTable). 1293Many predefined representation types are listed in 1294<filename class="headerfile"><X11/StringDefs.h></filename>. 1295 </para> 1296 </listitem> 1297 <listitem> 1298 <para> 1299New widget classes start with a capital and use uppercase for compound 1300words. 1301Given a new class name AbcXyz, you should derive several names: 1302 </para> 1303 <itemizedlist spacing='compact'> 1304 <listitem> 1305 <para> 1306Additional widget instance structure part name AbcXyzPart. 1307 </para> 1308 </listitem> 1309 <listitem> 1310 <para> 1311Complete widget instance structure names AbcXyzRec and _AbcXyzRec. 1312 </para> 1313 </listitem> 1314 <listitem> 1315 <para> 1316Widget instance structure pointer type name AbcXyzWidget. 1317 </para> 1318 </listitem> 1319 <listitem> 1320 <para> 1321Additional class structure part name AbcXyzClassPart. 1322 </para> 1323 </listitem> 1324 <listitem> 1325 <para> 1326Complete class structure names AbcXyzClassRec and _AbcXyzClassRec. 1327 </para> 1328 </listitem> 1329 <listitem> 1330 <para> 1331Class structure pointer type name AbcXyzWidgetClass. 1332 </para> 1333 </listitem> 1334 <listitem> 1335 <para> 1336Class structure variable abcXyzClassRec. 1337 </para> 1338 </listitem> 1339 <listitem> 1340 <para> 1341Class structure pointer variable abcXyzWidgetClass. 1342 </para> 1343 </listitem> 1344 </itemizedlist> 1345 </listitem> 1346 <listitem> 1347 <para> 1348Action procedures available to translation specifications should follow the 1349same naming conventions as procedures. 1350That is, 1351they start with a capital letter, and compound names use uppercase 1352(for example, “Highlight” and “NotifyClient”). 1353 </para> 1354 </listitem> 1355</itemizedlist> 1356<para> 1357The symbolic identifiers XtN..., XtC..., and XtR... 1358may be implemented 1359as macros, as global symbols, or as a mixture of the two. The 1360(implicit) type of the identifier is 1361<function>String</function>. 1362The pointer value itself 1363is not significant; clients must not assume that inequality of two 1364identifiers implies inequality of the resource name, class, or 1365representation string. Clients should also note that although global 1366symbols permit savings in literal storage in some environments, they 1367also introduce the possibility of multiple definition conflicts when 1368applications attempt to use independently developed widgets 1369simultaneously. 1370</para> 1371</sect2> 1372 1373<sect2 id="Widget_Subclassing_in_Public_h_Files"> 1374<title>Widget Subclassing in Public .h Files</title> 1375<para> 1376The public .h file for a widget class is imported by clients 1377and contains 1378</para> 1379<itemizedlist spacing='compact'> 1380 <listitem> 1381 <para> 1382A reference to the public .h file for the superclass. 1383 </para> 1384 </listitem> 1385 <listitem> 1386 <para> 1387Symbolic identifiers for 1388the names and classes of the new resources that this widget adds 1389to its superclass. 1390The definitions should 1391have a single space between the definition name and the value and no 1392trailing space or comment in order to reduce the possibility of 1393compiler warnings from similar declarations in multiple classes. 1394 </para> 1395 </listitem> 1396 <listitem> 1397 <para> 1398Type declarations for any new resource data types defined by the class. 1399 </para> 1400 </listitem> 1401 <listitem> 1402 <para> 1403The class record pointer variable used to create widget instances. 1404 </para> 1405 </listitem> 1406 <listitem> 1407 <para> 1408The C type that corresponds to widget instances of this class. 1409 </para> 1410 </listitem> 1411 <listitem> 1412 <para> 1413Entry points for new class methods. 1414 </para> 1415 </listitem> 1416</itemizedlist> 1417<para> 1418For example, the following is the public .h file for a possible 1419implementation of a Label widget: 1420</para> 1421<programlisting> 1422#ifndef LABEL_H 1423#define LABEL_H 1424 1425/* New resources */ 1426#define XtNjustify "justify" 1427#define XtNforeground "foreground" 1428#define XtNlabel "label" 1429#define XtNfont "font" 1430#define XtNinternalWidth "internalWidth" 1431#define XtNinternalHeight "internalHeight" 1432 1433/* Class record pointer */ 1434extern WidgetClass labelWidgetClass; 1435 1436/* C Widget type definition */ 1437typedef struct _LabelRec *LabelWidget; 1438 1439/* New class method entry points */ 1440extern void LabelSetText(Widget w, String text); 1441extern String LabelGetText(Widget w); 1442 1443#endif LABEL_H 1444</programlisting> 1445<para> 1446The conditional inclusion of the text allows the application 1447to include header files for different widgets without being concerned 1448that they already may be included as a superclass of another widget. 1449</para> 1450 1451<para> 1452To accommodate operating systems with file name length restrictions, 1453the name of the public .h file is the first ten characters of the 1454widget class. 1455For example, 1456the public .h file for the 1457Constraint 1458widget class is 1459<filename class="headerfile">Constraint.h</filename>. 1460</para> 1461</sect2> 1462 1463<sect2 id="Widget_Subclassing_in_Private_h_Files"> 1464<title>Widget Subclassing in Private .h Files</title> 1465<para> 1466The private .h file for a widget is imported by widget classes that are 1467subclasses of the widget and contains 1468</para> 1469<itemizedlist spacing='compact'> 1470 <listitem> 1471 <para> 1472A reference to the public .h file for the class. 1473 </para> 1474 </listitem> 1475 <listitem> 1476 <para> 1477A reference to the private .h file for the superclass. 1478 </para> 1479 </listitem> 1480 <listitem> 1481 <para> 1482Symbolic identifiers for any new resource representation types defined 1483by the class. The definitions should have a single space between the 1484definition name and the value and no trailing space or comment. 1485 </para> 1486 </listitem> 1487 <listitem> 1488 <para> 1489A structure part definition for 1490the new fields that the widget instance adds to its superclass's 1491widget structure. 1492 </para> 1493 </listitem> 1494 <listitem> 1495 <para> 1496The complete widget instance structure definition for this widget. 1497 </para> 1498 </listitem> 1499 <listitem> 1500 <para> 1501A structure part definition for 1502the new fields that this widget class adds to its superclass's 1503constraint 1504structure if the widget class is a subclass of 1505Constraint. 1506 </para> 1507 </listitem> 1508 <listitem> 1509 <para> 1510The complete 1511constraint 1512structure definition if the widget class is a subclass of 1513Constraint. 1514 </para> 1515 </listitem> 1516 <listitem> 1517 <para> 1518Type definitions for any new procedure types used by class methods 1519declared in the widget class part. 1520 </para> 1521 </listitem> 1522 <listitem> 1523 <para> 1524A structure part definition for 1525the new fields that this widget class adds to its superclass's widget class 1526structure. 1527 </para> 1528 </listitem> 1529 <listitem> 1530 <para> 1531The complete widget class structure definition for this widget. 1532 </para> 1533 </listitem> 1534 <listitem> 1535 <para> 1536The complete widget class extension structure definition 1537for this widget, if any. 1538 </para> 1539 </listitem> 1540 <listitem> 1541 <para> 1542The symbolic constant identifying the class extension version, if any. 1543 </para> 1544 </listitem> 1545 <listitem> 1546 <para> 1547The name of the global class structure variable containing the generic 1548class structure for this class. 1549 </para> 1550 </listitem> 1551 <listitem> 1552 <para> 1553An inherit constant for each new procedure in the widget class part structure. 1554 </para> 1555 </listitem> 1556</itemizedlist> 1557<para> 1558For example, the following is the private .h file for a possible Label widget: 1559</para> 1560<programlisting> 1561#ifndef LABELP_H 1562#define LABELP_H 1563 1564#include <X11/Label.h> 1565 1566/* New representation types used by the Label widget */ 1567#define XtRJustify "Justify" 1568 1569/* New fields for the Label widget record */ 1570typedef struct { 1571/* Settable resources */ 1572 Pixel foreground; 1573 XFontStruct *font; 1574 String label; /* text to display */ 1575 XtJustify justify; 1576 Dimension internal_width; /* # pixels horizontal border */ 1577 Dimension internal_height; /* # pixels vertical border */ 1578/* Data derived from resources */ 1579 GC normal_GC; 1580 GC gray_GC; 1581 Pixmap gray_pixmap; 1582 Position label_x; 1583 Position label_y; 1584 Dimension label_width; 1585 Dimension label_height; 1586 Cardinal label_len; 1587 Boolean display_sensitive; 1588} LabelPart; 1589 1590/* Full instance record declaration */ 1591typedef struct _LabelRec { 1592 CorePart core; 1593 LabelPart label; 1594} LabelRec; 1595 1596/* Types for Label class methods */ 1597typedef void (*LabelSetTextProc)(Widget w, String text); 1598typedef String (*LabelGetTextProc)(Widget w); 1599 1600/* New fields for the Label widget class record */ 1601typedef struct { 1602 LabelSetTextProc set_text; 1603 LabelGetTextProc get_text; 1604 XtPointer extension; 1605} LabelClassPart; 1606 1607/* Full class record declaration */ 1608typedef struct _LabelClassRec { 1609 CoreClassPart core_class; 1610 LabelClassPart label_class; 1611} LabelClassRec; 1612 1613/* Class record variable */ 1614extern LabelClassRec labelClassRec; 1615 1616#define LabelInheritSetText((LabelSetTextProc)_XtInherit) 1617#define LabelInheritGetText((LabelGetTextProc)_XtInherit) 1618 1619#endif LABELP_H 1620</programlisting> 1621<para> 1622To accommodate operating systems with file name length restrictions, 1623the name of the private .h file is the first nine characters of the 1624widget class followed by a capital P. 1625For example, 1626the private .h file for the 1627Constraint 1628widget class is 1629<filename class="headerfile">ConstrainP.h</filename>. 1630</para> 1631</sect2> 1632 1633<sect2 id="Widget_Subclassing_in_c_Files"> 1634<title>Widget Subclassing in .c Files</title> 1635<para> 1636The .c file for a widget contains the structure initializer 1637for the class record variable, 1638which contains the following parts: 1639</para> 1640<itemizedlist spacing='compact'> 1641 <listitem> 1642 <para> 1643Class information (for example, <emphasis remap='I'>superclass</emphasis>, <emphasis remap='I'>class_name</emphasis>, 1644<emphasis remap='I'>widget_size</emphasis>, 1645<emphasis remap='I'>class_initialize</emphasis>, and <emphasis remap='I'>class_inited</emphasis>). 1646 </para> 1647 </listitem> 1648 <listitem> 1649 <para> 1650Data constants (for example, <emphasis remap='I'>resources</emphasis> and <emphasis remap='I'>num_resources</emphasis>, 1651<emphasis remap='I'>actions</emphasis> and <emphasis remap='I'>num_actions</emphasis>, <emphasis remap='I'>visible_interest</emphasis>, 1652<emphasis remap='I'>compress_motion</emphasis>, 1653<emphasis remap='I'>compress_exposure</emphasis>, and <emphasis remap='I'>version</emphasis>). 1654 </para> 1655 </listitem> 1656 <listitem> 1657 <para> 1658Widget operations (for example, <emphasis remap='I'>initialize</emphasis>, <emphasis remap='I'>realize</emphasis>, <emphasis remap='I'>destroy</emphasis>, 1659<emphasis remap='I'>resize</emphasis>, <emphasis remap='I'>expose</emphasis>, <emphasis remap='I'>set_values</emphasis>, <emphasis remap='I'>accept_focus</emphasis>, 1660and any new operations specific to 1661the widget). 1662 </para> 1663 </listitem> 1664</itemizedlist> 1665<para> 1666The <emphasis remap='I'>superclass</emphasis> field points to the superclass 1667global class 1668record, declared in the superclass private .h file. 1669For direct subclasses of the generic core widget, 1670<emphasis remap='I'>superclass</emphasis> should be initialized to the address of the 1671<function>widgetClassRec</function> 1672structure. 1673The superclass is used for class chaining operations and for 1674inheriting or enveloping a superclass's operations 1675(see <xref linkend='Superclass_Chaining' />, 1676<xref linkend='Initializing_a_Widget_Class' />, and 1677<xref linkend='Inheritance_of_Superclass_Operations' />. 1678</para> 1679 1680<para> 1681The <emphasis remap='I'>class_name</emphasis> field contains the text name for this class, 1682which is used by 1683the resource manager. 1684For example, the Label widget has the string “Label”. 1685More than one widget class can share the same text class name. 1686This string must be permanently allocated prior to or during the 1687execution of the class initialization procedure and must not be 1688subsequently deallocated. 1689</para> 1690 1691<para> 1692The <emphasis remap='I'>widget_size</emphasis> field is the size of the corresponding widget 1693instance structure 1694(not the size of the class structure). 1695</para> 1696 1697<para> 1698The <emphasis remap='I'>version</emphasis> field indicates the toolkit 1699implementation version number and is used for 1700runtime consistency checking of the X Toolkit and widgets in an application. 1701Widget writers must set it to the 1702implementation-defined symbolic value 1703<function>XtVersion</function> 1704in the widget class structure initialization. 1705Those widget writers who believe that their widget binaries are compatible 1706with other implementations of the Intrinsics can put the special value 1707<function>XtVersionDontCheck</function> 1708in the <emphasis remap='I'>version</emphasis> field to disable version checking for those widgets. 1709If a widget needs to compile alternative code for different 1710revisions of the Intrinsics interface definition, it may use the symbol 1711<function>XtSpecificationRelease</function>, 1712as described in <xref linkend='Evolution_of_the_Intrinsics' />. 1713Use of 1714<function>XtVersion</function> 1715allows the Intrinsics implementation to recognize widget binaries 1716that were compiled with older implementations. 1717</para> 1718 1719<para> 1720The <emphasis remap='I'>extension</emphasis> field is for future upward compatibility. 1721If the widget programmer adds fields to class parts, 1722all subclass structure layouts change, 1723requiring complete recompilation. 1724To allow clients to avoid recompilation, 1725an extension field at the end of each class part can point to a record 1726that contains any additional class information required. 1727</para> 1728 1729<para> 1730All other fields are described in their respective sections. 1731</para> 1732 1733<para> 1734The .c file also contains the declaration of the global class 1735structure pointer variable used to create instances of the class. 1736The following is an abbreviated version of the .c file 1737for a Label widget. 1738The resources table is described in <xref linkend='Resource_Management' />. 1739</para> 1740<programlisting> 1741/* Resources specific to Label */ 1742static XtResource resources[] = { 1743 {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), 1744 XtOffset(LabelWidget, label.foreground), XtRString, 1745 XtDefaultForeground}, 1746 {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *), 1747 XtOffset(LabelWidget, label.font),XtRString, 1748 XtDefaultFont}, 1749 {XtNlabel, XtCLabel, XtRString, sizeof(String), 1750 XtOffset(LabelWidget, label.label), XtRString, NULL}, 1751 . 1752 . 1753 . 1754} 1755 1756/* Forward declarations of procedures */ 1757static void ClassInitialize(void); 1758static void Initialize(Widget, Widget, ArgList, Cardinal*); 1759static void Realize(Widget, XtValueMask*, XSetWindowAttributes*); 1760static void SetText(Widget, String); 1761static void GetText(Widget); 1762 . 1763 . 1764 . 1765</programlisting> 1766<programlisting> 1767/* Class record constant */ 1768LabelClassRec labelClassRec = { 1769 { 1770 /* core_class fields */ 1771 /* superclass */ (WidgetClass)&coreClassRec, 1772 /* class_name */ "Label", 1773 /* widget_size */ sizeof(LabelRec), 1774 /* class_initialize */ ClassInitialize, 1775 /* class_part_initialize */ NULL, 1776 /* class_inited */ False, 1777 /* initialize */ Initialize, 1778 /* initialize_hook */ NULL, 1779 /* realize */ Realize, 1780 /* actions */ NULL, 1781 /* num_actions */ 0, 1782 /* resources */ resources, 1783 /* num_resources */ XtNumber(resources), 1784 /* xrm_class */ NULLQUARK, 1785 /* compress_motion */ True, 1786 /* compress_exposure */ True, 1787 /* compress_enterleave */ True, 1788 /* visible_interest */ False, 1789 /* destroy */ NULL, 1790 /* resize */ Resize, 1791 /* expose */ Redisplay, 1792 /* set_values */ SetValues, 1793 /* set_values_hook */ NULL, 1794 /* set_values_almost */ XtInheritSetValuesAlmost, 1795 /* get_values_hook */ NULL, 1796 /* accept_focus */ NULL, 1797 /* version */ XtVersion, 1798 /* callback_offsets */ NULL, 1799 /* tm_table */ NULL, 1800 /* query_geometry */ XtInheritQueryGeometry, 1801 /* display_accelerator */ NULL, 1802 /* extension */ NULL 1803 }, 1804 { 1805 /* Label_class fields */ 1806 /* get_text */ GetText, 1807 /* set_text */ SetText, 1808 /* extension */ NULL 1809 } 1810}; 1811 1812/* Class record pointer */ 1813WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec; 1814 1815/* New method access routines */ 1816void LabelSetText(Widget w, String text) 1817{ 1818 LabelWidgetClass lwc = (Label WidgetClass)XtClass(w); 1819 XtCheckSubclass(w, labelWidgetClass, NULL); 1820 *(lwc->label_class.set_text)(w, text) 1821} 1822 1823/* Private procedures */ 1824 . 1825 . 1826 . 1827</programlisting> 1828</sect2> 1829 1830<sect2 id="Widget_Class_and_Superclass_Look_Up"> 1831<title>Widget Class and Superclass Look Up</title> 1832<para> 1833To obtain the class of a widget, use 1834<xref linkend='XtClass' xrefstyle='select: title'/>. 1835</para> 1836 1837 1838 1839<funcsynopsis id='XtClass'> 1840 <funcprototype> 1841 <funcdef>WidgetClass <function>XtClass</function></funcdef> 1842 <paramdef>Widget<parameter> w</parameter></paramdef> 1843 </funcprototype> 1844 </funcsynopsis> 1845 1846<variablelist> 1847 <varlistentry> 1848 <term> 1849 <emphasis remap='I'>w</emphasis> 1850 </term> 1851 <listitem> 1852 <para> 1853Specifies the widget. Must be of class Object or any subclass thereof. 1854 </para> 1855 </listitem> 1856 </varlistentry> 1857</variablelist> 1858 1859 1860<para> 1861The 1862<xref linkend='XtClass' xrefstyle='select: title'/> 1863function returns a pointer to the widget's class structure. 1864</para> 1865 1866<para> 1867To obtain the superclass of a widget, use 1868<function>XtSuperclass</function>. 1869</para> 1870 1871<!-- 1872--> 1873<funcsynopsis id='XtSuperClass'> 1874<funcprototype> 1875 <funcdef>WidgetClass <function>XtSuperClass</function></funcdef> 1876 <paramdef>Widget<parameter> w</parameter></paramdef> 1877</funcprototype> 1878</funcsynopsis> 1879 1880<variablelist> 1881 <varlistentry> 1882 <term> 1883 <emphasis remap='I'>w</emphasis> 1884 </term> 1885 <listitem> 1886 <para> 1887Specifies the widget. Must be of class Object or any subclass thereof. 1888 </para> 1889 </listitem> 1890 </varlistentry> 1891</variablelist> 1892<!-- 1893--> 1894 1895<para> 1896The 1897<function>XtSuperclass</function> 1898function returns a pointer to the widget's superclass class structure. 1899</para> 1900</sect2> 1901 1902<sect2 id="Widget_Subclass_Verification"> 1903<title>Widget Subclass Verification</title> 1904<para> 1905To check the subclass to which a widget belongs, use 1906<xref linkend='XtIsSubclass' xrefstyle='select: title'/>. 1907</para> 1908 1909<funcsynopsis id='XtIsSubclass'> 1910<funcprototype> 1911 <funcdef>Boolean <function>XtIsSubclass</function></funcdef> 1912 <paramdef>Widget<parameter> w</parameter></paramdef> 1913 <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef> 1914</funcprototype> 1915</funcsynopsis> 1916 1917<variablelist> 1918 <varlistentry> 1919 <term> 1920 <emphasis remap='I'>w</emphasis> 1921 </term> 1922 <listitem> 1923 <para> 1924Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. 1925 </para> 1926 </listitem> 1927 </varlistentry> 1928 <varlistentry> 1929 <term> 1930 <emphasis remap='I'>widget_class</emphasis> 1931 </term> 1932 <listitem> 1933 <para> 1934Specifies the widget class for which to test. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof. 1935 </para> 1936 </listitem> 1937 </varlistentry> 1938</variablelist> 1939 1940 1941<para> 1942The 1943<xref linkend='XtIsSubclass' xrefstyle='select: title'/> 1944function returns 1945<function>True</function> 1946if the class of the specified widget is equal to 1947or is a subclass of the specified class. 1948The widget's class can be any number of subclasses down the chain 1949and need not be an immediate subclass of the specified class. 1950Composite widgets that need to restrict the class of the items they 1951contain can use 1952<xref linkend='XtIsSubclass' xrefstyle='select: title'/> 1953to find out if a widget belongs to the desired class of objects. 1954</para> 1955 1956<para> 1957To test if a given widget belongs to a subclass of an Intrinsics-defined 1958class, the Intrinsics define macros or functions equivalent to 1959<xref linkend='XtIsSubclass' xrefstyle='select: title'/> 1960for each of the built-in classes. These procedures are 1961<function>XtIsObject</function>, 1962<function>XtIsRectObj</function>, 1963<function>XtIsWidget</function>, 1964<function>XtIsComposite</function>, 1965<function>XtIsConstraint</function>, 1966<function>XtIsShell</function>, 1967<function>XtIsOverrideShell</function>, 1968<function>XtIsWMShell</function>, 1969<function>XtIsVendorShell</function>, 1970<function>XtIsTransientShell</function>, 1971<function>XtIsTopLevelShell</function>, 1972<function>XtIsApplicationShell</function>, 1973and 1974<function>XtIsSessionShell</function>. 1975</para> 1976 1977<para> 1978All these macros and functions have the same argument description. 1979</para> 1980 1981<funcsynopsis id='XtIs'> 1982<funcprototype> 1983 <funcdef>Boolean <function>XtIs<subscript><class></subscript></function></funcdef> 1984 <paramdef>Widget<parameter> w</parameter></paramdef> 1985</funcprototype> 1986</funcsynopsis> 1987 1988<variablelist> 1989 <varlistentry> 1990 <term> 1991 <emphasis remap='I'>w</emphasis> 1992 </term> 1993 <listitem> 1994 <para> 1995Specifies the widget or object instance whose class is to be checked. Must be of class Object or any subclass thereof. 1996 </para> 1997 </listitem> 1998 </varlistentry> 1999</variablelist> 2000 2001<para> 2002These procedures may be faster than calling 2003<xref linkend='XtIsSubclass' xrefstyle='select: title'/> 2004directly for the built-in classes. 2005</para> 2006 2007<para> 2008To check a widget's class 2009and to generate a debugging error message, use 2010<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>, 2011defined in 2012<filename class="headerfile"><X11/IntrinsicP.h></filename>: 2013</para> 2014 2015<funcsynopsis id='XtCheckSubclass'> 2016<funcprototype> 2017 <funcdef>void <function>XtCheckSubclass</function></funcdef> 2018 <paramdef>Widget<parameter> w</parameter></paramdef> 2019 <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef> 2020 <paramdef>String<parameter> message</parameter></paramdef> 2021</funcprototype> 2022</funcsynopsis> 2023 2024<variablelist> 2025 <varlistentry> 2026 <term> 2027 <emphasis remap='I'>w</emphasis> 2028 </term> 2029 <listitem> 2030 <para> 2031Specifies the widget or object whose class is to be checked. Must be of class Object or any subclass thereof. 2032 </para> 2033 </listitem> 2034 </varlistentry> 2035 <varlistentry> 2036 <term> 2037 <emphasis remap='I'>widget_class</emphasis> 2038 </term> 2039 <listitem> 2040 <para> 2041Specifies the widget class for which to test. Must be <emphasis role='strong'>objectClass</emphasis> or any subclass thereof. 2042 </para> 2043 </listitem> 2044 </varlistentry> 2045 <varlistentry> 2046 <term> 2047 <emphasis remap='I'>message</emphasis> 2048 </term> 2049 <listitem> 2050 <para> 2051Specifies the message to be used. 2052 </para> 2053 </listitem> 2054 </varlistentry> 2055</variablelist> 2056 2057<para> 2058The 2059<xref linkend='XtCheckSubclass' xrefstyle='select: title'/> 2060macro determines if the class of the specified widget is equal to 2061or is a subclass of the specified class. 2062The widget's class can be any number of subclasses down the chain 2063and need not be an immediate subclass of the specified class. 2064If the specified widget's class is not a subclass, 2065<xref linkend='XtCheckSubclass' xrefstyle='select: title'/> 2066constructs an error message from the supplied message, 2067the widget's actual class, and the expected class and calls 2068<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. 2069<xref linkend='XtCheckSubclass' xrefstyle='select: title'/> 2070should be used at the entry point of exported routines to ensure 2071that the client has passed in a valid widget class for the exported operation. 2072</para> 2073 2074<para> 2075<xref linkend='XtCheckSubclass' xrefstyle='select: title'/> 2076is only executed when the module has been compiled with the compiler symbol 2077DEBUG defined; otherwise, it is defined as the empty string 2078and generates no code. 2079</para> 2080</sect2> 2081 2082<sect2 id="Superclass_Chaining"> 2083<title>Superclass Chaining</title> 2084<para> 2085While most fields in a widget class structure are self-contained, 2086some fields are linked to their corresponding fields in their superclass 2087structures. 2088With a linked field, 2089the Intrinsics access the field's value only after accessing its corresponding 2090superclass value (called downward superclass chaining) or 2091before accessing its corresponding superclass value (called upward superclass 2092chaining). The self-contained fields are</para> 2093<programlisting> 2094In all widget classes: <emphasis remap='I'>class_name</emphasis> 2095 <emphasis remap='I'>class_initialize</emphasis> 2096 <emphasis remap='I'>widget_size</emphasis> 2097 <emphasis remap='I'>realize</emphasis> 2098 <emphasis remap='I'>visible_interest</emphasis> 2099 <emphasis remap='I'>resize</emphasis> 2100 <emphasis remap='I'>expose</emphasis> 2101 <emphasis remap='I'>accept_focus</emphasis> 2102 <emphasis remap='I'>compress_motion</emphasis> 2103 <emphasis remap='I'>compress_exposure</emphasis> 2104 <emphasis remap='I'>compress_enterleave</emphasis> 2105 <emphasis remap='I'>set_values_almost</emphasis> 2106 <emphasis remap='I'>tm_table</emphasis> 2107 <emphasis remap='I'>version</emphasis> 2108 <emphasis remap='I'>allocate</emphasis> 2109 <emphasis remap='I'>deallocate</emphasis> 2110 2111In Composite widget classes: <emphasis remap='I'>geometry_manager</emphasis> 2112 <emphasis remap='I'>change_managed</emphasis> 2113 <emphasis remap='I'>insert_child</emphasis> 2114 <emphasis remap='I'>delete_child</emphasis> 2115 <emphasis remap='I'>accepts_objects</emphasis> 2116 <emphasis remap='I'>allows_change_managed_set</emphasis> 2117 2118In Constraint widget classes: <emphasis remap='I'>constraint_size</emphasis> 2119 2120In Shell widget classes: <emphasis remap='I'>root_geometry_manager</emphasis> 2121</programlisting> 2122 2123<para> 2124With downward superclass chaining, 2125the invocation of an operation first accesses the field from the 2126Object, 2127RectObj, 2128and 2129Core 2130class structures, then from the subclass structure, and so on down the class chain to 2131that widget's class structure. These superclass-to-subclass fields are 2132</para> 2133<programlisting> 2134 <emphasis remap='I'>class_part_initialize</emphasis> 2135 <emphasis remap='I'>get_values_hook</emphasis> 2136 <emphasis remap='I'>initialize</emphasis> 2137 <emphasis remap='I'>initialize_hook</emphasis> 2138 <emphasis remap='I'>set_values</emphasis> 2139 <emphasis remap='I'>set_values_hook</emphasis> 2140 <emphasis remap='I'>resources</emphasis> 2141</programlisting> 2142 2143<para> 2144In addition, for subclasses of 2145Constraint, 2146the following fields of the 2147<function>ConstraintClassPart</function> 2148and 2149<function>ConstraintClassExtensionRec</function> 2150structures are chained from the 2151Constraint 2152class down to the subclass: 2153</para> 2154<programlisting> 2155 <emphasis remap='I'>resources</emphasis> 2156 <emphasis remap='I'>initialize</emphasis> 2157 <emphasis remap='I'>set_values</emphasis> 2158 <emphasis remap='I'>get_values_hook</emphasis> 2159</programlisting> 2160 2161<para> 2162With upward superclass chaining, 2163the invocation of an operation first accesses the field from the widget 2164class structure, then from the superclass structure, 2165and so on up the class chain to the 2166Core, 2167RectObj, 2168and 2169Object 2170class structures. 2171The subclass-to-superclass fields are 2172</para> 2173<programlisting> 2174 <emphasis remap='I'>destroy</emphasis> 2175 <emphasis remap='I'>actions</emphasis> 2176</programlisting> 2177 2178<para> 2179For subclasses of 2180Constraint, 2181the following field of 2182<function>ConstraintClassPart</function> 2183is chained from the subclass up to the 2184Constraint class: 2185</para> 2186<programlisting> 2187 <emphasis remap='I'>destroy</emphasis> 2188</programlisting> 2189</sect2> 2190 2191<sect2 id="Class_Initialization_class_initialize_and_class_part_initialize_Procedures"> 2192<title>Class Initialization: class_initialize and class_part_initialize Procedures</title> 2193<para> 2194Many class records can be initialized completely at compile or link time. 2195In some cases, however, 2196a class may need to register type converters or perform other sorts of 2197once-only runtime initialization. 2198</para> 2199 2200<para> 2201Because the C language does not have initialization procedures 2202that are invoked automatically when a program starts up, 2203a widget class can declare a class_initialize procedure 2204that will be automatically called exactly once by the Intrinsics. 2205A class initialization procedure pointer is of type 2206<function>XtProc</function>: 2207</para> 2208 2209<para> 2210typedef void (*XtProc)(void); 2211</para> 2212<para> 2213A widget class indicates that it has no class initialization procedure by 2214specifying NULL in the <emphasis remap='I'>class_initialize</emphasis> field. 2215</para> 2216 2217<para> 2218In addition to the class initialization that is done exactly once, 2219some classes perform initialization for fields in their parts 2220of the class record. 2221These are performed not just for the particular class, 2222but for subclasses as well, and are 2223done in the class's class part initialization procedure, 2224a pointer to which is stored in the <emphasis remap='I'>class_part_initialize</emphasis> field. 2225The class_part_initialize procedure pointer is of type 2226<function>XtWidgetClassProc</function>. 2227</para> 2228 2229<funcsynopsis> 2230<funcprototype> 2231 <funcdef>typedef void <function>(*XtWidgetClassProc)(WidgetClass)</function></funcdef> 2232 <paramdef>WidgetClass<parameter> widget_class</parameter></paramdef> 2233</funcprototype> 2234</funcsynopsis> 2235 2236<variablelist> 2237 <varlistentry> 2238 <term> 2239 <emphasis remap='I'>widget_class</emphasis> 2240 </term> 2241 <listitem> 2242 <para> 2243Points to the class structure for the class being initialized. 2244 </para> 2245 </listitem> 2246 </varlistentry> 2247</variablelist> 2248<para> 2249During class initialization, 2250the class part initialization procedures for the class and all its superclasses 2251are called in superclass-to-subclass order on the class record. 2252These procedures have the responsibility of doing any dynamic initializations 2253necessary to their class's part of the record. 2254The most common is the resolution of any inherited methods defined in the 2255class. 2256For example, 2257if a widget class C has superclasses 2258Core, 2259Composite, 2260A, and B, the class record for C first is passed to 2261Core 's 2262class_part_initialize procedure. 2263This resolves any inherited Core methods and compiles the textual 2264representations of the resource list and action table that are defined in the 2265class record. 2266Next, Composite's 2267class_part_initialize procedure is called to initialize the 2268composite part of C's class record. 2269Finally, the class_part_initialize procedures for A, B, and C, in that order, 2270are called. 2271For further information, 2272see <xref linkend='Initializing_a_Widget_Class' /> 2273Classes that do not define any new class fields 2274or that need no extra processing for them can specify NULL 2275in the <emphasis remap='I'>class_part_initialize</emphasis> field. 2276</para> 2277 2278<para> 2279All widget classes, whether they have a class initialization procedure or not, 2280must start with their <emphasis remap='I'>class_inited</emphasis> field 2281<function>False</function>. 2282</para> 2283 2284<para> 2285The first time a widget of a class is created, 2286<xref linkend='XtCreateWidget' xrefstyle='select: title'/> 2287ensures that the widget class and all superclasses are initialized, in 2288superclass-to-subclass order, by checking each <emphasis remap='I'>class_inited</emphasis> field and, 2289if it is 2290<function>False</function>, 2291by calling the class_initialize and the class_part_initialize procedures 2292for the class and all its superclasses. 2293The Intrinsics then set the <emphasis remap='I'>class_inited</emphasis> field to a nonzero value. 2294After the one-time initialization, 2295a class structure is constant. 2296</para> 2297 2298<para> 2299The following example provides the class initialization procedure for a Label class. 2300</para> 2301<programlisting> 2302static void ClassInitialize(void) 2303{ 2304 XtSetTypeConverter(XtRString, XtRJustify, CvtStringToJustify, 2305 NULL, 0, XtCacheNone, NULL); 2306} 2307</programlisting> 2308</sect2> 2309 2310<sect2 id="Initializing_a_Widget_Class"> 2311<title>Initializing a Widget Class</title> 2312<para> 2313A class is initialized when the first widget of that class or any 2314subclass is created. 2315To initialize a widget class without creating any widgets, use 2316<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/>. 2317</para> 2318 2319<funcsynopsis id='XtInitializeWidgetClass'> 2320<funcprototype> 2321 <funcdef>void <function>XtInitializeWidgetClass</function></funcdef> 2322 <paramdef>WidgetClass<parameter> object_class</parameter></paramdef> 2323</funcprototype> 2324</funcsynopsis> 2325 2326<variablelist> 2327 <varlistentry> 2328 <term> 2329 <emphasis remap='I'>object_class</emphasis> 2330 </term> 2331 <listitem> 2332 <para> 2333Specifies the object class to initialize. May be 2334<function>objectClass</function> 2335or any subclass thereof. 2336 </para> 2337 </listitem> 2338 </varlistentry> 2339</variablelist> 2340 2341<para> 2342If the specified widget class is already initialized, 2343<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/> 2344returns immediately. 2345</para> 2346 2347<para> 2348If the class initialization procedure registers type converters, 2349these type converters are not available until the first object 2350of the class or subclass is created or 2351<xref linkend='XtInitializeWidgetClass' xrefstyle='select: title'/> 2352is called 2353(see <xref linkend='Resource_Conversions' />). 2354</para> 2355</sect2> 2356 2357<sect2 id="Inheritance_of_Superclass_Operations"> 2358<title>Inheritance of Superclass Operations</title> 2359<para> 2360A widget class is free to use any of its superclass's self-contained 2361operations rather than implementing its own code. 2362The most frequently inherited operations are 2363</para> 2364<itemizedlist spacing='compact'> 2365 <listitem> 2366 <para> 2367expose 2368 </para> 2369 </listitem> 2370 <listitem> 2371 <para> 2372realize 2373 </para> 2374 </listitem> 2375 <listitem> 2376 <para> 2377insert_child 2378 </para> 2379 </listitem> 2380 <listitem> 2381 <para> 2382delete_child 2383 </para> 2384 </listitem> 2385 <listitem> 2386 <para> 2387geometry_manager 2388 </para> 2389 </listitem> 2390 <listitem> 2391 <para> 2392set_values_almost 2393 </para> 2394 </listitem> 2395</itemizedlist> 2396 2397<para> 2398To inherit an operation <emphasis remap='I'>xyz</emphasis>, 2399specify the constant 2400<function>XtInherit</function> <emphasis remap='I'>Xyz</emphasis> 2401in your class record. 2402</para> 2403 2404<para> 2405Every class that declares a new procedure in its widget class part must 2406provide for inheriting the procedure in its class_part_initialize 2407procedure. 2408The chained operations declared in Core 2409and Constraint 2410records are never inherited. 2411Widget classes that do nothing beyond what their superclass does 2412specify NULL for chained procedures 2413in their class records. 2414</para> 2415 2416<para> 2417Inheriting works by comparing the value of the field with a known, special 2418value and by copying in the superclass's value for that field if a match 2419occurs. 2420This special value, called the inheritance constant, 2421is usually the Intrinsics internal value 2422<function>_XtInherit</function> 2423cast to the appropriate type. 2424<function>_XtInherit</function> 2425is a procedure that issues an error message if it is actually called. 2426</para> 2427 2428<para> 2429For example, 2430<filename class="headerfile">CompositeP.h</filename> 2431contains these definitions: 2432</para> 2433<programlisting> 2434#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit) 2435#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit) 2436#define XtInheritInsertChild ((XtArgsProc) _XtInherit) 2437#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit) 2438</programlisting> 2439<para> 2440Composite's class_part_initialize procedure begins as follows: 2441</para> 2442<programlisting> 2443static void CompositeClassPartInitialize(WidgetClass widgetClass) 2444{ 2445 CompositeWidgetClass wc = (CompositeWidgetClass)widgetClass; 2446 CompositeWidgetClass super = (CompositeWidgetClass)wc->core_class.superclass; 2447 if (wc->composite_class.geometry_manager == XtInheritGeometryManager) { 2448 wc->composite_class.geometry_manager = super->composite_class.geometry_manager; 2449 } 2450 if (wc->composite_class.change_managed == XtInheritChangeManaged) { 2451 wc->composite_class.change_managed = super->composite_class.change_managed; 2452 } 2453 . 2454 . 2455 . 2456} 2457</programlisting> 2458<para> 2459Nonprocedure fields may be inherited in the same manner as procedure 2460fields. The class may declare any reserved value it wishes for 2461the inheritance constant for its new fields. The following inheritance 2462constants are defined: 2463</para> 2464 2465<para> 2466For Object: 2467</para> 2468<itemizedlist spacing='compact'> 2469 <listitem> 2470 <para> 2471<function>XtInheritAllocate</function> 2472 </para> 2473 </listitem> 2474 <listitem> 2475 <para> 2476<function>XtInheritDeallocate</function> 2477 </para> 2478 </listitem> 2479</itemizedlist> 2480<para> 2481For Core: 2482</para> 2483<itemizedlist spacing='compact'> 2484 <listitem> 2485 <para> 2486<function>XtInheritRealize</function> 2487 </para> 2488 </listitem> 2489 <listitem> 2490 <para> 2491<function>XtInheritResize</function> 2492 </para> 2493 </listitem> 2494 <listitem> 2495 <para> 2496<function>XtInheritExpose</function> 2497 </para> 2498 </listitem> 2499 <listitem> 2500 <para> 2501<function>XtInheritSetValuesAlmost</function> 2502 </para> 2503 </listitem> 2504 <listitem> 2505 <para> 2506<function>XtInheritAcceptFocus</function> 2507 </para> 2508 </listitem> 2509 <listitem> 2510 <para> 2511<function>XtInheritQueryGeometry</function> 2512 </para> 2513 </listitem> 2514 <listitem> 2515 <para> 2516<function>XtInheritTranslations</function> 2517 </para> 2518 </listitem> 2519 <listitem> 2520 <para> 2521<function>XtInheritDisplayAccelerator</function> 2522 </para> 2523 </listitem> 2524</itemizedlist> 2525<para> 2526For Composite: 2527</para> 2528<itemizedlist spacing='compact'> 2529 <listitem> 2530 <para> 2531<function>XtInheritGeometryManager</function> 2532 </para> 2533 </listitem> 2534 <listitem> 2535 <para> 2536<function>XtInheritChangeManaged</function> 2537 </para> 2538 </listitem> 2539 <listitem> 2540 <para> 2541<function>XtInheritInsertChild</function> 2542 </para> 2543 </listitem> 2544 <listitem> 2545 <para> 2546<function>XtInheritDeleteChild</function> 2547 </para> 2548 </listitem> 2549</itemizedlist> 2550<para> 2551For Shell: 2552</para> 2553<itemizedlist spacing='compact'> 2554 <listitem> 2555 <para> 2556<function>XtInheritRootGeometryManager</function> 2557 </para> 2558 </listitem> 2559</itemizedlist> 2560</sect2> 2561 2562<sect2 id="Invocation_of_Superclass_Operations"> 2563<title>Invocation of Superclass Operations</title> 2564<para> 2565A widget sometimes needs to call a superclass operation 2566that is not chained. 2567For example, 2568a widget's expose procedure might call its superclass's <emphasis remap='I'>expose</emphasis> 2569and then perform a little more work on its own. 2570For example, a Composite 2571class with predefined managed children can implement insert_child 2572by first calling its superclass's <emphasis remap='I'>insert_child</emphasis> 2573and then calling 2574<xref linkend='XtManageChild' xrefstyle='select: title'/> 2575to add the child to the managed set. 2576</para> 2577 2578<note> 2579<para> 2580A class method should not use 2581<function>XtSuperclass</function> 2582but should instead call the class method of its own specific superclass 2583directly through the superclass record. 2584That is, it should use its own class pointers only, 2585not the widget's class pointers, 2586as the widget's class may be a subclass of the 2587class whose implementation is being referenced. 2588</para> 2589</note> 2590<para> 2591This technique is referred to as <emphasis remap='I'>enveloping</emphasis> the superclass's operation. 2592</para> 2593</sect2> 2594 2595<sect2 id="Class_Extension_Records"> 2596<title>Class Extension Records</title> 2597<para> 2598It may be necessary at times to add new fields to already existing 2599widget class structures. To permit this to be done without requiring 2600recompilation of all subclasses, the last field in a class part structure 2601should be an extension pointer. If no extension fields for a class 2602have yet been defined, subclasses should initialize the value of the 2603extension pointer to NULL. 2604</para> 2605 2606<para> 2607If extension fields exist, as is the case with the 2608Composite, 2609Constraint, 2610and 2611Shell 2612classes, subclasses can provide values for these fields by setting the 2613<emphasis remap='I'>extension</emphasis> pointer for the appropriate part in their class structure to 2614point to a statically declared extension record containing the 2615additional fields. 2616Setting the <emphasis remap='I'>extension</emphasis> field is never mandatory; code that uses fields 2617in the extension record must always check the <emphasis remap='I'>extension</emphasis> field and take 2618some appropriate default action if it is NULL. 2619</para> 2620 2621<para> 2622In order to permit multiple subclasses and libraries to chain extension 2623records from a single <emphasis remap='I'>extension</emphasis> field, extension records should be 2624declared as a linked list, and each extension record definition should 2625contain the following four fields at the beginning of the structure 2626declaration: 2627</para> 2628<programlisting> 2629struct { 2630 XtPointer next_extension; 2631 XrmQuark record_type; 2632 long version; 2633 Cardinal record_size; 2634}; 2635</programlisting> 2636 2637<variablelist> 2638 <varlistentry> 2639 <term> 2640 <emphasis remap='I'>next_extension</emphasis> 2641 </term> 2642 <listitem> 2643 <para> 2644Specifies the next record in the list, or NULL. 2645 </para> 2646 </listitem> 2647 </varlistentry> 2648 <varlistentry> 2649 <term> 2650 <emphasis remap='I'>record_type</emphasis> 2651 </term> 2652 <listitem> 2653 <para> 2654Specifies the particular structure declaration to which 2655each extension record instance conforms. 2656 </para> 2657 </listitem> 2658 </varlistentry> 2659 <varlistentry> 2660 <term> 2661 <emphasis remap='I'>version</emphasis> 2662 </term> 2663 <listitem> 2664 <para> 2665Specifies a version id symbolic constant supplied by 2666the definer of the structure. 2667 </para> 2668 </listitem> 2669 </varlistentry> 2670 <varlistentry> 2671 <term> 2672 <emphasis remap='I'>record_size</emphasis> 2673 </term> 2674 <listitem> 2675 <para> 2676Specifies the total number of bytes allocated for the 2677extension record. 2678 </para> 2679 </listitem> 2680 </varlistentry> 2681</variablelist> 2682 2683<para> 2684The <emphasis remap='I'>record_type</emphasis> field identifies the contents of the extension record 2685and is used by the definer of the record to locate its particular 2686extension record in the list. The 2687<emphasis remap='I'>record_type</emphasis> field is normally assigned the 2688result of 2689<function>XrmStringToQuark</function> 2690for a registered string constant. The 2691Intrinsics reserve all record type strings beginning with the two 2692characters “XT” for future standard uses. The value 2693<emphasis role='strong'>NULLQUARK</emphasis> 2694may also be used 2695by the class part owner in extension records attached to its own class 2696part extension field to identify the extension record unique to that 2697particular class. 2698</para> 2699 2700<para> 2701The <emphasis remap='I'>version</emphasis> field is an owner-defined constant that may be used to 2702identify binary files that have been compiled with alternate 2703definitions of the remainder of the extension record data structure. The private 2704header file for a widget class should provide a symbolic constant for 2705subclasses to use to initialize this field. 2706The <emphasis remap='I'>record_size</emphasis> field value includes the four common header fields and 2707should normally be initialized with 2708<function>sizeof().</function> 2709</para> 2710 2711<para> 2712Any value stored in the class part extension fields of 2713<function>CompositeClassPart</function>, 2714<function>ConstraintClassPart</function>, 2715or 2716<function>ShellClassPart</function> 2717must point to an extension record conforming to this definition. 2718</para> 2719 2720<para> 2721The Intrinsics provide a utility function for widget writers to locate a 2722particular class extension record in a linked list, given a widget class 2723and the offset of the <emphasis remap='I'>extension</emphasis> field in the class record. 2724</para> 2725 2726<para> 2727To locate a class extension record, use 2728<xref linkend='XtGetClassExtension' xrefstyle='select: title'/>. 2729</para> 2730 2731<funcsynopsis id='XtGetClassExtension'> 2732<funcprototype> 2733 <funcdef>XtPointer <function>XtGetClassExtension</function></funcdef> 2734 <paramdef>WidgetClass<parameter> object_class</parameter></paramdef> 2735 <paramdef>Cardinal<parameter> byte_offset</parameter></paramdef> 2736 <paramdef>XrmQuark<parameter> type</parameter></paramdef> 2737 <paramdef>long<parameter> version</parameter></paramdef> 2738 <paramdef>Cardinal<parameter> record_size</parameter></paramdef> 2739</funcprototype> 2740</funcsynopsis> 2741 2742<variablelist> 2743 <varlistentry> 2744 <term> 2745 <emphasis remap='I'>object_class</emphasis> 2746 </term> 2747 <listitem> 2748 <para> 2749Specifies the object class containing the extension list to be searched. 2750 </para> 2751 </listitem> 2752 </varlistentry> 2753 <varlistentry> 2754 <term> 2755 <emphasis remap='I'>byte_offset</emphasis> 2756 </term> 2757 <listitem> 2758 <para> 2759Specifies the offset in bytes from the base of the 2760class record of the extension field to be searched. 2761 </para> 2762 </listitem> 2763 </varlistentry> 2764 <varlistentry> 2765 <term> 2766 <emphasis remap='I'>type</emphasis> 2767 </term> 2768 <listitem> 2769 <para> 2770Specifies the record_type of the class extension to be located. 2771 </para> 2772 </listitem> 2773 </varlistentry> 2774 <varlistentry> 2775 <term> 2776 <emphasis remap='I'>version</emphasis> 2777 </term> 2778 <listitem> 2779 <para> 2780Specifies the minimum acceptable version of the class 2781extension required for a match. 2782 </para> 2783 </listitem> 2784 </varlistentry> 2785 <varlistentry> 2786 <term> 2787 <emphasis remap='I'>record_size</emphasis> 2788 </term> 2789 <listitem> 2790 <para> 2791Specifies the minimum acceptable length of the class 2792extension record required for a match, or 0. 2793 </para> 2794 </listitem> 2795 </varlistentry> 2796</variablelist> 2797 2798<para> 2799The list of extension records at the specified offset in the specified 2800object class will be searched for a match on the specified type, 2801a version greater than or equal to the specified version, and a record 2802size greater than or equal the specified record_size if it is nonzero. 2803<xref linkend='XtGetClassExtension' xrefstyle='select: title'/> 2804returns a pointer to a matching extension record or NULL if no match 2805is found. The returned extension record must not be modified or 2806freed by the caller if the caller is not the extension owner. 2807</para> 2808</sect2> 2809</sect1> 2810</chapter> 2811