home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH01 < prev    next >
Encoding:
Text File  |  1991-08-27  |  59.8 KB  |  2,307 lines

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