home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH12 < prev    next >
Encoding:
Text File  |  1991-07-31  |  20.9 KB  |  963 lines
  1. .\" $XConsortium: CH12,v 1.4 91/07/31 20:24:45 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. .sp 1
  18. .ce 3
  19. \s+1\fBChapter 12\fP\s-1
  20.  
  21. \s+1\fBNonwidget Objects\fP\s-1
  22. .sp 2
  23. .nr H1 12
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 12 \- Nonwidget Objects
  31. .XE
  32. .LP
  33. Although widget writers are free to treat
  34. Core
  35. as the base class of
  36. the widget hierarchy, there are actually three classes above it.
  37. These classes are
  38. Object,
  39. RectObj,
  40. (Rectangle Object) and (\fIunnamed\fP)
  41. and members of these classes
  42. are referred to generically as \fIobjects\fP.  By convention, the term
  43. \fIwidget\fP refers only to objects that are a subclass of
  44. Core,
  45. and the term \fInonwidget\fP refers to objects that are not a subclass of
  46. Core.
  47. In the preceding portion of this specification, the interface
  48. descriptions indicate explicitly whether the generic \fIwidget\fP argument
  49. is restricted to particular subclasses of Object.  Sections 12.2.5,
  50. 12.3.5, and 12.5 summarize the permissible classes of the arguments to, and
  51. return values from, each of the \*(xI routines.
  52.  
  53. .NH 2
  54. Data Structures
  55. .XS
  56. \*(SN Data Structures
  57. .XE
  58. .LP
  59. In order not to conflict with previous widget code, the data
  60. structures used by nonwidget objects do not follow all the same
  61. conventions as those for widgets.  In particular, the class records
  62. are not composed of parts but instead are complete data structures
  63. with filler for the widget fields they do not use.  This
  64. allows the static class initializers for existing widgets to remain
  65. unchanged.
  66.  
  67. .NH 2
  68. Object Objects
  69. .XS
  70. \fB\*(SN Object Objects\fP
  71. .XE
  72. .LP
  73. .IN "Object" "" "@DEF@"
  74. The
  75. Object
  76. object contains the definitions of fields common to all
  77. objects.  It encapsulates the mechanisms for resource management.
  78. All objects and widgets are members of subclasses of
  79. Object,
  80. which is defined by the
  81. .PN ObjectClassPart
  82. and
  83. .PN ObjectPart
  84. structures.
  85.  
  86. .NH 3
  87. ObjectClassPart Structure
  88. .XS
  89. \*(SN ObjectClassPart Structure
  90. .XE
  91.  
  92. .LP
  93. The common fields for all object classes are defined in the
  94. .PN ObjectClassPart
  95. structure.  All fields have the same purpose,
  96. function, and restrictions as the corresponding fields in
  97. .PN CoreClassPart ;
  98. fields whose
  99. names are obj\fI\s+1n\s-1\fP for some integer \s+1\fIn\fP\s-1 are not
  100. used for Object,
  101. but exist to pad the data structure so that it matches Core's class
  102. record.  The class record initialization must fill all
  103. obj\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type.
  104.  
  105. .IN "ObjectClassPart" "" "@DEF@"
  106. .Ds 0
  107. .TA .5i 3i
  108. .ta .5i 3i
  109. typedef struct _ObjectClassPart {
  110.     WidgetClass superclass;
  111.     String class_name;
  112.     Cardinal widget_size;
  113.     XtProc class_initialize;
  114.     XtWidgetClassProc class_part_initialize;
  115.     XtEnum class_inited;
  116.     XtInitProc initialize;
  117.     XtArgsProc initialize_hook;
  118.     XtProc obj1;
  119.     XtPointer obj2;
  120.     Cardinal obj3;
  121.     XtResourceList resources;
  122.     Cardinal num_resources;
  123.     XrmClass xrm_class;
  124.     Boolean obj4;
  125.     XtEnum obj5;
  126.     Boolean obj6;
  127.     Boolean obj7;
  128.     XtWidgetProc destroy;
  129.     XtProc obj8;
  130.     XtProc obj9;
  131.     XtSetValuesFunc set_values;
  132.     XtArgsFunc set_values_hook;
  133.     XtProc obj10;
  134.     XtArgsProc get_values_hook;
  135.     XtProc obj11;
  136.     XtVersionType version;
  137.     XtPointer callback_private;
  138.     String obj12;
  139.     XtProc obj13;
  140.     XtProc obj14;
  141.     XtPointer extension;
  142. } ObjectClassPart;
  143. .De
  144. .LP
  145. The prototypical
  146. .PN ObjectClass
  147. consists of just the
  148. .PN ObjectClassPart .
  149.  
  150. .IN "ObjectClassRec" "" "@DEF@"
  151. .IN "ObjectClass" "" "@DEF@"
  152. .IN "objectClass" "" "@DEF@"
  153. .Ds 0
  154. .TA .5i 3i
  155. .ta .5i 3i
  156. typedef struct _ObjectClassRec {
  157.     ObjectClassPart object_class;
  158. } ObjectClassRec, *ObjectClass;
  159. .De
  160.  
  161. The predefined class record and pointer for
  162. .PN ObjectClassRec
  163. are
  164. .LP
  165. In
  166. .PN IntrinsicP.h :
  167. .Ds 0
  168. extern ObjectClassRec objectClassRec;
  169. .De
  170. .LP
  171. In
  172. .PN Intrinsic.h :
  173. .Ds 0
  174. extern WidgetClass objectClass;
  175. .De
  176. .LP
  177. The opaque types
  178. .PN Object
  179. and
  180. .PN ObjectClass
  181. and the opaque variable
  182. .PN objectClass
  183. are defined for generic actions on objects.
  184. .PN Intrinsic.h
  185. uses an incomplete structure definition to ensure that the
  186. compiler catches attempts to access private data:
  187. .LP
  188. .Ds 0
  189. typedef struct _ObjectClassRec* ObjectClass;
  190. .De
  191.  
  192. .NH 3
  193. ObjectPart Structure
  194. .XS
  195. \*(SN ObjectPart Structure
  196. .XE
  197.  
  198. .LP
  199. The common fields for all object instances are defined in the
  200. .PN ObjectPart
  201. structure.  All fields have the same meaning as the
  202. corresponding fields in
  203. .PN CorePart .
  204.  
  205. .LP
  206. .Ds 0
  207. .TA .5i 3i
  208. .ta .5i 3i
  209. .IN "ObjectPart" "" "@DEF@"
  210. typedef struct _ObjectPart {
  211.     Widget self;
  212.     WidgetClass widget_class;
  213.     Widget parent;
  214.     Boolean being_destroyed;
  215.     XtCallbackList destroy_callbacks;
  216.     XtPointer constraints;
  217. } ObjectPart;
  218. .De
  219. .LP
  220. All object instances have the
  221. Object
  222. fields as their first component.  The prototypical type
  223. .PN Object
  224. is defined with only this set of fields.
  225. Various routines can cast object pointers, as needed, to specific
  226. object types.
  227.  
  228. .LP
  229. In
  230. .PN IntrinsicP.h :
  231. .Ds 0
  232. .TA .5i 3i
  233. .ta .5i 3i
  234. typedef struct _ObjectRec {
  235.     ObjectPart object;
  236. } ObjectRec, *Object;
  237. .De
  238. .IN "ObjectRec" "" "@DEF@"
  239. .LP
  240. In
  241. .PN Intrinsic.h :
  242. .Ds 0
  243. typedef struct _ObjectRec *Object;
  244. .De
  245.  
  246. .NH 3
  247. Object Resources
  248. .XS
  249. \fB\*(SN Object Resources\fP
  250. .XE
  251. .LP
  252. The resource names, classes, and representation types specified in the
  253. .PN objectClassRec
  254. resource list are
  255. .LP
  256. .TS
  257. lw(1.5i) lw(1.5i) lw(2.5i) .
  258. _
  259. .sp 6p
  260. Name    Class    Representation
  261. .sp 6p
  262. _
  263. .sp 6p
  264. XtNdestroyCallback    XtCCallback    XtRCallback
  265. .sp 6p
  266. _
  267. .TE
  268.  
  269. .NH 3
  270. ObjectPart Default Values
  271. .XS
  272. \fB\*(SN ObjectPart Default Values\fP
  273. .XE
  274. .LP
  275. All fields in
  276. .PN ObjectPart
  277. have the same default values as the corresponding fields in
  278. .PN CorePart .
  279.  
  280. .NH 3
  281. Object Arguments To \*(xI Routines
  282. .XS
  283. \*(SN Object Arguments To \*(xI Routines
  284. .XE
  285. .LP
  286. The WidgetClass arguments to the following procedures may be
  287. .PN objectClass
  288. or any subclass:
  289. .sp
  290. .IP
  291. .PN XtInitializeWidgetClass ,
  292. .PN XtCreateWidget ,
  293. .PN XtVaCreateWidget
  294. .IP
  295. .PN XtIsSubclass ,
  296. .PN XtCheckSubclass
  297. .IP
  298. .PN XtGetResourceList ,
  299. .PN XtGetConstraintResourceList
  300. .sp
  301. .LP
  302. The Widget arguments to the following procedures may be of class
  303. Object
  304. or any subclass:
  305. .sp
  306. .IP
  307. .PN XtCreateWidget ,
  308. .PN XtVaCreateWidget
  309. .IP
  310. .PN XtAddCallback ,
  311. .PN XtAddCallbacks ,
  312. .PN XtRemoveCallback ,
  313. .PN XtRemoveCallbacks ,
  314. .PN XtRemoveAllCallbacks ,
  315. .PN XtCallCallbacks ,
  316. .PN XtHasCallbacks ,
  317. .PN XtCallCallbackList
  318. .IP
  319. .PN XtClass ,
  320. .PN XtSuperclass ,
  321. .PN XtIsSubclass ,
  322. .PN XtCheckSubclass ,
  323. .PN XtIsObject ,
  324. .PN XtIsRectObj ,
  325. .PN XtIsWidget ,
  326. .PN XtIsComposite ,
  327. .PN XtIsConstraint ,
  328. .PN XtIsShell ,
  329. .PN XtIsOverrideShell ,
  330. .PN XtIsWMShell ,
  331. .PN XtIsVendorShell ,
  332. .PN XtIsTransientShell ,
  333. .PN XtIsToplevelShell ,
  334. .PN XtIsApplicationShell .
  335. .IP
  336. .PN XtIsManaged ,
  337. .PN XtIsSensitive
  338. .br
  339. (both will return
  340. .PN False
  341. if argument is not a subclass of
  342. RectObj)
  343. .IP
  344. .PN XtIsRealized
  345. .br
  346. (returns the state of the nearest windowed ancestor
  347. if class of argument is not a subclass of
  348. Core)
  349. .IP
  350. .PN XtWidgetToApplicationContext
  351. .IP    
  352. .PN XtDestroyWidget
  353. .IP
  354. .PN XtParent ,
  355. .PN XtDisplayOfObject ,
  356. .PN XtScreenOfObject ,
  357. .PN XtWindowOfObject
  358. .IP
  359. .PN XtSetKeyboardFocus
  360. (descendant)
  361. .IP
  362. .PN XtGetGC ,
  363. .PN XtReleaseGC
  364. .IP
  365. .PN XtName
  366. .IP
  367. .PN XtSetValues ,
  368. .PN XtGetValues ,
  369. .PN XtVaSetValues ,
  370. .PN XtVaGetValues
  371. .IP
  372. .PN XtGetSubresources ,
  373. .PN XtGetApplicationResources ,
  374. .PN XtVaGetSubresources ,
  375. .PN XtVaGetApplicationResources
  376. .IP
  377. .PN XtConvert ,
  378. .PN XtConvertAndStore
  379. .sp
  380. .LP
  381. The return value of the following procedures will be of class
  382. Object
  383. or a subclass:
  384. .sp
  385. .IP
  386. .PN XtCreateWidget ,
  387. .PN XtVaCreateWidget
  388. .IP
  389. .PN XtParent
  390. .IP
  391. .PN XtNameToWidget
  392. .sp
  393. .LP
  394. The return value of the following procedures will be
  395. .PN objectClass
  396. or a subclass:
  397. .sp
  398. .IP
  399. .PN XtClass ,
  400. .PN XtSuperclass
  401.  
  402. .NH 3
  403. Use of Objects
  404. .XS
  405. \fB\*(SN Use of Objects\fP
  406. .XE
  407. .LP
  408. The
  409. Object
  410. class exists to enable programmers to use the \*(xI'
  411. classing and resource-handling mechanisms for things smaller
  412. and simpler than widgets.
  413. Objects make obsolete many common uses of subresources as described in
  414. sections 9.4, 9.7.2.4, and 9.7.2.5.
  415. .LP
  416. Composite
  417. widget classes that wish to accept nonwidget children must
  418. set the \fIaccepts_objects\fP field in the
  419. .PN CompositeClassExtension
  420. structure to
  421. .PN True .
  422. .PN XtCreateWidget
  423. will otherwise generate an error message on an attempt to create a
  424. nonwidget child.
  425. .LP
  426. Of the classes defined by the \*(xI, only
  427. ApplicationShell
  428. accepts nonwidget children, and the class of any nonwidget child
  429. must not be
  430. .PN rectObjClass
  431. or any subclass.  The intent of allowing
  432. Object
  433. children of
  434. ApplicationShell
  435. is to provide clients a simple mechanism
  436. for establishing the resource-naming root of an object hierarchy.
  437.  
  438. .NH 2
  439. Rectangle Objects
  440. .XS
  441. \fB\*(SN Rectangle Objects\fP
  442. .XE
  443. .LP
  444. The class of rectangle objects is a subclass of
  445. Object
  446. that represents
  447. rectangular areas.  It encapsulates the mechanisms for geometry
  448. management, and is called RectObj
  449. .IN "RectObj" "" "@DEF@"
  450. to avoid conflict with the Xlib
  451. .PN Rectangle
  452. data type.
  453.  
  454. .NH 3
  455. RectObjClassPart Structure
  456. .XS
  457. \*(SN RectObjClassPart Structure
  458. .XE
  459. .LP
  460. As with the
  461. .PN ObjectClassPart
  462. structure, all fields in the
  463. .PN RectObjClassPart
  464. structure have the same
  465. purpose and function as the corresponding fields in
  466. .PN CoreClassPart ;
  467. fields whose names are rect\fI\s+1n\s-1\fP for some integer
  468. \fI\s+1n\s-1\fP are not used for
  469. RectObj but exist to pad the data structure so that it matches
  470. Core's
  471. class record.  The class record initialization must fill all
  472. rect\fI\s+1n\s-1\fP fields with NULL or zero as appropriate to the type.
  473. .LP
  474. .Ds 0
  475. .TA .5i 3i
  476. .ta .5i 3i
  477. .IN "RectObjClassPart" "" "@DEF@"
  478. typedef struct _RectObjClassPart {
  479.     WidgetClass superclass;
  480.     String class_name;
  481.     Cardinal widget_size;
  482.     XtProc class_initialize;
  483.     XtWidgetClassProc class_part_initialize;
  484.     XtEnum class_inited;
  485.     XtInitProc initialize;
  486.     XtArgsProc initialize_hook;
  487.     XtProc rect1;
  488.     XtPointer rect2;
  489.     Cardinal rect3;
  490.     XtResourceList resources;
  491.     Cardinal num_resources;
  492.     XrmClass xrm_class;
  493.     Boolean rect4;
  494.     XtEnum rect5;
  495.     Boolean rect6;
  496.     Boolean rect7;
  497.     XtWidgetProc destroy;
  498.     XtWidgetProc resize;
  499.     XtExposeProc expose;
  500.     XtSetValuesFunc set_values;
  501.     XtArgsFunc set_values_hook;
  502.     XtAlmostProc set_values_almost;
  503.     XtArgsProc get_values_hook;
  504.     XtProc rect9;
  505.     XtVersionType version;
  506.     XtPointer callback_private;
  507.     String rect10;
  508.     XtGeometryHandler query_geometry;
  509.     XtProc rect11;
  510.     XtPointer extension ;
  511. } RectObjClassPart;
  512. .De
  513. .LP
  514. The
  515. RectObj
  516. class record consists of just the
  517. .PN RectObjClassPart .
  518. .LP
  519. .Ds 0
  520. .TA .5i 3i
  521. .ta .5i 3i
  522. .IN "RectObjClassRec" "" "@DEF@"
  523. .IN "RectObjClass" "" "@DEF@"
  524. typedef struct _RectObjClassRec {
  525.     RectObjClassPart rect_class;
  526. } RectObjClassRec, *RectObjClass;
  527. .De
  528. .LP
  529. The predefined class record and pointer for
  530. .PN RectObjClassRec
  531. are
  532. .LP
  533. In
  534. .PN Intrinsic.h :
  535. .Ds 0
  536. extern RectObjClassRec rectObjClassRec;
  537. .De
  538. .LP
  539. In
  540. .PN Intrinsic.h :
  541. .Ds 0
  542. extern WidgetClass rectObjClass;
  543. .De
  544. .LP
  545. The opaque types
  546. .PN RectObj
  547. and
  548. .PN RectObjClass
  549. and the opaque variable
  550. .PN rectObjClass
  551. are defined for generic actions on objects
  552. whose class is RectObj or a subclass of
  553. RectObj.
  554. .PN Intrinsic.h
  555. uses an incomplete structure definition to ensure that the compiler
  556. catches attempts to access private data:
  557. .LP
  558. .Ds 0
  559. typedef struct _RectObjClassRec* RectObjClass;
  560. .De
  561.  
  562. .NH 3
  563. RectObjPart Structure
  564. .XS
  565. \*(SN RectObjPart Structure
  566. .XE
  567. .LP
  568. In addition to the
  569. .PN ObjectPart
  570. fields,
  571. RectObj
  572. objects have the following fields defined in the
  573. .PN RectObjPart
  574. structure.  All fields have the same meaning as the corresponding field in
  575. .PN CorePart .
  576. .LP
  577. .Ds 0
  578. .TA .5i 3i
  579. .ta .5i 3i
  580. .IN "RectObjPart" "" "@DEF@"
  581. typedef struct _RectObjPart {
  582.     Position x, y;
  583.     Dimension width, height;
  584.     Dimension border_width;
  585.     Boolean managed;
  586.     Boolean sensitive;
  587.     Boolean ancestor_sensitive;
  588. } RectObjPart;
  589. .De
  590. .LP
  591. RectObj
  592. objects have the RectObj fields immediately following the Object fields.
  593. .LP
  594. .Ds 0
  595. .TA .5i 3i
  596. .ta .5i 3i
  597. .IN "RectObjRec" "" "@DEF@"
  598. typedef struct _RectObjRec {
  599.     ObjectPart object;
  600.     RectObjPart rectangle;
  601. } RectObjRec, *RectObj;
  602. .De
  603. .LP
  604. In
  605. .PN Intrinsic.h :
  606. .Ds 0
  607. typedef struct _RectObjRec* RectObj;
  608. .De
  609.  
  610. .NH 3
  611. RectObj Resources
  612. .XS
  613. \fB\*(SN RectObj Resources\fP
  614. .XE
  615. .LP
  616. The resource names, classes, and representation types that are specified in the
  617. .PN rectObjClassRec
  618. resource list are
  619. .TS
  620. lw(1.5i) lw(1.5i) lw(2.5i) .
  621. _
  622. .sp 6p
  623. Name    Class    Representation
  624. .sp 6p
  625. _
  626. .sp 6p
  627. XtNancestorSensitive    XtCSensitive    XtRBoolean
  628. XtNborderWidth    XtCBorderWidth    XtRDimension
  629. XtNheight    XtCHeight    XtRDimension
  630. XtNsensitive    XtCSensitive    XtRBoolean
  631. XtNwidth    XtCWidth    XtRDimension
  632. XtNx    XtCPosition    XtRPosition
  633. XtNy    XtCPosition    XtRPosition
  634. .sp 6p
  635. _
  636. .TE
  637.  
  638. .NH 3
  639. RectObjPart Default Values
  640. .XS
  641. \fB\*(SN RectObjPart Default Values\fP
  642. .XE
  643. .LP
  644. All fields in
  645. .PN RectObjPart
  646. have the same default values as the corresponding fields in
  647. .PN CorePart .
  648.  
  649. .NH 3
  650. Widget Arguments To \*(xI Routines
  651. .XS
  652. \fB\*(SNWidget Arguments To \*(xI Routines\fP
  653. .XE
  654. .LP
  655. The WidgetClass arguments to the following procedures may be
  656. .PN rectObjClass
  657. or any subclass:
  658. .sp
  659. .IP
  660. .PN XtCreateManagedWidget ,
  661. .PN XtVaCreateManagedWidget
  662. .sp
  663. .LP
  664. The Widget arguments to the following procedures may be of class
  665. RectObj
  666. or any subclass:
  667. .sp
  668. .IP
  669. .PN XtConfigureWidget ,
  670. .PN XtMoveWidget ,
  671. .PN XtResizeWidget
  672. .IP
  673. .PN XtMakeGeometryRequest ,
  674. .PN XtMakeResizeRequest
  675. .IP
  676. .PN XtManageChildren ,
  677. .PN XtManageChild ,
  678. .PN XtUnmanageChildren ,
  679. .PN XtUnmanageChild
  680. .IP
  681. .PN XtQueryGeometry
  682. .IP
  683. .PN XtSetSensitive
  684. .IP
  685. .PN XtTranslateCoords
  686. .sp
  687. .LP
  688. The return value of the following procedures will be of class
  689. RectObj
  690. or a subclass:
  691. .sp
  692. .IP
  693. .PN XtCreateManagedWidget ,
  694. .PN XtVaCreateManagedWidget
  695.  
  696. .NH 3
  697. Use of Rectangle Objects
  698. .XS
  699. \*(SN Use of Rectangle Objects
  700. .XE
  701. .LP
  702. RectObj
  703. can be subclassed to provide widgetlike objects (sometimes
  704. called gadgets) that do not use windows and do not have
  705. features often unused in simple widgets.  This can save memory
  706. resources both in the server and in applications
  707. but requires additional support code in the parent.
  708. In the following
  709. discussion, \fIrectobj\fP refers only to objects
  710. whose class is RectObj or a subclass of
  711. RectObj
  712. but not Core or a subclass of
  713. Core. 
  714. .LP
  715. Composite
  716. widget classes that wish to accept rectobj children must set
  717. the \fIaccepts_objects\fP field in the
  718. .PN CompositeClassExtension
  719. extension structure to
  720. .PN True .
  721. .PN XtCreateWidget
  722. or
  723. .PN XtCreateManagedWidget
  724. will otherwise generate an error if called to create a nonwidget child.
  725. If the composite widget supports only children of class
  726. RectObj
  727. or a subclass (i.e., not of the general Object class), it
  728. must declare an insert_child procedure and check the subclass of each
  729. new child in that procedure.  None of the classes defined by the
  730. \*(xI accept rectobj children.
  731. .LP
  732. If gadgets are defined in an object set, the parent is responsible for
  733. much more than the parent of a widget.  The parent must request and handle
  734. input events that occur for the gadget and is responsible for making
  735. sure that when it receives an exposure event the gadget children get
  736. drawn correctly.
  737. Rectobj children may
  738. have expose procedures
  739. specified in their class records, but the parent is free to
  740. ignore them, instead drawing the contents of the child itself.  This
  741. can potentially save graphics context switching.  The precise contents
  742. of the exposure event and region arguments to the RectObj expose
  743. procedure are not specified by the \*(xI; a particular rectangle object is
  744. free to define the coordinate system origin (self-relative or
  745. parent-relative) and whether or not the rectangle or region is assumed to
  746. have been intersected with the visible region of the object.
  747. .LP
  748. In general, it is expected that a composite widget that accepts
  749. nonwidget children will document those children it is able to handle,
  750. since a gadget cannot be viewed as a completely self-contained entity,
  751. as can a widget.  Since a particular composite widget class is usually
  752. designed to handle nonwidget children of only a limited set of classes, it should
  753. check the classes of newly added children in its insert_child
  754. procedure to make sure that it can deal with them.
  755. .LP
  756. The \*(xI will clear areas of a parent window obscured by
  757. rectobj children, causing exposure events, under the following
  758. circumstances:
  759. .IP \(bu 5
  760. A rectobj child is managed or unmanaged.
  761. .IP \(bu 5
  762. In a call to
  763. .PN XtSetValues
  764. on a rectobj child, one or more of the set_values procedures returns
  765. .PN True .
  766. .IP \(bu 5
  767. In a call to
  768. .PN XtConfigureWidget
  769. on a rectobj child, areas will
  770. be cleared corresponding to both the old and the new child
  771. geometries, including the border, if the geometry changes.
  772. .IP \(bu 5
  773. In a call to
  774. .PN XtMoveWidget
  775. on a rectobj child, areas will be
  776. cleared corresponding to both the old and the new child
  777. geometries, including the border, if the geometry changes.
  778. .IP \(bu 5
  779. In a call to
  780. .PN XtResizeWidget
  781. on a rectobj child, an single
  782. rectangle will be cleared corresponding to the larger of the
  783. old and the new child geometries if they are different.
  784. .IP \(bu 5
  785. In a call to
  786. .PN XtMakeGeometryRequest
  787. (or
  788. .PN XtMakeResizeRequest )
  789. on a rectobj child with
  790. .PN XtQueryOnly
  791. not set, if the manager returns
  792. .PN XtGeometryYes ,
  793. two rectangles will be cleared corresponding to both the old and
  794. the new child geometries.
  795. .LP
  796. Stacking order is not supported for rectobj children.  Composite widgets with
  797. rectobj children are free to define any semantics desired if the child
  798. geometries overlap, including making this an error.
  799. .LP
  800. When a rectobj is playing the role of a widget, developers must be
  801. reminded to avoid making assumptions about the object passed in the
  802. Widget argument to a callback procedure.
  803.  
  804. .NH 2
  805. Undeclared Class
  806. .XS
  807. \*(SN Undeclared Class
  808. .XE
  809. .LP
  810. The \*(xI define an unnamed class between
  811. RectObj
  812. and
  813. Core
  814. for possible future use by the X Consortium. The only assumptions that
  815. may be made about the unnamed class are
  816. .IP \(bu 5
  817. the \fIcore_class.superclass\fP field of
  818. .PN coreWidgetClassRec
  819. contains a pointer to the unnamed class record.
  820. .IP \(bu 5
  821. a pointer to the unnamed class record when dereferenced as an
  822. .PN ObjectClass
  823. will contain a pointer to
  824. .PN rectObjClassRec
  825. in its \fIobject_class.superclass\fP field.
  826. .LP
  827. Except for the above, the contents of the class record for this class
  828. and the result of an attempt to subclass or to create a widget of this
  829. unnamed class are undefined.
  830.  
  831. .NH 2
  832. Widget Arguments To \*(xI Routines
  833. .XS
  834. \*(SN Widget Arguments To \*(xI Routines
  835. .XE
  836. .LP
  837. The WidgetClass arguments to the following procedures must be of class
  838. Shell
  839. or a subclass:
  840. .sp
  841. .IP
  842. .PN XtCreatePopupShell ,
  843. .PN XtVaCreatePopupShell ,
  844. .PN XtAppCreateShell ,
  845. .PN XtVaAppCreateShell
  846. .sp
  847. .LP
  848. The Widget arguments to the following procedures must be of class
  849. Core
  850. or any subclass:
  851. .sp
  852. .IP
  853. .PN XtCreatePopupShell ,
  854. .PN XtVaCreatePopupShell
  855. .IP
  856. .PN XtAddEventHandler ,
  857. .PN XtAddRawEventHandler ,
  858. .PN XtRemoveEventHandler ,
  859. .br
  860. .PN XtRemoveRawEventHandler ,
  861. .PN XtInsertEventHandler ,
  862. .PN XtInsertRawEventHandler
  863. .IP
  864. .PN XtAddGrab ,
  865. .PN XtRemoveGrab ,
  866. .PN XtGrabKey ,
  867. .PN XtGrabKeyboard ,
  868. .PN XtUngrabKey ,
  869. .PN XtUngrabKeyboard ,
  870. .PN XtGrabButton ,
  871. .PN XtGrabPointer ,
  872. .PN XtUngrabButton ,
  873. .br
  874. .PN XtUngrabPointer
  875. .IP
  876. .PN XtBuildEventMask
  877. .IP
  878. .PN XtCreateWindow ,
  879. .PN XtDisplay ,
  880. .PN XtScreen ,
  881. .PN XtWindow
  882. .IP
  883. .PN XtNameToWidget
  884. .IP
  885. .PN XtGetSelectionValue ,
  886. .PN XtGetSelectionValues ,
  887. .PN XtOwnSelection ,
  888. .PN XtDisownSelection ,
  889. .PN XtOwnSelectionIncremental ,
  890. .PN XtGetSelectionValueIncremental ,
  891. .PN XtGetSelectionValuesIncremental ,
  892. .br
  893. .PN XtGetSelectionRequest
  894. .IP
  895. .PN XtInstallAccelerators ,
  896. .PN XtInstallAllAccelerators
  897. (both destination and source)
  898. .IP
  899. .PN XtAugmentTranslations ,
  900. .PN XtOverrideTranslations ,
  901. .PN XtUninstallTranslations ,
  902. .br
  903. .PN XtCallActionProc
  904. .IP
  905. .PN XtMapWidget ,
  906. .PN XtUnmapWidget
  907. .IP
  908. .PN XtRealizeWidget ,
  909. .PN XtUnrealizeWidget
  910. .IP
  911. .PN XtSetMappedWhenManaged
  912. .IP
  913. .PN XtCallAcceptFocus ,
  914. .PN XtSetKeyboardFocus
  915. (subtree)
  916. .IP
  917. .PN XtResizeWindow
  918. .IP
  919. .PN XtSetWMColormapWindows
  920. .sp
  921. .LP
  922. The Widget arguments to the following procedures must be of class
  923. Composite
  924. or any subclass:
  925. .sp
  926. .IP
  927. .PN XtCreateManagedWidget ,
  928. .PN XtVaCreateManagedWidget
  929. .sp
  930. .LP
  931. The Widget arguments to the following procedures must be of a subclass of
  932. Shell:
  933. .sp
  934. .IP
  935. .PN XtPopdown ,
  936. .PN XtCallbackPopdown ,
  937. .PN XtPopup ,
  938. .PN XtCallbackNone ,
  939. .PN XtCallbackNonexclusive ,
  940. .PN XtCallbackExclusive ,
  941. .PN XtPopupSpringLoaded
  942. .sp
  943. .LP
  944. The return value of the following procedure will be of class
  945. Core
  946. or a subclass:
  947. .sp
  948. .IP
  949. .PN XtWindowToWidget
  950. .sp
  951. .LP
  952. The return value of the following procedures will be of a subclass of
  953. Shell :
  954. .sp
  955. .IP
  956. .PN XtAppCreateShell ,
  957. .PN XtVaAppCreateShell ,
  958. .PN XtAppInitialize ,
  959. .PN XtVaAppInitialize ,
  960. .PN XtCreatePopupShell ,
  961. .PN XtVaCreatePopupShell
  962. .bp
  963.