home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xt / CH07 < prev    next >
Encoding:
Text File  |  1991-08-27  |  63.4 KB  |  2,361 lines
  1. .\" $XConsortium: CH07,v 1.9 91/08/27 10:03:00 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 7\fP\s-1
  20.  
  21. \s+1\fBEvent Management\fP\s-1
  22. .sp 2
  23. .nr H1 7
  24. .nr H2 0
  25. .nr H3 0
  26. .nr H4 0
  27. .nr H5 0
  28. .LP
  29. .XS
  30. Chapter 7 \- Event Management
  31. .XE
  32. While Xlib allows the reading and processing of events anywhere in an application,
  33. widgets in the \*(tk neither directly read events
  34. nor grab the server or pointer.
  35. Widgets register procedures that are to be called
  36. when an event or class of events occurs in that widget.
  37. .LP
  38. A typical application consists of startup code followed by an event loop
  39. that reads events and dispatches them by calling
  40. the procedures that widgets have registered.
  41. The default event loop provided by the \*(xI is
  42. .PN XtAppMainLoop .
  43. .LP
  44. The event manager is a collection of functions to perform the following tasks:
  45. .IP \(bu 5
  46. Add or remove event sources other than X server events (in particular,
  47. timer interrupts and file input).
  48. .IP \(bu 5
  49. Query the status of event sources.
  50. .IP \(bu 5
  51. Add or remove procedures to be called when an event occurs for a particular
  52. widget.
  53. .IP \(bu 5
  54. Enable and
  55. disable the dispatching of user-initiated events (keyboard and pointer events)
  56. for a particular widget.
  57. .IP \(bu 5
  58. Constrain the dispatching of events to a cascade of pop-up widgets.
  59. .IP \(bu 5
  60. Register procedures to be called when specific events arrive.
  61. .LP
  62. Most widgets do not need to call any of the event handler functions explicitly.
  63. The normal interface to X events is through the higher-level
  64. translation manager,
  65. which maps sequences of X events, with modifiers, into procedure calls.
  66. Applications rarely use any of the event manager routines besides
  67. .PN XtAppMainLoop .
  68.  
  69. .NH 2
  70. Adding and Deleting Additional Event Sources
  71. .XS
  72. \fB\*(SN Adding and Deleting Additional Event Sources\fP
  73. .XE
  74. .LP
  75. While most applications are driven only by X events,
  76. some applications need to incorporate other sources of input 
  77. into the \*(xI event-handling mechanism.
  78. The event manager provides routines to integrate notification of timer events
  79. and file data pending into this mechanism.
  80. .LP
  81. The next section describes functions that provide input gathering from files.
  82. The application registers the files with the \*(xI read routine.
  83. When input is pending on one of the files,
  84. the registered callback procedures are invoked.
  85.  
  86. .NH 3
  87. Adding and Removing Input Sources
  88. .XS
  89. \fB\*(SN Adding and Removing Input Sources\fP
  90. .XE
  91. .LP
  92. To register a new file as an input source for a given application context, use
  93. .PN XtAppAddInput .
  94. .IN "XtAppAddInput" "" "@DEF@"
  95. .FD 0
  96. XtInputId XtAppAddInput(\fIapp_context\fP, \fIsource\fP, \fIcondition\fP, \
  97. \fIproc\fP, \fIclient_data\fP)
  98. .br
  99.       XtAppContext \fIapp_context\fP;
  100. .br
  101.       int \fIsource\fP;
  102. .br
  103.       XtPointer \fIcondition\fP;
  104. .br
  105.       XtInputCallbackProc \fIproc\fP;
  106. .br
  107.       XtPointer \fIclient_data\fP;
  108. .FN
  109. .IP \fIapp_context\fP 1i
  110. Specifies the application context that identifies the application.
  111. .IP \fIsource\fP 1i
  112. Specifies the source file descriptor on a POSIX-based system
  113. or other operating-system-dependent device specification.
  114. .IP \fIcondition\fP 1i
  115. Specifies the mask that indicates a read, write, or exception condition
  116. or some other operating-system-dependent condition.
  117. .IP \fIproc\fP 1i
  118. Specifies the procedure to be called when the condition is found.
  119. .IP \fIclient_data\fP 1i
  120. Specifies an argument passed to the specified procedure
  121. when it is called.
  122. .LP
  123. The
  124. .PN XtAppAddInput
  125. function registers with the \*(xI read routine a new source of events,
  126. which is usually file input but can also be file output.
  127. Note that \fIfile\fP should be loosely interpreted to mean any sink 
  128. or source of data.
  129. .PN XtAppAddInput
  130. also specifies the conditions under which the source can generate events.
  131. When an event is pending on this source,
  132. the callback procedure is called.
  133. .LP
  134. The legal values for the \fIcondition\fP argument are operating-system-dependent.
  135. On a POSIX-based system,
  136. \fIsource\fP is a file number and the condition is some union of the following:
  137. .IN "XtInputReadMask" "" "@DEF"
  138. .IP \fBXtInputReadMask\fR 1.5i
  139. Specifies that \fIproc\fP is to be called when \fIsource\fP has data to be read.
  140. .IN "XtInputWriteMask" "" "@DEF@"
  141. .IP \fBXtInputWriteMask\fR 1.5i
  142. Specifies that \fIproc\fP is to be called when \fIsource\fP is ready
  143. for writing.
  144. .IN "XtInputExceptMask" "" "@DEF@"
  145. .IP \fBXtInputExceptMask\fR 1.5i
  146. Specifies that \fIproc\fP is to be called when \fIsource\fP has
  147. exception data.
  148. .LP
  149. Callback procedure pointers used to handle file events are of
  150. type
  151. .PN XtInputCallbackProc .
  152. .IN "XtInputCallbackProc" "" "@DEF@"
  153. .FD 0
  154. typedef void (*XtInputCallbackProc)(XtPointer, int*, XtInputId*);
  155. .br
  156.       XtPointer \fIclient_data\fP;
  157. .br
  158.       int *\fIsource\fP;
  159. .br
  160.       XtInputId *\fIid\fP;
  161. .FN
  162. .IP \fIclient_data\fP 1i
  163. Passes the client data argument that was registered for this procedure in
  164. .PN XtApp\%AddInput .
  165. .IP \fIsource\fP 1i
  166. Passes the source file descriptor generating the event.
  167. .IP \fIid\fP 1i
  168. Passes the id returned from the corresponding
  169. .PN XtAppAddInput
  170. call.
  171. .sp
  172. .LP
  173. To discontinue a source of input, use
  174. .PN XtRemoveInput .
  175. .IN "XtRemoveInput" "" "@DEF@"
  176. .FD 0
  177. void XtRemoveInput(\fIid\fP)
  178. .br
  179.       XtInputId \fIid\fP;
  180. .FN
  181. .IP \fIid\fP 1i
  182. Specifies the id returned from the corresponding
  183. .PN XtAppAddInput
  184. call.
  185. .LP
  186. The
  187. .PN XtRemoveInput
  188. function causes the \*(xI read routine to stop watching for events
  189. from the file source specified by \fIid\fP.
  190.  
  191. .NH 3
  192. Adding and Removing Timeouts
  193. .XS
  194. \fB\*(SN Adding and Removing Timeouts\fP
  195. .XE
  196. .LP
  197. The timeout facility notifies the application or the widget
  198. through a callback procedure that a specified time interval has elapsed.
  199. Timeout values are uniquely identified by an interval id.
  200. .sp
  201. .LP
  202. To register a timeout callback, use
  203. .PN XtAppAddTimeOut .
  204. .IN "XtAppAddTimeOut" "" "@DEF@"
  205. .FD 0
  206. XtIntervalId XtAppAddTimeOut(\fIapp_context\fP, \fIinterval\fP, \fIproc\fP, \
  207. \fIclient_data\fP)
  208. .br
  209.       XtAppContext \fIapp_context\fP;
  210. .br
  211.       unsigned long \fIinterval\fP;
  212. .br
  213.       XtTimerCallbackProc \fIproc\fP;
  214. .br
  215.       XtPointer \fIclient_data\fP;
  216. .FN
  217. .IP \fIapp_context\fP 1i
  218. Specifies the application context for which the timer is to be set.
  219. .IP \fIinterval\fP 1i
  220. Specifies the time interval in milliseconds.
  221. .IP \fIproc\fP 1i
  222. Specifies the procedure to be called when the time expires.
  223. .IP \fIclient_data\fP 1i
  224. Specifies an argument passed to the specified procedure
  225. when it is called.
  226. .LP
  227. The
  228. .PN XtAppAddTimeOut
  229. function creates a timeout and returns an identifier for it.
  230. The timeout value is set to \fIinterval\fP.
  231. The callback procedure \fIproc\fP is called when
  232. .PN XtAppNextEvent
  233. or
  234. .PN XtAppProcessEvent
  235. is next called after the time interval elapses,
  236. and then the timeout is removed.
  237. .LP
  238. Callback procedure pointers used with timeouts are of
  239. type
  240. .PN XtTimerCallbackProc .
  241. .IN "XtTimerCallbackProc" "" "@DEF@"
  242. .FD 0
  243. typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId*);
  244. .br
  245.       XtPointer \fIclient_data\fP;
  246. .br
  247.       XtIntervalId *\fItimer\fP;
  248. .FN
  249. .IP \fIclient_data\fP 1i
  250. Passes the client data argument that was registered for this procedure in
  251. .PN XtApp\%AddTimeOut .
  252. .IP \fItimer\fP 1i
  253. Passes the id returned from the corresponding
  254. .PN XtAppAddTimeOut
  255. call.
  256. .sp
  257. .LP
  258. To clear a timeout value, use
  259. .PN XtRemoveTimeOut .
  260. .IN "XtRemoveTimeOut" "" "@DEF@"
  261. .FD 0
  262. void XtRemoveTimeOut(\fItimer\fP)
  263. .br
  264.       XtIntervalId \fItimer\fP;
  265. .FN
  266. .IP \fItimer\fP 1i
  267. Specifies the id for the timeout request to be cleared.
  268. .LP
  269. The
  270. .PN XtRemoveTimeOut
  271. function removes the pending timeout.
  272. Note that timeouts are automatically removed once they trigger.
  273.  
  274. .NH 2
  275. Constraining Events to a Cascade of Widgets
  276. .XS
  277. \fB\*(SN Constraining Events to a Cascade of Widgets\fP
  278. .XE
  279. .LP
  280. .IN "Grabbing Input"
  281. .IN "Input Grabbing"
  282. Modal widgets are widgets that, except for the input directed to them,
  283. lock out user input to the application.
  284. .LP
  285. When a modal menu or modal dialog box is popped up using
  286. .PN XtPopup ,
  287. user events (keyboard and pointer events) that occur outside the modal
  288. widget should be delivered to the modal widget or ignored.
  289. In no case will user events be delivered to a widget outside
  290. the modal widget.
  291. .LP
  292. Menus can pop up submenus, and dialog boxes can pop up further dialog
  293. boxes, to create a pop-up cascade.
  294. In this case,
  295. user events may be delivered to one of several modal widgets in the cascade.
  296. .LP
  297. Display-related events should be delivered outside the modal cascade so that
  298. exposure events and the like keep the application's display up-todate.
  299. Any event that occurs within the cascade is delivered as usual.
  300. The user events delivered to the most recent spring-loaded shell 
  301. in the cascade when they occur outside the cascade are called remap events 
  302. and are
  303. .PN KeyPress ,
  304. .PN KeyRelease ,
  305. .PN ButtonPress ,
  306. and
  307. .PN ButtonRelease .
  308. The user events ignored when they occur outside the cascade are
  309. .PN MotionNotify
  310. and
  311. .PN EnterNotify .
  312. All other events are delivered normally.
  313. In particular, note that this is one
  314. way in which widgets can receive
  315. .PN LeaveNotify
  316. events without first receiving
  317. .PN EnterNotify
  318. events; they should be prepared to deal with
  319. this, typically by ignoring any unmatched
  320. .PN LeaveNotify
  321. events.
  322. .LP
  323. .PN XtPopup
  324. uses the 
  325. .PN XtAddGrab
  326. and
  327. .PN XtRemoveGrab
  328. functions to constrain user events to a modal cascade 
  329. and subsequently to remove a grab when the modal widget is popped down.
  330.  
  331. .sp
  332. .LP
  333. To constrain or redirect user input to a modal widget, use
  334. .PN XtAddGrab .
  335. .IN "XtAddGrab" "" "@DEF@"
  336. .FD 0
  337. void XtAddGrab(\fIw\fP, \fIexclusive\fP, \fIspring_loaded\fP)
  338. .br
  339.       Widget \fIw\fP;
  340. .br
  341.       Boolean \fIexclusive\fP;
  342. .br
  343.       Boolean \fIspring_loaded\fP;
  344. .FN
  345. .IP \fIw\fP 1i
  346. Specifies the widget to add to the modal cascade. \*(cI
  347. .IP \fIexclusive\fP 1i
  348. Specifies whether user events should be dispatched exclusively to this widget 
  349. or also to previous widgets in the cascade.
  350. .IP \fIspring_loaded\fP 1i
  351. Specifies whether this widget was popped up because the user pressed
  352. a pointer button.
  353. .LP
  354. The
  355. .PN XtAddGrab
  356. function appends the widget to the modal cascade
  357. and checks that \fIexclusive\fP is 
  358. .PN True 
  359. if \fIspring_loaded\fP is 
  360. .PN True .
  361. If this condition is not met,
  362. .PN XtAddGrab
  363. generates a warning message.
  364. .LP
  365. The modal cascade is used by
  366. .PN XtDispatchEvent
  367. when it tries to dispatch a user event.
  368. When at least one modal widget is in the widget cascade, 
  369. .PN XtDispatchEvent
  370. first determines if the event should be delivered.
  371. It starts at the most recent cascade entry and follows the cascade up to and
  372. including the most recent cascade entry added with the \fIexclusive\fP parameter
  373. .PN True .
  374. .LP
  375. This subset of the modal cascade along with all descendants of these widgets
  376. comprise the active subset.
  377. User events that occur outside the widgets in this subset are ignored
  378. or remapped.
  379. Modal menus with submenus generally add a submenu widget to the cascade
  380. with \fIexclusive\fP 
  381. .PN False .
  382. Modal dialog boxes that need to restrict user input to the most deeply nested
  383. dialog box add a subdialog widget to the cascade with \fIexclusive\fP 
  384. .PN True .
  385. User events that occur within the active subset are delivered to the
  386. appropriate widget, which is usually a child or further descendant of the modal
  387. widget.
  388. .LP
  389. Regardless of where in the application they occur,
  390. remap events are always delivered to the most recent widget in the active
  391. subset of the cascade registered with \fIspring_loaded\fP 
  392. .PN True ,
  393. if any such widget exists.
  394. If the event
  395. occurred in the active subset of the cascade but outside the
  396. spring-loaded widget, it is delivered normally before being
  397. delivered also to the spring-loaded widget.
  398. Regardless of where it is dispatched, the \*(xI do not modify
  399. the contents of the event.
  400. .sp
  401. .LP
  402. To remove the redirection of user input to a modal widget, use
  403. .PN XtRemoveGrab .
  404. .IN "XtRemoveGrab" "" "@DEF@"
  405. .FD 0
  406. void XtRemoveGrab(\fIw\fP)
  407. .br
  408.       Widget \fIw\fP;
  409. .FN
  410. .IP \fIw\fP 1i
  411. Specifies the widget to remove from the modal cascade.
  412. .LP
  413. The
  414. .PN XtRemoveGrab
  415. function removes widgets from the modal cascade starting 
  416. at the most recent widget up to and including the specified widget.
  417. It issues a warning if the specified widget is not on the modal cascade.
  418.  
  419. .NH 3
  420. Requesting Key and Button Grabs
  421. .XS
  422. \fB\*(SN Requesting Key and Button Grabs\fP
  423. .XE
  424. .LP
  425. The \*(xI provide a set of key and button grab interfaces that
  426. are parallel to those provided by Xlib and that allow the \*(xI
  427. to modify event dispatching when necessary.  \*(tk applications and
  428. widgets that need to passively grab keys or buttons or actively grab
  429. the keyboard or pointer should use the
  430. following \*(xI routines rather than the corresponding Xlib
  431. routines.
  432. .sp
  433. .LP
  434. To passively grab a single key of the keyboard, use
  435. .PN XtGrabKey .
  436. .IN "XtGrabKey" "" "@DEF@"
  437. .FD 0
  438. void XtGrabKey(\fIwidget\fP, \fIkeycode\fP, \fImodifiers\fP, \
  439. \fIowner_events\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
  440. .br
  441.       Widget \fIwidget\fP;
  442. .br
  443.       KeyCode \fIkeycode\fP;
  444. .br
  445.       Modifiers \fImodifiers\fP;
  446. .br
  447.       Boolean \fIowner_events\fP;
  448. .br
  449.       int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
  450. .FN
  451. .IP \fIwidget\fP 1i
  452. Specifies the widget in whose window the key is to be grabbed.  \*(cI
  453. .sp 6p
  454. .IP \fIkeycode\fP
  455. .br
  456. .ns
  457. .IP \fImodifiers\fP
  458. .br
  459. .ns
  460. .IP \fIowner_events\fP
  461. .br
  462. .ns
  463. .IP \fIpointer_mode\fP
  464. .br
  465. .ns
  466. .IP \fIkeyboard_mode\fP 1i
  467. Specify arguments to
  468. .PN XGrabKey ;
  469. see Section 12.2 in \fI\*(xL\fP.
  470. .LP
  471. .PN XtGrabKey
  472. calls
  473. .PN XGrabKey
  474. specifying the widget's window as the grab
  475. window if the widget is realized.  The remaining arguments are exactly
  476. as for
  477. .PN XGrabKey .
  478. If the widget is not realized, or is later unrealized, the call to
  479. .PN XGrabKey
  480. will be performed (again) when
  481. the widget is realized and its window becomes mapped.  In the future,
  482. if
  483. .PN XtDispatchEvent
  484. is called with a
  485. .PN KeyPress
  486. event matching the specified keycode and modifiers (which may be
  487. .PN AnyKey
  488. or
  489. .PN AnyModifier ,
  490. respectively) for the
  491. widget's window, the \*(xI will call
  492. .PN XtUngrabKeyboard
  493. with the timestamp from the
  494. .PN KeyPress
  495. event if either of the following conditions is true:
  496. .IP \(bu 3
  497. There is a modal cascade and the widget is not in
  498. the active subset of the cascade and the keyboard was not previously
  499. grabbed, or
  500. .IP \(bu 3
  501. .PN XFilterEvent
  502. returns
  503. .PN True .
  504.  
  505. .sp
  506. .LP
  507. To cancel a passive key grab, use
  508. .PN XtUngrabKey .
  509. .IN "XtUngrabKey" "" "@DEF@"
  510. .FD 0
  511. void XtUngrabKey(\fIwidget\fP, \fIkeycode\fP\fI, modifiers\fP)
  512. .br
  513.       Widget \fIwidget\fP;
  514. .br
  515.       KeyCode \fIkeycode\fP;
  516. .br
  517.       Modifiers \fImodifiers\fP;
  518. .FN
  519. .IP \fIwidget\fP 1i
  520. Specifies the widget in whose window the key was grabbed.
  521. .sp 6p
  522. .IP \fIkeycode\fP
  523. .br
  524. .ns
  525. .IP \fImodifiers\fP 1i
  526. Specify arguments to
  527. .PN XUngrabKey ;
  528. see Section 12.2 in \fI\*(xL\fP.
  529.  
  530. .LP
  531. The
  532. .PN XtUngrabKey
  533. procedure calls
  534. .PN XUngrabKey
  535. specifying the widget's
  536. window as the ungrab window if the widget is realized.  The remaining
  537. arguments are exactly as for
  538. .PN XUngrabKey .
  539. If the widget is not realized,
  540. .PN XtUngrabKey
  541. removes a deferred
  542. .PN XtGrabKey
  543. request, if any, for the specified widget, keycode, and modifiers.
  544. .sp
  545. .LP
  546. To actively grab the keyboard, use
  547. .PN XtGrabKeyboard .
  548. .IN "XtGrabKeyboard" "" "@DEF@"
  549. .FD 0
  550. int XtGrabKeyboard(\fIwidget\fP, \fIowner_events\fP, \fIpointer_mode\fP, \
  551. \fIkeyboard_mode\fP, \fItime\fP)
  552. .br
  553.       Widget \fIwidget\fP;
  554. .br
  555.       Boolean \fIowner_events\fP;
  556. .br
  557.       int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
  558. .br
  559.       Time \fItime\fP;
  560. .br
  561. .FN
  562. .IP \fIwidget\fP 1i
  563. Specifies the widget for whose window the keyboard is to be grabbed.
  564. \*(cI
  565. .sp 6p
  566. .IP \fIowner_events\fP
  567. .br
  568. .ns
  569. .IP \fIpointer_mode\fP
  570. .br
  571. .ns
  572. .IP \fIkeyboard_mode\fP
  573. .br
  574. .ns
  575. .IP \fItime\fP 1i
  576. Specify arguments to
  577. .PN XGrabKeyboard ;
  578. see Section 12.2 in \fI\*(xL\fP.
  579. .LP
  580. If the specified widget is realized
  581. .PN XtGrabKeyboard
  582. calls
  583. .PN XGrabKeyboard
  584. specifying the widget's window as the grab window.  The remaining
  585. arguments and return value are exactly as for
  586. .PN XGrabKeyboard .
  587. If the widget is not realized,
  588. .PN XGrabKeyboard
  589. immediately returns
  590. .PN GrabNotViewable .
  591. No future automatic ungrab is implied by
  592. .PN XtGrabKeyboard .
  593. .sp
  594. .LP
  595. To cancel an active keyboard grab, use
  596. .PN XtUngrabKeyboard .
  597. .IN "XtUngrabKeyboard" "" "@DEF@"
  598. .FD 0
  599. void XtUngrabKeyboard(\fIwidget\fP, \fItime\fP)
  600. .br
  601.       Widget \fIwidget\fP;
  602. .br
  603.       Time \fItime\fP;
  604. .FN
  605. .IP \fIwidget\fP 1i
  606. Specifies the widget that has the active keyboard grab.
  607. .IP \fItime\fP 1i
  608. Specifies the additional argument to
  609. .PN XUngrabKeyboard ;
  610. see Section 12.2 in \fI\*(xL\fP.
  611.  
  612. .LP
  613. .PN XtUngrabKeyboard
  614. calls
  615. .PN XUngrabKeyboard
  616. with the specified time.
  617. .sp
  618. .LP
  619. To passively grab a single pointer button, use
  620. .PN XtGrabButton .
  621. .IN "XtGrabButton" "" "@DEF@"
  622. .FD 0
  623. void XtGrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP, \
  624. \fIowner_events\fP, \fIevent_mask\fP, \fIpointer_mode\fP,
  625.                   \fIkeyboard_mode\fP, \fIconfine_to\fP, \fIcursor\fP)
  626. .br
  627.       Widget \fIwidget\fP;
  628. .br
  629.       int \fIbutton\fP;
  630. .br
  631.       Modifiers \fImodifiers\fP;
  632. .br
  633.       Boolean \fIowner_events\fP;
  634. .br
  635.       unsigned int \fIevent_mask\fP;
  636. .br
  637.       int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
  638. .br
  639.       Window \fIconfine_to\fP;
  640. .br
  641.       Cursor \fIcursor\fP;
  642. .FN
  643. .IP \fIwidget\fP 1i
  644. Specifies the widget in whose window the button is to be grabbed.  \*(cI
  645. .sp 6p
  646. .IP \fIbutton\fP
  647. .br
  648. .ns
  649. .IP \fImodifiers\fP
  650. .br
  651. .ns
  652. .IP \fIowner_events\fP
  653. .br
  654. .ns
  655. .IP \fIevent_mask\fP
  656. .br
  657. .ns
  658. .IP \fIpointer_mode\fP
  659. .br
  660. .ns
  661. .IP \fIkeyboard_mode\fP
  662. .br
  663. .ns
  664. .IP \fIconfine_to\fP
  665. .br
  666. .ns
  667. .IP \fIcursor\fP 1i
  668. Specify arguments to
  669. .PN XGrabButton ;
  670. see Section 12.1 in \fI\*(xL\fP.
  671. .LP
  672. .PN XtGrabButton
  673. calls
  674. .PN XGrabButton
  675. specifying the widget's window as the
  676. grab window if the widget is realized.  The remaining arguments are
  677. exactly as for
  678. .PN XGrabButton .
  679. If the widget is not realized, or is later unrealized, the call to
  680. .PN XGrabButton
  681. will be performed (again)
  682. when the widget is realized and its window becomes mapped.  In the
  683. future, if
  684. .PN XtDispatchEvent
  685. is called with a
  686. .PN ButtonPress
  687. event matching the specified button and modifiers (which may be
  688. .PN AnyButton
  689. or
  690. .PN AnyModifier ,
  691. respectively)
  692. for the widget's window, the \*(xI will call
  693. .PN XtUngrabPointer
  694. with the timestamp from the
  695. .PN ButtonPress
  696. event if either of the following conditions is true:
  697. .IP \(bu 3
  698. There is a modal cascade and the
  699. widget is not in the active subset of the cascade and the pointer was
  700. not previously grabbed, or
  701. .IP \(bu 3
  702. .PN XFilterEvent
  703. returns
  704. .PN True .
  705.  
  706. .sp
  707. .LP
  708. To cancel a passive button grab, use
  709. .PN XtUngrabButton .
  710. .IN "XtUngrabButton" "" "@DEF@"
  711. .FD 0
  712. void XtUngrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP)
  713. .br
  714.       Widget \fIwidget\fP;
  715. .br
  716.       unsigned int \fIbutton\fP;
  717. .br
  718.       Modifiers \fImodifiers\fP;
  719. .FN
  720. .IP \fIwidget\fP 1i
  721. Specifies the widget in whose window the button was grabbed.
  722. .IP \fIbutton\fP
  723. .br
  724. .ns
  725. .IP \fImodifiers\fP 1i
  726. Specify arguments to
  727. .PN XUngrabButton ;
  728. see Section 12.1 in \fI\*(xL\fP.
  729. .LP
  730. The
  731. .PN XtUngrabButton
  732. procedure calls
  733. .PN XUngrabButton
  734. specifying the
  735. widget's window as the ungrab window if the widget is realized.  The
  736. remaining arguments are exactly as for
  737. .PN XUngrabButton .
  738. If the widget is not realized,
  739. .PN XtUngrabButton
  740. removes a deferred
  741. .PN XtGrabButton
  742. request, if any, for the specified widget, button, and modifiers.
  743. .sp
  744. .LP
  745. To actively grab the pointer, use
  746. .PN XtGrabPointer .
  747. .IN "XtGrabPointer" "" "@DEF@"
  748. .FD 0
  749. int XtGrabPointer(\fIwidget\fP, \fIowner_events\fP, \fIevent_mask\fP, \
  750. \fIpointer_mode\fP, \fIkeyboard_mode\fP,
  751.                   \fIconfine_to\fP, \fIcursor\fP, \fItime\fP)
  752. .br
  753.       Widget \fIwidget\fP;
  754. .br
  755.       Boolean \fIowner_events\fP;
  756. .br
  757.       unsigned int \fIevent_mask\fP;
  758. .br
  759.       int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
  760. .br
  761.       Window \fIconfine_to\fP;
  762. .br
  763.       Cursor \fIcursor\fP;
  764. .br
  765.       Time \fItime\fP;
  766. .FN
  767. .IP \fIwidget\fP 1i
  768. Specifies the widget for whose window the pointer is to be grabbed.  \*(cI
  769. .sp 6p
  770. .IP \fIowner_events\fP
  771. .br
  772. .ns
  773. .IP \fIevent_mask\fP
  774. .br
  775. .ns
  776. .IP \fIpointer_mode\fP
  777. .br
  778. .ns
  779. .IP \fIkeyboard_mode\fP
  780. .br
  781. .ns
  782. .IP \fIconfine_to\fP
  783. .br
  784. .ns
  785. .IP \fIcursor\fP
  786. .br
  787. .ns
  788. .IP \fItime\fP 1i
  789. Specify arguments to
  790. .PN XGrabPointer ;
  791. see Section 12.1 in \fI\*(xL\fP.
  792. .LP
  793. If the specified widget is realized,
  794. .PN XtGrabPointer
  795. calls
  796. .PN XGrabPointer ,
  797. specifying the widget's window as the grab window.  The remaining
  798. arguments and return value are exactly as for
  799. .PN XGrabPointer .
  800. If the widget is not realized,
  801. .PN XGrabPointer
  802. immediately returns
  803. .PN GrabNotViewable .
  804. No future automatic ungrab is implied by
  805. .PN XtGrabPointer .
  806. .sp
  807. .LP
  808. To cancel an active pointer grab, use
  809. .PN XtUngrabPointer .
  810. .IN "XtUngrabPointer" "" "@DEF@"
  811. .FD 0
  812. void XtUngrabPointer(\fIwidget\fP, \fItime\fP)
  813. .br
  814.       Widget \fIwidget\fP;
  815. .br
  816.       Time \fItime\fP;
  817. .FN
  818. .IP \fIwidget\fP 1i
  819. Specifies the widget that has the active pointer grab.
  820. .IP \fItime\fP 1i
  821. Specifies the time argument to
  822. .PN XUngrabPointer ;
  823. see Section 12.1 in \fI\*(xL\fP.
  824. .LP
  825. .PN XtUngrabPointer
  826. calls
  827. .PN XUngrabPointer
  828. with the specified time.
  829.  
  830. .NH 2
  831. Focusing Events on a Child
  832. .XS
  833. \fB\*(SN Focusing Events on a Child\fP
  834. .XE
  835. .LP
  836. To redirect keyboard input to a normal descendant of a
  837. widget without calling
  838. .PN XSetInputFocus ,
  839. use
  840. .PN XtSetKeyboardFocus .
  841. .IN "XtSetKeyboardFocus" "" "@DEF@"
  842. .FD 0
  843. void XtSetKeyboardFocus(\fIsubtree\fP\, \fIdescendant\fP)
  844. .br
  845.      Widget \fIsubtree\fP, \fIdescendant\fP;
  846. .FN
  847. .IP \fIsubtree\fP 1i
  848. Specifies the subtree of the hierarchy for which the keyboard focus is 
  849. to be set.  \*(cI
  850. .IP \fIdescendant\fP 1i
  851. Specifies either the normal (non-pop-up) descendant of \fIsubtree\fP to which
  852. keyboard events are logically directed, or 
  853. .PN None .
  854. It is not an error to specify
  855. .PN None
  856. when no input focus was previously set.  \*(oI
  857. .LP
  858. .PN XtSetKeyboardFocus
  859. causes
  860. .PN XtDispatchEvent
  861. to remap keyboard events occurring within the specified subtree
  862. and dispatch them to the specified descendant widget or to an ancestor.
  863. If the descendant's class is not a subclass of Core, the descendant is
  864. replaced by its closest windowed ancestor.
  865. .LP
  866. When there is no modal cascade, keyboard events can be dispatched
  867. to a widget in one of five ways.  Assume the server delivered the
  868. event to the window for widget E (because of X input focus, key or
  869. keyboard grabs, or pointer position).
  870. .IP \(bu 3
  871. If neither E nor any of E's ancestors have redirected the keyboard
  872. focus, or if the event activated a grab for E as specified by a call
  873. to
  874. .PN XtGrabKey
  875. with any value of \fIowner_events\fP, or
  876. if the keyboard is actively grabbed by E with \fIowner_events\fP
  877. .PN False
  878. via
  879. .PN XtGrabKeyboard
  880. or
  881. .PN XtGrabKey
  882. on a previous key press, the event is dispatched to E.
  883. .IP \(bu 3
  884. Beginning with the ancestor of E closest to the root that has
  885. redirected the keyboard focus or E if no such ancestor exists, if
  886. the target of that focus redirection has in turn redirected the
  887. keyboard focus, recursively follow this focus chain to find a widget
  888. F that has not redirected focus.
  889. .RS
  890. .IP \- 3
  891. If E is the final focus target widget F or a descendant of F, the
  892. event is dispatched to E.
  893. .IP \- 3
  894. If E is not F, an ancestor of F, or a descendant of F, and the event
  895. activated a grab for E as specified by a call to
  896. .PN XtGrabKey
  897. for E,
  898. .PN XtUngrabKeyboard
  899. is called.
  900. .IP \- 3
  901. If E is an ancestor of F, and the event is a key press, and either
  902. .RS
  903. .IP + 3
  904. E has grabbed the key with
  905. .PN XtGrabKey
  906. and \fIowner_events\fP
  907. .PN False ,
  908. or
  909. .IP + 3
  910. E has grabbed the key with
  911. .PN XtGrabKey
  912. and \fIowner_events\fP
  913. .PN True ,
  914. and the coordinates of the event are outside the rectangle specified
  915. by E's geometry,
  916. .RE
  917. then the event is dispatched to E.
  918. .IP \- 3
  919. Otherwise, define A as the closest common ancestor of E and F:
  920. .RS
  921. .IP + 3
  922. If there is an active keyboard grab for any widget via either
  923. .PN XtGrabKeyboard
  924. or
  925. .PN XtGrabKey
  926. on a previous key press, or
  927. if no widget between F and A (noninclusive) has grabbed
  928. the key and modifier combination with
  929. .PN XtGrabKey
  930. and any value of \fIowner_events\fP, the event is dispatched to F.
  931. .IP + 3
  932. Else, the event is dispatched to the ancestor of F closest to A
  933. that has grabbed the key and modifier combination with
  934. .PN XtGrabKey .
  935. .RE
  936. .RE
  937. .LP
  938. When there is a modal cascade, if the final destination widget as
  939. identified above is in the active subset of the cascade, the event is
  940. dispatched; otherwise the event is remapped to a spring-loaded shell
  941. or discarded.
  942. Regardless of where it is dispatched, the \*(xI do not modify
  943. the contents of the event.
  944. .LP
  945. When \fIsubtree\fP or one of its descendants acquires the X input focus
  946. or the pointer moves into the subtree such that keyboard events would
  947. now be delivered to the subtree, a
  948. .PN FocusIn
  949. event is generated for the descendant if
  950. .PN FocusChange
  951. events have been selected by the descendant.
  952. Similarly, when \fIsubtree\fP loses the X input focus
  953. or the keyboard focus for one of its ancestors, a
  954. .PN FocusOut
  955. event is generated for descendant if
  956. .PN FocusChange
  957. events have been selected by the descendant.
  958. .sp
  959. .LP
  960. A widget tree may also actively manage the X server input focus.  To
  961. do so, a widget class specifies an accept_focus procedure.
  962. .LP
  963. .IN "accept_focus procedure"
  964. The accept_focus procedure pointer is of type
  965. .PN XtAcceptFocusProc .
  966. .IN "XtAcceptFocusProc" ""@DEF@"
  967. .FD 0
  968. typedef Boolean (*XtAcceptFocusProc)(Widget, Time*);
  969. .br
  970.       Widget \fIw\fP;
  971. .br
  972.       Time *\fItime\fP;
  973. .FN
  974. .IP \fIw\fP 1i
  975. Specifies the widget.
  976. .IP \fItime\fP 1i
  977. Specifies the X time of the event causing the accept focus.
  978. .LP
  979. Widgets that need the input focus can call
  980. .PN XSetInputFocus
  981. explicitly, pursuant to the restrictions of the \fI\*(xC\fP.
  982. To allow outside agents, such as the parent,
  983. to cause a widget to take the input focus,
  984. every widget exports an accept_focus procedure.
  985. The widget returns a value indicating
  986. whether it actually took the focus or not,
  987. so that the parent can give the focus to another widget.
  988. Widgets that need to know when they lose the input focus must use
  989. the Xlib focus notification mechanism explicitly
  990. (typically by specifying translations for
  991. .PN FocusIn
  992. and
  993. .PN FocusOut
  994. events).
  995. Widgets classes that never want the input focus should set the
  996. \fIaccept_focus\fP field to NULL.
  997. .sp
  998. .LP
  999. To call a widget's accept_focus procedure, use
  1000. .PN XtCallAcceptFocus .
  1001. .IN "XtCallAcceptFocus" "" "@DEF@"
  1002. .FD 0
  1003. Boolean XtCallAcceptFocus(\fIw\fP, \fItime\fP)
  1004. .br
  1005.        Widget \fIw\fP;
  1006. .br
  1007.        Time *\fItime\fP;
  1008. .FN
  1009. .IP \fIw\fP 1i
  1010. Specifies the widget.  \*(cI
  1011. .IP \fItime\fP 1i
  1012. Specifies the X time of the event that is causing the focus change.
  1013. .LP
  1014. The
  1015. .PN XtCallAcceptFocus
  1016. function calls the specified widget's accept_focus procedure,
  1017. passing it the specified widget and time, and returns what the accept_focus
  1018. procedure returns.
  1019. If \fIaccept_focus\fP is NULL,
  1020. .PN XtCallAcceptFocus
  1021. returns
  1022. .PN False .
  1023.  
  1024. .NH 2
  1025. Querying Event Sources
  1026. .XS
  1027. \fB\*(SN Querying Event Sources\fP
  1028. .XE
  1029. .LP
  1030. The event manager provides several functions to examine and read events
  1031. (including file and timer events) that are in the queue.
  1032. The next three functions are \*(xI equivalents of the
  1033. .PN XPending ,
  1034. .PN XPeekEvent ,
  1035. and
  1036. .PN XNextEvent
  1037. Xlib calls.
  1038. .sp
  1039. .LP
  1040. .IN "Events
  1041. To determine if there are any events on the input queue for a given application,
  1042. use
  1043. .PN XtAppPending .
  1044. .IN "XtAppPending" "" "@DEF@"
  1045. .FD 0
  1046. XtInputMask XtAppPending(\fIapp_context\fP)
  1047. .br
  1048.       XtAppContext \fIapp_context\fP;
  1049. .FN
  1050. .IP \fIapp_context\fP 1i
  1051. Specifies the application context that identifies the application to check.
  1052. .LP
  1053. The
  1054. .PN XtAppPending
  1055. function returns a nonzero value if there are
  1056. events pending from the X server, timer pending, or other input sources
  1057. pending. The
  1058. value returned is a bit mask that is the OR of
  1059. .PN XtIMXEvent ,
  1060. .PN XtIMTimer ,
  1061. and
  1062. .PN XtIMAlternateInput
  1063. (see
  1064. .PN XtAppProcessEvent ).
  1065. If there are no events pending, 
  1066. .PN XtAppPending
  1067. flushes the output buffers of each Display in the application context
  1068. and returns zero.
  1069. .sp
  1070. .LP
  1071. To return the event from the head of a given application's input queue
  1072. without removing input from the queue, use
  1073. .PN XtAppPeekEvent .
  1074. .IN "XtAppPeekEvent" "" "@DEF@"
  1075. .FD 0
  1076. Boolean XtAppPeekEvent(\fIapp_context\fP, \fIevent_return\fP)
  1077. .br
  1078.       XtAppContext \fIapp_context\fP;
  1079. .br
  1080.       XEvent *\fIevent_return\fP;
  1081. .FN
  1082. .IP \fIapp_context\fP 1i
  1083. Specifies the application context that identifies the application.
  1084. .IP \fIevent_return\fP 1i
  1085. Returns the event information to the specified event structure.
  1086. .LP
  1087. If there is an X event in the queue,
  1088. .PN XtAppPeekEvent
  1089. copies it into \fIevent_return\fP and returns
  1090. .PN True .
  1091. If no X input is on the queue,
  1092. .PN XtAppPeekEvent
  1093. flushes the output buffers of each Display in the application context
  1094. and blocks until some input is available
  1095. (possibly calling some timeout callbacks in the interim).
  1096. If the next available input is an X event,
  1097. .PN XtAppPeekEvent
  1098. fills in \fIevent_return\fP and returns
  1099. .PN True .
  1100. Otherwise, the input is for an input source
  1101. registered with
  1102. .PN XtAppAddInput ,
  1103. and
  1104. .PN XtAppPeekEvent
  1105. returns
  1106. .PN False .
  1107. .sp
  1108. .LP
  1109. To remove and return the event
  1110. from the head of a given application's X event queue,
  1111. use
  1112. .PN XtAppNextEvent .
  1113. .IN "XtAppNextEvent" "" "@DEF@"
  1114. .FD 0
  1115. void XtAppNextEvent(\fIapp_context\fP, \fIevent_return\fP)
  1116. .br
  1117.       XtAppContext \fIapp_context\fP;
  1118. .br
  1119.       XEvent *\fIevent_return\fP;
  1120. .FN
  1121. .IP \fIapp_context\fP 1i
  1122. Specifies the application context that identifies the application.
  1123. .IP \fIevent_return\fP 1i
  1124. Returns the event information to the specified event structure.
  1125. .LP
  1126. If the X event queue is empty,
  1127. .PN XtAppNextEvent
  1128. flushes the X output buffers of each Display in the application context
  1129. and waits for an X event while looking at the other input sources
  1130. and timeout values and calling any callback procedures triggered by them.
  1131. This wait time can be used for background processing;
  1132. see Section 7.8.
  1133.  
  1134. .NH 2
  1135. Dispatching Events
  1136. .XS
  1137. \fB\*(SN Dispatching Events\fP
  1138. .XE
  1139. .LP
  1140. The \*(xI provide functions that dispatch events
  1141. to widgets or other application code.
  1142. Every client interested in X events on a widget uses
  1143. .PN XtAddEventHandler
  1144. to register which events it is
  1145. interested in and a procedure (event handler) to be called
  1146. when the event happens in that window.
  1147. The translation manager automatically registers event handlers for widgets
  1148. that use translation tables; see Chapter 10.
  1149. .sp
  1150. .LP
  1151. Applications that need direct control of the processing of different types
  1152. of input should use
  1153. .PN XtAppProcessEvent .
  1154. .IN "XtAppProcessEvent" "" "@DEF@"
  1155. .FD 0
  1156. void XtAppProcessEvent(\fIapp_context\fP, \fImask\fP)
  1157. .br
  1158.       XtAppContext \fIapp_context\fP;
  1159. .br
  1160.       XtInputMask \fImask\fP;
  1161. .FN
  1162. .IP \fIapp_context\fP 1i
  1163. Specifies the application context that identifies the
  1164. application for which to process input.
  1165. .IP \fImask\fP 1i
  1166. Specifies what types of events to process.
  1167. The mask is the bitwise inclusive OR of any combination of
  1168. .PN XtIMXEvent ,
  1169. .PN XtIMTimer ,
  1170. and
  1171. .PN XtIMAlternateInput .
  1172. As a convenience,
  1173. .PN Intrinsic.h
  1174. defines the symbolic name
  1175. .PN XtIMAll
  1176. to be the bitwise inclusive OR of these three event types.
  1177. .LP
  1178. The
  1179. .PN XtAppProcessEvent
  1180. function processes one timer, input source, or X event.
  1181. If there is no event or input of the appropriate type to process, then
  1182. .PN XtAppProcessEvent
  1183. blocks until there is.
  1184. If there is more than one type of input available to process,
  1185. it is undefined which will get processed.
  1186. Usually, this procedure is not called by client applications; see
  1187. .PN XtAppMainLoop .
  1188. .PN XtAppProcessEvent
  1189. processes timer events by calling any appropriate timer callbacks,
  1190. input sources by calling any appropriate input callbacks, and X events by
  1191. calling
  1192. .PN XtDispatchEvent .
  1193. .LP
  1194. When an X event is received,
  1195. it is passed to
  1196. .PN XtDispatchEvent ,
  1197. which calls the appropriate event handlers
  1198. and passes them the widget, the event, and client-specific data
  1199. registered with each procedure.
  1200. If no handlers for that event are registered,
  1201. the event is ignored and the dispatcher simply returns.
  1202.  
  1203. .sp
  1204. .LP
  1205. To dispatch an event returned by
  1206. .PN XtAppNextEvent ,
  1207. retrieved directly from the Xlib queue, or synthetically constructed,
  1208. to any registered event filters or event handlers call
  1209. .PN XtDispatchEvent .
  1210. .IN "XtDispatchEvent" "" "@DEF@"
  1211. .FD 0
  1212. Boolean XtDispatchEvent(\fIevent\fP)
  1213. .br
  1214.       XEvent *\fIevent\fP;
  1215. .FN
  1216. .IP \fIevent\fP 1i
  1217. Specifies a pointer to the event structure to be dispatched
  1218. to the appropriate event handlers.
  1219. .LP
  1220. The
  1221. .PN XtDispatchEvent
  1222. function first calls
  1223. .PN XFilterEvent
  1224. with the \fIevent\fP and the window of the widget to which the
  1225. \*(xI intend to dispatch the event, or the event window if
  1226. the \*(xI would not dispatch the event to any handlers.
  1227. If
  1228. .PN XFilterEvent
  1229. returns
  1230. .PN True
  1231. and the event activated a server grab as identified
  1232. by a previous call to
  1233. .PN XtGrabKey
  1234. or
  1235. .PN XtGrabButton ,
  1236. .PN XtDispatchEvent calls
  1237. .PN XtUngrabKeyboard
  1238. or
  1239. .PN XtUngrabPointer
  1240. with the timestamp from the event and immediately returns
  1241. .PN True .
  1242. If
  1243. .PN XFilterEvent
  1244. returns
  1245. .PN True
  1246. and a grab was not activated,
  1247. .PN XtDispatchEvent
  1248. just immediately returns
  1249. .PN True .
  1250. Otherwise,
  1251. .PN XtDispatchEvent
  1252. sends the event to the event handler functions that
  1253. have been previously registered with the dispatch routine.
  1254. .PN XtDispatchEvent
  1255. returns 
  1256. .PN True
  1257. if
  1258. .PN XFilterEvent
  1259. returned
  1260. .PN True ,
  1261. or if the event was dispatched to some handler and
  1262. .PN False
  1263. if it found no handler to which to dispatch the event.
  1264. .PN XtDispatchEvent
  1265. records the last timestamp in any event that
  1266. contains a timestamp (see
  1267. .PN XtLastTimestampProcessed ),
  1268. regardless of whether it was filtered or dispatched.
  1269. If a modal cascade is active with \fIspring_loaded\fP
  1270. .PN True ,
  1271. and if the event is a remap event as defined by
  1272. .PN XtAddGrab ,
  1273. .PN XtDispatchEvent
  1274. may dispatch the event a second time.  If it does so,
  1275. .PN XtDispatchEvent
  1276. will call
  1277. .PN XFilterEvent
  1278. again with the window of the spring-loaded widget prior to the second
  1279. dispatch and if
  1280. .PN XFilterEvent
  1281. returns
  1282. .PN True ,
  1283. the second dispatch will not be performed.
  1284.  
  1285. .NH 2
  1286. The Application Input Loop
  1287. .XS
  1288. \fB\*(SN The Application Input Loop\fP
  1289. .XE
  1290. .LP
  1291. To process all input from a given application in a continuous loop,
  1292. use the convenience procedure
  1293. .PN XtAppMainLoop .
  1294. .IN "XtAppMainLoop" "" "@DEF@"
  1295. .FD 0
  1296. void XtAppMainLoop(\fIapp_context\fP)
  1297. .br
  1298.       XtAppContext \fIapp_context\fP;
  1299. .FN
  1300. .IP \fIapp_context\fP 1i
  1301. Specifies the application context that identifies the application.
  1302. .LP
  1303. The
  1304. .PN XtAppMainLoop
  1305. function first reads the next incoming X event by calling
  1306. .PN XtAppNextEvent 
  1307. and then dispatches the event to the appropriate registered procedure 
  1308. by calling
  1309. .PN XtDispatchEvent .
  1310. This constitutes the main loop of \*(tk applications,
  1311. and, as such, it does not return.
  1312. Applications are expected to exit in response to some user action
  1313. within a callback procedure.
  1314. There is nothing special about
  1315. .PN XtAppMainLoop ;
  1316. it is simply an infinite loop that calls
  1317. .PN XtAppNextEvent
  1318. and then
  1319. .PN XtDispatchEvent .
  1320. .LP
  1321. Applications can provide their own version of this loop,
  1322. which tests some global termination flag or tests that the number
  1323. of top-level widgets is larger than zero before circling back to the call to
  1324. .PN XtAppNextEvent .
  1325.  
  1326. .NH 2
  1327. Setting and Checking the Sensitivity State of a Widget
  1328. .XS
  1329. \fB\*(SN Setting and Checking the Sensitivity State of a Widget\fP
  1330. .XE
  1331. .LP
  1332. Many widgets have a mode in which they assume a different appearance
  1333. (for example, are grayed out or stippled), do not respond to user events,
  1334. and become dormant.
  1335. .LP
  1336. When dormant,
  1337. a widget is considered to be insensitive.
  1338. If a widget is insensitive,
  1339. the event manager does not dispatch any events to the widget
  1340. with an event type of
  1341. .PN KeyPress ,
  1342. .PN KeyRelease ,
  1343. .PN ButtonPress ,
  1344. .PN ButtonRelease ,
  1345. .PN MotionNotify ,
  1346. .PN EnterNotify ,
  1347. .PN LeaveNotify ,
  1348. .PN FocusIn ,
  1349. or
  1350. .PN FocusOut .
  1351. .LP
  1352. A widget can be insensitive because its \fIsensitive\fP field is
  1353. .PN False
  1354. or because one of its ancestors is insensitive and thus the widget's
  1355. \fIancestor_sensitive\fP field also is 
  1356. .PN False .
  1357. A widget can but does not need to distinguish these two cases visually.
  1358. .NT
  1359. Pop-up shells will have
  1360. \fIancestor_sensitive\fP
  1361. .PN False
  1362. if the parent was insensitive when the shell
  1363. was created.  Since
  1364. .PN XtSetSensitive
  1365. on the parent will not
  1366. modify the resource of the pop-up child, clients are advised to include
  1367. a resource specification of the form
  1368. ``*TransientShell.ancestorSensitive: True''
  1369. in the application defaults resource file or to
  1370. otherwise ensure that the parent is
  1371. sensitive when creating pop-up shells.
  1372. .NE
  1373. .sp
  1374. .LP
  1375. To set the sensitivity state of a widget, use
  1376. .PN XtSetSensitive .
  1377. .IN "XtSetSensitive" "" "@DEF@"
  1378. .FD 0
  1379. void XtSetSensitive(\fIw\fP, \fIsensitive\fP)
  1380. .br
  1381.       Widget \fIw\fP;
  1382. .br
  1383.       Boolean \fIsensitive\fP;
  1384. .FN
  1385. .IP \fIw\fP 1i
  1386. Specifies the widget.  \*(rI
  1387. .IP \fIsensitive\fP 1i
  1388. Specifies whether the widget should receive
  1389. keyboard, pointer, and focus events.
  1390. .LP
  1391. The
  1392. .PN XtSetSensitive
  1393. function first calls
  1394. .PN XtSetValues
  1395. on the current widget with an argument list specifying the
  1396. XtNsensitive resource and the new value.
  1397. If \fIsensitive\fP is
  1398. .PN False
  1399. and the widget's class is a subclass of
  1400. Composite,
  1401. .PN XtSetSensitive
  1402. recursively propagates the new value
  1403. down the child tree by calling
  1404. .PN XtSetValues
  1405. on each child to set \fIancestor_sensitive\fP to
  1406. .PN False .
  1407. If \fIsensitive\fP is
  1408. .PN True
  1409. and the widget's class is a subclass of
  1410. Composite
  1411. and the widget's \fIancestor_sensitive\fP field is
  1412. .PN True ,
  1413. .PN XtSetSensitive
  1414. sets the \fIancestor_sensitive\fP of each child to
  1415. .PN True
  1416. and then recursively calls
  1417. .PN XtSetValues
  1418. on each normal descendant that is now sensitive to set
  1419. \fIancestor_sensitive\fP to
  1420. .PN True .
  1421. .LP
  1422. .PN XtSetSensitive
  1423. calls
  1424. .PN XtSetValues
  1425. to change the \fIsensitive\fP and \fIancestor_sensitive\fP fields
  1426. of each affected widget.
  1427. Therefore, when one of these changes,
  1428. the widget's set_values procedure should
  1429. take whatever display actions are needed
  1430. (for example, graying out or stippling the widget).
  1431. .LP
  1432. .PN XtSetSensitive
  1433. maintains the invariant that if the parent has either \fIsensitive\fP 
  1434. or \fIancestor_sensitive\fP 
  1435. .PN False ,
  1436. then all children have \fIancestor_sensitive\fP 
  1437. .PN False .
  1438. .sp
  1439. .LP
  1440. To check the current sensitivity state of a widget,
  1441. use
  1442. .PN XtIsSensitive .
  1443. .IN "XtIsSensitive" "" "@DEF@"
  1444. .FD 0
  1445. Boolean XtIsSensitive(\fIw\fP)
  1446. .br
  1447.      Widget \fIw\fP;
  1448. .FN
  1449. .IP \fIw\fP 1i
  1450. Specifies the object.  \*(oI
  1451. .LP
  1452. The
  1453. .PN XtIsSensitive
  1454. function returns 
  1455. .PN True 
  1456. or 
  1457. .PN False 
  1458. to indicate whether user input events are being dispatched.
  1459. If object's class is a subclass of RectObj and
  1460. both \fIsensitive\fP and \fIancestor_sensitive\fP are 
  1461. .PN True ,
  1462. .PN XtIsSensitive
  1463. returns 
  1464. .PN True ;
  1465. otherwise, it returns 
  1466. .PN False .
  1467.  
  1468. .NH 2
  1469. Adding Background Work Procedures
  1470. .XS
  1471. \fB\*(SN Adding Background Work Procedures\fP
  1472. .XE
  1473. .LP
  1474. The \*(xI have some limited support for background processing.
  1475. Because most applications spend most of their time waiting for input, 
  1476. you can register an idle-time work procedure
  1477. that will be called when the toolkit would otherwise block in
  1478. .PN XtAppNextEvent
  1479. or
  1480. .PN XtAppProcessEvent .
  1481. Work procedure pointers are of type
  1482. .PN XtWorkProc .
  1483. .IN "XtWorkProc" "" "@DEF@"
  1484. .FD 0
  1485. typedef Boolean (*XtWorkProc)(XtPointer);
  1486. .br
  1487.       XtPointer \fIclient_data\fP;
  1488. .FN
  1489. .IP \fIclient_data\fP 1i
  1490. Passes the client data specified when the work procedure was registered.
  1491. .LP
  1492. This procedure should return
  1493. .PN True
  1494. when it is done to indicate that it
  1495. should be removed.
  1496. If the procedure returns
  1497. .PN False ,
  1498. it will remain registered and will be called again when the
  1499. application is next idle.
  1500. Work procedures should be very judicious about how much they do. 
  1501. If they run for more than a small part of a second,
  1502. interactive feel is likely to suffer.
  1503. .sp
  1504. .LP
  1505. To register a work procedure for a given application, use
  1506. .PN XtAppAddWorkProc .
  1507. .IN "XtAppAddWorkProc" "" "@DEF@"
  1508. .FD 0
  1509. XtWorkProcId XtAppAddWorkProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
  1510. .br
  1511.       XtAppContext \fIapp_context\fP;
  1512. .br
  1513.       XtWorkProc \fIproc\fP;
  1514. .br
  1515.       XtPointer \fIclient_data\fP;
  1516. .FN
  1517. .IP \fIapp_context\fP 1i
  1518. Specifies the application context that identifies the application.
  1519. .IP \fIproc\fP 1i
  1520. Specifies the procedure to be called when the application is idle.
  1521. .IP \fIclient_data\fP 1i
  1522. Specifies the argument passed to the specified procedure
  1523. when it is called.
  1524. .LP
  1525. The
  1526. .PN XtAppAddWorkProc
  1527. function adds the specified work procedure for the application identified
  1528. by \fIapp_context\fP
  1529. and returns an opaque unique identifier for this work procedure.
  1530. Multiple work procedures can be registered,
  1531. and the most recently added one is always the one that is called.
  1532. However, if a work procedure adds another work procedure, 
  1533. the newly added one has lower priority than the current one.
  1534. .sp
  1535. .LP
  1536. To remove a work procedure, either return 
  1537. .PN True 
  1538. from the procedure when it is called or use
  1539. .PN XtRemoveWorkProc .
  1540. .IN "XtRemoveWorkProc" "" "@DEF@"
  1541. .FD 0
  1542. void XtRemoveWorkProc(\fIid\fP)
  1543. .br
  1544.       XtWorkProcId \fIid\fP;
  1545. .FN
  1546. .IP \fIid\fP 1i
  1547. Specifies which work procedure to remove.
  1548. .LP
  1549. The
  1550. .PN XtRemoveWorkProc
  1551. function explicitly removes the specified background work procedure.
  1552.  
  1553. .NH 2
  1554. X Event Filters
  1555. .XS
  1556. \*(SN X Event Filters
  1557. .XE
  1558. .LP
  1559. The event manager provides filters that can be applied to
  1560. specific X events.
  1561. The filters, which screen out events that are redundant or are temporarily
  1562. unwanted, handle
  1563. pointer motion compression,
  1564. enter/leave compression, and
  1565. exposure compression.
  1566.  
  1567. .NH 3
  1568. Pointer Motion Compression
  1569. .XS
  1570. \*(SN Pointer Motion Compression
  1571. .XE
  1572. .LP
  1573. Widgets can have a hard time keeping up with a rapid stream of
  1574. pointer motion events.  Further,
  1575. they usually do not care about every motion event.  To throw out
  1576. redundant motion events, the widget class field \fIcompress_motion\fP should be
  1577. .PN True .
  1578. .IN "compress_motion field"
  1579. When a request for an event would return a motion event,
  1580. the \*(xI check if there are any other motion events
  1581. for the same widget immediately
  1582. following the current one and, if so, skip all but the last of them.
  1583.  
  1584. .NH 3
  1585. Enter/Leave Compression
  1586. .XS
  1587. \*(SN Enter/Leave Compression
  1588. .XE
  1589. .LP
  1590. To throw out pairs of enter and leave events that have no intervening events,
  1591. as can happen when the user moves the pointer across a widget 
  1592. without stopping in it,
  1593. the widget class field \fIcompress_enterleave\fP should be 
  1594. .PN True .
  1595. .IN "compress_enterleave field"
  1596. These enter and leave events are not delivered to the client
  1597. if they are found together in the input queue.
  1598.  
  1599. .NH 3
  1600. Exposure Compression
  1601. .XS
  1602. \*(SN Exposure Compression
  1603. .XE
  1604. .LP
  1605. .IN "compress_expose field"
  1606. Many widgets prefer to process a series of exposure events as a
  1607. single expose region rather than as individual rectangles.  Widgets
  1608. with complex displays might use the expose region as a clip list
  1609. in a graphics context, and widgets with simple displays might
  1610. ignore the region entirely and redisplay their whole window or
  1611. might get the bounding box from the region and redisplay only that
  1612. rectangle.
  1613. .LP
  1614. In either case, these widgets do not care about getting partial exposure events.
  1615. The \fIcompress_exposure\fP field in the widget class
  1616. structure specifies the type and number of exposure events that will
  1617. be dispatched to the widget's expose procedure.  This field must be
  1618. initialized to one of the following values,
  1619. .sp
  1620. .Ds 0
  1621. .TA 3i
  1622. .ta 3i
  1623. #define XtExposeNoCompress    ((XtEnum)False)
  1624. #define XtExposeCompressSeries    ((XtEnum)True)
  1625. #define XtExposeCompressMultiple    <implementation-defined>
  1626. #define XtExposeCompressMaximal    <implementation-defined>
  1627. .De
  1628. .LP
  1629. optionally ORed with any combination of the following flags (all with
  1630. implementation-defined values):
  1631.  
  1632. .PN XtExposeGraphicsExpose ,
  1633. .PN XtExposeGraphicsExposeMerged
  1634. and
  1635. .PN XtExposeNoExpose .
  1636.  
  1637. .LP
  1638. If the \fIcompress_exposure\fP field in the widget class structure does not
  1639. specify
  1640. .PN XtExposeNoCompress ,
  1641. the event manager calls the widget's expose procedure only
  1642. once for a series of exposure events.
  1643. In this case, all
  1644. .PN Expose
  1645. or
  1646. .PN GraphicsExpose
  1647. events are accumulated into a region.
  1648. When the final event is received,
  1649. the event manager replaces the rectangle in the event with the
  1650. bounding box for the region
  1651. and calls the widget's expose procedure,
  1652. passing the modified exposure event and the region.
  1653. For more information on regions, see Section 16.5 in \fI\*(xL\fP.)
  1654. .LP
  1655. The values have the following interpretation:
  1656. .sp
  1657. .LP
  1658. .PN XtExposeNoCompress
  1659. .IN "XtExposeNoCompress" "" "@DEF@"
  1660. .IP
  1661. No exposure compression is performed; every selected event is
  1662. individually dispatched to the expose procedure with a \fIregion\fP
  1663. argument of NULL.
  1664. .sp
  1665. .LP
  1666. .PN XtExposeCompressSeries
  1667. .IN "XtExposeCompressSeries" "" "@DEF@"
  1668. .IP
  1669. Each series of exposure events is coalesced into a single event,
  1670. which is dispatched
  1671. when an exposure event with count equal to zero is reached.
  1672. .sp
  1673. .LP
  1674. .PN XtExposeCompressMultiple
  1675. .IN "XtExposeCompressMultiple" "" "@DEF@"
  1676. .IP
  1677. Consecutive series of exposure events are coalesced into a single
  1678. event, which is dispatched
  1679. when an exposure event with count equal to zero is reached and either
  1680. the event queue is empty or the next event is not an exposure event
  1681. for the same widget.
  1682. .sp
  1683. .LP
  1684. .PN XtExposeCompressMaximal
  1685. .IN "XtExposeCompressMaximal" "" "@DEF"
  1686. .IP
  1687. All expose series currently in the queue for the widget
  1688. are coalesced into a single
  1689. event without regard to intervening nonexposure events.  If a
  1690. partial series is in the end of the queue, the \*(xI will
  1691. block until the end of the series is received.
  1692. .sp
  1693. .LP
  1694. The additional flags have the following meaning:
  1695. .sp
  1696. .LP
  1697. .PN XtExposeGraphicsExpose
  1698. .IN "XtExposeGraphicsExpose" "" "@DEF@"
  1699. .IP
  1700. Specifies that
  1701. .PN GraphicsExpose
  1702. events are also to be dispatched to
  1703. the expose procedure.
  1704. .PN GraphicsExpose
  1705. events will be compressed, if specified, in the same manner as
  1706. .PN Expose
  1707. events.
  1708. .sp
  1709. .LP
  1710. .PN XtExposeGraphicsExposeMerged
  1711. .IN "XtExposeGraphicsExposeMerged" "" "@DEF@"
  1712. .IP
  1713. Specifies in the case of
  1714. .PN XtExposeCompressMultiple
  1715. and
  1716. .PN XtExposeCompressMaximal
  1717. that series of
  1718. .PN GraphicsExpose
  1719. and
  1720. .PN Expose
  1721. events are to be compressed together, with the final event type
  1722. determining the type of the event passed to the expose procedure.
  1723. If this flag is not set, then only series of the same event type
  1724. as the event at the head of the queue are coalesced.  This flag
  1725. also implies
  1726. .PN XtExposeGraphicsExpose .
  1727. .sp
  1728. .LP
  1729. .PN XtExposeNoExpose
  1730. .IN "XtExposeNoExpose" "" "@DEF@"
  1731. .IP
  1732. Specifies that
  1733. .PN NoExpose
  1734. events are also to be dispatched to the expose procedure.
  1735. .PN NoExpose
  1736. events are never coalesced with
  1737. other exposure events or with each other.
  1738.  
  1739. .NH 2
  1740. Widget Exposure and Visibility
  1741. .XS
  1742. \*(SN Widget Exposure and Visibility
  1743. .XE
  1744. .LP
  1745. Every primitive widget and some composite widgets display data on the screen
  1746. by means of direct Xlib calls.
  1747. Widgets cannot simply write to the screen and forget what they have done.
  1748. They must keep enough state to redisplay the window or parts
  1749. of it if a portion is obscured and then reexposed.
  1750.  
  1751. .NH 3
  1752. Redisplay of a Widget: the expose Procedure
  1753. .XS
  1754. \*(SN Redisplay of a Widget: the expose Procedure
  1755. .XE
  1756. .IN "expose procedure"
  1757. .LP
  1758. The expose procedure pointer in a widget class is of type
  1759. .PN XtExposeProc .
  1760. .IN "XtExposeProc" "" "@DEF@"
  1761. .FD 0
  1762. typedef void (*XtExposeProc)(Widget, XEvent*, Region);
  1763. .br
  1764.       Widget \fIw\fP;
  1765. .br
  1766.       XEvent *\fIevent\fP;
  1767. .br
  1768.       Region \fIregion\fP;
  1769. .FN
  1770. .IP \fIw\fP 1i
  1771. Specifies the widget instance requiring redisplay.
  1772. .IP \fIevent\fP 1i
  1773. Specifies the exposure event giving the rectangle requiring redisplay.
  1774. .IP \fIregion\fP 1i
  1775. Specifies the union of all rectangles in this exposure sequence.
  1776. .LP
  1777. The redisplay of a widget upon exposure is the responsibility of the
  1778. expose procedure in the widget's class record.
  1779. If a widget has no display semantics,
  1780. it can specify NULL for the \fIexpose\fP field.
  1781. Many composite widgets serve only as containers for their children
  1782. and have no expose procedure.
  1783. .NT
  1784. If the \fIexpose\fP procedure is NULL,
  1785. .PN XtRealizeWidget
  1786. fills in a default bit gravity of
  1787. .PN NorthWestGravity
  1788. before it calls the widget's realize procedure.
  1789. .NE
  1790. .LP
  1791. If the widget's \fIcompress_exposure\fP class field specifies
  1792. .PN XtExposeNoCompress
  1793. or the event type is
  1794. .PN NoExpose
  1795. (see Section 7.9.3),
  1796. \fIregion\fP is NULL; otherwise, the event
  1797. is the final event in the compressed series but \fIx\fP, \fIy\fP, \fIwidth\fP,
  1798. and
  1799. \fIheight\fP contain the bounding box for \fIregion\fP.
  1800. The region is created and destroyed by the \*(xI, but
  1801. the widget is permitted to modify the region contents.
  1802. .LP
  1803. A small simple widget (for example, Label) can ignore the bounding box
  1804. information in the event and redisplay the entire window.
  1805. A more complicated widget (for example, Text) can use the bounding box
  1806. information to minimize the amount of calculation and redisplay it does.
  1807. A very complex widget uses the region as a clip list in a GC and
  1808. ignores the event information.
  1809. The expose procedure is not chained and is therefore
  1810. responsible for exposure of all superclass data
  1811. as well as its own.
  1812. .LP
  1813. However,
  1814. it often is possible to anticipate the display needs of several levels
  1815. of subclassing.
  1816. For example, rather than implement separate display procedures for
  1817. the widgets Label, Pushbutton, and Toggle,
  1818. you could write a single display routine in Label that uses display state
  1819. fields like
  1820. .LP
  1821. .DS
  1822. Boolean invert;
  1823. Boolean highlight;
  1824. Dimension highlight_width;
  1825. .DE
  1826. Label would have \fIinvert\fP and \fIhighlight\fP always 
  1827. .PN False
  1828. and \fIhighlight_width\fP zero.
  1829. Pushbutton would dynamically set \fIhighlight\fP and \fIhighlight_width\fP, 
  1830. but it would leave \fIinvert\fP always 
  1831. .PN False .
  1832. Finally, Toggle would dynamically set all three.
  1833. In this case,
  1834. the expose procedures for Pushbutton and Toggle inherit
  1835. their superclass's expose procedure;
  1836. see Section 1.6.10.
  1837.  
  1838. .NH 3
  1839. Widget Visibility
  1840. .XS
  1841. \*(SN Widget Visibility
  1842. .XE
  1843. .LP
  1844. Some widgets may use substantial computing resources to produce the
  1845. data they will display.
  1846. However, this effort is wasted if the widget is not actually visible
  1847. on the screen, that is, if the widget is obscured by another application 
  1848. or is iconified.
  1849. .LP
  1850. .IN "Visibility"
  1851. The \fIvisible\fP field in the
  1852. core
  1853. widget structure provides a hint to the widget that it need not compute
  1854. display data.
  1855. This field is guaranteed to be
  1856. .PN True
  1857. by the time an
  1858. exposure
  1859. event is processed if any part of the widget is visible
  1860. but is
  1861. .PN False 
  1862. if the widget is fully obscured.
  1863. .LP
  1864. Widgets can use or ignore the \fIvisible\fP hint.
  1865. If they ignore it,
  1866. they should have \fIvisible_interest\fP in their widget class record set 
  1867. .PN False .
  1868. In such cases,
  1869. the \fIvisible\fP field is initialized 
  1870. .PN True 
  1871. and never changes.
  1872. If \fIvisible_interest\fP is 
  1873. .PN True ,
  1874. the event manager asks for
  1875. .PN VisibilityNotify
  1876. events for the widget and sets \fIvisible\fP to
  1877. .PN True
  1878. on
  1879. .PN VisibilityUnobscured
  1880. or
  1881. .PN VisibilityPartiallyObscured
  1882. .IN VisibilityNotify
  1883. events and
  1884. .PN False
  1885. on
  1886. .PN VisibilityFullyObscured
  1887. events.
  1888.  
  1889. .NH 2
  1890. X Event Handlers
  1891. .XS
  1892. \*(SN X Event Handlers
  1893. .XE
  1894. .LP
  1895. Event handlers are procedures called when specified events
  1896. occur in a widget.
  1897. Most widgets need not use event handlers explicitly.
  1898. Instead, they use the \*(xI translation manager.
  1899. Event handler procedure pointers are of the type
  1900. .PN XtEventHandler .
  1901. .IN "XtEventHandler" "" "@DEF@"
  1902. .FD 0
  1903. typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*);
  1904. .br
  1905.       Widget \fIw\fP;
  1906. .br
  1907.       XtPointer \fIclient_data\fP;
  1908. .br
  1909.       XEvent *\fIevent\fP;
  1910. .br
  1911.       Boolean *\fIcontinue_to_dispatch\fP;
  1912. .FN
  1913. .IP \fIw\fP 1i
  1914. Specifies the widget for which the event arrived.
  1915. .IP \fIclient_data\fP 1i
  1916. Specifies any client-specific information registered with the event handler.
  1917. .IP \fIevent\fP 1i
  1918. Specifies the triggering event.
  1919. .IP \fIcontinue_to_dispatch\fP 1i
  1920. Specifies whether the remaining event
  1921. handlers registered for the current event
  1922. should be called.
  1923. .LP
  1924. After receiving an event and before calling any event handlers, the
  1925. Boolean pointed to by \fIcontinue_to_dispatch\fP is initialized to
  1926. .PN True .
  1927. When an event handler is called, it may decide that further processing
  1928. of the event is not desirable and may store
  1929. .PN False
  1930. in this Boolean, in
  1931. which case any handlers remaining to be called for the event will be
  1932. ignored.
  1933. .LP
  1934. The circumstances under which the \*(xI may add event handlers
  1935. to a widget are currently implementation-dependent.  Clients must
  1936. therefore be aware that storing
  1937. .PN False
  1938. into the \fIcontinue_to_dispatch\fP argument can lead to portability problems.
  1939.  
  1940. .NH 3
  1941. Event Handlers that Select Events
  1942. .XS
  1943. \*(SN Event Handlers that Select Events
  1944. .XE
  1945. .LP
  1946. To register an event handler procedure with the dispatch mechanism, use
  1947. .PN XtAddEventHandler .
  1948. .IN "XtAddEventHandler" "" "@DEF@"
  1949. .FD 0
  1950. void XtAddEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
  1951. \fIproc\fP, \fIclient_data\fP)
  1952. .br
  1953.       Widget \fIw\fP;
  1954. .br
  1955.       EventMask \fIevent_mask\fP;
  1956. .br
  1957.       Boolean \fInonmaskable\fP;
  1958. .br
  1959.       XtEventHandler \fIproc\fP;
  1960. .br
  1961.       XtPointer \fIclient_data\fP;
  1962. .FN
  1963. .IP \fIw\fP 1i
  1964. Specifies the widget for which this event handler is being registered.  \*(cI
  1965. .IP \fIevent_mask\fP 1i
  1966. Specifies the event mask for which to call this procedure.
  1967. .IP \fInonmaskable\fP 1i
  1968. Specifies whether this procedure should be 
  1969. called on the nonmaskable events
  1970. .Pn ( GraphicsExpose ,
  1971. .PN NoExpose ,
  1972. .PN SelectionClear ,
  1973. .PN SelectionRequest ,
  1974. .PN SelectionNotify ,
  1975. .PN ClientMessage ,
  1976. and
  1977. .PN MappingNotify ).
  1978. .IP \fIproc\fP 1i
  1979. Specifies the procedure to be called.
  1980. .IP \fIclient_data\fP 1i
  1981. Specifies additional data to be passed to the event handler.
  1982. .LP
  1983. The
  1984. .PN XtAddEventHandler
  1985. function registers a procedure with the dispatch mechanism that is
  1986. to be called when an event that matches the mask occurs on the specified
  1987. widget.
  1988. Each widget has a single registered event handler list, which will
  1989. contain any procedure--client_data pair exactly once regardless of
  1990. the manner in which it is registered.
  1991. If the procedure is already registered with the same \fIclient_data\fP
  1992. value,
  1993. the specified mask augments the existing mask.
  1994. If the widget is realized,
  1995. .PN XtAddEventHandler
  1996. calls
  1997. .PN XSelectInput ,
  1998. if necessary.
  1999. The order in which this procedure is called relative to other handlers
  2000. registered for the same event is not defined.
  2001. .sp
  2002. .LP
  2003. To remove a previously registered event handler, use
  2004. .PN XtRemoveEventHandler .
  2005. .IN "XtRemoveEventHandler" "" "@DEF@"
  2006. .FD 0
  2007. void XtRemoveEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
  2008. \fIproc\fP, \fIclient_data\fP)
  2009. .br
  2010.       Widget \fIw\fP;
  2011. .br
  2012.       EventMask \fIevent_mask\fP;
  2013. .br
  2014.       Boolean \fInonmaskable\fP;
  2015. .br
  2016.       XtEventHandler \fIproc\fP;
  2017. .br
  2018.       XtPointer \fIclient_data\fP;
  2019. .FN
  2020. .IP \fIw\fP 1i
  2021. Specifies the widget for which this procedure is registered.  \*(cI
  2022. .IP \fIevent_mask\fP 1i
  2023. Specifies the event mask for which to unregister this procedure.
  2024. .IP \fInonmaskable\fP 1i
  2025. Specifies whether this procedure should be 
  2026. removed on the nonmaskable events
  2027. .Pn ( GraphicsExpose ,
  2028. .PN NoExpose ,
  2029. .PN SelectionClear ,
  2030. .PN SelectionRequest ,
  2031. .PN SelectionNotify ,
  2032. .PN ClientMessage ,
  2033. and
  2034. .PN MappingNotify ).
  2035. .IP \fIproc\fP 1i
  2036. Specifies the procedure to be removed.
  2037. .IP \fIclient_data\fP 1i
  2038. Specifies the registered client data.
  2039. .LP
  2040. The
  2041. .PN XtRemoveEventHandler
  2042. function unregisters an event handler registered with
  2043. .PN XtAddEventHandler
  2044. or
  2045. .PN XtInsertEventHandler
  2046. for the specified events.
  2047. The request is ignored if \fIclient_data\fP does not match the value given
  2048. when the handler was registered.
  2049. If the widget is realized and no other event handler requires the event,
  2050. .PN XtRemoveEventHandler
  2051. calls
  2052. .PN XSelectInput .
  2053. If the specified procedure has not been registered 
  2054. or if it has been registered with a different value of \fIclient_data\fP,
  2055. .PN XtRemoveEventHandler
  2056. returns without reporting an error.
  2057. .LP
  2058. To stop a procedure registered with
  2059. .PN XtAddEventHandler
  2060. or
  2061. .PN XtInsertEventHandler
  2062. from receiving all selected events, call
  2063. .PN XtRemoveEventHandler
  2064. with an \fIevent_mask\fP of
  2065. .PN XtAllEvents
  2066. and \fInonmaskable\fP 
  2067. .PN True .
  2068. The procedure will continue to receive any events
  2069. that have been specified in calls to
  2070. .PN XtAddRawEventHandler
  2071. or
  2072. .PN XtInsertRawEventHandler .
  2073. .sp
  2074. .LP
  2075. To register an event handler procedure that receives events before or
  2076. after all previously registered event handlers, use
  2077. .PN XtInsertEventHandler .
  2078. .IN "XtInsertEventHandler" "" "@DEF@"
  2079. .sp
  2080. .Ds 0
  2081. typedef enum {XtListHead, XtListTail} XtListPosition;
  2082. .De
  2083. .IN "XtListPosition" "" "@DEF@"
  2084. .FD 0
  2085. void XtInsertEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
  2086. \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
  2087. .br
  2088.       Widget \fIw\fP;
  2089. .br
  2090.       EventMask \fIevent_mask\fP;
  2091. .br
  2092.       Boolean \fInonmaskable\fP;
  2093. .br
  2094.       XtEventHandler \fIproc\fP;
  2095. .br
  2096.       XtPointer \fIclient_data\fP;
  2097. .br
  2098.       XtListPosition \fIposition\fP;
  2099. .FN
  2100. .IP \fIw\fP 1i
  2101. Specifies the widget for which this event handler is being registered. \*(cI
  2102. .IP \fIevent_mask\fP 1i
  2103. Specifies the event mask for which to call this procedure.
  2104. .IP \fInonmaskable\fP 1i
  2105. Specifies whether this procedure should be 
  2106. called on the nonmaskable events
  2107. .Pn ( GraphicsExpose ,
  2108. .PN NoExpose ,
  2109. .PN SelectionClear ,
  2110. .PN SelectionRequest ,
  2111. .PN SelectionNotify ,
  2112. .PN ClientMessage ,
  2113. and
  2114. .PN MappingNotify ).
  2115. .IP \fIproc\fP 1i
  2116. Specifies the procedure to be called.
  2117. .IP \fIclient_data\fP 1i
  2118. Specifies additional data to be passed to the client's event handler.
  2119. .IP \fIposition\fP 1i
  2120. Specifies when the event handler is to be called
  2121. relative to other previously registered handlers.
  2122. .LP
  2123. .PN XtInsertEventHandler
  2124. is identical to
  2125. .PN XtAddEventHandler
  2126. with the additional \fIposition\fP argument.  If \fIposition\fP is
  2127. .PN XtListHead ,
  2128. the event
  2129. handler is registered so that it will be called before any event
  2130. handlers that were previously registered for the same widget.  If
  2131. \fIposition\fP is
  2132. .PN XtListTail ,
  2133. the event handler is registered to be called
  2134. after any previously registered event handlers.  If the procedure is
  2135. already registered with the same \fIclient_data\fP value, the specified mask
  2136. augments the existing mask and the procedure is repositioned in
  2137. the list.
  2138.  
  2139. .NH 3
  2140. Event Handlers that Do Not Select Events
  2141. .XS
  2142. \*(SN Event Handlers that Do Not Select Events
  2143. .XE
  2144. .LP
  2145. On occasion,
  2146. clients need to register an event handler procedure with the
  2147. dispatch mechanism without explicitly
  2148. causing the X server to select for that event.
  2149. To do this, use
  2150. .PN XtAddRawEventHandler .
  2151. .IN "XtAddRawEventHandler" "" "@DEF@"
  2152. .FD 0
  2153. void XtAddRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
  2154. \fIproc\fP, \fIclient_data\fP)
  2155. .br
  2156.       Widget \fIw\fP;
  2157. .br
  2158.       EventMask \fIevent_mask\fP;
  2159. .br
  2160.       Boolean \fInonmaskable\fP;
  2161. .br
  2162.       XtEventHandler \fIproc\fP;
  2163. .br
  2164.       XtPointer \fIclient_data\fP;
  2165. .FN
  2166. .IP \fIw\fP 1i
  2167. Specifies the widget for which this event handler is being registered. \*(cI
  2168. .IP \fIevent_mask\fP 1i
  2169. Specifies the event mask for which to call this procedure.
  2170. .IP \fInonmaskable\fP 1i
  2171. Specifies whether this procedure should be 
  2172. called on the nonmaskable events
  2173. .Pn ( GraphicsExpose ,
  2174. .PN NoExpose ,
  2175. .PN SelectionClear ,
  2176. .PN SelectionRequest ,
  2177. .PN SelectionNotify ,
  2178. .PN ClientMessage ,
  2179. and
  2180. .PN MappingNotify ).
  2181. .IP \fIproc\fP 1i
  2182. Specifies the procedure to be called.
  2183. .IP \fIclient_data\fP 1i
  2184. Specifies additional data to be passed to the client's event handler.
  2185. .LP
  2186. The
  2187. .PN XtAddRawEventHandler
  2188. function is similar to
  2189. .PN XtAddEventHandler 
  2190. except that it does not affect the widget's event mask and never causes an
  2191. .PN XSelectInput
  2192. for its events.
  2193. Note that the widget might already have those mask bits set
  2194. because of other nonraw event handlers registered on it.
  2195. If the procedure is already registered with the same \fIclient_data\fP,
  2196. the specified mask augments the existing mask.
  2197. The order in which this procedure is called relative to other handlers
  2198. registered for the same event is not defined.
  2199. .sp
  2200. .LP
  2201. To remove a previously registered raw event handler, use
  2202. .PN XtRemoveRawEventHandler .
  2203. .IN "XtRemoveRawEventHandler" "" "@DEF@"
  2204. .FD 0
  2205. void XtRemoveRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
  2206. \fIproc\fP, \fIclient_data\fP)
  2207. .br
  2208.       Widget \fIw\fP;
  2209. .br
  2210.       EventMask \fIevent_mask\fP;
  2211. .br
  2212.       Boolean \fInonmaskable\fP;
  2213. .br
  2214.       XtEventHandler \fIproc\fP;
  2215. .br
  2216.       XtPointer \fIclient_data\fP;
  2217. .FN
  2218. .IP \fIw\fP 1i
  2219. Specifies the widget for which this procedure is registered.  \*(cI
  2220. .IP \fIevent_mask\fP 1i
  2221. Specifies the event mask for which to unregister this procedure.
  2222. .IP \fInonmaskable\fP 1i
  2223. Specifies whether this procedure should be 
  2224. removed on the nonmaskable events
  2225. .Pn ( GraphicsExpose ,
  2226. .PN NoExpose ,
  2227. .PN SelectionClear ,
  2228. .PN SelectionRequest ,
  2229. .PN SelectionNotify ,
  2230. .PN ClientMessage ,
  2231. and
  2232. .PN MappingNotify ).
  2233. .IP \fIproc\fP 1i
  2234. Specifies the procedure to be registered.
  2235. .IP \fIclient_data\fP 1i
  2236. Specifies the registered client data.
  2237. .LP
  2238. The
  2239. .PN XtRemoveRawEventHandler
  2240. function unregisters an event handler registered with
  2241. .PN XtAddRawEventHandler
  2242. or
  2243. .PN XtInsertRawEventHandler
  2244. for the specified events without changing
  2245. the window event mask.
  2246. The request is ignored if \fIclient_data\fP does not match the value given
  2247. when the handler was registered.
  2248. If the specified procedure has not been registered 
  2249. or if it has been registered with a different value of \fIclient_data\fP,
  2250. .PN XtRemoveRawEventHandler
  2251. returns without reporting an error.
  2252. .LP
  2253. To stop a procedure
  2254. registered with
  2255. .PN XtAddRawEventHandler
  2256. or
  2257. .PN XtInsertRawEventHandler
  2258. from receiving all nonselected events, call
  2259. .PN XtRemoveRawEventHandler
  2260. with an \fIevent_mask\fP of
  2261. .PN XtAllEvents
  2262. and \fInonmaskable\fP
  2263. .PN True .
  2264. The procedure
  2265. will continue to receive any events that have been specified in calls to
  2266. .PN XtAddEventHandler
  2267. or
  2268. .PN XtInsertEventHandler .
  2269. .sp
  2270. .LP
  2271. To register an event handler procedure that receives events before or
  2272. after all previously registered event handlers without selecting for
  2273. the events, use
  2274. .PN XtInsertRawEventHandler .
  2275. .IN "XtInsertRawEventHandler" "" "@DEF@"
  2276. .FD 0
  2277. void XtInsertRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
  2278. \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
  2279. .br
  2280.       Widget \fIw\fP;
  2281. .br
  2282.       EventMask \fIevent_mask\fP;
  2283. .br
  2284.       Boolean \fInonmaskable\fP;
  2285. .br
  2286.       XtEventHandler \fIproc\fP;
  2287. .br
  2288.       XtPointer \fIclient_data\fP;
  2289. .br
  2290.       XtListPosition \fIposition\fP;
  2291. .FN
  2292. .IP \fIw\fP 1i
  2293. Specifies the widget for which this event handler is being registered. \*(cI
  2294. .IP \fIevent_mask\fP 1i
  2295. Specifies the event mask for which to call this procedure.
  2296. .IP \fInonmaskable\fP 1i
  2297. Specifies whether this procedure should be 
  2298. called on the nonmaskable events
  2299. .Pn ( GraphicsExpose ,
  2300. .PN NoExpose ,
  2301. .PN SelectionClear ,
  2302. .PN SelectionRequest ,
  2303. .PN SelectionNotify ,
  2304. .PN ClientMessage ,
  2305. and
  2306. .PN MappingNotify ).
  2307. .IP \fIproc\fP 1i
  2308. Specifies the procedure to be registered.
  2309. .IP \fIclient_data\fP 1i
  2310. Specifies additional data to be passed to the client's event handler.
  2311. .IP \fIposition\fP 1i
  2312. Specifies when the event handler is to be called
  2313. relative to other previously registered handlers.
  2314. .LP
  2315. The
  2316. .PN XtInsertRawEventHandler
  2317. function is similar to
  2318. .PN XtInsertEventHandler
  2319. except that it does not modify the widget's event
  2320. mask and never causes an
  2321. .PN XSelectInput
  2322. for the specified events.  If
  2323. the procedure is already registered with the same \fIclient_data\fP
  2324. value, the
  2325. specified mask augments the existing mask and the procedure is
  2326. repositioned in the list.
  2327.  
  2328. .NH 3
  2329. Current Event Mask
  2330. .XS
  2331. \*(SN Current Event Mask
  2332. .XE
  2333. .LP
  2334. To retrieve the event mask for a given widget, use
  2335. .PN XtBuildEventMask .
  2336. .IN "XtBuildEventMask" "" "@DEF@"
  2337. .FD 0
  2338. EventMask XtBuildEventMask(\fIw\fP)
  2339. .br
  2340.       Widget \fIw\fP;
  2341. .FN
  2342. .IP \fIw\fP 1i
  2343. Specifies the widget.  \*(cI
  2344. .LP
  2345. The
  2346. .PN XtBuildEventMask
  2347. function returns the event mask representing the logical OR
  2348. of all event masks for event handlers registered on the widget with
  2349. .PN XtAddEventHandler
  2350. and
  2351. .PN XtInsertEventHandler
  2352. and all event translations, including accelerators,
  2353. installed on the widget.
  2354. This is the same event mask stored into the 
  2355. .PN XSetWindowAttributes
  2356. structure by
  2357. .PN XtRealizeWidget
  2358. and sent to the server when event handlers and translations are installed or
  2359. removed on the realized widget.
  2360. .bp
  2361.