home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH02 < prev    next >
Encoding:
Text File  |  1991-08-27  |  84.6 KB  |  2,803 lines
  1. .\" $XConsortium: CH02,v 1.11 91/08/27 09:59:40 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 2\fP\s-1
  20.  
  21. \s+1\fBWidget Instantiation\fP\s-1
  22. .sp 2
  23. .nr H1 2
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 2 \- Widget Instantiation
  31. .XE
  32. A hierarchy of widget instances constitutes a widget tree.
  33. The shell widget returned by
  34. .PN XtAppCreateShell
  35. is the root of the widget tree instance.
  36. The widgets with one or more children are the intermediate nodes of that tree,
  37. and the widgets with no children of any kind are the leaves of the widget tree.
  38. With the exception of pop-up children (see Chapter 5),
  39. this widget tree instance defines the associated X Window tree.
  40. .LP
  41. Widgets can be either composite or primitive.
  42. Both kinds of widgets can contain children,
  43. but the \*(xI provide a set of management mechanisms for constructing
  44. and interfacing between composite widgets, their children, and
  45. other clients.
  46. .LP
  47. Composite widgets, that is, members of the class
  48. .PN compositeWidgetClass ,
  49. are containers for an arbitrary 
  50. but widget implementation-defined collection of children,
  51. which may be instantiated by the composite widget itself, 
  52. by other clients, or by a combination of the two.
  53. Composite widgets also contain methods for managing the geometry (layout) 
  54. of any child widget.
  55. Under unusual circumstances,
  56. a composite widget may have zero children, 
  57. but it usually has at least one.
  58. By contrast, 
  59. primitive widgets that contain children typically instantiate 
  60. specific children of known classes themselves and do not expect external 
  61. clients to do so.
  62. Primitive widgets also do not have general geometry management methods.
  63. .LP
  64. In addition,
  65. the \*(xI recursively perform many operations 
  66. (for example, realization and destruction)
  67. on composite widgets and all their children.
  68. Primitive widgets that have children must be prepared 
  69. to perform the recursive operations themselves on behalf of their children. 
  70. .LP
  71. A widget tree is manipulated by several \*(xI functions.
  72. For example,
  73. .PN XtRealizeWidget
  74. traverses the tree downward and recursively realizes all 
  75. pop-up widgets and children of composite widgets.
  76. .PN XtDestroyWidget
  77. traverses the tree downward and destroys all pop-up widgets 
  78. and children of composite widgets.
  79. The functions that fetch and modify resources traverse the tree upward
  80. and determine the inheritance of resources from a widget's ancestors.
  81. .PN XtMakeGeometryRequest
  82. traverses the tree up one level and calls the geometry manager 
  83. that is responsible for a widget child's geometry.
  84. .LP
  85. To facilitate upward traversal of the widget tree,
  86. each widget has a pointer to its parent widget.
  87. The
  88. Shell 
  89. widget that
  90. .PN XtAppCreateShell 
  91. returns has a \fIparent\fP pointer of NULL.
  92. .LP
  93. To facilitate downward traversal of the widget tree,
  94. the \fIchildren\fP field of
  95. each composite widget is a pointer to an array of child widgets,
  96. which includes all normal children created,
  97. not just the subset of children that are managed by the composite widget's
  98. geometry manager.
  99. Primitive widgets
  100. that instantiate children are entirely responsible for all operations
  101. that require downward traversal below themselves.
  102. In addition,
  103. every widget has a pointer to an array of pop-up children.
  104.  
  105. .NH 2
  106. Initializing the \*(tk
  107. .XS
  108. \fB\*(SN Initializing the \*(tk\fP
  109. .XE
  110. .LP
  111. Before an application can call any \*(xI function
  112. other than
  113. .PN XtSetLanguageProc ,
  114. it must initialize the \*(xI by using
  115. .IP \(bu 5
  116. .PN XtToolkitInitialize ,
  117. which initializes the \*(xI internals.
  118. .IP \(bu 5
  119. .PN XtCreateApplicationContext ,
  120. which initializes the per-application state.
  121. .IP \(bu 5
  122. .PN XtDisplayInitialize
  123. or
  124. .PN XtOpenDisplay ,
  125. which initializes the per-display state.
  126. .IP \(bu 5
  127. .PN XtAppCreateShell ,
  128. which creates the root of a widget tree.
  129. .LP
  130. or an application can call the convenience procedure
  131. .PN XtAppInitialize
  132. which combines the functions of the preceding procedures.
  133. An application wishing to use the ANSI C locale mechanism should call
  134. .PN XtSetLanguageProc
  135. prior to calling
  136. .PN XtDisplayInitialize ,
  137. .PN XtOpenDisplay ,
  138. or
  139. .PN XtAppInitialize .
  140. .LP
  141. Multiple instances of \*(tk applications may be implemented 
  142. in a single address space.
  143. Each instance needs to be able to read
  144. input and dispatch events independently of any other instance.
  145. Further, an application instance may need multiple display connections 
  146. to have widgets on multiple displays.
  147. From the application's point of view, multiple display connections
  148. usually are treated together as a single unit
  149. for purposes of event dispatching.
  150. .IN "application context" "" "@DEF@"
  151. To accommodate both requirements, 
  152. the \*(xI define application contexts,
  153. each of which provides the information needed to distinguish one application
  154. instance from another.
  155. The major component of an application context is a list of one or more X
  156. .PN Display
  157. pointers for that application.
  158. The \*(xI handle all display connections within a single application
  159. context simultaneously, handling input in a round-robin fashion.
  160. The application context type
  161. .PN XtAppContext
  162. .IN "XtAppContext" "" "@DEF@"
  163. is opaque to clients.
  164. .sp
  165. .LP
  166. To initialize the \*(xI internals, use
  167. .PN XtToolkitInitialize .
  168. .IN "XtToolkitInitialize" "" "@DEF@"
  169. .FD 0
  170. void XtToolkitInitialize()
  171. .FN
  172. .LP
  173. The semantics of calling
  174. .PN XtToolkitInitialize
  175. more than once are undefined.
  176. .sp
  177. .LP
  178. To create an application context, use
  179. .PN XtCreateApplicationContext .
  180. .IN "XtCreateApplicationContext" "" "@DEF@"
  181. .FD 0
  182. XtAppContext XtCreateApplicationContext()
  183. .FN
  184. The
  185. .PN XtCreateApplicationContext
  186. function returns an application context,
  187. which is an opaque type.
  188. Every application must have at least one application context.
  189. .sp
  190. .LP
  191. To destroy an application context and close any
  192. remaining display connections in it, use
  193. .PN XtDestroyApplicationContext .
  194. .IN "XtDestroyApplicationContext" "" "@DEF@"
  195. .FD 0
  196. void XtDestroyApplicationContext(\fIapp_context\fP)
  197. .br
  198.       XtAppContext \fIapp_context\fP;
  199. .FN
  200. .IP \fIapp_context\fP 1i
  201. Specifies the application context.
  202. .LP
  203. The
  204. .PN XtDestroyApplicationContext
  205. function destroys the specified application context as soon as it is safe 
  206. to do so.
  207. If called from within an event dispatch (for example, in a callback procedure),
  208. .PN XtDestroyApplicationContext
  209. does not destroy the application context until the dispatch is complete.
  210. .sp
  211. .LP
  212. To get the application context in which a given widget was created, use
  213. .PN XtWidgetToApplicationContext .
  214. .IN "XtWidgetToApplicationContext" "" "@DEF@"
  215. .FD 0
  216. XtAppContext XtWidgetToApplicationContext(\fIw\fP)
  217. .br
  218.       Widget \fIw\fP;
  219. .FN
  220. .IP \fIw\fP 1i
  221. Specifies the widget for which you want the application context.  \*(oI
  222. .LP
  223. The
  224. .PN XtWidgetToApplicationContext
  225. function returns the application context for the specified widget.
  226. .sp
  227. .LP
  228. To initialize a display and add it to an application context, use
  229. .PN XtDisplayInitialize .
  230. .IN "XtDisplayInitialize" "" "@DEF@"
  231. .FD 0
  232. void XtDisplayInitialize(\fIapp_context\fP, \fIdisplay\fP, \
  233. \fIapplication_name\fP, \fIapplication_class\fP,
  234. .br
  235.                        \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP)
  236. .br
  237.       XtAppContext \fIapp_context\fP;
  238. .br
  239.       Display *\fIdisplay\fP;
  240. .br
  241.       String \fIapplication_name\fP;
  242. .br
  243.       String \fIapplication_class\fP;
  244. .br
  245.       XrmOptionDescRec *\fIoptions\fP;
  246. .br
  247.       Cardinal \fInum_options\fP;
  248. .br
  249.       int *\fIargc\fP;
  250. .br
  251.       String *\fIargv\fP;
  252. .FN
  253. .IP \fIapp_context\fP 1.4i
  254. Specifies the application context.
  255. .IP \fIdisplay\fP 1.4i
  256. Specifies a previously opened display connection.  Note that a single
  257. display connection can be in at most one application context.
  258. .IP \fIapplication_name\fP 1.4i
  259. Specifies the name of the application instance.
  260. .IP \fIapplication_class\fP 1.4i
  261. Specifies the class name of this application,
  262. which is usually the generic name for all instances of this application.
  263. .IP \fIoptions\fP 1.4i
  264. Specifies how to parse the command line for any application-specific resources.
  265. The \fIoptions\fP argument is passed as a parameter to
  266. .PN XrmParseCommand .
  267. For further information,
  268. see Section 15.9 in \fI\*(xL\fP and Section 2.4 of this specification.
  269. .IP \fInum_options\fP 1.4i
  270. Specifies the number of entries in the options list.
  271. .IP \fIargc\fP 1.4i
  272. Specifies a pointer to the number of command line parameters.
  273. .IP \fIargv\fP 1.4i
  274. Specifies the list of command line parameters.
  275. .LP
  276. The
  277. .PN XtDisplayInitialize
  278. function retrieves the language string to be
  279. used for the specified display (see Section 11.11),
  280. calls the language procedure (if set) with that language string,
  281. builds the resource database for the default screen, calls the Xlib
  282. .PN XrmParseCommand
  283. function to parse the command line, 
  284. and performs other per-display initialization.
  285. After 
  286. .PN XrmParseCommand 
  287. has been called,
  288. \fIargc\fP and \fIargv\fP contain only those parameters that
  289. were not in the standard option table or in the table specified by the
  290. \fIoptions\fP argument.
  291. If the modified \fIargc\fP is not zero,
  292. most applications simply print out the modified \fIargv\fP along with a message
  293. listing the allowable options.
  294. On POSIX-based systems,
  295. the application name is usually the final component of \fIargv\fP[0].
  296. If the synchronous resource is
  297. .PN True ,
  298. .PN XtDisplayInitialize
  299. calls the Xlib
  300. .PN XSynchronize
  301. function to put Xlib into synchronous mode for this display connection
  302. and any others currently open in the application context.
  303. See Sections 2.3 and 2.4 for details on the \fIapplication_name\fP,
  304. \fIapplication_class\fP, \fIoptions\fP, and \fInum_options\fP arguments.
  305. .LP
  306. .PN XtDisplayInitialize
  307. calls
  308. .PN XrmSetDatabase
  309. to associate the resource database of the default screen with the
  310. display before returning.
  311.  
  312. .bp
  313. .LP
  314. To open a display, initialize it, and then
  315. add it to an application context, use 
  316. .PN XtOpenDisplay .
  317. .IN "XtOpenDisplay" "" "@DEF@"
  318. .FD 0
  319. Display *XtOpenDisplay(\fIapp_context\fP, \fIdisplay_string\fP, \
  320. \fIapplication_name\fP, \fIapplication_class\fP, 
  321. .br
  322.                        \fIoptions\fP, \fInum_options\fP, \fIargc\fP, \fIargv\fP)
  323. .br
  324.        XtAppContext \fIapp_context\fP;
  325. .br
  326.        String \fIdisplay_string\fP;
  327. .br
  328.        String \fIapplication_name\fP;
  329. .br
  330.        String \fIapplication_class\fP;
  331. .br
  332.        XrmOptionDescRec *\fIoptions\fP;
  333. .br
  334.        Cardinal \fInum_options\fP;
  335. .br
  336.        int *\fIargc\fP;
  337. .br
  338.        String *\fIargv\fP;
  339. .FN
  340. .IP \fIapp_context\fP 1.4i
  341. Specifies the application context.
  342. .IP \fIdisplay_string\fP 1.4i
  343. Specifies the display string, or NULL.
  344. .IP \fIapplication_name\fP 1.4i
  345. Specifies the name of the application instance, or NULL.
  346. .IP \fIapplication_class\fP 1.4i
  347. Specifies the class name of this application,
  348. which is usually the generic name for all instances of this application.
  349. .IP \fIoptions\fP 1.4i
  350. Specifies how to parse the command line for any application-specific resources.
  351. The options argument is passed as a parameter to
  352. .PN XrmParseCommand .
  353. .IP \fInum_options\fP 1.4i
  354. Specifies the number of entries in the options list.
  355. .IP \fIargc\fP 1.4i
  356. Specifies a pointer to the number of command line parameters.
  357. .IP \fIargv\fP 1.4i
  358. Specifies the list of command line parameters.
  359. .LP
  360. The
  361. .PN XtOpenDisplay
  362. function calls
  363. .PN XOpenDisplay 
  364. with the specified \fIdisplay_string\fP.
  365. If \fIdisplay_string\fP is NULL,
  366. .PN XtOpenDisplay
  367. uses the current value of the \-display option specified in \fIargv\fP.
  368. If no display is specified in \fIargv\fP,
  369. the user's default display is retrieved from the environment.
  370. On POSIX-based systems, 
  371. this is the value of the
  372. .PN \s-1DISPLAY\s+1
  373. environment variable.
  374. .LP
  375. If this succeeds,
  376. .PN XtOpenDisplay
  377. then calls
  378. .PN XtDisplayInitialize
  379. and passes it the opened display and
  380. the value of the \-name option specified in \fIargv\fP as the application name.
  381. If no \-name option is specified
  382. and \fIapplication_name\fP is
  383. non-NULL, \fIapplication_name\fP is passed to
  384. .PN XtDisplayInitialize .
  385. If \fIapplication_name\fP is NULL and if the environment variable
  386. .PN \s-1RESOURCE_NAME\s+1
  387. is set, the value of
  388. .PN \s-1RESOURCE_NAME\s+1
  389. is used.  Otherwise, the application
  390. name is the name used to invoke the program.  On implementations that
  391. conform to ANSI C Hosted Environment support, the application name will
  392. be \fIargv\fP[0] less any directory and file type components, that is, the
  393. final component of \fIargv\fP[0], if specified.  If \fIargv\fP[0] does not exist or
  394. is the empty string, the application name is ``main''.
  395. .PN XtOpenDisplay
  396. returns the newly opened display or NULL if it failed.
  397. .sp
  398. .LP
  399. To close a display and remove it from an application context, use
  400. .PN XtCloseDisplay .
  401. .IN "XtCloseDisplay" "" "@DEF@"
  402. .FD 0
  403. void XtCloseDisplay(\fIdisplay\fP)
  404. .br
  405.       Display *\fIdisplay\fP;
  406. .FN
  407. .IP \fIdisplay\fP 1i
  408. Specifies the display.
  409. .LP
  410. The
  411. .PN XtCloseDisplay
  412. function calls
  413. .PN XCloseDisplay
  414. with the specified \fIdisplay\fP as soon as it is safe to do so.
  415. If called from within an event dispatch (for example, a callback procedure),
  416. .PN XtCloseDisplay
  417. does not close the display until the dispatch is complete.
  418. Note that applications need only call
  419. .PN XtCloseDisplay
  420. if they are to continue executing after closing the display; 
  421. otherwise, they should call
  422. .PN XtDestroyApplicationContext
  423. or just exit.
  424.  
  425. .NH 2
  426. Establishing the Locale
  427. .XS
  428. \fB\*(SN Establishing the Locale\fP
  429. .XE
  430.  
  431. .LP
  432. Resource databases are specified to be created in the current process
  433. locale.  During display initialization prior to creating the
  434. per-screen resource database, the \*(xI will call out to a specified
  435. application procedure to set the locale according to options found on
  436. the command line or in the per-display resource specifications.
  437. .LP
  438. The callout procedure provided by the application is of type
  439. .PN XtLanguageProc .
  440. .IN "XtLanguageProc" "" "@DEF@"
  441.  
  442. .FD 0
  443. typedef String (*XtLanguageProc)(Display*, String, XtPointer);
  444. .br
  445.       Display *\fIdisplay\fP;
  446. .br
  447.       String \fIlanguage\fP;
  448. .br
  449.       XtPointer \fIclient_data\fP;
  450. .FN
  451. .IP \fIdisplay\fP 1i
  452. Passes the display.
  453. .IP \fIlanguage\fP
  454. Passes the initial language value obtained from the command line
  455. or server per-display resource specifications.
  456. .IP \fIclient_data\fP
  457. Passes the additional client data specified in the call to
  458. .PN XtSetLanguageProc .
  459. .LP
  460. The language procedure allows an application to set the locale to
  461. the value of the language resource determined by
  462. .PN XtDisplayInitialize .
  463. The function returns a new language string that
  464. will be subsequently used by
  465. .PN XtDisplayInitialize
  466. to establish the path for loading resource files.  The returned
  467. string  will be copied by the \*(xI into new memory.
  468.  
  469. .sp
  470. .LP
  471. Initially, no language procedure is set by the \*(xI.
  472. To set the language procedure for use by
  473. .PN XtDisplayInitialize
  474. use
  475. .PN XtSetLanguageProc .
  476. .IN XtSetLanguageProc "" "@DEF@"
  477. .IN "language procedure" "" "@DEF@
  478. .FD 0
  479. XtLanguageProc XtSetLanguageProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
  480. .br
  481.       XtAppContext \fIapp_context\fP;
  482. .br
  483.       XtLanguageProc \fIproc\fP;
  484. .br
  485.       XtPointer \fIclient_data\fP;
  486. .FN
  487. .IP \fIapp_context\fP 1i
  488. Specifies the application context in which the language procedure is
  489. to be used, or NULL.
  490. .IP \fIproc\fP 1i
  491. Specifies the language procedure.
  492. .IP \fIclient_data\fP 1i
  493. Specified additional client data to be passed to the language
  494. procedure when it is called.
  495. .LP
  496. .PN XtSetLanguageProc
  497. sets the language procedure that will be called from
  498. .PN XtDisplayInitialize
  499. for all subsequent Displays initialized in the specified application
  500. context.   If \fIapp_context\fP is NULL, the specified language
  501. procedure is registered in all application contexts created by the
  502. calling process, including any future application contexts that may
  503. be created.   If \fIproc\fP is NULL a default language procedure is
  504. registered.
  505. .PN XtSetLanguageProc
  506. returns the previously registered language procedure.
  507. If a language procedure has not yet been registered, the return value
  508. is unspecified but if this return value is used in a subsequent call to
  509. .PN XtSetLanguageProc ,
  510. it will cause the default language procedure to be registered.
  511. .LP
  512. The default language procedure does the following:
  513. .IP \(bu 5
  514. Sets the locale according to the environment.  On ANSI C-based
  515. systems this is done by calling
  516. .PN setlocale (
  517. .PN LC_ALL ,
  518. \fIlanguage\fP ).
  519. If an error is encountered a warning message is issued with
  520. .PN XtWarning .
  521. .IP \(bu 5
  522. Calls
  523. .PN XSupportsLocale
  524. to verify that the current locale is supported.
  525. If the locale is not supported, a warning message is issued with
  526. .PN XtWarning
  527. and the locale is set to ``C''.
  528. .IP \(bu 5
  529. Calls
  530. .PN XSetLocaleModifiers
  531. specifying the empty string.
  532. .IP \(bu 5
  533. Returns the value of the current locale.  On ANSI C-based systems this
  534. is the return value from a final call to
  535. .PN setlocale (
  536. .PN LC_ALL ,
  537. NULL ).
  538. .LP
  539. A client wishing to use this mechanism to establish locale can do so
  540. by calling
  541. .PN XtSetLanguageProc
  542. prior to
  543. .PN XtDisplayInitialize ,
  544. as in the following example.
  545. .LP
  546. .Ds 0
  547. .TA .5i
  548.     Widget top;
  549.     XtSetLanguageProc(NULL, NULL, NULL);
  550.     top = XtAppInitialize( ... );
  551.     ...
  552. .De
  553.  
  554. .NH 2
  555. Loading the Resource Database
  556. .XS
  557. \fB\*(SN Loading the Resource Database\fP
  558. .XE
  559.  
  560. .LP
  561. The
  562. .PN XtDisplayInitialize
  563. function first determines the language
  564. string to be used for the specified display.  It then
  565. creates a resource database for the default screen of the display by
  566. combining the following sources in order, with the entries in the
  567. first named source having highest precedence:
  568.  
  569. .IP \(bu 5
  570. Application command line (\fIargc\fP, \fIargv\fP).
  571. .IP \(bu 5
  572. Per-host user environment resource file on the local host.
  573. .IP \(bu 5
  574. Per-screen resource specifications from the server.
  575. .IP \(bu 5
  576. Per-display resource specifications from the server or from
  577. .br
  578. the user preference file on the local host.
  579. .IP \(bu 5
  580. Application-specific user resource file on the local host.
  581. .IP \(bu 5
  582. Application-specific class resource file on the local host.
  583.  
  584. .LP
  585. When the resource database for a particular screen on the display
  586. is needed (either internally, or when
  587. .PN XtScreenDatabase
  588. is called),
  589. it is created in the following manner using the sources listed
  590. above in the same order:
  591.  
  592. .IP \(bu 5
  593. A temporary database, the ``server resource database'', is
  594. created from the string returned by
  595. .PN XResourceManagerString
  596. or, if
  597. .PN XResourceManagerString
  598. returns NULL, the contents of a resource file in the user's home
  599. directory.  On POSIX-based systems, the usual name for this user
  600. preference resource file is $HOME/\fB.Xdefaults\fP.
  601. .IN ".Xdefaults" "" "@DEF@"
  602.  
  603. .IP \(bu 5
  604. If a language procedure has been set,
  605. .PN XtDisplayInitialize
  606. first searches the command line for the option ``-xnlLanguage'', or
  607. for a -xrm option that specifies the xnlLanguage/XnlLanguage resource,
  608. as specified by Section 2.4.
  609. If such a resource is found, the value is assumed to be
  610. entirely in XPCS, the X Portable Character Set.  If neither option is
  611. specified on the command line,
  612. .PN XtDisplayInitialize
  613. queries the server resource database (which is assumed to be entirely
  614. in XPCS) for the resource
  615. \fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP
  616. where \fIname\fP
  617. .IN "xnlLanguage" "" "@DEF@"
  618. .IN "Resources" "xnlLanguage"
  619. and \fIClass\fP are the \fIapplication_name\fP and
  620. \fIapplication_class\fP specified to
  621. .PN XtDisplayInitialize .
  622. The language procedure is then invoked with
  623. the resource value if found, else the empty string.  The
  624. string returned from the language procedure is saved for all future
  625. references in the \*(xI that require the per-display language string.
  626.  
  627. .IP \(bu 5
  628. The screen resource database is initialized by parsing the command
  629. line in the manner specified by Section 2.4.
  630.  
  631. .IP \(bu 5
  632. If a language procedure has not been set,
  633. the initial database is then queried for the resource
  634. \fIname\fP\fB.xnlLanguage\fP, class \fIClass\fP\fB.XnlLanguage\fP
  635. as specified above.
  636. If this database query fails, the server resource database is
  637. queried; if this query also fails, the language is determined from
  638. the environment; on POSIX-based systems, this is done by retrieving the
  639. value of the
  640. .PN \s-1LANG\s+1
  641. environment variable.  If no language string is
  642. found, the empty string is used.
  643. This language string is saved for all future references in the \*(xI
  644. that require the per-display language string.
  645.  
  646. .IP \(bu 5
  647. After determining the language string, the user's environment resource
  648. file is then merged into the initial resource database if the file exists.
  649. This file is user-, host-, and process-specific and is expected to
  650. contain user preferences that are to override those specifications in
  651. the per-display and per-screen resources.
  652. On POSIX-based systems, the user's environment resource file name is
  653. specified by the value of the
  654. .PN \s-1XENVIRONMENT\s+1
  655. environment variable.
  656. If this environment variable does not exist, the user's home directory
  657. is searched for a file named
  658. .PN \&.Xdefaults-\fIhost\fP ,
  659. where \fIhost\fP is the host name of the machine on which the
  660. application is running.
  661.  
  662. .IP \(bu 5
  663. The per-screen resource specifications are then merged into the screen
  664. resource database, if they exist.  These specifications are the string
  665. returned by
  666. .PN XScreenResourceString
  667. for the respective screen and are owned entirely by the user.
  668.  
  669. .IP \(bu 5
  670. Next, the server resource database created earlier is merged into the
  671. screen resource database.  The server property, and corresponding user
  672. preference file, are owned and constructed entirely by the user.
  673.  
  674. .IP \(bu 5
  675. The application-specific user resource file from the local host is
  676. then merged into the screen resource database.
  677. This file contains user customizations and is stored
  678. in a directory owned by the user.
  679. Either the user or the application or both can store resource specifications
  680. in the file.  Each should be prepared to find and respect entries made
  681. by the other.
  682. The file name is found by calling
  683. .PN XrmSetDatabase
  684. with the current screen resource database, after preserving the
  685. original display-associated database, then calling
  686. .PN XtResolvePathname
  687. with the parameters
  688. (\fIdisplay\fP, NULL, NULL, NULL, \fIpath\fP, NULL, 0, NULL)
  689. where \fIpath\fP is defined in an operating-system-specific way.
  690. On POSIX-based systems, \fIpath\fP is defined to be the value
  691. of the environment variable
  692. .PN \s-1XUSERFILESEARCHPATH\s+1
  693. if this is defined.  If
  694. .PN \s-1XUSERFILESEARCHPATH\s+1
  695. is not defined, an implementation-dependent default value is used.
  696. This default value is constrained in the following manner:
  697.  
  698. .RS
  699. .IP \- 3
  700. If the environment variable
  701. .PN \s-1XAPPLRESDIR\s+1
  702. is not defined, the default
  703. .PN \s-1XUSERFILESEARCHPATH\s+1
  704. must contain at least six entries.  These entries must contain
  705. .IN "XUSERFILESEARCHPATH" "" "@DEF@"
  706. .IN "XAPPLRESDIR" "" "@DEF@"
  707. .IN "$HOME"
  708. $HOME as the directory prefix, plus the following substitutions:
  709.  
  710. .nf
  711. .ta .3i 1.5i 2i
  712. 1.    %C, %N, %L    or    %C, %N, %l, %t, %c
  713. 2.    %C, %N, %l
  714. 3.    %C, %N
  715. 4.    %N, %L    or    %N, %l, %t, %c
  716. 5.    %N, %l
  717. 6.    %N
  718. .fi
  719.  
  720. The order of these six entries within the path must be as given above.
  721. The order and use of substitutions within a given entry is implementation
  722. dependent.
  723.  
  724. .IP \- 3
  725. If
  726. .PN \s-1XAPPLRESDIR\s+1
  727. is defined, the default
  728. .PN \s-1XUSERFILESEARCHPATH\s+1
  729. must contain at least seven entries.  These entries must contain the
  730. following directory prefixes and substitutions:
  731.  
  732. .ne 1.1
  733. .nf
  734. .ta .3i 1.6i 2.2i 3.3i 3.7i
  735. 1.    $XAPPLRESDIR    with    %C, %N, %L    or    %C, %N, %l, %t, %c
  736. 2.    $XAPPLRESDIR    with    %C, %N, %l
  737. 3.    $XAPPLRESDIR    with    %C, %N
  738. 4.    $XAPPLRESDIR    with    %N, %L    or    %N, %l, %t, %c
  739. 5.    $XAPPLRESDIR    with    %N, %l
  740. 6.    $XAPPLRESDIR    with    %N
  741. 7.    $HOME    with    %N
  742. .fi
  743.  
  744. The order of these seven entries within the path must be as given above.
  745. The order and use of substitutions within a given entry is implementation
  746. dependent.
  747. .RE
  748.  
  749. .IP \(bu 5
  750. Lastly, the application-specific class resource file from the local
  751. host is merged into the screen resource database.
  752. This file is owned by the application and is usually installed in
  753. a system directory when the application is installed.
  754. It may contain site-wide customizations specified by the system manager.
  755. The name of the application class resource file is found by calling
  756. .PN XtResolvePathname
  757. with the parameters
  758. (\fIdisplay\fP, ``app-defaults'', NULL, NULL, NULL, NULL, 0, NULL).
  759. This file is expected to be provided by the developer of the application
  760. and may be required for the application to function properly.
  761. A simple application that wants to be assured of having a minimal
  762. set of resources in the absence of its class resource file can declare
  763. fallback resource specifications with
  764. .PN XtAppSetFallbackResources .
  765. Note that the customization substitution string is retrieved
  766. dynamically by
  767. .PN XtResolvePathname
  768. so that the resolved file name of the application class resource file
  769. can be affected by any of the earlier sources for the screen resource
  770. database, even though the contents of the class resource file have
  771. lowest precedence.  After calling
  772. .PN XtResolvePathname ,
  773. the original display-associated database is restored.
  774.  
  775. .sp
  776. .LP
  777. To obtain the resource database for a particular screen, use
  778. .PN XtScreenDatabase .
  779. .IN "XtScreenDatabase" "" "@DEF@"
  780. .FD 0
  781. XrmDatabase XtScreenDatabase(\fIscreen\fP)
  782. .br
  783.       Screen *\fIscreen\fP;
  784. .FN
  785. .IP \fIscreen\fP 1i
  786. Specifies the screen whose resource database is to be returned.
  787. .LP
  788. The
  789. .PN XtScreenDatabase
  790. function returns the fully merged resource database as specified above,
  791. associated with the specified screen.  If the specified \fIscreen\fP
  792. does not belong to a
  793. .PN Display
  794. initialized by
  795. .PN XtDisplayInitialize ,
  796. the results are undefined.
  797.  
  798. .sp
  799. .LP
  800. To obtain the default resource database associated with a particular display, use
  801. .PN XtDatabase .
  802. .IN "XtDatabase" "" "@DEF@"
  803. .FD 0
  804. XrmDatabase XtDatabase(\fIdisplay\fP)
  805. .br
  806.       Display *\fIdisplay\fP;
  807. .FN
  808. .IP \fIdisplay\fP 1i
  809. Specifies the display.
  810. .LP
  811. The
  812. .PN XtDatabase
  813. function is equivalent to
  814. .PN XrmGetDatabase .
  815. It returns the database associated with the specified display, or
  816. NULL if a database has not been set.
  817.  
  818. .sp
  819. .LP
  820. To specify a default set of resource values that will be used to
  821. initialize the resource database if no application-specific class
  822. resource file is found (the last of the six sources listed above),
  823. use
  824. .PN XtAppSetFallbackResources .
  825. .IN "XtAppSetFallbackResources" "" "@DEF@"
  826. .FD 0
  827. void XtAppSetFallbackResources(\fIapp_context\fP, \fIspecification_list\fP)
  828. .br
  829.       XtAppContext \fIapp_context\fP;
  830. .br
  831.       String *\fIspecification_list\fP;
  832. .FN
  833. .IP \fIapp_context\fP 1.25i
  834. Specifies the application context in which
  835. the fallback specifications will be used.
  836. .IP \fIspecification_list\fP 1.25i
  837. Specifies a NULL-terminated list of
  838. resource specifications to preload
  839. the database, or NULL.
  840. .LP
  841. Each entry in \fIspecification_list\fP points to a string in the format of
  842. .PN XrmPutLineResource .
  843. Following a call to
  844. .PN XtAppSetFallbackResources ,
  845. when a resource database is being created for a particular screen and
  846. the \*(xI are not able
  847. to find or read an application-specific class resource file according to the
  848. rules given above and if \fIspecification_list\fP is not NULL the
  849. resource specifications in \fIspecification_list\fP will be merged
  850. into the screen resource database in place of the application-specific
  851. class resource file.
  852. .PN XtAppSetFallbackResources
  853. is not
  854. required to copy \fIspecification_list\fP; the caller must ensure that the
  855. contents of the list and of the strings addressed by the list remain
  856. valid until all displays are initialized or until
  857. .PN XtAppSetFallbackResources
  858. is called again.  The value NULL for
  859. \fIspecification_list\fP removes any previous fallback resource specification
  860. for the application context.  The intended use for fallback resources
  861. is to provide a minimal
  862. number of resources that will make the application usable (or at
  863. least terminate with helpful diagnostic messages) when some problem
  864. exists in finding and loading the application defaults file.
  865.  
  866. .NH 2
  867. Parsing the Command Line
  868. .XS
  869. \fB\*(SN Parsing the Command Line\fP
  870. .XE
  871. .LP
  872. The
  873. .PN XtOpenDisplay
  874. function first parses the command line for the following options:
  875. .IP \-display 1i
  876. Specifies the display name for
  877. .PN XOpenDisplay .
  878. .IP \-name 1i
  879. Sets the resource name prefix, 
  880. which overrides the application name passed to
  881. .PN XtOpenDisplay .
  882. .IP \-xnllanguage 1i
  883. Specifies the initial language string for establishing locale
  884. and for finding application class resource files.
  885. .LP
  886. .PN XtDisplayInitialize
  887. has a table of standard command line options that are passed to
  888. .PN XrmParseCommand
  889. for adding resources to the resource database, 
  890. and it takes as a parameter additional
  891. application-specific resource abbreviations.
  892. .IN "XrmOptionDescRec" "" "@DEF@"
  893. The format of this table is described in Section 15.9 in \fI\*(xL\fP.
  894. .LP
  895. .Ds 0
  896. .TA .5i 2.75i
  897. .ta .5i 2.75i
  898. typedef enum {
  899.     XrmoptionNoArg,    /* Value is specified in OptionDescRec.value */
  900.     XrmoptionIsArg,    /* Value is the option string itself */
  901.     XrmoptionStickyArg,    /* Value is characters immediately following option */
  902.     XrmoptionSepArg,    /* Value is next argument in argv */
  903.     XrmoptionResArg,    /* Use the next argument as input to XrmPutLineResource*/
  904.     XrmoptionSkipArg,    /* Ignore this option and the next argument in argv */
  905.     XrmoptionSkipNArgs,    /* Ignore this option and the next */
  906.         /* OptionDescRec.value arguments in argv */
  907.     XrmoptionSkipLine    /* Ignore this option and the rest of argv */
  908. } XrmOptionKind;
  909.  
  910. typedef struct {
  911.     char *option;    /* Option name in argv */
  912.     char *specifier;    /* Resource name (without application name) */
  913.     XrmOptionKind argKind;    /* Location of the resource value */
  914.     XPointer value;    /* Value to provide if XrmoptionNoArg */
  915. } XrmOptionDescRec, *XrmOptionDescList;
  916.  
  917. .De
  918. .LP
  919. The standard table contains the following entries:
  920. .TS
  921. l l l l .
  922. _
  923. .sp 6p
  924. .TB
  925. Option String    Resource Name    Argument Kind    Resource Value
  926. .sp 6p
  927. _
  928. .sp 6p
  929. \-background    *background    SepArg    next argument
  930. \-bd    *borderColor    SepArg    next argument
  931. \-bg    *background    SepArg    next argument
  932. \-borderwidth    .borderWidth    SepArg    next argument
  933. \-bordercolor    *borderColor    SepArg    next argument
  934. \-bw    .borderWidth    SepArg    next argument
  935. \-display    .display    SepArg    next argument
  936. \-fg    *foreground    SepArg    next argument
  937. \-fn    *font    SepArg    next argument
  938. \-font    *font    SepArg    next argument
  939. \-foreground    *foreground    SepArg    next argument
  940. \-geometry    .geometry    SepArg    next argument
  941. \-iconic    .iconic    NoArg    ``true''
  942. \-name    .name    SepArg    next argument
  943. \-reverse    .reverseVideo    NoArg    ``on''
  944. \-rv    .reverseVideo    NoArg    ``on''
  945. +rv    .reverseVideo    NoArg    ``off''
  946. \-selectionTimeout    .selectionTimeout    SepArg    next argument
  947. \-synchronous    .synchronous    NoArg    ``on''
  948. +synchronous    .synchronous    NoArg    ``off''
  949. \-title    .title    SepArg    next argument
  950. \-xnllanguage    .xnlLanguage    SepArg    next argument
  951. \-xrm    next argument    ResArg    next argument
  952. .sp 6p
  953. _
  954. .TE
  955. .LP
  956. Note that any unique abbreviation for an option name in the standard table
  957. or in the application table is accepted.
  958. .NE
  959. .LP
  960. If reverseVideo is
  961. .PN True ,
  962. the values of
  963. .PN XtDefaultForeground
  964. and
  965. .PN XtDefaultBackground
  966. are exchanged for all screens on the Display.
  967. .LP
  968. .IN "synchronous" "" "@DEF@"
  969. .IN "Resources" "synchronous"
  970. The value of the synchronous resource specifies whether or not
  971. Xlib is put into synchronous mode.  If a value is found in the resource
  972. database during display initialization,
  973. .PN XtDisplayInitialize
  974. makes a call to
  975. .PN XSynchronize
  976. for all display
  977. connections currently open in the application context.  Therefore,
  978. when multiple displays are initialized in the same application
  979. context, the most recent value specified for the synchronous resource
  980. is used for all displays in the application context.
  981. .LP
  982. .IN "selectionTimeout" "" "@DEF@"
  983. .IN "Resources" "selectionTimeout"
  984. The value of the selectionTimeout resource applies to all displays
  985. opened in the same application context.  When multiple displays are
  986. initialized in the same application context, the most recent value
  987. specified is used for all displays in the application context.
  988. .LP
  989. The \-xrm option provides a method of setting any resource in an application.
  990. The next argument should be a quoted string identical in format to a line in
  991. the user resource file.
  992. For example,
  993. to give a red background to all command buttons in an application named
  994. .PN xmh ,
  995. you can start it up as
  996. .LP
  997. .Ds
  998. xmh \-xrm 'xmh*Command.background: red'
  999. .DE
  1000. .LP
  1001. When it parses the command line,
  1002. .PN XtDisplayInitialize
  1003. merges the application option table with the standard option table
  1004. before calling the Xlib
  1005. .PN XrmParseCommand
  1006. function.
  1007. An entry in the application table with the same name as an entry
  1008. in the standard table overrides the standard table entry.
  1009. If an option name is a prefix of another option name,
  1010. both names are kept in the merged table.
  1011. The \*(xI reserve all option names
  1012. beginning with the characters ``-xt'' for future standard uses.
  1013.  
  1014. .NH 2
  1015. Creating Widgets
  1016. .XS
  1017. \fB\*(SN Creating Widgets\fP
  1018. .XE
  1019. .LP
  1020. The creation of widget instances is a three-phase process:
  1021. .IP 1. 5
  1022. The widgets are allocated and initialized with resources
  1023. and are optionally added to the managed subset of their parent.
  1024. .IP 2. 5
  1025. All composite widgets are notified of their managed children
  1026. in a bottom-up traversal of the widget tree.
  1027. .IP 3. 5
  1028. The widgets create X windows, which then are mapped.
  1029. .LP
  1030. .EQ
  1031. delim $$
  1032. .EN
  1033. To start the first phase, 
  1034. the application calls
  1035. .PN XtCreateWidget
  1036. for all its widgets and adds some (usually, most or all) of its widgets
  1037. to their respective parents' managed set by calling
  1038. .PN XtManageChild .
  1039. To avoid an $O( n sup 2 )$ creation process where each composite widget 
  1040. lays itself out each time a widget is created and managed,
  1041. parent widgets are not notified of changes in their managed set
  1042. during this phase.
  1043. .EQ
  1044. delim off
  1045. .EN
  1046. .LP
  1047. After all widgets have been created,
  1048. the application calls
  1049. .PN XtRealizeWidget
  1050. with the top-level widget to execute the second and third phases.
  1051. .PN XtRealizeWidget
  1052. first recursively traverses the widget tree in a postorder (bottom-up)
  1053. traversal and then notifies each composite widget with one
  1054. or more managed children by means of its change_managed procedure.
  1055. .LP
  1056. Notifying a parent about its managed set involves geometry layout and
  1057. possibly geometry negotiation.
  1058. A parent deals with constraints on its size imposed from above
  1059. (for example, when a user specifies the application window size)
  1060. and suggestions made from below (for example, 
  1061. when a primitive child computes its preferred size).
  1062. One difference between the two can cause geometry changes to ripple
  1063. in both directions through the widget tree.
  1064. The parent may force some of its children to change size and position
  1065. and may issue geometry requests to its own parent in order to better
  1066. accommodate all its children.
  1067. You cannot predict where anything will go on the screen
  1068. until this process finishes.
  1069. .LP
  1070. Consequently, in the first and second phases,
  1071. no X windows are actually created, because it is likely
  1072. that they will get moved around after creation.
  1073. This avoids unnecessary requests to the X server.
  1074. .LP
  1075. Finally,
  1076. .PN XtRealizeWidget
  1077. starts the third phase by making a preorder (top-down) traversal 
  1078. of the widget tree, allocates an X window to each widget by means of 
  1079. its realize procedure, and finally maps the widgets that are managed.
  1080.  
  1081. .NH 3
  1082. Creating and Merging Argument Lists
  1083. .XS
  1084. \fB\*(SN Creating and Merging Argument Lists\fP
  1085. .XE
  1086. .LP
  1087. Many \*(xI functions may be passed pairs of resource names and
  1088. values.
  1089. These are passed as an arglist, a pointer to an array of
  1090. .PN Arg
  1091. structures, which contains
  1092. .IN "ArgList" "" "@DEF@"
  1093. .IN "Arg" "" "@DEF@"
  1094. .LP
  1095. .Ds 0
  1096. .TA .5i 3i
  1097. .ta .5i 3i
  1098. typedef struct {
  1099.     String name;
  1100.     XtArgVal value;
  1101. } Arg, *ArgList;
  1102. .De
  1103. .LP
  1104. where
  1105. .PN XtArgVal
  1106. is as defined in Section 1.5.
  1107. .LP
  1108. If the size of the resource is less than or equal to the size of an
  1109. .PN XtArgVal ,
  1110. the resource value is stored directly in \fIvalue\fP;
  1111. otherwise, a pointer to it is stored in \fIvalue\fP.
  1112. .LP
  1113. To set values in an
  1114. .PN ArgList ,
  1115. use
  1116. .PN XtSetArg .
  1117. .IN "XtSetArg" "" "@DEF@"
  1118. .FD 0
  1119. void XtSetArg(\fIarg\fP, \fIname\fP, \fIvalue\fP)
  1120. .br
  1121.       Arg \fIarg\fP;
  1122. .br
  1123.       String \fIname\fP;
  1124. .br
  1125.       XtArgVal \fIvalue\fP;
  1126. .FN
  1127. .IP \fIarg\fP 1i
  1128. Specifies the \fIname/value\fP pair to set.
  1129. .IP \fIname\fP 1i
  1130. Specifies the name of the resource.
  1131. .IP \fIvalue\fP 1i
  1132. Specifies the value of the resource if it will fit in an
  1133. .PN XtArgVal ,
  1134. else the address.
  1135. .LP
  1136. The
  1137. .PN XtSetArg
  1138. function is usually used in a highly stylized manner to
  1139. minimize the probability of making a mistake; for example:
  1140. .LP
  1141. .Ds
  1142. .TA .5i 3i
  1143. .ta .5i 3i
  1144. Arg args[20];
  1145. int n;
  1146.  
  1147. n = 0;
  1148. XtSetArg(args[n], XtNheight, 100);    n++;
  1149. XtSetArg(args[n], XtNwidth, 200);    n++;
  1150. XtSetValues(widget, args, n);
  1151. .De
  1152. .LP
  1153. Alternatively, an application can statically declare the argument list
  1154. and use
  1155. .PN XtNumber :
  1156. .LP
  1157. .Ds
  1158. .TA .5i 3i
  1159. .ta .5i 3i
  1160. static Args args[] = {
  1161.     {XtNheight, (XtArgVal) 100},
  1162.     {XtNwidth, (XtArgVal) 200},
  1163. };
  1164. XtSetValues(Widget, args, XtNumber(args));
  1165. .De
  1166. .LP
  1167. Note that you should not use expressions with side effects such as
  1168. auto-increment or auto-decrement
  1169. within the first argument to
  1170. .PN XtSetArg .
  1171. .PN XtSetArg
  1172. can be implemented as a macro that evaluates the first argument twice.
  1173. .sp
  1174. .LP
  1175. To merge two
  1176. arglist arrays, use
  1177. .PN XtMergeArgLists .
  1178. .IN "XtMergeArgLists" "" "@DEF@"
  1179. .FD 0
  1180. ArgList XtMergeArgLists(\fIargs1\fP, \fInum_args1\fP, \fIargs2\fP, \
  1181. \fInum_args2\fP)
  1182. .br
  1183.      ArgList \fIargs1\fP;
  1184. .br
  1185.      Cardinal \fInum_args1\fP;
  1186. .br
  1187.      ArgList \fIargs2\fP;
  1188. .br
  1189.      Cardinal \fInum_args2\fP;
  1190. .FN
  1191. .IP \fIargs1\fP 1i
  1192. Specifies the first argument list.
  1193. .IP \fInum_args1\fP 1i
  1194. Specifies the number of entries in the first argument list.
  1195. .IP \fIargs2\fP 1i
  1196. Specifies the second argument list.
  1197. .IP \fInum_args2\fP 1i
  1198. Specifies the number of entries in the second argument list.
  1199. .LP
  1200. The
  1201. .PN XtMergeArgLists
  1202. function allocates enough storage to hold the combined
  1203. arglist arrays and copies them into it.
  1204. Note that it does not check for duplicate entries.
  1205. The length of the returned list is the sum of the lengths of the
  1206. specified lists.
  1207. When it is no longer needed,
  1208. free the returned storage by using
  1209. .PN XtFree .
  1210. .sp
  1211. .LP
  1212. .IN "varargs" "" "@DEF@"
  1213. All \*(xI interfaces that require
  1214. .PN ArgList
  1215. arguments have analogs
  1216. conforming to the ANSI C variable argument list
  1217. (traditionally called ``varargs'')
  1218. calling convention.  The name of the analog is formed by prefixing
  1219. ``Va'' to the name of the corresponding
  1220. .PN ArgList
  1221. procedure; e.g.,
  1222. .PN \%XtVaCreateWidget .
  1223. Each procedure named \fBXtVa\fP\fIsomething\fP takes as its
  1224. last arguments, in place of the corresponding
  1225. .PN ArgList /
  1226. .PN Cardinal
  1227. parameters, a variable parameter list of resource name and
  1228. value pairs where each name is of type
  1229. .PN String
  1230. and each value is of type
  1231. .PN XtArgVal .
  1232. The end of the list is identified by a \fIname\fP entry
  1233. containing NULL.  Developers writing in the C language wishing to pass
  1234. resource name and value pairs to any of these interfaces may use the
  1235. .PN ArgList
  1236. and varargs forms interchangeably.
  1237. .LP
  1238. Two special names are defined for use only in varargs lists:
  1239. .PN XtVaTypedArg
  1240. and
  1241. .PN XtVaNestedList .
  1242. .sp
  1243. .LP
  1244. .IN "XtVaTypedArg" "" "@DEF@"
  1245. .Ds 0
  1246. #define XtVaTypedArg "XtVaTypedArg"
  1247. .De
  1248.  
  1249. If the name
  1250. .PN XtVaTypedArg
  1251. is specified in place of a resource
  1252. name, then the following four arguments are interpreted as a
  1253. \fIname/type/value/size\fP tuple \fIwhere\fP name is of type
  1254. .PN String ,
  1255. \fItype\fP is of type
  1256. .PN String ,
  1257. \fIvalue\fP is of type
  1258. .PN XtArgVal ,
  1259. and \fIsize\fP is of type int.  When a varargs list containing
  1260. .PN XtVaTypedArg
  1261. is processed, a resource type
  1262. conversion (see Section 9.6) is performed if necessary to convert the
  1263. value into the format required by the associated resource.  If \fItype\fP is
  1264. XtRString then \fIvalue\fP contains a pointer to the string and \fIsize\fP
  1265. contains the number of bytes allocated, including the trailing null
  1266. byte.  If \fItype\fP is not XtRString, then \fIif\fP size is
  1267. less than or equal to
  1268. \fBsizeof\fP(\fBXtArgVal\fP), the value should be the data cast to the type
  1269. .PN XtArgVal ,
  1270. otherwise \fIvalue\fP is a pointer to the data.  If the type
  1271. conversion fails for any reason, a warning message is issued and the
  1272. list entry is skipped.
  1273. .sp
  1274. .LP
  1275. .IN "XtVaNestedList" "" "@DEF@"
  1276. .Ds 0
  1277. #define XtVaNestedList  "XtVaNestedList"
  1278. .De
  1279. .LP
  1280. If the name
  1281. .PN XtVaNestedList
  1282. is specified in place of a resource name,
  1283. then the following argument is interpreted as an
  1284. .PN XtVarArgsList
  1285. value, which specifies another
  1286. varargs list that is logically inserted into the original list at the
  1287. point of declaration.  The end of the nested list is identified with a
  1288. name entry containing NULL.  Varargs lists may nest to any depth.
  1289. .sp
  1290. .LP
  1291. To dynamically allocate a varargs list for use with
  1292. .PN XtVaNestedList
  1293. in multiple calls, use
  1294. .PN XtVaCreateArgsList .
  1295. .IN "XtVaCreateArgsList" "" "@DEF@"
  1296. .sp
  1297. .LP
  1298. .Ds 0
  1299. typedef XtPointer XtVarArgsList;
  1300. .De
  1301. .LP
  1302. .FD 0
  1303. XtVarArgsList XtVaCreateArgsList(\fIunused\fP, ...)
  1304. .br
  1305.       XtPointer \fIunused\fP;
  1306. .FN
  1307. .IP \fIunused\fP 1i
  1308. This argument is not currently used and must be specified as NULL.
  1309. .IP ... 1i
  1310. Specifies a variable parameter list of resource
  1311. name and value pairs.
  1312. .LP
  1313. The
  1314. .PN XtVaCreateArgsList
  1315. function allocates memory and copies its arguments into a
  1316. single list pointer, which may be used with
  1317. .PN XtVaNestedList .
  1318. The end of
  1319. both lists is identified by a \fIname\fP entry containing NULL.  Any entries
  1320. of type
  1321. .PN XtVaTypedArg
  1322. are copied as specified without applying
  1323. conversions.  Data passed by reference (including Strings) are not
  1324. copied, only the pointers themselves; the caller must ensure that the
  1325. data remain valid for the lifetime of the created varargs list.  The
  1326. list should be freed using
  1327. .PN XtFree
  1328. when no longer needed.
  1329. .LP
  1330. Use of resource files and the resource database is generally
  1331. encouraged over lengthy arglist or varargs lists whenever possible in
  1332. order to permit modification without recompilation.
  1333.  
  1334. .NH 3
  1335. Creating a Widget Instance
  1336. .XS
  1337. \fB\*(SN Creating a Widget Instance\fP
  1338. .XE
  1339. .LP
  1340. To create an instance of a widget, use
  1341. .PN XtCreateWidget .
  1342. .IN "XtCreateWidget" "" "@DEF@"
  1343. .FD 0
  1344. Widget XtCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, \
  1345. \fIargs\fP, \fInum_args\fP)
  1346. .br
  1347.       String \fIname\fP;
  1348. .br
  1349.       WidgetClass \fIobject_class\fP;
  1350. .br
  1351.       Widget \fIparent\fP;
  1352. .br
  1353.       ArgList \fIargs\fP;
  1354. .br
  1355.       Cardinal \fInum_args\fP;
  1356. .FN
  1357. .IP \fIname\fP 1i
  1358. Specifies the resource instance name for the created widget,
  1359. which is used for retrieving resources
  1360. and, for that reason, should not be the same as any other widget
  1361. that is a child of the same parent.
  1362. .IP \fIobject_class\fP 1i
  1363. Specifies the widget class pointer for the created object.  \*(oC
  1364. .IP \fIparent\fP 1i
  1365. Specifies the parent widget.  \*(oI
  1366. .IP \fIargs\fP 1i
  1367. Specifies the argument list to override any other resource specifications.
  1368. .IP \fInum_args\fP 1i
  1369. Specifies the number of entries in the argument list.
  1370. .LP
  1371. The
  1372. .PN XtCreateWidget
  1373. function performs all the boilerplate operations of widget
  1374. creation, doing the following in order:
  1375. .IP \(bu 5
  1376. Checks to see if the class_initialize procedure has been called for this class
  1377. and for all superclasses and, if not, calls those necessary in a
  1378. superclass-to-subclass order.
  1379. .IP \(bu 5
  1380. If the specified class is not
  1381. .PN coreWidgetClass
  1382. or a subclass thereof,
  1383. and the parent's class is a subclass of
  1384. .PN compositeWidgetClass
  1385. and either no extension record in
  1386. the parent's composite class part extension field exists with the
  1387. \fIrecord_type\fP
  1388. .PN \s-1NULLQUARK\s+1
  1389. or the \fIaccepts_objects\fP field in the extension
  1390. record is
  1391. .PN False ,
  1392. .PN XtCreateWidget
  1393. issues a fatal error; see Section 3.1 and Chapter 12.
  1394. .IP \(bu 5
  1395. Allocates memory for the widget instance.
  1396. .IP \(bu 5
  1397. If the parent is a member of the class
  1398. .PN constraintWidgetClass ,
  1399. allocates memory for the parent's constraints
  1400. and stores the address of this memory into the \fIconstraints\fP field.
  1401. .IP \(bu 5
  1402. Initializes the Core nonresource data fields
  1403. (for example, \fIparent\fP and \fIvisible\fP).
  1404. .IP \(bu 5
  1405. Initializes the resource fields (for example, \fIbackground_pixel\fP)
  1406. by using the
  1407. .PN CoreClassPart
  1408. resource lists specified for this class and all superclasses.
  1409. .IP \(bu 5
  1410. If the parent is a member of the class
  1411. .PN constraintWidgetClass ,
  1412. initializes the resource fields of the constraints record
  1413. by using the
  1414. .PN ConstraintClassPart
  1415. resource lists specified for the parent's class
  1416. and all superclasses up to
  1417. .PN constraintWidgetClass .
  1418. .IP \(bu 5
  1419. Calls the initialize procedures for the widget starting at the 
  1420. Object
  1421. initialize procedure on down to the widget's initialize procedure.
  1422. .IP \(bu 5
  1423. If the parent is a member of the class
  1424. .PN compositeWidgetClass ,
  1425. puts the widget into its parent's children list by calling its parent's
  1426. insert_child procedure.
  1427. For further information,
  1428. see Section 3.1.
  1429. .IP \(bu 5
  1430. If the parent is a member of the class
  1431. .PN constraintWidgetClass ,
  1432. calls the
  1433. .PN ConstraintClassPart
  1434. initialize procedures,
  1435. starting at
  1436. .PN constraintWidgetClass
  1437. on down to the parent's
  1438. .PN ConstraintClassPart
  1439. initialize procedure.
  1440. .sp
  1441. .LP
  1442. To create an instance of a widget using varargs lists, use
  1443. .PN XtVaCreateWidget .
  1444. .IN "XtVaCreateWidget" "" "@DEF@"
  1445. .FD 0
  1446. Widget XtVaCreateWidget(\fIname\fP, \fIobject_class\fP, \fIparent\fP, ...)
  1447. .br
  1448.       String \fIname\fP;
  1449. .br
  1450.       WidgetClass \fIobject_class\fP;
  1451. .br
  1452.       Widget \fIparent\fP;
  1453. .FN
  1454. .IP \fIname\fP 1i
  1455. Specifies the resource name for the created widget.
  1456. .IP \fIobject_class\fP 1i
  1457. Specifies the widget class pointer for the created object.  \*(oC
  1458. .IP \fIparent\fP 1i
  1459. Specifies the parent widget.  \*(oI
  1460. .IP ... 1i
  1461. Specifies the variable argument list to override any other
  1462. resource specifications.
  1463. .LP
  1464. The
  1465. .PN XtVaCreateWidget
  1466. procedure is identical in function to
  1467. .PN XtCreateWidget
  1468. with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
  1469. as described
  1470. in Section 2.5.1.
  1471.  
  1472. .NH 3
  1473. Creating an Application Shell Instance
  1474. .XS
  1475. \fB\*(SN Creating an Application Shell Instance\fP
  1476. .XE
  1477. .LP
  1478. An application can have multiple top-level widgets, each of which
  1479. specifies a unique widget tree
  1480. which can potentially be on different screens or displays.
  1481. An application uses 
  1482. .PN XtAppCreateShell
  1483. to create independent widget trees.
  1484. .LP
  1485. .IN "XtAppCreateShell" "" "@DEF@"
  1486. .FD 0
  1487. Widget XtAppCreateShell(\fIname\fP, \
  1488. \fIapplication_class\fP, \fIwidget_class\fP, \fIdisplay\fP,
  1489. .br
  1490.                         \fIargs\fP, \fInum_args\fP)
  1491. .br
  1492.       String \fIname\fP;
  1493. .br
  1494.       String \fIapplication_class\fP;
  1495. .br
  1496.       WidgetClass \fIwidget_class\fP;
  1497. .br
  1498.       Display *\fIdisplay\fP;
  1499. .br
  1500.       ArgList \fIargs\fP;
  1501. .br
  1502.       Cardinal \fInum_args\fP;
  1503. .FN
  1504. .IP \fIname\fP 1.25i
  1505. Specifies the instance name of the shell widget.
  1506. If \fIname\fP is NULL,
  1507. the application name passed to
  1508. .PN XtDisplayInitialize
  1509. is used.
  1510. .IP \fIapplication_class\fP 1.25i
  1511. Specifies the resource class string to be used in
  1512. place of the widget \fIclass_name\fP string when
  1513. \fIwidget_class\fP is
  1514. .PN applicationShellWidgetClass
  1515. or a subclass thereof.
  1516. .IP \fIwidget_class\fP 1.25i
  1517. Specifies the widget class for the top-level widget (e.g.,
  1518. .PN applicationShellWidgetClass )
  1519. .IP \fIdisplay\fP 1.25i
  1520. Specifies the display for the default screen
  1521. and for the resource database used to retrieve
  1522. the shell widget resources.
  1523. .IP \fIargs\fP 1.25i
  1524. Specifies the argument list to override any other resource specifications.
  1525. .IP \fInum_args\fP 1.25i
  1526. Specifies the number of entries in the argument list.
  1527.  
  1528. .LP
  1529. The
  1530. .PN XtAppCreateShell
  1531. function
  1532. creates a new shell widget instance as the root of a widget tree.
  1533. The screen resource for this widget is determined by first scanning
  1534. \fIargs\fP for the XtNscreen argument.  If no XtNscreen argument is
  1535. found, the resource database associated with the default screen of
  1536. the specified display is queried for the resource \fIname\fP.screen,
  1537. class \fIClass\fP.Screen where \fIClass\fP is the specified
  1538. \fIapplication_class\fP if \fIwidget_class\fP is
  1539. .PN applicationShellWidgetClass
  1540. or a subclass thereof.  If \fIwidget_class\fP is not
  1541. .PN application\%Shell\%Widget\%Class
  1542. or a subclass, \fIClass\fP is the \fIclass_name\fP
  1543. field from the
  1544. .PN CoreClassPart
  1545. of the specified \fIwidget_class\fP.
  1546. If this query fails, the default
  1547. screen of the specified display is used.  Once the screen is determined,
  1548. the resource database associated with that screen is used to retrieve
  1549. all remaining resources for the shell widget not specified in
  1550. \fIargs\fP.  The widget name and \fIClass\fP as determined above are
  1551. used as the leftmost (i.e., root) components in all fully qualified
  1552. resource names for objects within this widget tree.
  1553.  
  1554. .LP
  1555. If the specified widget class is a subclass of WMShell, the name and
  1556. \fIClass\fP as determined above will be stored into the
  1557. .PN WM_CLASS
  1558. property on the widget's window when it becomes realized.
  1559. If the specified \fIwidget_class\fP is
  1560. .PN applicationShellWidgetClass
  1561. or a subclass thereof the
  1562. .PN WM_COMMAND
  1563. property will also be set from the values of the XtNargv and
  1564. XtNargc resources.
  1565.  
  1566. .LP
  1567. To create multiple top-level shells within a single (logical)
  1568. application, 
  1569. you can use one of two methods:
  1570. .IP \(bu 5
  1571. Designate one shell as the real top-level shell and
  1572. create the others as pop-up children of it by using 
  1573. .PN XtCreatePopupShell .
  1574. .IP \(bu 5
  1575. Have all shells as pop-up children of an unrealized top-level shell. 
  1576. .LP
  1577. The first method, 
  1578. which is best used when there is a clear choice for what is the main window, 
  1579. leads to resource specifications like the following:
  1580. .LP
  1581. .Ds
  1582. .TA 2i
  1583. .ta 2i
  1584. xmail.geometry:...    (the main window)
  1585. xmail.read.geometry:...    (the read window)
  1586. xmail.compose.geometry:...    (the compose window)
  1587. .De
  1588. .LP
  1589. The second method, 
  1590. which is best if there is no main window,
  1591. leads to resource specifications like the following:
  1592. .LP
  1593. .Ds
  1594. .TA 2i
  1595. .ta 2i
  1596. xmail.headers.geometry:...    (the headers window)
  1597. xmail.read.geometry:...    (the read window)
  1598. xmail.compose.geometry:...    (the compose window)
  1599. .De
  1600. .sp
  1601. .LP
  1602. To create a top-level widget that is the root of a widget tree using
  1603. varargs lists, use
  1604. .PN XtVaAppCreateShell .
  1605. .IN "XtVaAppCreateShell" "" "@DEF@"
  1606. .FD 0
  1607. Widget XtVaAppCreateShell(\fIname\fP, \fIapplication_class\fP, \
  1608. \fIwidget_class\fP, \fIdisplay\fP, ...)
  1609. .br
  1610.     String \fIname\fP;
  1611. .br
  1612.     String \fIapplication_class\fP;
  1613. .br
  1614.     WidgetClass \fIwidget_class\fP;
  1615. .br
  1616.     Display *\fIdisplay\fP;
  1617. .FN
  1618. .IP \fIname\fP 1i
  1619. Specifies the instance name of the shell widget.
  1620. If \fIname\fP is NULL,
  1621. the application name passed to
  1622. .PN XtDisplayInitialize
  1623. is used.
  1624. .IP \fIapplication_class\fP 1i
  1625. Specifies the resource class string to be used in
  1626. place of the widget \fIclass_name\fP string when
  1627. \fIwidget_class\fP is
  1628. .PN applicationShellWidgetClass
  1629. or a subclass thereof.
  1630. .IP \fIwidget_class\fP 1i
  1631. Specifies the widget class for the top-level widget.
  1632. .IP \fIdisplay\fP 1i
  1633. Specifies the display for the default screen
  1634. and for the resource database used to retrieve
  1635. the shell widget resources.
  1636. .IP ... 1i
  1637. Specifies the variable argument list to override any other
  1638. resource specifications.
  1639. .LP
  1640. The
  1641. .PN XtVaAppCreateShell
  1642. procedure is identical in function to
  1643. .PN XtAppCreateShell
  1644. with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list, as
  1645. described in Section 2.5.1.
  1646.  
  1647. .NH 3
  1648. Convenience Procedure to Initialize an Application
  1649. .XS
  1650. \fB\*(SN Convenience Procedure to Initialize an Application\fP
  1651. .XE
  1652. .LP
  1653. To initialize the \*(xI internals, create an application context,
  1654. open and initialize a display, and create the initial application shell
  1655. instance, an application may use
  1656. .PN XtAppInitialize
  1657. or
  1658. .PN XtVaAppInitialize .
  1659. .IN "XtVaAppInitialize" "" "@DEF@"
  1660. .FD 0
  1661. Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
  1662. \fIoptions\fP, \fInum_options\fP,
  1663. .br
  1664.                        \fIargc_in_out\fP, \fIargv_in_out\fP, \
  1665. \fIfallback_resources\fP, \fIargs\fP, \fInum_args\fP)
  1666. .br
  1667.       XtAppContext *\fIapp_context_return\fP;
  1668. .br
  1669.       String \fIapplication_class\fP;
  1670. .br
  1671.       XrmOptionDescList \fIoptions\fP;
  1672. .br
  1673.       Cardinal \fInum_options\fP;
  1674. .br
  1675.       int *\fIargc_in_out\fP;
  1676. .br
  1677.       String *\fIargv_in_out\fP;
  1678. .br
  1679.       String *\fIfallback_resources\fP;
  1680. .br
  1681.       ArgList \fIargs\fP;
  1682. .br
  1683.       Cardinal \fInum_args\fP;
  1684. .FN
  1685. .IP \fIapp_context_return\fP 1.5i
  1686. Returns the application context, if non-NULL.
  1687. .IP \fIapplication_class\fP 1.5i
  1688. Specifies the class name of the application.
  1689. .IP \fIoptions\fP 1.5i
  1690. Specifies the command line options table.
  1691. .IP \fInum_options\fP 1.5i
  1692. Specifies the number of entries in \fIoptions\fP.
  1693. .IP \fIargc_in_out\fP 1.5i
  1694. Specifies a pointer to the number of command line arguments.
  1695. .IP \fIargv_in_out\fP 1.5i
  1696. Specifies a pointer to the command line arguments.
  1697. .IP \fIfallback_resources\fP 1.5i
  1698. Specifies resource values to be used if the application class resource
  1699. file cannot be opened or read, or NULL.
  1700. .IP \fIargs\fP 1.5i
  1701. Specifies the argument list to override any
  1702. other resource specifications for the created shell widget.
  1703. .IP \fInum_args\fP 1.5i
  1704. Specifies the number of entries in the argument list.
  1705. .LP
  1706. The
  1707. .PN XtAppInitialize
  1708. function calls
  1709. .PN XtToolkitInitialize
  1710. followed by
  1711. .PN XtCreateApplicationContext ,
  1712. then calls
  1713. .PN XtOpenDisplay
  1714. with \fIdisplay_string\fP NULL and
  1715. \fIapplication_name\fP NULL, and finally calls
  1716. .PN XtAppCreateShell
  1717. with \fIapplication_name\fP NULL, \fIwidget_class\fP
  1718. .PN application\%Shell\%Widget\%Class ,
  1719. and the specified \fIargs\fP and \fInum_args\fP
  1720. and returns the created shell.  The modified \fIargc\fP and \fIargv\fP returned by
  1721. .PN XtDisplayInitialize
  1722. are returned in \fIargc_in_out\fP and \fIargv_in_out\fP.  If
  1723. \fIapp_context_return\fP is not NULL, the created application context is
  1724. also returned.  If the display specified by the command line cannot be
  1725. opened, an error message is issued and
  1726. .PN XtAppInitialize
  1727. terminates the application.  If \fIfallback_resources\fP is non-NULL,
  1728. .PN XtAppSetFallbackResources
  1729. is called with the value prior to calling
  1730. .PN XtOpenDisplay .
  1731. .sp
  1732. .LP
  1733. .IN "XtVaAppInitialize" "" "@DEF@"
  1734. .FD 0
  1735. Widget XtVaAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
  1736. \fIoptions\fP, \fInum_options\fP,
  1737. .br
  1738.                          \fIargc_in_out\fP, \fIargv_in_out\fP, \
  1739. \fIfallback_resources\fP, ...)
  1740. .br
  1741.     XtAppContext *\fIapp_context_return\fP;
  1742. .br
  1743.     String \fIapplication_class\fP;
  1744. .br
  1745.     XrmOptionDescList \fIoptions\fP;
  1746. .br
  1747.     Cardinal \fInum_options\fP;
  1748. .br
  1749.     int *\fIargc_in_out\fP;
  1750. .br
  1751.     String *\fIargv_in_out\fP;
  1752. .br
  1753.     String *\fIfallback_resources\fP;
  1754. .FN
  1755. .IP \fIapp_context_return\fP 1.5i
  1756. Returns the application context, if non-NULL.
  1757. .IP \fIapplication_class\fP 1.5i
  1758. Specifies the class name of the application.
  1759. .IP \fIoptions\fP 1.5i
  1760. Specifies the command line options table.
  1761. .IP \fInum_options\fP 1.5i
  1762. Specifies the number of entries in \fIoptions\fP.
  1763. .IP \fIargc_in_out\fP 1.5i
  1764. Specifies a pointer to the number of command line arguments.
  1765. .IP \fIargv_in_out\fP 1.5i
  1766. Specifies the command line arguments array.
  1767. .IP \fIfallback_resources\fP 1.5i
  1768. Specifies resource values to be used if the application class
  1769. resource file cannot be opened, or NULL.
  1770. .IP ... 1.5i
  1771. Specifies the variable argument list to override any other
  1772. resource specifications for the created shell.
  1773. .LP
  1774. The
  1775. .PN XtVaAppInitialize
  1776. procedure is identical in function to
  1777. .PN XtAppInitialize
  1778. with the \fIargs\fP and \fInum_args\fP parameters replaced by a varargs list,
  1779. as described
  1780. in Section 2.5.1.
  1781.  
  1782. .NH 3
  1783. Widget Instance Initialization: the initialize Procedure
  1784. .XS
  1785. \*(SN Widget Instance Initialization: the initialize Procedure
  1786. .XE
  1787. .IN "Initialization"
  1788. .IN "Chaining"
  1789. .IN "Superclass Chaining"
  1790. .IN "Inheritance"
  1791. .LP
  1792. The initialize procedure pointer in a widget class is of type
  1793. .PN XtInitProc .
  1794. .IN "XtInitProc" "" "@DEF@"
  1795. .IN "initialize procedure" "" "@DEF@"
  1796. .FD 0
  1797. typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal*);
  1798. .br
  1799.       Widget \fIrequest\fP;
  1800. .br
  1801.       Widget \fInew\fP;
  1802. .br
  1803.       ArgList \fIargs\fP;
  1804. .br
  1805.       Cardinal *\fInum_args\fP;
  1806. .FN
  1807. .IP \fIrequest\fP 1i
  1808. Specifies a copy of the widget with resource values as requested by the
  1809. argument list, the resource database, and the widget defaults.
  1810. .IP \fInew\fP 1i
  1811. Specifies the widget with the new values, both resource and nonresource,
  1812. that are actually allowed.
  1813. .IP \fIargs\fP 1i
  1814. Specifies the argument list passed by the client, for
  1815. computing derived resource values.
  1816. If the client created the widget using a varargs form, any resources
  1817. specified via
  1818. .PN XtVaTypedArg
  1819. are converted to the widget representation and the list is transformed
  1820. into the
  1821. .PN ArgList
  1822. format.
  1823. .IP \fInum_args\fP 1i
  1824. Specifies the number of entries in the argument list.
  1825. .LP
  1826. An initialization procedure performs the following:
  1827. .IP \(bu 5
  1828. Allocates space for and copies any resources referenced by address
  1829. that the client is allowed to free or modify
  1830. after the widget has been created.
  1831. For example,
  1832. if a widget has a field that is a 
  1833. .PN String ,
  1834. it may choose not to
  1835. depend on the characters at that address remaining constant 
  1836. but dynamically allocate space for the string and copy it to the new space.
  1837. Widgets that do not copy one or more resources referenced
  1838. by address should clearly so state in their user documentation.
  1839. .NT
  1840. It is not necessary to allocate space for or to copy callback lists.
  1841. .NE
  1842. .IP \(bu 5
  1843. Computes values for unspecified resource fields.
  1844. For example, \fIif\fP width and \fIheight\fP are zero,
  1845. the widget should compute an appropriate width and height 
  1846. based on its other resources.
  1847. .NT
  1848. A widget may only directly assign
  1849. its own \fIwidth\fP and \fIheight\fP within the initialize, initialize_hook,
  1850. set_values and
  1851. set_values_hook procedures; see Chapter 6.
  1852. .NE
  1853. .IP \(bu 5
  1854. Computes values for uninitialized nonresource fields that are derived from
  1855. resource fields.
  1856. For example, graphics contexts (GCs) that the widget uses are derived from
  1857. resources like background, foreground, and font.
  1858. .LP
  1859. An initialization procedure also can check certain fields for
  1860. internal consistency.
  1861. For example, it makes no sense to specify a colormap for a depth
  1862. that does not support that colormap.
  1863. .LP
  1864. Initialization procedures are called in superclass-to-subclass order
  1865. after all fields specified in the resource lists have been
  1866. initialized.  The initialize procedure does not need to examine
  1867. \fIargs\fP and \fInum_args\fP
  1868. if all public resources are declared in the resource list.
  1869. Most of the initialization code for a specific widget class deals with fields
  1870. defined in that class and not with fields defined in its superclasses.
  1871. .LP
  1872. If a subclass does not need an initialization procedure
  1873. because it does not need to perform any of the above operations,
  1874. it can specify NULL for the \fIinitialize\fP field in the class record.
  1875. .LP
  1876. Sometimes a subclass may want to overwrite values filled in by its
  1877. superclass.
  1878. In particular, size calculations of a superclass are often
  1879. incorrect for a subclass, and in this case,
  1880. the subclass must modify or recalculate fields declared
  1881. and computed by its superclass.
  1882. .LP
  1883. As an example,
  1884. a subclass can visually surround its superclass display.
  1885. In this case, the width and height calculated by the superclass initialize
  1886. procedure are too small and need to be incremented by the size of the surround.
  1887. The subclass needs to know if its superclass's size was calculated by the
  1888. superclass or was specified explicitly.
  1889. All widgets must place themselves into whatever size is explicitly given,
  1890. but they should compute a reasonable size if no size is requested.
  1891. .LP
  1892. The \fIrequest\fP and \fInew\fP arguments provide the necessary information for
  1893. a subclass to determine the difference between an explicitly specified field
  1894. and a field computed by a superclass.
  1895. The \fIrequest\fP widget is a copy of the widget as initialized by the
  1896. arglist and resource database.
  1897. The \fInew\fP widget starts with the values in the request,
  1898. but it has been updated by all superclass initialization procedures called
  1899. so far.
  1900. A subclass initialize procedure can compare these two to resolve
  1901. any potential conflicts.
  1902. .LP
  1903. In the above example,
  1904. the subclass with the visual surround can see
  1905. if the \fIwidth\fP and \fIheight\fP in the \fIrequest\fP widget are zero.
  1906. If so,
  1907. it adds its surround size to the \fIwidth\fP and \fIheight\fP
  1908. fields in the \fInew\fP widget.
  1909. If not, it must make do with the size originally specified.
  1910. .LP
  1911. The \fInew\fP widget will become the actual widget instance record.
  1912. Therefore,
  1913. the initialization procedure should do all its work on the \fInew\fP widget;
  1914. the \fIrequest\fP widget should never be modified.
  1915. If the initialize procedure
  1916. needs to call any routines that operate on a widget,
  1917. it should specify \fInew\fP as the widget instance.
  1918.  
  1919. .NH 3
  1920. Constraint Instance Initialization: the ConstraintClassPart initialize Procedure
  1921. .XS
  1922. \*(SN Constraint Instance Initialization: the ConstraintClassPart initialize Procedure
  1923. .XE
  1924. .IN "Initialization"
  1925. .IN "XtInitProc"
  1926. .IN "initialize procedure"
  1927. .IN "Chaining"
  1928. .IN "Superclass Chaining"
  1929. .IN "Inheritance"
  1930. .LP
  1931. The constraint initialization procedure pointer, found in the
  1932. .PN ConstraintClassPart
  1933. \fIinitialize\fP field of the widget class record, is of type
  1934. .PN XtInitProc .
  1935. The values passed to the parent constraint initialization procedures
  1936. are the same as those passed to the child's class widget initialization
  1937. procedures.
  1938. .LP
  1939. The \fIconstraints\fP field of the \fIrequest\fP widget points to a copy of the
  1940. constraints record as initialized by the arglist and resource database.
  1941. .LP
  1942. The constraint initialization procedure should compute any constraint fields
  1943. derived from constraint resources.
  1944. It can make further changes to the \fInew\fP widget to make the widget
  1945. and any other constraint fields
  1946. conform to the specified constraints, for example, 
  1947. changing the widget's size or position.
  1948. .LP
  1949. If a constraint class does not need a constraint initialization procedure,
  1950. it can specify NULL for the \fIinitialize\fP field of the
  1951. .PN ConstraintClassPart
  1952. in the class record.
  1953.  
  1954. .NH 3
  1955. Nonwidget Data Initialization: the initialize_hook Procedure
  1956. .XS
  1957. \*(SN Nonwidget Data Initialization: the initialize_hook Procedure
  1958. .XE
  1959. .IN "Initialization"
  1960. .LP
  1961. .NT
  1962. The initialize_hook procedure is obsolete, as the same information
  1963. is now available to the initialize procedure.  The procedure has been
  1964. retained for those widgets that used it in previous releases.
  1965. .NE
  1966. .LP
  1967. The initialize_hook procedure pointer is of type
  1968. .PN XtArgsProc :
  1969. .IN "initialize_hook procedure" "" "@DEF@"
  1970. .IN "XtArgsProc" "" "@DEF@"
  1971. .FD 0
  1972. typedef void (*XtArgsProc)(Widget, ArgList, Cardinal*);
  1973. .br
  1974.       Widget \fIw\fP;
  1975. .br
  1976.       ArgList \fIargs\fP;
  1977. .br
  1978.       Cardinal *\fInum_args\fP;
  1979. .FN
  1980. .IP \fIw\fP 1i
  1981. Specifies the widget.
  1982. .IP \fIargs\fP 1i
  1983. Specifies the argument list passed by the client.
  1984. If the client created the widget using a varargs form, any resources
  1985. specified via
  1986. .PN XtVaTypedArg
  1987. are converted to the widget representation and the list is transformed
  1988. into the
  1989. .PN ArgList
  1990. format.
  1991. .IP \fInum_args\fP 1i
  1992. Specifies the number of entries in the argument list.
  1993. .LP
  1994. If this procedure is not NULL,
  1995. it is called immediately after the corresponding initialize
  1996. procedure or in its place if the \fIinitialize\fP field is NULL.
  1997. .LP
  1998. The initialize_hook procedure allows a widget instance to initialize
  1999. nonresource data using information from the specified argument list
  2000. as if it were a resource.
  2001.  
  2002. .NH 2
  2003. Realizing Widgets
  2004. .XS
  2005. \fB\*(SN Realizing Widgets\fP
  2006. .XE
  2007. .LP
  2008. To realize a widget instance, use
  2009. .PN XtRealizeWidget .
  2010. .IN "XtRealizeWidget" "" "@DEF@"
  2011. .FD 0
  2012. void XtRealizeWidget(\fIw\fP)
  2013. .br
  2014.       Widget \fIw\fP;
  2015. .FN
  2016. .IP \fIw\fP 1i
  2017. Specifies the widget.  \*(cI
  2018. .LP
  2019. If the widget is already realized,
  2020. .PN XtRealizeWidget
  2021. simply returns. 
  2022. Otherwise it performs the following:
  2023. .IP \(bu 5
  2024. Binds all action names in the widget's
  2025. translation table to procedures (see Section 10.1.2).
  2026. .IP \(bu 5
  2027. Makes a postorder traversal of the widget tree rooted
  2028. at the specified widget and calls each non-NULL change_managed procedure
  2029. of all composite widgets that have one or more managed children.
  2030. .IP \(bu 5
  2031. Constructs an
  2032. .PN XSetWindowAttributes
  2033. structure filled in with information derived from the 
  2034. Core 
  2035. widget fields and calls the realize procedure for the widget,
  2036. which adds any widget-specific attributes and creates the X window.
  2037. .IP \(bu 5
  2038. If the widget is
  2039. not a subclass of 
  2040. .PN compositeWidgetClass ,
  2041. .PN XtRealizeWidget
  2042. returns; otherwise it continues and performs the following:
  2043. .RS
  2044. .IP \- 5
  2045. Descends recursively to each of the widget's
  2046. managed children and calls the realize procedures.
  2047. Primitive widgets that instantiate children are responsible for realizing
  2048. those children themselves.
  2049. .IP \- 5
  2050. Maps all of the managed children windows that have \fImapped_when_managed\fP 
  2051. .PN True .
  2052. If a widget is managed but \fImapped_when_managed\fP is 
  2053. .PN False , 
  2054. the widget is allocated visual space but is not displayed.
  2055. .RE
  2056. .LP
  2057. If the widget is a top-level shell widget (that is, it has no parent), and
  2058. \fImapped_when_managed\fP is 
  2059. .PN True , 
  2060. .PN XtRealizeWidget
  2061. maps the widget window.
  2062. .LP
  2063. .PN XtCreateWidget ,
  2064. .PN XtVaCreateWidget ,
  2065. .PN XtRealizeWidget ,
  2066. .PN XtManageChildren ,
  2067. .PN XtUnmanage\%Children ,
  2068. .PN XtUnrealizeWidget ,
  2069. .PN XtSetMappedWhenManaged ,
  2070. and
  2071. .PN XtDestroy\%Widget
  2072. maintain the following invariants:
  2073. .IP \(bu 5
  2074. If a composite widget is realized, then all its managed children are realized.
  2075. .IP \(bu 5
  2076. If a composite widget is realized, then all its managed children that have
  2077. \fImapped_when_managed\fP
  2078. .PN True
  2079. are mapped.
  2080. .LP
  2081. All \*(xI functions and all widget routines should accept
  2082. either realized or unrealized widgets.
  2083. When calling the realize or change_managed
  2084. procedures for children of a composite
  2085. widget,
  2086. .PN XtRealizeWidget
  2087. calls the procedures in reverse order of
  2088. appearance in the
  2089. .PN CompositePart
  2090. \fIchildren\fP list.  By default, this
  2091. ordering of the realize procedures will
  2092. result in the stacking order of any newly created subwindows being
  2093. top-to-bottom in the order of appearance on the list, and the most
  2094. recently created child will be at the bottom.
  2095. .sp
  2096. .LP
  2097. To check whether or not a widget has been realized, use
  2098. .PN XtIsRealized .
  2099. .IN "XtIsRealized" "" "@DEF@"
  2100. .FD 0
  2101. Boolean XtIsRealized(\fIw\fP)
  2102. .br
  2103.       Widget \fIw\fP;
  2104. .FN
  2105. .IP \fIw\fP 1i
  2106. Specifies the widget.  \*(oI
  2107. .LP
  2108. The
  2109. .PN XtIsRealized
  2110. function returns 
  2111. .PN True 
  2112. if the widget has been realized,
  2113. that is, if the widget has a nonzero window ID.
  2114. If the specified object is not a widget, the state of the nearest
  2115. widget ancestor is returned.
  2116. .LP
  2117. Some widget procedures (for example, set_values) might wish to
  2118. operate differently
  2119. after the widget has been realized.
  2120.  
  2121. .NH 3
  2122. Widget Instance Window Creation: the realize Procedure
  2123. .XS
  2124. \*(SN Widget Instance Window Creation: the realize Procedure
  2125. .XE
  2126. .LP
  2127. The realize procedure pointer in a widget class is of type
  2128. .PN XtRealizeProc .
  2129. .IN "XtRealizeProc" "" "@DEF@"
  2130. .FD 0
  2131. typedef void (*XtRealizeProc)(Widget, XtValueMask*, XSetWindowAttributes*);
  2132. .br
  2133.       Widget \fIw\fP;
  2134. .br
  2135.       XtValueMask *\fIvalue_mask\fP;
  2136. .br
  2137.       XSetWindowAttributes *\fIattributes\fP;
  2138. .FN
  2139. .IP \fIw\fP 1i
  2140. Specifies the widget.
  2141. .IP \fIvalue_mask\fP 1i
  2142. Specifies which fields in the \fIattributes\fP structure are used.
  2143. .IP \fIattributes\fP 1i
  2144. Specifies the window attributes to use in the
  2145. .PN XCreateWindow
  2146. call.
  2147. .LP
  2148. The realize procedure must create the widget's window.
  2149. .LP
  2150. Before calling the class realize procedure, the generic
  2151. .PN XtRealizeWidget
  2152. function fills in a mask and a corresponding
  2153. .PN XSetWindowAttributes
  2154. structure.
  2155. It sets the following fields in \fIattributes\fP and
  2156. corresponding bits in \fIvalue_mask\fP
  2157. based on information in the widget
  2158. core
  2159. structure:
  2160. .IP \(bu 5
  2161. The \fIbackground_pixmap\fP (or \fIbackground_pixel\fP if \fIbackground_pixmap\fP is
  2162. .PN XtUnspecifiedPixmap )
  2163. is filled in from the corresponding field.
  2164. .IP \(bu 5
  2165. The \fIborder_pixmap\fP (or \fIborder_pixel\fP if \fIborder_pixmap\fP is
  2166. .PN XtUnspecifiedPixmap )
  2167. is filled in from the corresponding field.
  2168. .IP \(bu 5
  2169. The \fIcolormap\fP is filled in from the corresponding field.
  2170. .IP \(bu 5
  2171. The \fIevent_mask\fP is filled in based on the event handlers registered,
  2172. the event translations specified, whether the \fIexpose\fP field is non-NULL,
  2173. and whether \fIvisible_interest\fP is 
  2174. .PN True .
  2175. .IP \(bu 5
  2176. The \fIbit_gravity\fP is set to
  2177. .PN NorthWestGravity
  2178. if the \fIexpose\fP field is NULL.
  2179. .LP
  2180. These or any other fields in attributes and the corresponding bits in
  2181. \fIvalue_mask\fP can be set by the realize procedure.
  2182. .LP
  2183. Note that because realize is not a chained operation,
  2184. the widget class realize procedure must update the
  2185. .PN XSetWindowAttributes
  2186. structure with all the appropriate fields from 
  2187. non-Core
  2188. superclasses.
  2189. .LP
  2190. .IN "Inheritance"
  2191. A widget class can inherit its realize procedure from its superclass
  2192. during class initialization.
  2193. The realize procedure defined for
  2194. .PN coreWidgetClass 
  2195. calls
  2196. .PN XtCreateWindow
  2197. with the passed \fIvalue_mask\fP and \fIattributes\fP
  2198. and with \fIwindow_class\fP and \fIvisual\fP set to
  2199. .PN CopyFromParent .
  2200. Both
  2201. .PN compositeWidgetClass
  2202. and
  2203. .PN constraintWidgetClass
  2204. inherit this realize procedure, and most new widget subclasses
  2205. can do the same (see Section 1.6.10).
  2206. .LP
  2207. The most common noninherited realize procedures set \fIbit_gravity\fP in the mask
  2208. and attributes to the appropriate value and then create the window.
  2209. For example, depending on its justification, Label might set \fIbit_gravity\fP to
  2210. .PN WestGravity ,
  2211. .PN CenterGravity ,
  2212. or
  2213. .PN EastGravity .
  2214. Consequently, shrinking it would just move the bits appropriately,
  2215. and no
  2216. exposure
  2217. event is needed for repainting.
  2218. .LP
  2219. If a composite widget's children should be realized in an order other
  2220. than that specified
  2221. (to control the stacking order, for example),
  2222. it should call
  2223. .PN XtRealizeWidget
  2224. on its children itself in the appropriate order from within its own
  2225. realize procedure.
  2226. .LP
  2227. Widgets that have children and whose class is not a subclass of
  2228. .PN compositeWidgetClass
  2229. are responsible for calling
  2230. .PN XtRealizeWidget
  2231. on their children, usually from within the realize procedure.
  2232.  
  2233. .NH 3
  2234. Window Creation Convenience Routine
  2235. .XS
  2236. \*(SN Window Creation Convenience Routine
  2237. .XE
  2238. .LP
  2239. Rather than call the Xlib
  2240. .PN XCreateWindow
  2241. .IN "realize procedure"
  2242. function explicitly, a realize procedure should normally call the \*(xI analog
  2243. .PN XtCreateWindow ,
  2244. which simplifies the creation of windows for widgets.
  2245. .IN "XtCreateWindow" "" "@DEF@"
  2246. .FD 0
  2247. void XtCreateWindow(\fIw\fP, \fIwindow_class\fP, \fIvisual\fP, \
  2248. \fIvalue_mask\fP, \fIattributes\fP)
  2249. .br
  2250.       Widget \fIw\fP;
  2251. .br
  2252.       unsigned int \fIwindow_class\fP;
  2253. .br
  2254.       Visual *\fIvisual\fP;
  2255. .br
  2256.       XtValueMask \fIvalue_mask\fP;
  2257. .br
  2258.       XSetWindowAttributes *\fIattributes\fP;
  2259. .FN
  2260. .IP \fIw\fP 1i
  2261. Specifies the widget that defines the additional window attributed.  \*(cI
  2262. .IP \fIwindow_class\fP 1i
  2263. Specifies the Xlib window class (for example,
  2264. .PN InputOutput ,
  2265. .PN InputOnly ,
  2266. or
  2267. .PN CopyFromParent ).
  2268. .IP \fIvisual\fP 1i
  2269. Specifies the visual type (usually
  2270. .PN CopyFromParent ).
  2271. .ds Vm attribute fields to use
  2272. .IP \fIvalue_mask\fP 1i
  2273. Specifies which fields in the \fIattributes\fP structure are used.
  2274. .IP \fIattributes\fP 1i
  2275. Specifies the window attributes to use in the
  2276. .PN XCreateWindow
  2277. call.
  2278. .LP
  2279. The
  2280. .PN XtCreateWindow
  2281. function calls the Xlib
  2282. .PN XCreateWindow
  2283. function with values from the widget structure and the passed parameters.
  2284. Then, it assigns the created window to the widget's \fIwindow\fP field.
  2285. .LP
  2286. .PN XtCreateWindow
  2287. evaluates the following fields of the widget core
  2288. structure: \fIdepth\fP, \fIscreen\fP, \fIparent->core.window\fP, \fIx\fP,
  2289. \fIy\fP, \fIwidth\fP, \fIheight\fP, and
  2290. \fIborder_width\fP.
  2291.  
  2292. .NH 2
  2293. Obtaining Window Information from a Widget
  2294. .XS
  2295. \fB\*(SN Obtaining Window Information from a Widget\fP
  2296. .XE
  2297. .LP
  2298. The 
  2299. Core
  2300. widget class definition contains the screen and window ids.
  2301. The \fIwindow\fP field may be NULL for a while
  2302. (see Sections 2.5 and 2.6).
  2303. .LP
  2304. The display pointer, the parent widget, screen pointer,
  2305. and window of a widget are available to the widget writer by means of macros 
  2306. and to the application writer by means of functions.
  2307. .sp
  2308. .IN "XtDisplay" "" "@DEF@"
  2309. .FD 0
  2310. Display *XtDisplay(\fIw\fP)
  2311. .br
  2312.       Widget \fIw\fP;
  2313. .FN
  2314. .IP \fIw\fP 1i
  2315. Specifies the widget.  \*(cI
  2316. .LP
  2317. .PN XtDisplay
  2318. returns the display pointer for the specified widget.
  2319. .sp
  2320. .LP
  2321. .IN "XtParent" "" "@DEF@"
  2322. .FD 0
  2323. Widget XtParent(\fIw\fP)
  2324. .br
  2325.      Widget \fIw\fP;
  2326. .FN
  2327. .IP \fIw\fP 1i
  2328. Specifies the widget.  \*(oI
  2329. .LP
  2330. .PN XtParent
  2331. returns the parent object for the specified widget. The returned object
  2332. will be of class Object or a subclass.
  2333. .sp
  2334. .LP
  2335. .IN "XtScreen" "" "@DEF@"
  2336. .FD 0
  2337. Screen *XtScreen(\fIw\fP)
  2338. .br
  2339.       Widget \fIw\fP;
  2340. .FN
  2341. .IP \fIw\fP 1i
  2342. Specifies the widget.  \*(cI
  2343. .LP
  2344. .PN XtScreen
  2345. returns the screen pointer for the specified widget.
  2346. .sp
  2347. .LP
  2348. .IN "XtWindow" "" "@DEF@"
  2349. .FD 0
  2350. Window XtWindow(\fIw\fP)
  2351. .br
  2352.       Widget \fIw\fP;
  2353. .FN
  2354. .IP \fIw\fP 1i
  2355. Specifies the widget.  \*(cI
  2356. .LP
  2357. .PN XtWindow
  2358. returns the window of the specified widget.
  2359. .sp
  2360. .LP
  2361. The display pointer, screen pointer, and window of a widget or
  2362. of the closest widget ancestor of a nonwidget object are available
  2363. by means of
  2364. .PN XtDisplayOfObject ,
  2365. .PN XtScreenOfObject ,
  2366. and
  2367. .PN XtWindowOfObject .
  2368. .IN "XtDisplayOfObject" "" "@DEF@"
  2369. .sp
  2370. .LP
  2371. .FD 0
  2372. Display *XtDisplayOfObject(\fIobject\fP)
  2373. .br
  2374.       Widget \fIobject\fP;
  2375. .FN
  2376. .IP \fIobject\fP 1i
  2377. Specifies the object.  \*(oI
  2378. .LP
  2379. .PN XtDisplayOfObject
  2380. is identical in function to
  2381. .PN XtDisplay
  2382. if the object is a widget; otherwise
  2383. .PN XtDisplayOfObject
  2384. returns the display
  2385. pointer for the nearest ancestor of \fIobject\fP that is of class
  2386. Widget or a subclass thereof.
  2387. .sp
  2388. .IN "XtScreenOfObject" "" "@DEF@"
  2389. .FD 0
  2390. Screen *XtScreenOfObject(\fIobject\fP)
  2391. .br
  2392.       Widget \fIobject\fP;
  2393. .FN
  2394. .IP \fIobject\fP 1i
  2395. Specifies the object.  \*(oI
  2396. .LP
  2397. .PN XtScreenOfObject
  2398. is identical in function to
  2399. .PN XtScreen
  2400. if the object is a widget; otherwise
  2401. .PN XtScreenOfObject
  2402. returns the screen pointer
  2403. for the nearest ancestor of \fIobject\fP that is of class
  2404. Widget or a subclass thereof.
  2405. .sp
  2406. .IN "XtWindowOfObject" "" "@DEF@"
  2407. .FD 0
  2408. Window XtWindowOfObject(\fIobject\fP)
  2409. .br
  2410.       Widget \fIobject\fP;
  2411. .FN
  2412. .IP \fIobject\fP 1i
  2413. Specifies the object.  \*(oI
  2414. .LP
  2415. .PN XtWindowOfObject
  2416. is identical in function to
  2417. .PN XtWindow
  2418. if the object is a widget; otherwise
  2419. .PN XtWindowOfObject
  2420. returns the window for the nearest ancestor of \fIobject\fP that is of class
  2421. Widget or a subclass thereof.
  2422. .sp
  2423. .LP
  2424. To retrieve the instance name of an object, use
  2425. .PN XtName .
  2426. .IN "XtName" "" "@DEF@"
  2427. .FD 0
  2428. String XtName(\fIobject\fP)
  2429. .br
  2430.       Widget \fIobject\fP;
  2431. .FN
  2432. .IP \fIobject\fP 1i
  2433. Specifies the object whose name is desired.  \*(oI
  2434. .LP
  2435. .PN XtName
  2436. returns a pointer to the instance name of the specified object.
  2437. The storage is owned by the \*(xI and must not be modified.  The
  2438. name is not qualified by the names of any of the object's ancestors.
  2439. .LP
  2440. Several window attributes are locally cached in the widget instance.
  2441. Thus, they can be set by the resource manager and
  2442. .PN XtSetValues 
  2443. as well as used by routines that derive structures from these values
  2444. (for example, \fIdepth\fP for deriving pixmaps,
  2445. \fIbackground_pixel\fP for deriving GCs, and so on) or in the
  2446. .PN XtCreateWindow
  2447. call.
  2448. .LP
  2449. The \fIx\fP, \fIy\fP, \fIwidth\fP, \fIheight\fP, and \fIborder_width\fP
  2450. window attributes are available to
  2451. geometry managers.
  2452. These fields are maintained synchronously inside the \*(xI.
  2453. When an
  2454. .PN XConfigureWindow
  2455. is issued by the \*(xI on the widget's window (on request of its parent),
  2456. these values are updated immediately rather than some time later
  2457. when the server generates a
  2458. .PN ConfigureNotify
  2459. event.
  2460. (In fact, most widgets do not select
  2461. .PN SubstructureNotify
  2462. events.)
  2463. This ensures that all geometry calculations are based on the internally
  2464. consistent toolkit world rather than on either
  2465. an inconsistent world updated by asynchronous
  2466. .PN ConfigureNotify
  2467. events or a consistent but slow world in which geometry managers ask the server
  2468. for window sizes whenever they need to lay out their managed children
  2469. (see Chapter 6).
  2470.  
  2471. .NH 3
  2472. Unrealizing Widgets
  2473. .XS
  2474. \fB\*(SN Unrealizing Widgets\fP
  2475. .XE
  2476. .LP
  2477. To destroy the windows associated with a widget and its
  2478. non-pop-up descendants, use
  2479. .PN XtUnrealizeWidget .
  2480. .IN "XtUnrealizeWidget" "" "@DEF@"
  2481. .FD 0
  2482. void XtUnrealizeWidget(\fIw\fP)
  2483. .br
  2484.       Widget \fIw\fP;
  2485. .FN
  2486. .IP \fIw\fP 1i
  2487. Specifies the widget.  \*(cI
  2488. .LP
  2489. If the widget is currently unrealized,
  2490. .PN XtUnrealizeWidget
  2491. simply returns.  Otherwise it performs the following:
  2492. .IP \(bu 5
  2493. Unmanages the widget if the widget is managed.
  2494. .IP \(bu 5
  2495. Makes a postorder (child-to-parent) traversal of the widget tree
  2496. rooted at the specified widget and, for each widget that has
  2497. declared a callback list resource named ``unrealizeCallback'', executes the
  2498. procedures on the
  2499. .IN XtNunrealizeCallback
  2500. XtNunrealizeCallback
  2501. list.
  2502. .IN "unrealizeCallback" "" "@DEF@"
  2503. .IP \(bu 5
  2504. Destroys the widget's window and any subwindows by calling
  2505. .PN XDestroyWindow
  2506. with the specified widget's \fIwindow\fP field.
  2507. .LP
  2508. Any events in the queue or which arrive following a call to
  2509. .PN XtUnrealizeWidget
  2510. will be dispatched as if the window(s) of the
  2511. unrealized widget(s) had never existed.
  2512.  
  2513. .NH 2
  2514. Destroying Widgets
  2515. .XS
  2516. \fB\*(SN Destroying Widgets\fP
  2517. .XE
  2518. .LP
  2519. The \*(xI provide support
  2520. .IP \(bu 5
  2521. To destroy all the pop-up children of the widget being destroyed
  2522. and destroy all children of composite widgets.
  2523. .IP \(bu 5
  2524. To remove (and unmap) the widget from its parent.
  2525. .IP \(bu 5
  2526. To call the callback procedures that have been registered to trigger 
  2527. when the widget is destroyed.
  2528. .IP \(bu 5
  2529. To minimize the number of things a widget has to deallocate when destroyed.
  2530. .IP \(bu 5
  2531. To minimize the number of
  2532. .PN XDestroyWindow
  2533. calls when destroying a widget tree.
  2534. .sp
  2535. .LP
  2536. To destroy a widget instance, use
  2537. .PN XtDestroyWidget .
  2538. .IN "XtDestroyWidget" "" "@DEF@"
  2539. .FD 0
  2540. void XtDestroyWidget(\fIw\fP)
  2541. .br
  2542.       Widget \fIw\fP;
  2543. .FN
  2544. .IP \fIw\fP 1i
  2545. Specifies the widget.  \*(oI
  2546. .LP
  2547. The
  2548. .PN XtDestroyWidget
  2549. function provides the only method of destroying a widget,
  2550. including widgets that need to destroy themselves.
  2551. It can be called at any time,
  2552. including from an application callback routine of the widget being destroyed.
  2553. This requires a two-phase destroy process in order to avoid dangling
  2554. references to destroyed widgets.
  2555. .LP
  2556. In phase 1,
  2557. .PN XtDestroyWidget
  2558. performs the following:
  2559. .IP \(bu 5
  2560. If the \fIbeing_destroyed\fP field of the widget is 
  2561. .PN True ,
  2562. it returns immediately.
  2563. .IP \(bu 5
  2564. Recursively descends the widget tree and
  2565. sets the \fIbeing_destroyed\fP field to 
  2566. .PN True 
  2567. for the widget and all normal and pop-up children.
  2568. .IP \(bu 5
  2569. Adds the widget to a list of widgets (the destroy list) that should be
  2570. destroyed when it is safe to do so.
  2571. .LP
  2572. Entries on the destroy list satisfy the invariant that
  2573. if w2 occurs after w1 on the destroy list, then w2 is not a descendent,
  2574. either normal or pop-up, of w1.
  2575. .LP
  2576. Phase 2 occurs when all procedures that should execute as a result of
  2577. the current event have been called, including all procedures registered with
  2578. the event and translation managers,
  2579. that is, when the current invocation of
  2580. .PN XtDispatchEvent
  2581. is about to return, or immediately if not in
  2582. .PN XtDispatchEvent .
  2583. .LP
  2584. In phase 2,
  2585. .PN XtDestroyWidget
  2586. performs the following on each entry in the destroy list in the order
  2587. specified:
  2588. .IP \(bu 5
  2589. Calls the destroy callback procedures registered on the widget 
  2590. and all normal and pop-up descendants in postorder (it calls child
  2591. callbacks before parent callbacks).
  2592. .IP \(bu 5
  2593. If the widget is not a pop-up child and the widget's parent is a subclass of 
  2594. .PN composite\%WidgetClass ,
  2595. and if the parent is not being destroyed, 
  2596. it calls 
  2597. .PN XtUnmanageChild 
  2598. on the widget and then calls the widget's parent's delete_child procedure
  2599. (see Section 3.3).
  2600. .IP \(bu 5
  2601. If the widget is not a pop-up child and the widget's parent is a subclass of
  2602. .PN constraint\%WidgetClass ,
  2603. it calls the
  2604. .PN ConstraintClassPart
  2605. destroy procedure for the parent,
  2606. then for the parent's superclass,
  2607. until finally it calls the
  2608. .PN ConstraintClassPart
  2609. destroy procedure for
  2610. .PN constraintWidgetClass .
  2611. .IP \(bu 5
  2612. Calls the destroy procedures
  2613. for the widget and all normal and pop-up descendants
  2614. in postorder.
  2615. For each such widget,
  2616. it calls the
  2617. .PN CoreClassPart
  2618. destroy procedure declared in the widget class,
  2619. then the destroy procedure declared in its superclass,
  2620. until finally it calls the destroy procedure declared in the Object
  2621. class record.
  2622. .IP \(bu 5
  2623. Calls
  2624. .PN XDestroyWindow
  2625. if the specified widget is realized (that is, has an X window).
  2626. The server recursively destroys all normal descendant windows.
  2627. .IP \(bu 5
  2628. Recursively descends the tree and destroys the windows for all
  2629. realized pop-up descendants,
  2630. deallocates all pop-up descendants, constraint
  2631. records, callback lists, and if the widget's class is a subclass of 
  2632. .PN compositeWidgetClass , 
  2633. children.
  2634.  
  2635. .NH 3
  2636. Adding and Removing Destroy Callbacks
  2637. .XS
  2638. \fB\*(SN Adding and Removing Destroy Callbacks\fP
  2639. .XE
  2640. .LP
  2641. When an application needs to perform additional processing during the
  2642. destruction of a widget,
  2643. it should register a destroy callback procedure for the widget.
  2644. The destroy callback procedures use the mechanism described in Chapter 8.
  2645. .IN "Destroy Callbacks"
  2646. The destroy callback list is identified by the resource name
  2647. XtNdestroyCallback.
  2648. .LP
  2649. For example, the following adds an application-supplied destroy callback 
  2650. procedure \fIClientDestroy\fP with client data to a widget by calling
  2651. .PN XtAddCallback .
  2652. .IN "XtAddCallback"
  2653. .Ds
  2654. XtAddCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
  2655. .De
  2656. .LP
  2657. Similarly, the following removes the application-supplied destroy callback
  2658. procedure \fIClientDestroy\fP by calling
  2659. .PN XtRemoveCallback .
  2660. .IN "XtRemoveCallback"
  2661. .Ds
  2662. XtRemoveCallback(\fIw\fP, XtNdestroyCallback, \fIClientDestroy\fP, \fIclient_data\fP)
  2663. .De
  2664. .LP
  2665. The \fIClientDestroy\fP argument is of type
  2666. .PN XtCallbackProc ;
  2667. see Section 8.1.
  2668.  
  2669. .NH 3
  2670. Dynamic Data Deallocation: the destroy Procedure
  2671. .XS
  2672. \*(SN Dynamic Data Deallocation: the destroy Procedure
  2673. .XE
  2674. .LP
  2675. .IN "destroy procedure" "" "@DEF@"
  2676. The destroy procedure pointers in the
  2677. .PN ObjectClassPart ,
  2678. .PN RectObjClassPart ,
  2679. and
  2680. .PN CoreClassPart
  2681. structures are of type
  2682. .PN XtWidgetProc .
  2683. .IN "XtWidgetProc" "" "@DEF@"
  2684. .FD 0
  2685. typedef void (*XtWidgetProc)(Widget);
  2686. .br
  2687.       Widget \fIw\fP;
  2688. .FN
  2689. .IP \fIw\fP i1
  2690. Specifies the widget being destroyed.
  2691. .LP
  2692. The destroy procedures are called in subclass-to-superclass order.
  2693. Therefore, a widget's destroy procedure only should deallocate storage
  2694. that is specific to the subclass and should ignore the storage
  2695. allocated by any of its superclasses.
  2696. The destroy procedure should only deallocate resources that have been
  2697. explicitly created by the subclass.
  2698. Any resource that was obtained from the resource database 
  2699. or passed in an argument list was not created by the widget
  2700. and therefore should not be destroyed by it.
  2701. If a widget does not need to deallocate any storage,
  2702. the destroy procedure entry in its class record can be NULL.
  2703. .LP
  2704. Deallocating storage includes, but is not limited to,
  2705. the following steps:
  2706. .IP \(bu 5
  2707. Calling
  2708. .PN XtFree
  2709. on dynamic storage allocated with
  2710. .PN XtMalloc ,
  2711. .PN XtCalloc ,
  2712. and so on.
  2713. .IP \(bu 5
  2714. Calling
  2715. .PN XFreePixmap
  2716. on pixmaps created with direct X calls.
  2717. .IP \(bu 5
  2718. Calling
  2719. .PN XtReleaseGC
  2720. on GCs allocated with
  2721. .PN XtGetGC .
  2722. .IP \(bu 5
  2723. Calling
  2724. .PN XFreeGC
  2725. on GCs allocated with direct X calls.
  2726. .IP \(bu 5
  2727. Calling
  2728. .PN XtRemoveEventHandler
  2729. on event handlers added to other widgets.
  2730. .IP \(bu 5
  2731. Calling
  2732. .PN XtRemoveTimeOut
  2733. on timers created with
  2734. .PN XtAppAddTimeOut .
  2735. .IP \(bu 5
  2736. Calling
  2737. .PN XtDestroyWidget
  2738. for each child if the widget has children
  2739. and is not a subclass of 
  2740. .PN compositeWidgetClass .
  2741. .LP
  2742. During destroy phase 2 for each widget, the \*(xI remove the widget
  2743. from the modal cascade, unregister all event handlers, remove all key,
  2744. keyboard, button, and pointer grabs and remove all callback procedures
  2745. registered on the widget.  Any outstanding selection transfers will time out.
  2746.  
  2747. .NH 3
  2748. Dynamic Constraint Data Deallocation: the ConstraintClassPart destroy Procedure
  2749. .XS
  2750. \*(SN Dynamic Constraint Data Deallocation: the ConstraintClassPart destroy Procedure
  2751. .XE
  2752. .LP
  2753. The constraint destroy procedure identified in the
  2754. .PN ConstraintClassPart
  2755. structure is called for a widget whose parent is a subclass of
  2756. .PN constraintWidgetClass .
  2757. This constraint destroy procedure pointer is of type
  2758. .PN XtWidgetProc .
  2759. The constraint destroy procedures are called in subclass-to-superclass order,
  2760. starting at the class of the widget's parent and ending at
  2761. .PN constraint\%WidgetClass .
  2762. Therefore, a parent's constraint destroy procedure only should deallocate
  2763. storage that is specific to the constraint subclass
  2764. and not storage allocated by any of its superclasses.
  2765. .LP
  2766. If a parent does not need to deallocate any constraint storage,
  2767. the constraint destroy procedure entry
  2768. in its class record can be NULL.
  2769.  
  2770. .NH 2
  2771. Exiting from an Application
  2772. .XS
  2773. \fB\*(SN Exiting from an Application\fP
  2774. .XE
  2775. .LP
  2776. All \*(tk applications should terminate
  2777. by calling
  2778. .PN XtDestroyApplicationContext
  2779. and then exiting
  2780. using the
  2781. standard method for their operating system (typically, by calling
  2782. .PN exit
  2783. for POSIX-based systems).
  2784. The quickest way to make the windows disappear while exiting is to call
  2785. .PN XtUnmapWidget
  2786. on each top-level shell widget.
  2787. The \*(xI have no resources beyond those in the program image,
  2788. and the X server will free its resources when its connection
  2789. to the application is broken.
  2790. .LP
  2791. Depending upon the widget set in use, it may be necessary to explicitly
  2792. destroy individual widgets or widget trees with
  2793. .PN XtDestroyWidget
  2794. before calling
  2795. .PN XtDestroyApplicationContext
  2796. in order to ensure that any
  2797. required widget cleanup is properly executed. The application developer
  2798. must refer to the widget documentation to learn if a widget needs to
  2799. perform additional cleanup beyond that performed automatically by the
  2800. operating system. None of the widget classes defined by the Intrinsics
  2801. require additional cleanup.
  2802. .bp
  2803.