home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH08 < prev    next >
Encoding:
Text File  |  1991-08-27  |  11.4 KB  |  399 lines
  1. .\" $XConsortium: CH08,v 1.7 91/08/26 13:34:44 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 8\fP\s-1
  20.  
  21. \s+1\fBCallbacks\fP\s-1
  22. .sp 2
  23. .nr H1 8
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 8 \- Callbacks
  31. .XE
  32. .IN "Destroy Callbacks"
  33. Applications and other widgets often need to register a procedure
  34. with a widget that gets called under certain prespecified conditions.
  35. For example,
  36. when a widget is destroyed,
  37. every procedure on the widget's \fIdestroy_callbacks\fP
  38. list is called to notify clients of the widget's impending doom.
  39. .LP
  40. Every widget has an XtNdestroyCallbacks callback list resource.
  41. Widgets can define additional callback lists as they see fit.
  42. For example, the Pushbutton widget has a callback
  43. list to notify clients when the button has been activated.
  44. .LP
  45. Except where otherwise noted, it is the intent that all Intrinsics
  46. functions may be called at any time, including from within callback
  47. procedures, action routines, and event handlers.
  48.  
  49. .NH 2
  50. Using Callback Procedure and Callback List Definitions
  51. .XS
  52. \fB\*(SN Using Callback Procedure and Callback List Definitions\fP
  53. .XE
  54. .IN "XtCallbackList"
  55. .IN "XtCallbackProc"
  56. .LP
  57. Callback procedure pointers for use in callback lists are of type
  58. .PN XtCallbackProc .
  59. .IN "XtCallbackProc" "" "@DEF@"
  60. .FD 0
  61. typedef void (*XtCallbackProc)(Widget, XtPointer, XtPointer);
  62. .br
  63.       Widget \fIw\fP;
  64. .br
  65.       XtPointer \fIclient_data\fP;
  66. .br
  67.       XtPointer \fIcall_data\fP;
  68. .FN
  69. .IP \fIw\fP 1i
  70. Specifies the widget owning the list in which the callback is registered.
  71. .IP \fIclient_data\fP 1i
  72. Specifies additional data supplied by the client when the procedure
  73. was registered.
  74. .IP \fIcall_data\fP 1i
  75. Specifies any callback-specific data the widget wants to pass to the client.
  76. For example,  when Scrollbar executes its XtNthumbChanged callback list,
  77. it passes the new position of the thumb.
  78. .LP
  79. The \fIclient_data\fP argument provides a way for the
  80. client registering the callback procedure also to register client-specific data,
  81. for example, a pointer to additional information about the widget, 
  82. a reason for invoking the callback, and so on.
  83. The \fIclient_data\fP value may be NULL
  84. if all necessary information is in the widget.
  85. The \fIcall_data\fP argument is a convenience to avoid having simple
  86. cases where the client could otherwise always call
  87. .PN XtGetValues
  88. or a widget-specific function to retrieve data from the widget.
  89. Widgets should generally avoid putting complex state information 
  90. in \fIcall_data\fP.
  91. The client can use the more general data retrieval methods, if necessary.
  92. .LP
  93. Whenever a client wants to pass a callback list as an argument in an
  94. .PN XtCreateWidget ,
  95. .PN XtSetValues ,
  96. or
  97. .PN XtGetValues
  98. call, it should specify the address
  99. of a NULL-terminated array of type
  100. .PN XtCallbackList .
  101. .IN "XtCallbackList" "" "@DEF@"
  102. .IN "XtCallbackRec" "" "@DEF@"
  103. .LP
  104. .Ds 0
  105. .TA .5i 3i
  106. .ta .5i 3i
  107. typedef struct {
  108.     XtCallbackProc callback;
  109.     XtPointer closure;
  110. } XtCallbackRec, *XtCallbackList;
  111. .De
  112. .LP
  113. For example, the callback list for procedures A and B with client data
  114. clientDataA and clientDataB, respectively, is
  115. .LP
  116. .KS
  117. .Ds 5
  118. .TA .5i 3i
  119. .ta .5i 3i
  120. static XtCallbackRec callbacks[] = {
  121.     {A, (XtPointer) clientDataA},
  122.     {B, (XtPointer) clientDataB},
  123.     {(XtCallbackProc) NULL, (XtPointer) NULL}
  124. };
  125. .De
  126. .KE
  127. .LP
  128. Although callback lists are passed by address in arglists
  129. and varargs lists,
  130. the \*(xI recognize callback lists
  131. throught the widget resource list and will copy the contents
  132. when necessary.
  133. Widget initialize and set_values procedures
  134. should not allocate memory for the callback list contents.
  135. The \*(xI automatically do this,
  136. potentially using a different structure for their
  137. internal representation.
  138.  
  139. .NH 2
  140. Identifying Callback Lists
  141. .XS
  142. \fB\*(SN Identifying Callback Lists\fP
  143. .XE
  144. .LP
  145. Whenever a widget contains a callback list for use by clients, 
  146. it also exports in its public .h file the resource name of the callback list.
  147. Applications and client widgets never access callback list fields directly.
  148. Instead, they always identify the desired callback list by using the exported
  149. resource name.
  150. All the callback manipulation functions described in this chapter 
  151. except
  152. .PN XtCallCallbackList
  153. check 
  154. to see that the requested callback list is indeed implemented by the widget.
  155. .LP
  156. For the \*(xI to find and correctly handle callback lists,
  157. they must be declared with a resource type of
  158. .PN XtRCallback .
  159. The internal representation of a callback list is
  160. implementation-dependent; widgets may make no assumptions about the
  161. value stored in this resource if it is non-NULL.  Except to compare
  162. the value to NULL (which is equivalent to
  163. .PN XtCallbackStatus
  164. .PN XtCallbackHasNone ),
  165. access to callback list resources must be made
  166. through other \*(xI procedures.
  167.  
  168. .NH 2
  169. Adding Callback Procedures
  170. .XS
  171. \fB\*(SN Adding Callback Procedures\fP
  172. .XE
  173. .LP
  174. To add a callback procedure to a widget's callback list, use
  175. .PN XtAddCallback .
  176. .IN "XtAddCallback" "" "@DEF@"
  177. .FD 0
  178. void XtAddCallback(\fIw\fP, \fIcallback_name, \fP\fIcallback\fP, \
  179. \fIclient_data\fP)
  180. .br
  181.       Widget \fIw\fP;
  182. .br
  183.       String \fIcallback_name\fP;
  184. .br
  185.       XtCallbackProc \fIcallback\fP;
  186. .br
  187.       XtPointer \fIclient_data\fP;
  188. .FN
  189. .IP \fIw\fP 1i
  190. Specifies the widget.  \*(oI
  191. .IP \fIcallback_name\fP 1i
  192. Specifies the callback list to which the procedure is to be appended.
  193. .IP \fIcallback\fP 1i
  194. Specifies the callback procedure.
  195. .IP \fIclient_data\fP 1i
  196. Specifies additional data to be passed to the specified procedure
  197. when it is invoked,
  198. or NULL.
  199. .LP
  200. A callback will be invoked as many times as it occurs in the callback list.
  201. .sp
  202. .LP
  203. To add a list of callback procedures to a given widget's callback list, use
  204. .PN XtAddCallbacks .
  205. .IN "XtAddCallbacks" "" "@DEF@"
  206. .FD 0
  207. void XtAddCallbacks(\fIw\fP, \fIcallback_name, \fP\fIcallbacks\fP)
  208. .br
  209.       Widget \fIw\fP;
  210. .br
  211.       String \fIcallback_name\fP;
  212. .br
  213.       XtCallbackList \fIcallbacks\fP;
  214. .FN
  215. .IP \fIw\fP 1i
  216. Specifies the widget.  \*(oI
  217. .IP \fIcallback_name\fP 1i
  218. Specifies the callback list to which the procedures are to be appended.
  219. .IP \fIcallbacks\fP 1i
  220. Specifies the null-terminated list of callback procedures and corresponding
  221. client data.
  222.  
  223. .NH 2
  224. Removing Callback Procedures
  225. .XS
  226. \fB\*(SN Removing Callback Procedures\fP
  227. .XE
  228. .LP
  229. To delete a callback procedure from a widget's callback list, use
  230. .PN XtRemoveCallback .
  231. .IN "XtRemoveCallback" "" "@DEF@"
  232. .FD 0
  233. void XtRemoveCallback(\fIw\fP, \fIcallback_name\fP, \fIcallback\fP, \
  234. \fIclient_data\fP)
  235. .br
  236.       Widget \fIw\fP;
  237. .br
  238.       String \fIcallback_name\fP;
  239. .br
  240.       XtCallbackProc \fIcallback\fP;
  241. .br
  242.       XtPointer \fIclient_data\fP;
  243. .FN
  244. .IP \fIw\fP 1i
  245. Specifies the widget.  \*(oI
  246. .IP \fIcallback_name\fP 1i
  247. Specifies the callback list from which the procedure is to be deleted.
  248. .IP \fIcallback\fP 1i
  249. Specifies the callback procedure.
  250. .IP \fIclient_data\fP 1i
  251. Specifies the client data to match with the registered callback entry.
  252. .LP
  253. The
  254. .PN XtRemoveCallback
  255. function removes a callback only if both the procedure and the client
  256. data match.
  257. .sp
  258. .LP
  259. To delete a list of callback procedures from a given widget's callback list, use
  260. .PN XtRemoveCallbacks .
  261. .IN "XtRemoveCallbacks" "" "@DEF@"
  262. .FD 0
  263. void XtRemoveCallbacks(\fIw\fP, \fIcallback_name\fP, \fIcallbacks\fP)
  264. .br
  265.       Widget \fIw\fP;
  266. .br
  267.       String \fIcallback_name\fP;
  268. .br
  269.       XtCallbackList \fIcallbacks\fP;
  270. .FN
  271. .IP \fIw\fP 1i
  272. Specifies the widget.  \*(oI
  273. .IP \fIcallback_name\fP 1i
  274. Specifies the callback list from which the procedures are to be deleted.
  275. .IP \fIcallbacks\fP 1i
  276. Specifies the null-terminated list of callback procedures and corresponding
  277. client data.
  278. .sp
  279. .LP
  280. To delete all callback procedures from a given widget's callback list
  281. and free all storage associated with the callback list, use
  282. .PN XtRemoveAllCallbacks .
  283. .IN "XtRemoveAllCallbacks" "" "@DEF@"
  284. .FD 0
  285. void XtRemoveAllCallbacks(\fIw\fP, \fIcallback_name\fP)
  286. .br
  287.       Widget \fIw\fP;
  288. .br
  289.       String \fIcallback_name\fP;
  290. .FN
  291. .IP \fIw\fP 1i
  292. Specifies the widget.  \*(oI
  293. .IP \fIcallback_name\fP 1i
  294. Specifies the callback list to be cleared.
  295.  
  296. .NH 2
  297. Executing Callback Procedures
  298. .XS
  299. \*(SN Executing Callback Procedures
  300. .XE
  301. .LP
  302. To execute the procedures in a given widget's callback list,
  303. specifying the callback list by resource name, use
  304. .PN XtCallCallbacks .
  305. .IN "XtCallCallbacks" "" "@DEF@"
  306. .FD 0
  307. void XtCallCallbacks(\fIw\fP, \fIcallback_name\fP, \fIcall_data\fP)
  308. .br
  309.       Widget \fIw\fP;
  310. .br
  311.       String \fIcallback_name\fP;
  312. .br
  313.       XtPointer \fIcall_data\fP;
  314. .FN
  315. .IP \fIw\fP 1i
  316. Specifies the widget.  \*(oI
  317. .IP \fIcallback_name\fP 1i
  318. Specifies the callback list to be executed.
  319. .IP \fIcall_data\fP 1i
  320. Specifies a callback-list-specific data value to pass to each of the callback
  321. procedure in the list, or NULL.
  322. .sp
  323. .LP
  324. .PN XtCallCallbacks
  325. calls each of the callback procedures in the list
  326. named by \fIcallback_name\fP in the specified widget, passing the client
  327. data registered with the procedure and \fIcall-data\fP.
  328. .sp
  329. .LP
  330. To execute the procedures in a callback list, specifying the callback
  331. list by address, use
  332. .PN XtCallCallbackList .
  333. .IN "XtCallCallbackList" "" "@DEF@"
  334. .FD 0
  335. void XtCallCallbackList(\fIwidget\fP, \fIcallbacks\fP, \fIcall_data\fP)
  336. .br
  337.       Widget \fIwidget\fP;
  338. .br
  339.       XtCallbackList \fIcallbacks\fP;
  340. .br
  341.       XtPointer \fIcall_data\fP;
  342. .FN
  343. .IP \fIwidget\fP 1i
  344. Specifies the widget instance that contains the callback list.  \*(oI
  345. .IP \fIcallbacks\fP 1i
  346. Specifies the callback list to be executed.
  347. .IP \fIcall_data\fP 1i
  348. Specifies a callback-list-specific data value to pass
  349. to each of the callback procedures in the list, or NULL.
  350. .LP
  351. The \fIcallbacks\fP parameter must specify the contents of a widget or
  352. object resource declared with representation type
  353. .PN XtRCallback .
  354. If \fIcallbacks\fP is NULL,
  355. .PN XtCallCallbackList
  356. returns immediately; otherwiese it calls each of the callback
  357. procedures in the list, passing the client data and \fIcall_data\fP.
  358.  
  359. .NH 2
  360. Checking the Status of a Callback List
  361. .XS
  362. \*(SN Checking the Status of a Callback List
  363. .XE
  364. .LP
  365. To find out the status of a given widget's callback list, use
  366. .PN XtHasCallbacks .
  367. .IN "XtHasCallbacks" "" "@DEF@"
  368. .sp
  369. .FD 0
  370. typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} \
  371. XtCallbackStatus;
  372. .sp
  373. XtCallbackStatus XtHasCallbacks(\fIw\fP, \fIcallback_name\fP)
  374. .br
  375.       Widget \fIw\fP;
  376. .br
  377.       String \fIcallback_name\fP;
  378. .FN
  379. .IP \fIw\fP 1i
  380. Specifies the widget.  \*(oI
  381. .IP \fIcallback_name\fP 1i
  382. Specifies the callback list to be checked.
  383. .LP
  384. The
  385. .PN XtHasCallbacks
  386. function first checks to see if the widget has a callback list identified 
  387. by \fIcallback_name\fP.
  388. If the callback list does not exist,
  389. .PN XtHasCallbacks
  390. returns
  391. .PN XtCallbackNoList .
  392. If the callback list exists but is empty,
  393. it returns
  394. .PN XtCallbackHasNone .
  395. If the callback list exists and has at least one callback registered,
  396. it returns
  397. .PN XtCallbackHasSome .
  398. .bp
  399.