home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / appC < prev    next >
Encoding:
Text File  |  1991-08-27  |  26.5 KB  |  960 lines
  1. .\" $XConsortium: appC,v 1.7 91/08/26 14:37:45 swick Exp $
  2. .\"
  3. .\" Copyright 1985, 1986, 1987, 1988, 1991
  4. .\" Massachusetts Institute of Technology, Cambridge, Massachusetts,
  5. .\" and Digital Equipment Corporation, Maynard, Massachusetts.
  6. .\"
  7. .\" Permission to use, copy, modify and distribute this documentation for any
  8. .\" purpose and without fee is hereby granted, provided that the above copyright
  9. .\" notice appears in all copies and that both that copyright notice and this
  10. .\" permission notice appear in supporting documentation, and that the name of
  11. .\" M.I.T. or Digital not be used in in advertising or publicity pertaining
  12. .\" to distribution of the software without specific, written prior permission.
  13. .\" M.I.T and Digital makes no representations about the suitability of the
  14. .\" software described herein for any purpose.
  15. .\" It is provided ``as is'' without express or implied warranty.
  16. .bp
  17. \&
  18. .sp 1
  19. .ce 3
  20. \s+1\fBAppendix C\fP\s-1
  21.  
  22. \s+1\fBCompatibility Functions\fP\s-1
  23. .sp 2
  24. .LP
  25. .XS
  26. Appendix C \- Compatibility Functions
  27. .XE
  28. .LP
  29. In prototype versions of the \*(tk
  30. each widget class
  31. implemented an Xt<\^\fIWidget\fP\^>Create (for example,
  32. .PN XtLabelCreate )
  33. function, in which most of the code was identical from widget to widget.
  34. In the \*(xI, a single generic
  35. .PN XtCreateWidget
  36. performs most of the common work and then calls the initialize procedure
  37. implemented for the particular widget class.
  38. .LP
  39. Each Composite class also implemented the procedures
  40. Xt<\^\fIWidget\fP\^>Add and an Xt<\^\fIWidget\fP\^>Delete (for example,
  41. .PN XtButtonBoxAddButton
  42. and
  43. .PN XtButtonBoxDeleteButton ).
  44. In the \*(xI, the Composite generic procedures
  45. .PN XtManageChildren
  46. and
  47. .PN XtUnmanageChildren
  48. perform error checking and screening out of certain children.
  49. Then they call the change_managed procedure
  50. implemented for the widget's Composite class.
  51. If the widget's parent has not yet been realized,
  52. the call to the change_managed procedure is delayed until realization time.
  53. .LP
  54. Old style calls can be implemented in the \*(tk by defining
  55. one-line procedures or macros that invoke a generic routine.  For example,
  56. you could define the macro
  57. .PN XtLabelCreate
  58. as:
  59. .IP
  60. .Ds 0
  61. .TA .5i 3i
  62. .ta .5i 3i
  63. #define XtLabelCreate(\fIname\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP) \\
  64.         ((LabelWidget) XtCreateWidget(\fIname\fP, \fIlabelWidgetClass\fP,   \
  65. \fIparent\fP, \fIargs\fP, \fInum_args\fP))
  66. .De
  67. .sp
  68. .LP
  69. Pop-up shells in some of the prototypes automatically performed an
  70. .PN XtManageChild
  71. on their child within their insert_child procedure.
  72. .IN "insert_child procedure"
  73. Creators of pop-up children need to call
  74. .PN XtManageChild
  75. themselves.
  76. .sp
  77. .LP
  78. As a convenience to people converting from earlier versions of the toolkit
  79. without application contexts, the following routines exist:
  80. .PN XtInitialize ,
  81. .PN XtMainLoop ,
  82. .PN XtNextEvent ,
  83. .PN XtProcessEvent ,
  84. .PN XtPeekEvent ,
  85. .PN XtPending ,
  86. .PN XtAddInput ,
  87. .PN XtAddTimeOut ,
  88. .PN XtAddWorkProc ,
  89. .PN XtCreateApplicationShell ,
  90. .PN XtAddActions ,
  91. .PN XtSetSelectionTimeout ,
  92. and
  93. .PN XtGetSelectionTimeout .
  94. .sp
  95. .IN "XtInitialize" "" "@DEF@"
  96. .FD 0
  97. Widget XtInitialize(\fIshell_name\fP, \fIapplication_class\fP, \fIoptions\fP, \
  98. \fInum_options\fP, \fIargc\fP, \fIargv\fP)
  99. .br
  100.       String \fIshell_name\fP;
  101. .br
  102.       String \fIapplication_class\fP;
  103. .br
  104.       XrmOptionDescRec \fIoptions\fP[];
  105. .br
  106.       Cardinal \fInum_options\fP;
  107. .br
  108.       int *\fIargc\fP;
  109. .br
  110.       String \fIargv\fP[];
  111. .FN
  112. .IP \fIshell_name\fP 1i
  113. This parameter is ignored; therefore, you can specify NULL.
  114. .IP \fIapplication_class\fP 1i
  115. Specifies the class name of this application.
  116. .IP \fIoptions\fP 1i
  117. Specifies how to parse the command line for any application-specific resources.
  118. The \fIoptions\fP argument is passed as a parameter to 
  119. .PN XrmParseCommand .
  120. .IP \fInum_options\fP 1i
  121. Specifies the number of entries in the options list.
  122. .IP \fIargc\fP 1i
  123. Specifies a pointer to the number of command line parameters.
  124. .IP \fIargv\fP 1i
  125. Specifies the command line parameters.
  126. .LP
  127. .PN XtInitialize
  128. calls
  129. .PN XtToolkitInitialize
  130. to initialize the toolkit internals,
  131. creates a default application context for use by the other convenience
  132. routines, calls
  133. .PN XtOpenDisplay
  134. with \fIdisplay_string\fP NULL and \fIapplication_name\fP NULL, and
  135. finally calls
  136. .PN XtAppCreateShell
  137. with \fIapplication_name\fP NULL and
  138. returns the created shell.
  139. The semantics of calling
  140. .PN XtInitialize
  141. more than once are undefined.
  142. This routine has been replaced by
  143. .PN XtAppInitialize .
  144. .sp
  145. .IN "XtMainLoop" "" "@DEF@"
  146. .FD 0
  147. void XtMainLoop(void)
  148. .FN
  149. .PN XtMainLoop
  150. first reads the next alternate input, timer, or X event by calling
  151. .PN XtNextEvent .
  152. Then it dispatches this to the appropriate registered procedure by calling
  153. .PN XtDispatchEvent .
  154. This routine has been replaced by
  155. .PN XtAppMainLoop .
  156. .sp
  157. .IN "XtNextEvent" "" "@DEF@"
  158. .FD 0
  159. void XtNextEvent(\fIevent_return\fP)
  160. .br
  161.       XEvent *\fIevent_return\fP;
  162. .FN
  163. .IP \fIevent_return\fP 1i
  164. Returns the event information to the specified event structure.
  165. .LP
  166. If no input is on the X input queue for the default application context, 
  167. .PN XtNextEvent 
  168. flushes the X output buffer 
  169. and waits for an event while looking at the alternate input sources 
  170. and timeout values and calling any callback procedures triggered by them.
  171. This routine has been replaced by
  172. .PN XtAppNextEvent .
  173. .PN XtInitialize
  174. must be called before using this routine.
  175. .sp
  176. .IN "XtProcessEvent" "" "@DEF@"
  177. .FD 0
  178. void XtProcessEvent(\fImask\fP)
  179. .br
  180.       XtInputMask \fImask\fP;
  181. .FN
  182. .IP \fImask\fP 1i
  183. Specifies the type of input to process.
  184. .LP
  185. .PN XtProcessEvent
  186. processes one X event, timeout, or alternate input source 
  187. (depending on the value of \fImask\fP), blocking if necessary.
  188. It has been replaced by
  189. .PN XtAppProcessEvent .
  190. .PN XtInitialize
  191. must be called before using this function.
  192. .sp
  193. .IN "XtPeekEvent" "" "@DEF@"
  194. .FD 0
  195. Boolean XtPeekEvent(\fIevent_return\fP)
  196. .br
  197.       XEvent *\fIevent_return\fP;
  198. .FN
  199. .IP \fIevent_return\fP 1i
  200. Returns the event information to the specified event structure.
  201. .LP
  202. If there is an event in the queue for the default application context, 
  203. .PN XtPeekEvent
  204. fills in the event and returns a nonzero value.
  205. If no X input is on the queue, 
  206. .PN XtPeekEvent
  207. flushes the output buffer and blocks until input is available, possibly
  208. calling some timeout callbacks in the process.
  209. If the input is an event,
  210. .PN XtPeekEvent
  211. fills in the event and returns a nonzero value. 
  212. Otherwise, the input is for an alternate input source, and
  213. .PN XtPeekEvent
  214. returns zero. 
  215. This routine has been replaced by
  216. .PN XtAppPeekEvent .
  217. .PN XtInitialize
  218. must be called before using this routine.
  219. .sp
  220. .IN "XtPending" "" "@DEF@"
  221. .FD 0
  222. Boolean XtPending()
  223. .FN
  224. .PN XtPending
  225. returns a nonzero value if there are 
  226. events pending from the X server or alternate input sources in the default
  227. application context.
  228. If there are no events pending, 
  229. it flushes the output buffer and returns a zero value.
  230. It has been replaced by
  231. .PN XtAppPending .
  232. .PN XtInitialize
  233. must be called before using this routine.
  234. .sp
  235. .IN "XtAddInput" "" "@DEF@"
  236. .FD 0
  237. XtInputId XtAddInput(\fIsource\fP, \fIcondition\fP, \fIproc\fP, \
  238. \fIclient_data\fP)
  239. .br
  240.       int \fIsource\fP;
  241. .br
  242.       XtPointer \fIcondition\fP;
  243. .br
  244.       XtInputCallbackProc \fIproc\fP;
  245. .br
  246.       XtPointer \fIclient_data\fP;
  247. .FN
  248. .IP \fIsource\fP 1i
  249. Specifies the source file descriptor on a POSIX-based system 
  250. or other operating-system-dependent device specification.
  251. .IP \fIcondition\fP 1i
  252. Specifies the mask that indicates either a read, write, or exception condition
  253. or some operating-system-dependent condition.
  254. .IP \fIproc\fP 1i
  255. Specifies the procedure called when input is available.
  256. .IP \fIclient_data\fP 1i
  257. Specifies the parameter to be passed to \fIproc\fP when input is available.
  258. .LP
  259. The 
  260. .PN XtAddInput
  261. function registers in the default application context a new 
  262. source of events, 
  263. which is usually file input but can also be file output.
  264. (The word \fIfile\fP should be loosely interpreted to mean any sink 
  265. or source of data.)
  266. .PN XtAddInput
  267. also specifies the conditions under which the source can generate events.
  268. When input is pending on this source in the default application context, 
  269. the callback procedure is called.
  270. This routine has been replaced by
  271. .PN XtAppAddInput .
  272. .PN XtInitialize
  273. must be called before using this routine.
  274. .sp
  275. .IN "XtAddTimeOut" "" "@DEF@"
  276. .FD 0
  277. XtIntervalId XtAddTimeOut(\fIinterval\fP, \fIproc\fP, \fIclient_data\fP)
  278. .br
  279.       unsigned long \fIinterval\fP;
  280. .br
  281.       XtTimerCallbackProc \fIproc\fP;
  282. .br
  283.       XtPointer \fIclient_data\fP;
  284. .FN
  285. .IP \fIinterval\fP 1i
  286. Specifies the time interval in milliseconds.
  287. .IP \fIproc\fP 1i
  288. Specifies the procedure to be called when time expires.
  289. .IP \fIclient_data\fP 1i
  290. Specifies the parameter to be passed to \fIproc\fP when it is called.
  291. .LP
  292. The 
  293. .PN XtAddTimeOut
  294. function creates a timeout in the default application context
  295. and returns an identifier for it.
  296. The timeout value is set to \fIinterval\fP.
  297. The callback procedure will be called after
  298. the time interval elapses, after which the timeout is removed.
  299. This routine has been replaced by 
  300. .PN XtAppAddTimeOut .
  301. .PN XtInitialize
  302. must be called before using this routine.
  303. .sp
  304. .IN "XtAddWorkProc" "" "@DEF@"
  305. .FD 0
  306. XtWorkProcId XtAddWorkProc(\fIproc\fP, \fIclient_data\fP)
  307. .br
  308.       XtWorkProc \fIproc\fP;
  309. .br
  310.       XtPointer \fIclient_data\fP;
  311. .FN
  312. .IP \fIproc\fP 1i
  313. Procedure to call to do the work.
  314. .IP \fIclient_data\fP 1i
  315. Client data to pass to \fIproc\fP when it is called.
  316. .LP
  317. This routine registers a work procedure in the default application context. It has
  318. been replaced by
  319. .PN XtAppAddWorkProc .
  320. .PN XtInitialize
  321. must be called before using this routine.
  322. .sp
  323. .IN "XtCreateApplicationShell" "" "@DEF@"
  324. .FD 0
  325. Widget XtCreateApplicationShell(\fIname\fP, \fIwidget_class\fP, \fIargs\fP, \
  326. \fInum_args\fP)
  327. .br
  328.       String \fIname\fP;
  329. .br
  330.       WidgetClass \fIwidget_class\fP;
  331. .br
  332.       ArgList \fIargs\fP;
  333. .br
  334.       Cardinal \fInum_args\fP;
  335. .FN
  336. .IP \fIname\fP 1i
  337. This parameter is ignored; therefore, you can specify NULL.
  338. .IP \fIwidget_class\fP 1i
  339. Specifies the widget class pointer for the created application shell widget.
  340. This will usually be 
  341. .PN topLevelShellWidgetClass 
  342. or a subclass thereof.
  343. .IP \fIargs\fP 1i
  344. Specifies the argument list to override  any other resource specifications.
  345. .IP \fInum_args\fP 1i
  346. Specifies the number of entries in \fIargs\fP.
  347. .LP
  348. The procedure
  349. .PN XtCreateApplicationShell
  350. calls
  351. .PN XtAppCreateShell
  352. with \fIapplication_name\fP NULL, the application class passed to
  353. .PN XtInitialize ,
  354. and the default application context created by
  355. .PN XtInitialize .
  356. This routine has been replaced by
  357. .PN XtAppCreateShell .
  358.  
  359. .sp
  360. .LP
  361. An old-format resource type converter procedure pointer is of type
  362. .PN XtConverter .
  363. .IN "XtConverter" "" "@DEF@"
  364. .FD 0
  365. typedef void (*XtConverter)(XrmValue*, Cardinal*, XrmValue*, XrmValue*);
  366. .br
  367.       XrmValue *\fIargs\fP;
  368. .br
  369.       Cardinal *\fInum_args\fP;
  370. .br
  371.       XrmValue *\fIfrom\fP;
  372. .br
  373.       XrmValue *\fIto\fP;
  374. .FN
  375. .IP \fIargs\fP 1i
  376. Specifies a list of additional
  377. .PN XrmValue
  378. arguments to the converter if additional context is needed
  379. to perform the conversion, or NULL.
  380. .IP \fInum_args\fP 1i
  381. Specifies the number of entries in \fIargs\fP.
  382. .IP \fIfrom\fP 1i
  383. Specifies the value to convert.
  384. .IP \fIto\fP 1i
  385. Specifies the descriptor to use to return the converted value.
  386. .LP
  387. Type converters should perform the following actions:
  388. .IP \(bu 5
  389. Check to see that the number of arguments passed is correct.
  390. .IP \(bu 5
  391. Attempt the type conversion.
  392. .IP \(bu 5
  393. If successful, return the size and pointer to the data in the \fIto\fP argument;
  394. otherwise, call
  395. .PN XtWarningMsg
  396. and return without modifying the \fIto\fP argument.
  397. .LP
  398. Most type converters just take the data described by the specified \fIfrom\fP
  399. argument and return data by writing into the specified \fIto\fP argument.
  400. A few need other information, which is available in the specified 
  401. argument list.
  402. A type converter can invoke another type converter,
  403. which allows differing sources that may convert into a common intermediate
  404. result to make maximum use of the type converter cache.
  405. .LP
  406. Note that the address returned in \fIto->addr\fP cannot be that of a local variable of 
  407. the converter because this is not valid after the converter returns.
  408. It should be a pointer to a static variable.
  409. .LP
  410. The procedure type
  411. .PN XtConverter
  412. has been replaced by
  413. .PN XtTypeConverter .
  414. .sp
  415. .LP
  416. The
  417. .PN XtStringConversionWarning
  418. .IN "XtStringConversionWarning" "" "@DEF@"
  419. function is a convenience routine for old-format resource converters
  420. that convert from strings.
  421. .FD 0
  422. void XtStringConversionWarning(\fIsrc\fP, \fIdst_type\fP)
  423. .br
  424.       String \fIsrc\fP, \fIdst_type\fP;
  425. .FN
  426. .IP \fIsrc\fP 1i
  427. Specifies the string that could not be converted.
  428. .IP \fIdst_type\fP 1i
  429. Specifies the name of the type to which the string could not be converted.
  430. .LP
  431. The
  432. .PN XtStringConversionWarning
  433. function issues a warning message with name ``conversionError'',
  434. type ``string'', class ``XtToolkitError, and the default message string
  435. ``Cannot convert "\fIsrc\fP" to type \fIdst_type\fP''.  This routine
  436. has been superseded by
  437. .PN XtDisplayStringConversionWarning .
  438.  
  439. .sp
  440. .LP
  441. To register an old-format converter, use
  442. .PN XtAddConverter
  443. .IN "XtAddConverter" "" "@DEF@"
  444. or
  445. .PN XtAppAddConverter .
  446. .IN "XtAppAddConverter" "" "@DEF@"
  447. .FD 0
  448. void XtAddConverter(\fIfrom_type\fP, \fIto_type\fP, \fIconverter\fP, \
  449. \fIconvert_args\fP, \fInum_args\fP)
  450. .br
  451.       String \fIfrom_type\fP;
  452. .br
  453.       String \fIto_type\fP;
  454. .br
  455.       XtConverter \fIconverter\fP;
  456. .br
  457.       XtConvertArgList \fIconvert_args\fP;
  458. .br
  459.       Cardinal \fInum_args\fP;
  460. .FN
  461. .IP \fIfrom_type\fP 1i
  462. Specifies the source type.
  463. .IP \fIto_type\fP 1i
  464. Specifies the destination type.
  465. .IP \fIconverter\fP 1i
  466. Specifies the type converter procedure.
  467. .IP \fIconvert_args\fP 1i
  468. Specifies how to compute the additional arguments to the converter, or NULL.
  469. .IP \fInum_args\fP 1i
  470. Specifies the number of entries in \fIconvert_args\fP.
  471. .sp
  472. .LP
  473. .PN XtAddConverter
  474. is equivalent in function to
  475. .PN XtSetTypeConverter
  476. with \fIcache_type\fP equal to
  477. .PN XtCacheAll
  478. for old-format type converters.  It has been superseded by
  479. .PN XtSetTypeConverter.
  480.  
  481. .sp
  482. .FD 0
  483. void XtAppAddConverter(\fIapp_context\fP, \fIfrom_type\fP, \fIto_type\fP, \
  484. \fIconverter\fP, \fIconvert_args\fP, \fInum_args\fP)
  485. .br
  486.       XtAppContext \fIapp_context\fP;
  487. .br
  488.       String \fIfrom_type\fP;
  489. .br
  490.       String \fIto_type\fP;
  491. .br
  492.       XtConverter \fIconverter\fP;
  493. .br
  494.       XtConvertArgList \fIconvert_args\fP;
  495. .br
  496.       Cardinal \fInum_args\fP;
  497. .FN
  498. .IP \fIapp_context\fP 1i
  499. Specifies the application context.
  500. .IP \fIfrom_type\fP 1i
  501. Specifies the source type.
  502. .IP \fIto_type\fP 1i
  503. Specifies the destination type.
  504. .IP \fIconverter\fP 1i
  505. Specifies the type converter procedure.
  506. .IP \fIconvert_args\fP 1i
  507. Specifies how to compute the additional arguments to the converter, or NULL.
  508. .IP \fInum_args\fP 1i
  509. Specifies the number of entries in \fIconvert_args\fP.
  510. .LP
  511. .PN XtAppAddConverter
  512. is equivalent in function to
  513. .PN XtAppSetTypeConverter
  514. with \fIcache_type\fP equal to
  515. .PN XtCacheAll
  516. for old-format type converters.  It has been superseded by
  517. .PN XtAppSetTypeConverter .
  518.  
  519. .sp
  520. .LP
  521. To invoke resource conversions, a client may use
  522. .PN XtConvert
  523. or, for old-format converters only,
  524. .PN XtDirectConvert .
  525. .LP
  526. .sp
  527. .IN "XtConvert" "" "@DEF@"
  528. .FD 0
  529. void XtConvert(\fIw\fP, \fIfrom_type\fP, \fIfrom\fP, \fIto_type\fP, \
  530. \fIto_return\fP)
  531. .br
  532.       Widget \fIw\fP;
  533. .br
  534.       String \fIfrom_type\fP;
  535. .br
  536.       XrmValuePtr \fIfrom\fP;
  537. .br
  538.       String \fIto_type\fP;
  539. .br
  540.       XrmValuePtr \fIto_return\fP;
  541. .FN
  542. .IP \fIw\fP 1i
  543. Specifies the widget to use for additional arguments, if any are
  544. needed.  \(*oI
  545. .IP \fIfrom_type\fP 1i
  546. Specifies the source type.
  547. .IP \fIfrom\fP 1i
  548. Specifies the value to be converted.
  549. .IP \fIto_type\fP 1i
  550. Specifies the destination type.
  551. .IP \fIto_return\fP 1i
  552. Returns the converted value.
  553. .LP
  554. .IN "XtDirectConvert" "" "@DEF@"
  555. .FD 0
  556. void XtDirectConvert(\fIconverter\fP, \fIargs\fP, \fInum_args\fP, \fIfrom\fP, \
  557. \fIto_return\fP)
  558. .br
  559.       XtConverter \fIconverter\fP;
  560. .br
  561.       XrmValuePtr \fIargs\fP;
  562. .br
  563.       Cardinal \fInum_args\fP;
  564. .br
  565.       XrmValuePtr \fIfrom\fP;
  566. .br
  567.       XrmValuePtr \fIto_return\fP;
  568. .FN
  569. .IP \fIconverter\fP 1i
  570. Specifies the conversion procedure to be called.
  571. .IP \fIargs\fP 1i
  572. Specifies the argument list that contains the additional arguments
  573. needed to perform the conversion (often NULL).
  574. .IP \fInum_args\fP 1i
  575. Specifies the number of entries in \fIargs\fP.
  576. .IP \fIfrom\fP 1i
  577. Specifies the value to be converted.
  578. .IP \fIto_return\fP 1i
  579. Returns the converted value.
  580. .LP
  581. The
  582. .PN XtConvert
  583. function looks up the type converter registered to convert \fIfrom_type\fP 
  584. to \fIto_type\fP, computes any additional arguments needed, and then calls
  585. .PN XtDirectConvert or
  586. .PN XtCallConverter .
  587. The
  588. .PN XtDirectConvert
  589. function looks in the converter cache to see if this conversion procedure
  590. has been called with the specified arguments.
  591. If so, it returns a descriptor for information stored in the cache;
  592. otherwise, it calls the converter and enters the result in the cache.
  593. .LP
  594. Before calling the specified converter,
  595. .PN XtDirectConvert
  596. sets the return value size to zero and the return value address to NULL.
  597. To determine if the conversion was successful,
  598. the client should check \fIto_return.addr\fP for non-NULL.
  599. The data returned by
  600. .PN XtConvert
  601. must be copied immediately by the caller,
  602. as it may point to static data in the type converter.
  603. .LP
  604. .PN XtConvert
  605. has been replaced by
  606. .PN XtConvertAndStore ,
  607. and
  608. .PN XtDirectConvert
  609. has been superseded by
  610. .PN XtCallConverter .
  611.  
  612. .sp
  613. .LP
  614. To deallocate a shared GC when it is no longer needed, use
  615. .PN XtDestroyGC .
  616. .IN "XtDestroyGC" "" "@DEF@"
  617. .FD 0
  618. void XtDestroyGC(\fIw\fP, \fIgc\fP)
  619. .br
  620.       Widget \fIw\fP;
  621. .br
  622.       GC \fIgc\fP;
  623. .FN
  624. .IP \fIw\fP 1i
  625. Specifies any object on the display for which the shared GC was
  626. created.  \*(oI
  627. .IP \fIgc\fP 1i
  628. Specifies the shared GC to be deallocated.
  629. .LP
  630. References to sharable GCs are counted and a free request is generated to the
  631. server when the last user of a given GC destroys it.
  632. Note that some earlier versions of
  633. .PN XtDestroyGC
  634. had only a \fIgc\fP argument.
  635. Therefore, this function is not very portable,
  636. and you are encouraged to use
  637. .PN XtReleaseGC
  638. instead.
  639. .sp
  640. .LP
  641. To declare an action table in the default application context
  642. and register it with the translation manager, use
  643. .PN XtAddActions .
  644. .IN "XtAddActions" "" "@DEF@"
  645. .FD 0
  646. void XtAddActions(\fIactions\fP, \fInum_actions\fP)
  647. .br
  648.       XtActionList \fIactions\fP;
  649. .br
  650.       Cardinal \fInum_actions\fP;
  651. .FN
  652. .IP \fIactions\fP 1i
  653. Specifies the action table to register.
  654. .IP \fInum_actions\fP 1i
  655. Specifies the number of entries in \fIactions\fP.
  656. .LP
  657. If more than one action is registered with the same name, 
  658. the most recently registered action is used.
  659. If duplicate actions exist in an action table,
  660. the first is used.
  661. The \*(xI register an action table for
  662. .PN XtMenuPopup
  663. and
  664. .PN XtMenuPopdown
  665. as part of \*(tk initialization.
  666. This routine has been replaced by
  667. .PN XtAppAddActions .
  668. .PN XtInitialize
  669. must be called before using this routine.
  670. .sp
  671. .LP
  672. To set the \*(xI selection timeout in the default application context, use
  673. .PN XtSetSelectionTimeout .
  674. .IN "XtSetSelectionTimeout" "" "@DEF@"
  675. .FD 0
  676. void XtSetSelectionTimeout(\fItimeout\fP)
  677. .br
  678.       unsigned long \fItimeout\fP;
  679. .FN
  680. .IP \fItimeout\fP 1i
  681. Specifies the selection timeout in milliseconds.
  682. This routine has been replaced by
  683. .PN XtAppSetSelectionTimeout .
  684. .PN XtInitialize
  685. must be called before using this routine.
  686. .sp
  687. .LP
  688. To get the current selection timeout value in the default application
  689. context, use
  690. .PN XtGetSelectionTimeout .
  691. .IN "XtGetSelectionTimeout" "" "@DEF@"
  692. .FD 0
  693. unsigned long XtGetSelectionTimeout()
  694. .FN
  695. .LP
  696. The selection timeout is the time within which the two communicating 
  697. applications must respond to one another.
  698. If one of them does not respond within this interval,
  699. the \*(xI abort the selection request.
  700.  
  701. This routine has been replaced by
  702. .PN XtAppGetSelectionTimeout .
  703. .PN XtInitialize
  704. must be called before using this routine.
  705. .sp
  706. .LP
  707. To obtain the global error database (for example, to merge with
  708. an application- or widget-specific database), use
  709. .PN XtGetErrorDatabase .
  710. .IN "XtGetErrorDatabase" "" "@DEF@"
  711. .FD 0
  712. XrmDatabase *XtGetErrorDatabase()
  713. .FN
  714. .LP
  715. The
  716. .PN XtGetErrorDatabase
  717. function returns the address of the error database.
  718. The \*(xI do a lazy binding of the error database and do not merge in the
  719. database file until the first call to
  720. .PN XtGetErrorDatbaseText .
  721. This routine has been replaced by
  722. .PN XtAppGetErrorDatabase .
  723. .sp
  724. .LP
  725. An error message handler can obtain the error database text for an
  726. error or a warning by calling
  727. .PN XtGetErrorDatabaseText .
  728. .IN "XtGetErrorDatabaseText" "" "@DEF@"
  729. .FD 0
  730. void XtGetErrorDatabaseText(\fIname\fP, \fItype\fP, \fIclass\fP, \
  731. \fIdefault\fP, \fIbuffer_return\fP, \fInbytes\fP)
  732. .br
  733.       String \fIname\fP, \fItype\fP, \fIclass\fP;
  734. .br
  735.       String \fIdefault\fP;
  736. .br
  737.       String \fIbuffer_return\fP;
  738. .br
  739.       int \fInbytes\fP;
  740. .FN
  741. .IP \fIname\fP 1i
  742. .br
  743. .ns
  744. .IP \fItype\fP 1i
  745. Specify the name and type that are concatenated to form the resource name 
  746. of the error message.
  747. .IP \fIclass\fP 1i
  748. Specifies the resource class of the error message.
  749. .IP \fIdefault\fP 1i
  750. Specifies the default message to use if an error database entry is not found.
  751. .IP \fIbuffer_return\fP 1i
  752. Specifies the buffer into which the error message is to be returned.
  753. .IP \fInbytes\fP 1i
  754. Specifies the size of the buffer in bytes.
  755. .LP
  756. The
  757. .PN XtGetErrorDatabaseText
  758. returns the appropriate message from the error database
  759. associated with the default application context
  760. or returns the specified default message if one is not found in the
  761. error database.
  762. To form the full resource name and class when querying the database,
  763. the \fIname\fP and \fItype\fP are concatenated with a single ``.''
  764. between them and the \fIclass\fP is concatenated with itself with a
  765. single ``.'' if it does not already contain a ``.''.
  766. This routine has been superseded by
  767. .PN XtAppGetErrorDatabaseText .
  768. .sp
  769. .LP
  770. To register a procedure to be called on fatal error conditions, use
  771. .PN XtSetErrorMsgHandler .
  772. .IN "XtSetErrorMsgHandler" "" "@DEF@"
  773. .FD 0
  774. void XtSetErrorMsgHandler(\fImsg_handler\fP)
  775. .br
  776.       XtErrorMsgHandler \fImsg_handler\fP;
  777. .FN
  778. .IP \fImsg_handler\fP 1i
  779. Specifies the new fatal error procedure, which should not return.
  780. .LP
  781. The default error handler provided by the \*(xI constructs a
  782. string from the error resource database and calls
  783. .PN XtError .
  784. Fatal error message handlers should not return.
  785. If one does,
  786. subsequent \*(xI behavior is undefined.
  787. This routine has been superseded by
  788. .PN XtAppSetErrorMsgHandler .
  789. .sp
  790. .LP
  791. To call the high-level error handler, use
  792. .PN XtErrorMsg .
  793. .IN "XtErrorMsg" "" "@DEF@"
  794. .FD 0
  795. void XtErrorMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
  796. \fIparams\fP, \fInum_params\fP)
  797. .br
  798.       String \fIname\fP;
  799. .br
  800.       String \fItype\fP;
  801. .br
  802.       String \fIclass\fP;
  803. .br
  804.       String \fIdefault\fP;
  805. .br
  806.       String *\fIparams\fP;
  807. .br
  808.       Cardinal *\fInum_params\fP;
  809. .FN
  810. .IP \fIname\fP 1i
  811. Specifies the general kind of error.
  812. .IP \fItype\fP 1i
  813. Specifies the detailed name of the error.
  814. .IP \fIclass\fP 1i
  815. Specifies the resource class.
  816. .IP \fIdefault\fP 1i
  817. Specifies the default message to use if an error database entry is not found.
  818. .IP \fIparams\fP 1i
  819. Specifies a pointer to a list of values to be stored in the message.
  820. .IP \fInum_params\fP 1i
  821. Specifies the number of entries in \fIparams\fP.
  822. .LP
  823. This routine has been superseded by
  824. .PN XtAppErrorMsg .
  825. .sp
  826. .LP
  827. To register a procedure to be called on nonfatal error conditions, use
  828. .PN XtSetWarningMsgHandler .
  829. .IN "XtSetWarningMsgHandler" "" "@DEF@"
  830. .FD 0
  831. void XtSetWarningMsgHandler(\fImsg_handler\fP)
  832. .br
  833.       XtErrorMsgHandler \fImsg_handler\fP;
  834. .FN
  835. .IP \fImsg_handler\fP 1i
  836. Specifies the new nonfatal error procedure, which usually returns.
  837. .LP
  838. The default warning handler provided by the \*(xI constructs a string
  839. from the error resource database and calls
  840. .PN XtWarning .
  841. This routine has been superseded by
  842. .PN XtAppSetWarningMsgHandler .
  843. .sp
  844. .LP
  845. To call the installed high-level warning handler, use
  846. .PN XtWarningMsg .
  847. .IN "XtWarningMsg" "" "@DEF@"
  848. .FD 0
  849. void XtWarningMsg(\fIname\fP, \fItype\fP, \fIclass\fP, \fIdefault\fP, \
  850. \fIparams\fP, \fInum_params\fP)
  851. .br
  852.       String \fIname\fP;
  853. .br
  854.       String \fItype\fP;
  855. .br
  856.       String \fIclass\fP;
  857. .br
  858.       String \fIdefault\fP;
  859. .br
  860.       String *\fIparams\fP;
  861. .br
  862.       Cardinal *\fInum_params\fP;
  863. .FN
  864. .IP \fIname\fP 1i
  865. Specifies the general kind of error.
  866. .IP \fItype\fP 1i
  867. Specifies the detailed name of the error.
  868. .IP \fIclass\fP 1i
  869. Specifies the resource class.
  870. .IP \fIdefault\fP 1i
  871. Specifies the default message to use if an error database entry is not found.
  872. .IP \fIparams\fP 1i
  873. Specifies a pointer to a list of values to be stored in the message.
  874. .IP \fInum_params\fP 1i
  875. Specifies the number of entries in \fIparams\fP.
  876. .LP
  877. This routine has been superseded by
  878. .PN XtAppWarningMsg .
  879. .sp
  880. .LP
  881. To register a procedure to be called on fatal error conditions, use
  882. .PN XtSetErrorHandler .
  883. .IN "XtSetErrorHandler" "" "@DEF@"
  884. .FD 0
  885. void XtSetErrorHandler(\fIhandler\fP)
  886. .br
  887.       XtErrorHandler \fIhandler\fP;
  888. .FN
  889. .IP \fIhandler\fP 1i
  890. Specifies the new fatal error procedure, which should not return.
  891. .LP
  892. The default error handler provided by the \*(xI is
  893. .PN _XtError .
  894. On POSIX-based systems,
  895. it prints the message to standard error and terminates the application.
  896. Fatal error message handlers should not return.
  897. If one does,
  898. subsequent \*(tk behavior is undefined.
  899. This routine has been superseded by
  900. .PN XtAppSetErrorHandler .
  901. .sp
  902. .LP
  903. To call the installed fatal error procedure, use
  904. .PN XtError .
  905. .IN "XtError" "" "@DEF@"
  906. .FD 0
  907. void XtError(\fImessage\fP)
  908. .br
  909.       String \fImessage\fP;
  910. .FN
  911. .IP \fImessage\fP 1i
  912. Specifies the message to be reported.
  913. .LP
  914. Most programs should use
  915. .PN XtAppErrorMsg ,
  916. not
  917. .PN XtError ,
  918. to provide for customization and internationalization of error
  919. messages.  This routine has been superseded by
  920. .PN XtAppError .
  921. .sp
  922. .LP
  923. To register a procedure to be called on nonfatal error conditions, use
  924. .PN XtSetWarningHandler .
  925. .IN "XtSetWarningHandler" "" "@DEF@"
  926. .FD 0
  927. void XtSetWarningHandler(\fIhandler\fP)
  928. .br
  929.       XtErrorHandler \fIhandler\fP;
  930. .FN
  931. .IP \fIhandler\fP 1i
  932. Specifies the new nonfatal error procedure, which usually returns.
  933. .LP
  934. The default warning handler provided by the \*(xI is
  935. .PN _XtWarning .
  936. On POSIX-based systems,
  937. it prints the message to standard error and returns to the caller.
  938. This routine has been superseded by
  939. .PN XtAppSetWarningHandler .
  940. .sp
  941. .LP
  942. To call the installed nonfatal error procedure, use
  943. .PN XtWarning .
  944. .IN "XtWarning" "" "@DEF@"
  945. .FD 0
  946. void XtWarning(\fImessage\fP)
  947. .br
  948.       String \fImessage\fP;
  949. .FN
  950. .IP \fImessage\fP 1i
  951. Specifies the nonfatal error message to be reported.
  952. .LP
  953. Most programs should use
  954. .PN XtAppWarningMsg ,
  955. not
  956. .PN XtWarning ,
  957. to provide for customization and internationalization of warning messages.
  958. This routine has been superseded by
  959. .PN XtAppWarning .
  960.