home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH11 < prev    next >
Encoding:
Text File  |  1991-07-30  |  48.1 KB  |  1,714 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 11\fP\s-1
  5.  
  6. \s+1\fBEvent Handling Functions\fP\s-1
  7. .sp 2
  8. .nr H1 11
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 11: Event Handling Functions 
  17. .XE
  18. This chapter discusses the Xlib functions you can use to:
  19. .IP \(bu 5
  20. Select events
  21. .IP \(bu 5
  22. Handle the output buffer and the event queue
  23. .IP \(bu 5
  24. Select events from the event queue 
  25. .IP \(bu 5
  26. Send and get events
  27. .IP \(bu 5
  28. Handle protocol errors
  29. .LE
  30. .RE
  31. .NT Note
  32. Some toolkits use their own event-handling functions
  33. and do not allow you to interchange these event-handling functions
  34. with those in Xlib.
  35. For further information, 
  36. see the documentation supplied with the toolkit.
  37. .NE
  38. .LP
  39. Most applications simply are event loops:
  40. they wait for an event, decide what to do with it,
  41. execute some amount of code that results in changes to the display,
  42. and then wait for the next event.
  43. .NH 2
  44. Selecting Events
  45. .XS
  46. \*(SN Selecting Events 
  47. .XE
  48. .LP
  49. There are two ways to select the events you want reported to your client
  50. application.
  51. One way is to set the event_mask member of the
  52. .PN XSetWindowAttributes
  53. structure when you call
  54. .PN XCreateWindow
  55. and
  56. .PN XChangeWindowAttributes .
  57. Another way is to use
  58. .PN XSelectInput . 
  59. .IN "XSelectInput" "" "@DEF@"
  60. .\" Start marker code here
  61. .FD 0
  62. .\" $Header: XSelectInput.f,v 1.2 88/05/04 06:25:22 mento Exp $
  63. XSelectInput\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^)
  64. .br
  65.       Display *\fIdisplay\fP\^;
  66. .br
  67.       Window \fIw\fP\^;
  68. .br
  69.       long \fIevent_mask\fP\^;
  70. .FN    
  71. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  72. .IP \fIdisplay\fP 1i
  73. Specifies the connection to the X server.
  74. .ds Wi whose events you are interested in
  75. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  76. .IP \fIw\fP 1i
  77. Specifies the window \*(Wi.
  78. .\" $Header: eventmask.a,v 1.2 88/05/14 13:04:06 mento Exp $
  79. .IP \fIevent_mask\fP 1i
  80. Specifies the event mask.
  81. .\" End marker code here
  82. .LP 
  83. .\" $Header: XSelectInput.d,v 1.3 88/06/11 07:52:55 mento Exp $
  84. The
  85. .PN XSelectInput
  86. function requests that the X server report the events associated with the 
  87. specified event mask.
  88. Initially, X will not report any of these events.
  89. Events are reported relative to a window.
  90. If a window is not interested in a device event, it usually propagates to
  91. the closest ancestor that is interested,
  92. unless the do_not_propagate mask prohibits it.
  93. .IN "Event" "propagation"
  94. .LP
  95. Setting the event-mask attribute of a window overrides any previous call
  96. for the same window but not for other clients.
  97. Multiple clients can select for the same events on the same window
  98. with the following restrictions:
  99. .IP \(bu 5
  100. Multiple clients can select events on the same window because their event masks
  101. are disjoint.
  102. When the X server generates an event, it reports it
  103. to all interested clients.
  104. .IP \(bu 5
  105. Only one client at a time can select
  106. .PN CirculateRequest ,
  107. .PN ConfigureRequest ,
  108. or
  109. .PN MapRequest
  110. events, which are associated with
  111. the event mask
  112. .PN SubstructureRedirectMask . 
  113. .IP \(bu 5
  114. Only one client at a time can select
  115. a
  116. .PN ResizeRequest
  117. event, which is associated with
  118. the event mask
  119. .PN ResizeRedirectMask . 
  120. .IP \(bu 5
  121. Only one client at a time can select a 
  122. .PN ButtonPress 
  123. event, which is associated with
  124. the event mask
  125. .PN ButtonPressMask .
  126. .LP
  127. The server reports the event to all interested clients.
  128. .LP
  129. .PN XSelectInput
  130. can generate a
  131. .PN BadWindow 
  132. error.
  133. .NH 2
  134. Handling the Output Buffer
  135. .XS
  136. \*(SN Handling the Output Buffer
  137. .XE
  138. .LP
  139. The output buffer is an area used by Xlib to store requests.
  140. The functions described in this section flush the output buffer
  141. if the function would block or not return an event.
  142. That is, all requests residing in the output buffer that
  143. have not yet been sent are transmitted to the X server.
  144. These functions differ in the additional tasks they might perform.
  145. .LP
  146. .sp
  147. To flush the output buffer, use 
  148. .PN XFlush .
  149. .IN "XFlush" "" "@DEF@"
  150. .\" Start marker code here
  151. .FD 0
  152. .\" $Header: XFlush.f,v 1.1 88/02/26 10:00:10 mento Exp $
  153. XFlush\^(\^\fIdisplay\fP\^)
  154. .br
  155.       Display *\fIdisplay\fP\^;
  156. .FN
  157. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  158. .IP \fIdisplay\fP 1i
  159. Specifies the connection to the X server.
  160. .\" End marker code here
  161. .LP
  162. .\" $Header: XFlush.d,v 1.2 88/06/11 07:50:19 mento Exp $
  163. The
  164. .PN XFlush
  165. function
  166. flushes the output buffer.
  167. Most client applications need not use this function because the output
  168. buffer is automatically flushed as needed by calls to
  169. .PN XPending ,
  170. .PN XNextEvent ,
  171. and
  172. .PN XWindowEvent .
  173. .IN "XPending"
  174. .IN "XNextEvent"
  175. .IN "XWindowEvent"
  176. Events generated by the server may be enqueued into the library's event queue.
  177. .LP
  178. .sp
  179. To flush the output buffer and then wait until all requests have been processed,
  180. use 
  181. .PN XSync .
  182. .IN "XSync" "" "@DEF@"
  183. .\" Start marker code here
  184. .FD 0
  185. .\" $Header: XSync.f,v 1.2 88/04/07 12:52:07 mento Exp $
  186. XSync\^(\^\fIdisplay\fP, \fIdiscard\fP\^)
  187. .br
  188.       Display *\fIdisplay\fP\^;
  189. .br
  190.       Bool \fIdiscard\fP\^;
  191. .FN
  192. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  193. .IP \fIdisplay\fP 1i
  194. Specifies the connection to the X server.
  195. .\" $Header: discard.a,v 1.3 88/05/14 13:09:22 mento Exp $
  196. .IP \fIdiscard\fP 1i
  197. Specifies a Boolean value that indicates whether 
  198. .PN XSync
  199. discards all events on the event queue.
  200. .\" End marker code here
  201. .LP
  202. .\" $Header: XSync.d,v 1.2 88/06/11 07:53:53 mento Exp $
  203. The
  204. .PN XSync
  205. function
  206. flushes the output buffer and then waits until all requests have been received
  207. and processed by the X server.
  208. Any errors generated must be handled by the error handler.
  209. For each protocol error received by Xlib,
  210. .PN XSync
  211. calls the client application's error handling routine (see section 11.8.2).
  212. Any events generated by the server are enqueued into the library's 
  213. event queue.
  214. .LP
  215. Finally, if you passed 
  216. .PN False ,
  217. .PN XSync
  218. does not discard the events in the queue.
  219. If you passed 
  220. .PN True ,
  221. .PN XSync 
  222. discards all events in the queue,
  223. including those events that were on the queue before
  224. .PN XSync
  225. was called.
  226. Client applications seldom need to call
  227. .PN XSync .
  228. .NH 2
  229. Event Queue Management
  230. .XS
  231. \*(SN Event Queue Management
  232. .XE
  233. .LP
  234. Xlib maintains an event queue.
  235. However, the operating system also may be buffering data 
  236. in its network connection that is not yet read into the event queue.
  237. .LP
  238. .sp
  239. To check the number of events in the event queue, use
  240. .PN XEventsQueued .
  241. .IN "XEventsQueued" "" "@DEF@"
  242. .\" Start marker code here
  243. .FD 0
  244. int XEventsQueued\^(\^\fIdisplay\fP, \fImode\fP\^)
  245. .br
  246.      Display *\fIdisplay\fP\^;
  247. .br
  248.      int \fImode\fP\^;
  249. .FN
  250. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  251. .IP \fIdisplay\fP 1i
  252. Specifies the connection to the X server.
  253. .IP \fImode\fP 1i
  254. Specifies the mode.
  255. You can pass
  256. .PN QueuedAlready ,
  257. .PN QueuedAfterFlush ,
  258. or
  259. .PN QueuedAfterReading .
  260. .\" End marker code here
  261. .LP
  262. If mode is 
  263. .PN QueuedAlready ,
  264. .PN XEventsQueued 
  265. returns the number of events
  266. already in the event queue (and never performs a system call).
  267. If mode is 
  268. .PN QueuedAfterFlush , 
  269. .PN XEventsQueued
  270. returns the number of events already in the queue if the number is nonzero.
  271. If there are no events in the queue, 
  272. .PN XEventsQueued
  273. flushes the output buffer, 
  274. attempts to read more events out of the application's connection,
  275. and returns the number read.
  276. If mode is 
  277. .PN QueuedAfterReading , 
  278. .PN XEventsQueued
  279. returns the number of events already in the queue if the number is nonzero. 
  280. If there are no events in the queue, 
  281. .PN XEventsQueued
  282. attempts to read more events out of the application's connection 
  283. without flushing the output buffer and returns the number read.
  284. .LP
  285. .PN XEventsQueued
  286. always returns immediately without I/O if there are events already in the
  287. queue.
  288. .PN XEventsQueued
  289. with mode 
  290. .PN QueuedAfterFlush
  291. is identical in behavior to
  292. .PN XPending .
  293. .PN XEventsQueued
  294. with mode
  295. .PN QueuedAlready
  296. is identical to the
  297. .PN XQLength
  298. function.
  299. .LP
  300. .sp
  301. To return the number of events that are pending, use 
  302. .PN XPending .
  303. .IN "XPending" "" "@DEF@"
  304. .\" Start marker code here
  305. .FD 0
  306. .\" $Header: XPending.f,v 1.1 88/02/26 10:01:44 mento Exp $
  307. int XPending\^(\^\fIdisplay\fP\^)
  308. .br
  309.       Display *\fIdisplay\fP\^;
  310. .FN    
  311. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  312. .IP \fIdisplay\fP 1i
  313. Specifies the connection to the X server.
  314. .\" End marker code here
  315. .LP
  316. .\" $Header: XPending.d,v 1.2 88/06/11 07:52:06 mento Exp $
  317. The
  318. .PN XPending
  319. function returns the number of events that have been received from the
  320. X server but have not been removed from the event queue.
  321. .PN XPending
  322. is identical to
  323. .PN XEventsQueued
  324. with the mode
  325. .PN QueuedAfterFlush
  326. specified.
  327. .NH 2
  328. Manipulating the Event Queue
  329. .XS
  330. \*(SN Manipulating the Event Queue 
  331. .XE
  332. .LP
  333. Xlib provides functions that let you manipulate the event queue.
  334. This section discusses how to:
  335. .IP \(bu 5
  336. Obtain events, in order, and remove them from the queue
  337. .IP \(bu 5
  338. Peek at events in the queue without removing them
  339. .IP \(bu 5
  340. Obtain events that match the event mask or the arbitrary
  341. predicate procedures that you provide
  342. .NH 3
  343. Returning the Next Event
  344. .XS
  345. \*(SN Returning the Next Event
  346. .XE
  347. .LP
  348. To get the next event and remove it from the queue, use
  349. .PN XNextEvent .
  350. .IN "XNextEvent" "" "@DEF@"
  351. .\" Start marker code here
  352. .FD 0
  353. .\" $Header: XNextEvent.f,v 1.1 88/02/26 10:01:33 mento Exp $
  354. XNextEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^)
  355. .br
  356.       Display *\fIdisplay\fP\^;
  357. .br
  358.       XEvent *\fIevent_return\fP\^;
  359. .FN
  360. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  361. .IP \fIdisplay\fP 1i
  362. Specifies the connection to the X server.
  363. .\" $Header: event_next.a,v 1.1 88/04/08 14:22:34 mento Exp $
  364. .IP \fIevent_return\fP 1i
  365. Returns the next event in the queue.
  366. .\" End marker code here
  367. .LP
  368. .\" $Header: XNextEvent.d,v 1.2 88/06/11 07:52:01 mento Exp $
  369. The
  370. .PN XNextEvent
  371. function copies the first event from the event queue into the specified
  372. .PN XEvent
  373. structure and then removes it from the queue.
  374. If the event queue is empty,
  375. .PN XNextEvent
  376. flushes the output buffer and blocks until an event is received.
  377. .LP
  378. .sp
  379. To peek at the event queue, use
  380. .PN XPeekEvent .
  381. .IN "XPeekEvent" "" "@DEF@"
  382. .\" Start marker code here
  383. .FD 0
  384. .\" $Header: XPeekEvent.f,v 1.1 88/02/26 10:01:43 mento Exp $
  385. XPeekEvent\^(\^\fIdisplay\fP, \fIevent_return\fP\^)
  386. .br
  387.       Display *\fIdisplay\fP\^;
  388. .br
  389.       XEvent *\fIevent_return\fP\^;
  390. .FN
  391. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  392. .IP \fIdisplay\fP 1i
  393. Specifies the connection to the X server.
  394. .IP \fIevent_return\fP 1i
  395. Returns a copy of the matched event's associated structure.
  396. .\" End marker code here
  397. .LP
  398. .\" $Header: XPeekEvent.d,v 1.2 88/06/11 07:52:05 mento Exp $
  399. The
  400. .PN XPeekEvent
  401. function returns the first event from the event queue,
  402. but it does not remove the event from the queue.
  403. If the queue is empty,
  404. .PN XPeekEvent
  405. flushes the output buffer and blocks until an event is received.
  406. It then copies the event into the client-supplied
  407. .PN XEvent
  408. structure without removing it from the event queue.
  409. .NH 3
  410. Selecting Events Using a Predicate Procedure
  411. .XS
  412. \*(SN Selecting Events Using a Predicate Procedure
  413. .XE
  414. .LP
  415. Each of the functions discussed in this section requires you to
  416. pass a predicate procedure that determines if an event matches 
  417. what you want.
  418. Your predicate procedure must decide only if the event is useful
  419. and must not call Xlib functions.
  420. In particular,
  421. a predicate is called from inside the event routine,
  422. which must lock data structures so that the event queue is consistent in a 
  423. multi-threaded environment.
  424. .LP
  425. The predicate procedure and its associated arguments are:
  426. .\" Start marker code here
  427. .FD 0
  428. Bool (\^*\fIpredicate\fP\^)\^(\^\fIdisplay\fP, \fIevent\fP, \fIarg\fP\^)
  429. .br
  430.      Display *\fIdisplay\fP\^;
  431. .br
  432.      XEvent *\fIevent\fP\^;
  433. .br
  434.      XPointer \fIarg\fP\^;
  435. .FN
  436. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  437. .IP \fIdisplay\fP 1i
  438. Specifies the connection to the X server.
  439. .IP \fIevent\fP 1i
  440. Specifies the
  441. .PN XEvent
  442. structure.
  443. .IP \fIarg\fP 1i
  444. Specifies the argument passed in from the 
  445. .PN XIfEvent ,
  446. .PN XCheckIfEvent ,
  447. or
  448. .PN XPeekIfEvent 
  449. function.
  450. .\" End marker code here
  451. .LP
  452. The predicate procedure is called once for each
  453. event in the queue until it finds a match. 
  454. After finding a match, the predicate procedure must return 
  455. .PN True .
  456. If it did not find a match, it must return
  457. .PN False .
  458. .LP
  459. .sp
  460. To check the event queue for a matching event
  461. and, if found, remove the event from the queue, use
  462. .PN XIfEvent .
  463. .IN "XIfEvent" "" "@DEF@"
  464. .\" Start marker code here
  465. .FD 0
  466. XIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
  467. .br
  468.       Display *\fIdisplay\fP\^;
  469. .br
  470.       XEvent *\fIevent_return\fP\^;
  471. .br
  472.       Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
  473. .br
  474.       XPointer \fIarg\fP\^;
  475. .FN
  476. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  477. .IP \fIdisplay\fP 1i
  478. Specifies the connection to the X server.
  479. .\" $Header: event.a,v 1.4 88/05/14 13:23:54 mento Exp $
  480. .IP \fIevent_return\fP 1i
  481. Returns the matched event's associated structure.
  482. .IP \fIpredicate\fP 1i
  483. Specifies the procedure that is to be called to determine
  484. if the next event in the queue matches what you want.
  485. .IP \fIarg\fP 1i
  486. Specifies the user-supplied argument that will be passed to the predicate procedure.
  487. .\" End marker code here
  488. .LP
  489. .\" $Header: XIfEvent.d,v 1.2 88/06/11 07:51:39 mento Exp $
  490. The
  491. .PN XIfEvent
  492. function completes only when the specified predicate
  493. procedure returns 
  494. .PN True 
  495. for an event, 
  496. which indicates an event in the queue matches.
  497. .PN XIfEvent
  498. flushes the output buffer if it blocks waiting for additional events.
  499. .PN XIfEvent
  500. removes the matching event from the queue 
  501. and copies the structure into the client-supplied
  502. .PN XEvent
  503. structure.
  504. .LP
  505. .sp
  506. To check the event queue for a matching event without blocking, use
  507. .PN XCheckIfEvent .
  508. .IN "XCheckIfEvent" "" "@DEF@"
  509. .\" Start marker code here
  510. .FD 0
  511. Bool XCheckIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
  512. .br
  513.       Display *\fIdisplay\fP\^;
  514. .br
  515.       XEvent *\fIevent_return\fP\^;
  516. .br
  517.       Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
  518. .br
  519.       XPointer \fIarg\fP\^;
  520. .FN
  521. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  522. .IP \fIdisplay\fP 1i
  523. Specifies the connection to the X server.
  524. .IP \fIevent_return\fP 1i
  525. Returns a copy of the matched event's associated structure.
  526. .IP \fIpredicate\fP 1i
  527. Specifies the procedure that is to be called to determine
  528. if the next event in the queue matches what you want.
  529. .IP \fIarg\fP 1i
  530. Specifies the user-supplied argument that will be passed to the predicate procedure.
  531. .\" End marker code here
  532. .LP
  533. .\" $Header: XCkIfEvent.d,v 1.2 88/06/11 07:49:21 mento Exp $
  534. When the predicate procedure finds a match,
  535. .PN XCheckIfEvent
  536. copies the matched event into the client-supplied
  537. .PN XEvent
  538. structure and returns 
  539. .PN True .
  540. (This event is removed from the queue.)
  541. If the predicate procedure finds no match,
  542. .PN XCheckIfEvent
  543. returns
  544. .PN False ,
  545. and the output buffer will have been flushed.
  546. All earlier events stored in the queue are not discarded.
  547. .LP
  548. .sp
  549. To check the event queue for a matching event
  550. without removing the event from the queue, use
  551. .PN XPeekIfEvent .
  552. .IN "XPeekIfEvent" "" "@DEF@"
  553. .\" Start marker code here
  554. .FD 0
  555. XPeekIfEvent\^(\^\fIdisplay\fP, \fIevent_return\fP, \fIpredicate\fP, \fIarg\fP\^)
  556. .br
  557.       Display *\fIdisplay\fP\^;
  558. .br
  559.       XEvent *\fIevent_return\fP\^;
  560. .br
  561.       Bool (\^*\fIpredicate\fP\^)\^(\^)\^;
  562. .br
  563.       XPointer \fIarg\fP\^;
  564. .FN
  565. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  566. .IP \fIdisplay\fP 1i
  567. Specifies the connection to the X server.
  568. .IP \fIevent_return\fP 1i
  569. Returns a copy of the matched event's associated structure.
  570. .IP \fIpredicate\fP 1i
  571. Specifies the procedure that is to be called to determine
  572. if the next event in the queue matches what you want.
  573. .IP \fIarg\fP 1i
  574. Specifies the user-supplied argument that will be passed to the predicate procedure.
  575. .\" End marker code here
  576. .LP
  577. .\" $Header: XPkIfEvent.d,v 1.3 88/06/11 07:52:13 mento Exp $
  578. The
  579. .PN XPeekIfEvent
  580. function returns only when the specified predicate
  581. procedure returns 
  582. .PN True
  583. for an event.
  584. After the predicate procedure finds a match,
  585. .PN XPeekIfEvent
  586. copies the matched event into the client-supplied
  587. .PN XEvent
  588. structure without removing the event from the queue.
  589. .PN XPeekIfEvent
  590. flushes the output buffer if it blocks waiting for additional events.
  591. .NH 3
  592. Selecting Events Using a Window or Event Mask
  593. .XS
  594. \*(SN Selecting Events Using a Window or Event Mask
  595. .XE
  596. .LP
  597. The functions discussed in this section let you select events by window 
  598. or event types, allowing you to process events out of order.
  599. .LP
  600. .sp
  601. To remove the next event that matches both a window and an event mask, use
  602. .PN XWindowEvent .
  603. .IN "XWindowEvent" "" "@DEF@"
  604. .\" Start marker code here
  605. .FD 0
  606. .\" $Header: XWindowEvent.f,v 1.1 88/02/26 10:04:15 mento Exp $
  607. XWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^)
  608. .br
  609.       Display *\fIdisplay\fP\^;
  610. .br
  611.       Window \fIw\fP\^;
  612. .br
  613.       long \fIevent_mask\fP\^;
  614. .br
  615.       XEvent *\fIevent_return\fP\^;
  616. .FN
  617. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  618. .IP \fIdisplay\fP 1i
  619. Specifies the connection to the X server.
  620. .ds Wi whose events you are interested in
  621. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  622. .IP \fIw\fP 1i
  623. Specifies the window \*(Wi.
  624. .\" $Header: eventmask.a,v 1.2 88/05/14 13:04:06 mento Exp $
  625. .IP \fIevent_mask\fP 1i
  626. Specifies the event mask.
  627. .\" $Header: event.a,v 1.4 88/05/14 13:23:54 mento Exp $
  628. .IP \fIevent_return\fP 1i
  629. Returns the matched event's associated structure.
  630. .\" End marker code here
  631. .LP
  632. .\" $Header: XWindowEvent.d,v 1.2 88/06/11 07:54:37 mento Exp $
  633. The
  634. .PN XWindowEvent
  635. function searches the event queue for an event that matches both the specified
  636. window and event mask.
  637. When it finds a match,
  638. .PN XWindowEvent
  639. removes that event from the queue and copies it into the specified
  640. .PN XEvent
  641. structure.
  642. The other events stored in the queue are not discarded.
  643. If a matching event is not in the queue,
  644. .PN XWindowEvent
  645. flushes the output buffer and blocks until one is received.
  646. .LP
  647. .sp
  648. To remove the next event that matches both a window and an event mask (if any),
  649. use
  650. .PN XCheckWindowEvent .
  651. .IN "XCheckWindowEvent"
  652. This function is similar to
  653. .PN XWindowEvent 
  654. except that it never blocks and it returns a 
  655. .PN Bool 
  656. indicating if the event was returned.
  657. .IN "XCheckWindowEvent" "" "@DEF@"
  658. .\" Start marker code here
  659. .FD 0
  660. .\" $Header: XChkWinEvnt.f,v 1.2 88/05/04 06:26:26 mento Exp $
  661. Bool XCheckWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_mask\fP\^, \fIevent_return\fP\^)
  662. .br
  663.       Display *\fIdisplay\fP\^;
  664. .br
  665.       Window \fIw\fP\^;
  666. .br
  667.       long \fIevent_mask\fP\^;
  668. .br
  669.       XEvent *\fIevent_return\fP\^;
  670. .FN
  671. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  672. .IP \fIdisplay\fP 1i
  673. Specifies the connection to the X server.
  674. .ds Wi whose events you are interested in
  675. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  676. .IP \fIw\fP 1i
  677. Specifies the window \*(Wi.
  678. .\" $Header: eventmask.a,v 1.2 88/05/14 13:04:06 mento Exp $
  679. .IP \fIevent_mask\fP 1i
  680. Specifies the event mask.
  681. .\" $Header: event.a,v 1.4 88/05/14 13:23:54 mento Exp $
  682. .IP \fIevent_return\fP 1i
  683. Returns the matched event's associated structure.
  684. .\" End marker code here
  685. .LP
  686. .\" $Header: XChkWinEvnt.d,v 1.4 88/06/11 07:49:18 mento Exp $
  687. The
  688. .PN XCheckWindowEvent
  689. function searches the event queue and then the events available 
  690. on the server connection for the first event that matches the specified window
  691. and event mask.
  692. If it finds a match,
  693. .PN XCheckWindowEvent
  694. removes that event, copies it into the specified
  695. .PN XEvent
  696. structure, and returns
  697. .PN True .
  698. The other events stored in the queue are not discarded.
  699. If the event you requested is not available,
  700. .PN XCheckWindowEvent
  701. returns
  702. .PN False ,
  703. and the output buffer will have been flushed.
  704. .LP
  705. .sp
  706. To remove the next event that matches an event mask, use
  707. .PN XMaskEvent .
  708. .IN "XMaskEvent" "" "@DEF@"
  709. .\" Start marker code here
  710. .FD 0
  711. .\" $Header: XMaskEvent.f,v 1.2 88/05/04 06:27:18 mento Exp $
  712. XMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^)
  713. .br
  714.       Display *\fIdisplay\fP\^;
  715. .br
  716.       long \fIevent_mask\fP\^;
  717. .br
  718.       XEvent *\fIevent_return\fP\^;
  719. .FN
  720. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  721. .IP \fIdisplay\fP 1i
  722. Specifies the connection to the X server.
  723. .\" $Header: eventmask.a,v 1.2 88/05/14 13:04:06 mento Exp $
  724. .IP \fIevent_mask\fP 1i
  725. Specifies the event mask.
  726. .\" $Header: event.a,v 1.4 88/05/14 13:23:54 mento Exp $
  727. .IP \fIevent_return\fP 1i
  728. Returns the matched event's associated structure.
  729. .\" End marker code here
  730. .LP
  731. .\" $Header: XMaskEvent.d,v 1.3 88/06/11 07:51:58 mento Exp $
  732. The
  733. .PN XMaskEvent
  734. function searches the event queue for the events associated with the 
  735. specified mask.
  736. When it finds a match,
  737. .PN XMaskEvent
  738. removes that event and copies it into the specified
  739. .PN XEvent
  740. structure.
  741. The other events stored in the queue are not discarded.
  742. If the event you requested is not in the queue,
  743. .PN XMaskEvent
  744. flushes the output buffer and blocks until one is received.
  745. .LP
  746. .sp
  747. To return and remove the next event that matches an event mask (if any), use
  748. .PN XCheckMaskEvent .
  749. This function is similar to 
  750. .PN XMaskEvent 
  751. except that it never blocks and it returns a 
  752. .PN Bool 
  753. indicating if the event was returned.
  754. .IN "XCheckMaskEvent" "" "@DEF@"
  755. .\" Start marker code here
  756. .FD 0
  757. .\" $Header: XChkMskEvnt.f,v 1.2 88/05/04 06:28:11 mento Exp $
  758. Bool XCheckMaskEvent\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIevent_return\fP\^)
  759. .br
  760.       Display *\fIdisplay\fP\^;
  761. .br
  762.       long \fIevent_mask\fP\^;
  763. .br
  764.       XEvent *\fIevent_return\fP\^;
  765. .FN
  766. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  767. .IP \fIdisplay\fP 1i
  768. Specifies the connection to the X server.
  769. .\" $Header: eventmask.a,v 1.2 88/05/14 13:04:06 mento Exp $
  770. .IP \fIevent_mask\fP 1i
  771. Specifies the event mask.
  772. .\" $Header: event.a,v 1.4 88/05/14 13:23:54 mento Exp $
  773. .IP \fIevent_return\fP 1i
  774. Returns the matched event's associated structure.
  775. .\" End marker code here
  776. .LP
  777. .\" $Header: XChkMskEvnt.d,v 1.4 88/06/11 07:49:13 mento Exp $
  778. The
  779. .PN XCheckMaskEvent
  780. function searches the event queue and then any events available on the
  781. server connection for the first event that matches the specified mask.
  782. If it finds a match,
  783. .PN XCheckMaskEvent
  784. removes that event, copies it into the specified
  785. .PN XEvent
  786. structure, and returns
  787. .PN True .
  788. The other events stored in the queue are not discarded.
  789. If the event you requested is not available,
  790. .PN XCheckMaskEvent
  791. returns
  792. .PN False ,
  793. and the output buffer will have been flushed.
  794. .LP
  795. .sp 
  796. To return and remove the next event in the queue that matches an event type, use
  797. .PN XCheckTypedEvent .
  798. .IN "XCheckTypedEvent" "" "@DEF@"
  799. .\" Start marker code here
  800. .FD 0
  801. .\" $Header: XChkTypEvnt.f,v 1.1 88/02/26 09:58:39 mento Exp $
  802. Bool XCheckTypedEvent\^(\^\fIdisplay\fP, \fIevent_type\fP\^, \fIevent_return\fP\^)
  803. .br
  804.       Display *\fIdisplay\fP\^;
  805. .br
  806.       int \fIevent_type\fP\^;
  807. .br
  808.       XEvent *\fIevent_return\fP\^;
  809. .FN
  810. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  811. .IP \fIdisplay\fP 1i
  812. Specifies the connection to the X server.
  813. .\" $Header: event_type.a,v 1.1 88/02/26 10:26:48 mento Exp $
  814. .IP \fIevent_type\fP 1i
  815. Specifies the event type to be compared.
  816.  
  817. .\" $Header: event.a,v 1.4 88/05/14 13:23:54 mento Exp $
  818. .IP \fIevent_return\fP 1i
  819. Returns the matched event's associated structure.
  820. .\" End marker code here
  821. .LP
  822. The
  823. .PN XCheckTypedEvent
  824. function searches the event queue and then any events available  
  825. on the server connection for the first event that matches the specified type.
  826. If it finds a match,
  827. .PN XCheckTypedEvent
  828. removes that event, copies it into the specified
  829. .PN XEvent
  830. structure, and returns
  831. .PN True .
  832. The other events in the queue are not discarded.
  833. If the event is not available,
  834. .PN XCheckTypedEvent
  835. returns
  836. .PN False ,
  837. and the output buffer will have been flushed.
  838. .LP
  839. .sp
  840. To return and remove the next event in the queue that matches an event type 
  841. and a window, use
  842. .PN XCheckTypedWindowEvent .
  843. .IN "XCheckTypedWindowEvent" "" "@DEF@"
  844. .\" Start marker code here
  845. .FD 0
  846. .\" $Header: XChkTypWEvnt.f,v 1.1 88/02/26 09:58:39 mento Exp $
  847. Bool XCheckTypedWindowEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_type\fP\^, \fIevent_return\fP\^)
  848. .br
  849.       Display *\fIdisplay\fP\^;
  850. .br
  851.       Window \fIw\fP\^;
  852. .br
  853.       int \fIevent_type\fP\^;
  854. .br
  855.       XEvent *\fIevent_return\fP\^;
  856. .FN
  857. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  858. .IP \fIdisplay\fP 1i
  859. Specifies the connection to the X server.
  860. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  861. .IP \fIw\fP 1i
  862. Specifies the window.
  863. .\" $Header: event_type.a,v 1.1 88/02/26 10:26:48 mento Exp $
  864. .IP \fIevent_type\fP 1i
  865. Specifies the event type to be compared.
  866.  
  867. .\" $Header: event.a,v 1.4 88/05/14 13:23:54 mento Exp $
  868. .IP \fIevent_return\fP 1i
  869. Returns the matched event's associated structure.
  870. .\" End marker code here
  871. .LP
  872. The
  873. .PN XCheckTypedWindowEvent
  874. function searches the event queue and then any events available  
  875. on the server connection for the first event that matches the specified
  876. type and window.
  877. If it finds a match,
  878. .PN XCheckTypedWindowEvent
  879. removes the event from the queue, copies it into the specified
  880. .PN XEvent
  881. structure, and returns
  882. .PN True .
  883. The other events in the queue are not discarded.
  884. If the event is not available,
  885. .PN XCheckTypedWindowEvent
  886. returns
  887. .PN False ,
  888. and the output buffer will have been flushed.
  889. .NH 2
  890. Putting an Event Back into the Queue
  891. .XS
  892. \*(SN Putting an Event Back into the Queue 
  893. .XE
  894. .LP
  895. To push an event back into the event queue, use
  896. .PN XPutBackEvent .
  897. .IN "XPutBackEvent" "" "@DEF@"
  898. .\" Start marker code here
  899. .FD 0
  900. .\" $Header: XPutBckEvent.f,v 1.1 88/02/26 10:02:01 mento Exp $
  901. XPutBackEvent\^(\^\fIdisplay\fP, \fIevent\fP\^)
  902. .br
  903.       Display *\fIdisplay\fP\^;
  904. .br
  905.       XEvent *\fIevent\fP\^;
  906. .FN
  907. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  908. .IP \fIdisplay\fP 1i
  909. Specifies the connection to the X server.
  910. .IP \fIevent\fP 1i
  911. Specifies the event.
  912. .\" End marker code here
  913. .LP 
  914. .\" $Header: XPutBckEvent.d,v 1.3 88/06/11 07:52:25 mento Exp $
  915. The
  916. .PN XPutBackEvent
  917. function pushes an event back onto the head of the display's event queue
  918. by copying the event into the queue.
  919. This can be useful if you read an event and then decide that you
  920. would rather deal with it later.
  921. There is no limit to the number of times in succession that you can call
  922. .PN XPutBackEvent .
  923. .NH 2
  924. Sending Events to Other Applications
  925. .XS
  926. \*(SN Sending Events to Other Applications
  927. .XE
  928. .LP
  929. To send an event to a specified window, use
  930. .PN XSendEvent .
  931. .IN "XSendEvent"
  932. This function is often used in selection processing.
  933. For example, the owner of a selection should use
  934. .PN XSendEvent
  935. to send a
  936. .PN SelectionNotify
  937. event to a requestor when a selection has been converted 
  938. and stored as a property.
  939. .IN "XSendEvent" "" "@DEF@"
  940. .\" Start marker code here
  941. .FD 0
  942. .\" $Header: XSendEvent.f,v 1.2 88/05/04 06:29:14 mento Exp $
  943. Status XSendEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIpropagate\fP\^, \fIevent_mask\fP\^, \fIevent_send\fP\^)
  944. .br
  945.       Display *\fIdisplay\fP\^;
  946. .br
  947.       Window \fIw\fP\^;
  948. .br
  949.       Bool \fIpropagate\fP\^;
  950. .br
  951.       long \fIevent_mask\fP\^;
  952. .br
  953.       XEvent *\fIevent_send\fP\^;
  954. .FN
  955. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  956. .IP \fIdisplay\fP 1i
  957. Specifies the connection to the X server.
  958. .\" $Header: w_send.a,v 1.1 88/05/14 13:40:46 mento Exp $
  959. .IP \fIw\fP 1i
  960. Specifies the window the event is to be sent to,
  961. .PN PointerWindow ,
  962. or
  963. .PN InputFocus .
  964. .\" $Header: propagate.a,v 1.3 88/05/14 13:42:06 mento Exp $
  965. .IP \fIpropagate\fP 1i
  966. Specifies a Boolean value.
  967. .\" $Header: eventmask.a,v 1.2 88/05/14 13:04:06 mento Exp $
  968. .IP \fIevent_mask\fP 1i
  969. Specifies the event mask.
  970. .IP \fIevent_send\fP 1i
  971. Specifies the event that is to be sent.
  972. .\" End marker code here
  973. .LP
  974. .\" $Header: XSendEvent.d,v 1.4 88/08/20 09:17:09 mento Exp $
  975. The
  976. .PN XSendEvent
  977. function identifies the destination window, 
  978. determines which clients should receive the specified events, 
  979. and ignores any active grabs.
  980. This function requires you to pass an event mask.
  981. For a discussion of the valid event mask names,
  982. see section 10.3.
  983. This function uses the w argument to identify the destination window as follows:
  984. .IP \(bu 5
  985. If w is
  986. .PN PointerWindow ,
  987. the destination window is the window that contains the pointer.
  988. .IP \(bu 5
  989. If w is
  990. .PN InputFocus 
  991. and if the focus window contains the pointer, 
  992. the destination window is the window that contains the pointer; 
  993. otherwise, the destination window is the focus window.
  994. .LP
  995. To determine which clients should receive the specified events,
  996. .PN XSendEvent
  997. uses the propagate argument as follows:
  998. .IP \(bu 5
  999. If event_mask is the empty set,
  1000. the event is sent to the client that created the destination window.
  1001. If that client no longer exists,
  1002. no event is sent.
  1003. .IP \(bu 5
  1004. If propagate is 
  1005. .PN False ,
  1006. the event is sent to every client selecting on destination any of the event
  1007. types in the event_mask argument.
  1008. .IP \(bu 5
  1009. If propagate is 
  1010. .PN True 
  1011. and no clients have selected on destination any of
  1012. the event types in event-mask, the destination is replaced with the
  1013. closest ancestor of destination for which some client has selected a
  1014. type in event-mask and for which no intervening window has that type in its
  1015. do-not-propagate-mask. 
  1016. If no such window exists or if the window is
  1017. an ancestor of the focus window and 
  1018. .PN InputFocus 
  1019. was originally specified
  1020. as the destination, the event is not sent to any clients.
  1021. Otherwise, the event is reported to every client selecting on the final
  1022. destination any of the types specified in event_mask.
  1023. .LP
  1024. The event in the
  1025. .PN XEvent
  1026. structure must be one of the core events or one of the events
  1027. defined by an extension (or a 
  1028. .PN BadValue
  1029. error results) so that the X server can correctly byte-swap 
  1030. the contents as necessary.  
  1031. The contents of the event are
  1032. otherwise unaltered and unchecked by the X server except to force send_event to
  1033. .PN True
  1034. in the forwarded event and to set the serial number in the event correctly.
  1035. .LP
  1036. .PN XSendEvent
  1037. returns zero if the conversion to wire protocol format failed
  1038. and returns nonzero otherwise.
  1039. .LP
  1040. .PN XSendEvent
  1041. can generate
  1042. .PN BadValue
  1043. and 
  1044. .PN BadWindow 
  1045. errors.
  1046. .NH 2
  1047. Getting Pointer Motion History
  1048. .XS
  1049. \*(SN Getting Pointer Motion History
  1050. .XE
  1051. .LP
  1052. Some X server implementations will maintain a more complete
  1053. history of pointer motion than is reported by event notification.
  1054. The pointer position at each pointer hardware interrupt may be
  1055. stored in a buffer for later retrieval.
  1056. This buffer is called the motion history buffer.
  1057. For example, a few applications, such as paint programs,
  1058. want to have a precise history of where the pointer
  1059. traveled. 
  1060. However, this historical information is highly excessive for most applications.
  1061. .LP
  1062. .sp
  1063. To determine the approximate maximum number of elements in the motion buffer, 
  1064. use
  1065. .PN XDisplayMotionBufferSize .
  1066. .IN "XDisplayMotionBufferSize" "" "@DEF@"
  1067. .\" Start marker code here
  1068. .FD 0
  1069. unsigned long XDisplayMotionBufferSize\^(\^\fIdisplay\fP\^)
  1070. .br
  1071.         Display *\fIdisplay\fP\^;
  1072. .FN
  1073. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1074. .IP \fIdisplay\fP 1i
  1075. Specifies the connection to the X server.
  1076. .\" End marker code here
  1077. .LP
  1078. The server may retain the recent history of the pointer motion
  1079. and do so to a finer granularity than is reported by
  1080. .PN MotionNotify
  1081. events.
  1082. The
  1083. .PN XGetMotionEvents
  1084. function makes this history available.
  1085. .LP
  1086. .sp
  1087. To get the motion history for a specified window and time, use
  1088. .PN XGetMotionEvents .
  1089. .IN "XGetMotionEvents" "" "@DEF@"
  1090. .\" Start marker code here
  1091. .FD 0
  1092. .\" $Header: XGetMoEvents.f,v 1.1 88/02/26 10:00:51 mento Exp $
  1093. XTimeCoord *XGetMotionEvents\^(\^\fIdisplay\fP, \fIw\fP\^, \fIstart\fP\^, \fIstop\fP\^, \fInevents_return\fP\^)
  1094. .br
  1095.       Display *\fIdisplay\fP\^;
  1096. .br
  1097.       Window \fIw\fP\^;
  1098. .br
  1099.       Time \fIstart\fP\^, \fIstop\fP\^;    
  1100. .br
  1101.       int *\fInevents_return\fP\^;
  1102. .FN
  1103. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1104. .IP \fIdisplay\fP 1i
  1105. Specifies the connection to the X server.
  1106. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1107. .IP \fIw\fP 1i
  1108. Specifies the window.
  1109. .\" $Header: startstop.a,v 1.2 88/05/14 13:47:41 mento Exp $
  1110. .IP \fIstart\fP 1i
  1111. .br
  1112. .ns
  1113. .IP \fIstop\fP 1i
  1114. Specify the time interval in which the events are returned from the motion
  1115. history buffer.
  1116. You can pass a timestamp or
  1117. .PN CurrentTime .
  1118. .\" $Header: nevents.a,v 1.1 88/02/26 10:29:31 mento Exp $
  1119. .IP \fInevents_return\fP 1i
  1120. Returns the number of events from the motion history buffer.
  1121. .\" End marker code here
  1122. .LP
  1123. .\" $Header: XGetMoEvents.d,v 1.3 88/06/11 07:51:11 mento Exp $
  1124. The
  1125. .PN XGetMotionEvents
  1126. function returns all events in the motion history buffer that fall between the
  1127. specified start and stop times, inclusive, and that have coordinates
  1128. that lie within the specified window (including its borders) at its present
  1129. placement.
  1130. If the server does not support motion history, 
  1131. or if the start time is later than the stop time,
  1132. or if the start time is in the future, 
  1133. no events are returned, and
  1134. .PN XGetMotionEvents
  1135. returns NULL.
  1136. If the stop time is in the future, it is equivalent to specifying
  1137. .PN CurrentTime .
  1138. The return type for this function is a structure defined as follows:
  1139. .LP
  1140. .IN "XTimeCoord" "" "@DEF@"
  1141. .\" Start marker code here
  1142. .Ds 0
  1143. .TA .5i
  1144. .ta .5i
  1145. typedef struct {
  1146.     Time time;
  1147.     short x, y;
  1148. } XTimeCoord;
  1149. .De
  1150. .\" End marker code here
  1151. .LP
  1152. The time member is set to the time, in milliseconds. 
  1153. The x and y members are set to the coordinates of the pointer and
  1154. are reported relative to the origin
  1155. of the specified window.
  1156. To free the data returned from this call, use
  1157. .PN XFree .
  1158. .LP
  1159. .PN XGetMotionEvents
  1160. can generate a
  1161. .PN BadWindow 
  1162. error.
  1163. .NH 2
  1164. Handling Protocol Errors
  1165. .XS
  1166. \*(SN Handling Protocol Errors
  1167. .XE
  1168. .LP
  1169. Xlib provides functions that you can use to enable or disable synchronization
  1170. and to use the default error handlers.
  1171. .NH 3
  1172. Enabling or Disabling Synchronization
  1173. .XS
  1174. \*(SN Enabling or Disabling Synchronization 
  1175. .XE
  1176. .LP
  1177. When debugging X applications, 
  1178. it often is very convenient to require Xlib to behave synchronously
  1179. so that errors are reported as they occur.
  1180. The following function lets you disable or enable synchronous behavior.
  1181. Note that graphics may occur 30 or more times more slowly when 
  1182. synchronization is enabled.
  1183. .IN "_Xdebug"
  1184. On POSIX-conformant systems,
  1185. there is also a global variable 
  1186. .PN _Xdebug 
  1187. that, if set to nonzero before starting a program under a debugger, will force
  1188. synchronous library behavior.
  1189. .LP
  1190. After completing their work,
  1191. all Xlib functions that generate protocol requests call what is known as
  1192. an after function.
  1193. .PN XSetAfterFunction
  1194. sets which function is to be called.
  1195. .IN "XSetAfterFunction" "" "@DEF@"
  1196. .\" Start marker code here
  1197. .FD 0
  1198. .\" $Header: XSyncHandler.f,v 1.2 88/08/20 09:27:02 mento Exp $
  1199. int (*XSetAfterFunction\^(\^\fIdisplay\fP, \fIprocedure\fP\^))()
  1200. .br
  1201.       Display *\fIdisplay\fP\^;
  1202. .br
  1203.       int (\^*\^\fIprocedure\fP\^)\^();
  1204. .FN
  1205. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1206. .IP \fIdisplay\fP 1i
  1207. Specifies the connection to the X server.
  1208. .\" $Header: func.a,v 1.2 88/08/20 09:26:05 mento Exp $
  1209. .IP \fIprocedure\fP 1i
  1210. Specifies the function to be called.
  1211. .\" End marker code here
  1212. .LP
  1213. .\" $Header: XSyncHandler.d,v 1.8 88/08/20 09:25:04 mento Exp $
  1214. The specified procedure is called with only a display pointer.
  1215. .PN XSetAfterFunction
  1216. returns the previous after function.
  1217. .LP
  1218. To enable or disable synchronization, use 
  1219. .PN XSynchronize .
  1220. .IN "Debugging" "synchronous mode"
  1221. .IN "XSynchronize" "" "@DEF@"
  1222. .\" Start marker code here
  1223. .FD 0
  1224. .\" $Header: XSynchronize.f,v 1.2 88/05/14 13:57:23 mento Exp $
  1225. int (*XSynchronize\^(\^\fIdisplay\fP, \fIonoff\fP\^)\^)()
  1226. .br
  1227.       Display *\fIdisplay\fP\^;
  1228. .br
  1229.       Bool \fIonoff\fP\^;
  1230. .FN
  1231. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1232. .IP \fIdisplay\fP 1i
  1233. Specifies the connection to the X server.
  1234. .\" $Header: onoff.a,v 1.2 88/05/14 13:58:45 mento Exp $
  1235. .IP \fIonoff\fP 1i
  1236. Specifies a Boolean value that indicates whether to enable 
  1237. or disable synchronization.
  1238. .\" End marker code here
  1239. .LP
  1240. .\" $Header: XSynchronize.d,v 1.2 88/06/11 07:54:00 mento Exp $
  1241. The
  1242. .PN XSynchronize
  1243. function returns 
  1244. the previous after function.
  1245. If onoff is 
  1246. .PN True , 
  1247. .PN XSynchronize
  1248. turns on synchronous behavior.
  1249. If onoff is
  1250. .PN False ,
  1251. .PN XSynchronize 
  1252. turns off synchronous behavior.
  1253. .NH 3
  1254. Using the Default Error Handlers
  1255. .XS
  1256. \*(SN Using the Default Error Handlers 
  1257. .XE
  1258. .LP
  1259. .IN "Debugging" "error handlers"
  1260. .IN "Error" "handlers"
  1261. There are two default error handlers in Xlib: 
  1262. one to handle typically fatal conditions (for example, 
  1263. the connection to a display server dying because a machine crashed) 
  1264. and one to handle protocol errors from the X server.
  1265. These error handlers can be changed to user-supplied routines if you
  1266. prefer your own error handling and can be changed as often as you like.
  1267. If either function is passed a NULL pointer, it will
  1268. reinvoke the default handler.
  1269. The action of the default handlers is to print an explanatory
  1270. message and exit.
  1271. .LP
  1272. .sp
  1273. To set the error handler, use
  1274. .PN XSetErrorHandler .
  1275. .IN "XSetErrorHandler" "" "@DEF@"
  1276. .\" Start marker code here
  1277. .FD 0
  1278. .\" $Header: XErrHndlr.f,v 1.1 88/02/26 09:59:49 mento Exp $
  1279. int (*XSetErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^)
  1280. .br
  1281.       int (\^*\^\fIhandler\fP\^)\^(Display *, XErrorEvent *)
  1282. .FN
  1283. .\" $Header: handler.a,v 1.1 88/02/26 10:27:49 mento Exp $
  1284. .IP \fIhandler\fP 1i
  1285. Specifies the program's supplied error handler.
  1286. .\" End marker code here
  1287. .LP 
  1288. .\" $Header: XErrHndlr.d,v 1.2 88/06/11 07:50:10 mento Exp $
  1289. Xlib generally calls the program's
  1290. supplied error handler whenever an error is received.
  1291. It is not called on
  1292. .PN BadName
  1293. errors from
  1294. .PN OpenFont ,
  1295. .PN LookupColor ,
  1296. or
  1297. .PN AllocNamedColor
  1298. protocol requests or on
  1299. .PN BadFont
  1300. errors from a
  1301. .PN QueryFont
  1302. protocol request.
  1303. These errors generally are reflected back to the program through the
  1304. procedural interface.
  1305. Because this condition is not assumed to be fatal, 
  1306. it is acceptable for your error handler to return.
  1307. However, the error handler should not
  1308. call any functions (directly or indirectly) on the display
  1309. that will generate protocol requests or that will look for input events.
  1310. The previous error handler is returned.
  1311. .LP
  1312. The 
  1313. .PN XErrorEvent
  1314. structure contains:
  1315. .IN "Debugging" "error event"
  1316. .LP
  1317. .IN "XErrorEvent" "" "@DEF"
  1318. .Ds 0
  1319. .TA .5i 2.5i
  1320. .ta .5i 2.5i
  1321. typedef struct {
  1322.     int type;
  1323.     Display *display;    /* Display the event was read from */
  1324.     unsigned long serial;        /* serial number of failed request */
  1325.     unsigned char error_code;    /* error code of failed request */
  1326.     unsigned char request_code;    /* Major op-code of failed request */
  1327.     unsigned char minor_code;    /* Minor op-code of failed request */
  1328.     XID resourceid;        /* resource id */
  1329. } XErrorEvent;
  1330. .De
  1331. .LP
  1332. .IN "Serial Number"
  1333. The serial member is the number of requests, starting from one, 
  1334. sent over the network connection since it was opened. 
  1335. It is the number that was the value of 
  1336. .PN NextRequest 
  1337. immediately before the failing call was made.  
  1338. The request_code member is a protocol request
  1339. of the procedure that failed, as defined in 
  1340. .Pn < X11/Xproto.h >.
  1341. The following error codes can be returned by the functions described in this
  1342. chapter:
  1343. .IN "Debugging" "error numbers"
  1344. .IN "Error" "codes"
  1345. .\".CP T 3
  1346. .\"Error Codes
  1347. .IN "BadAccess" "" "@DEF@"
  1348. .IN "BadAlloc" "" "@DEF@"
  1349. .IN "BadAtom" "" "@DEF@"
  1350. .IN "BadColor" "" "@DEF@"
  1351. .IN "BadCursor" "" "@DEF@"
  1352. .IN "BadDrawable" "" "@DEF@"
  1353. .IN "BadFont" "" "@DEF@"
  1354. .IN "BadGC" "" "@DEF@"
  1355. .IN "BadIDChoice" "" "@DEF@"
  1356. .TS H
  1357. l c
  1358. lw(1.75i) lw(4i).
  1359. _
  1360. .sp 6p
  1361. .B
  1362. Error Code    Description
  1363. .sp 6p
  1364. _
  1365. .sp 6p
  1366. .TH
  1367. .R
  1368. T{
  1369. .PN BadAccess
  1370. T}    T{
  1371. A client attempts to grab a key/button combination already grabbed 
  1372. by another client.
  1373. .sp 3p
  1374. A client attempts to free a colormap entry that it had not already allocated,
  1375. or to free an entry in a colormap that was created with all entries writable.
  1376. .sp 3p
  1377. A client attempts to store into a read-only or unallocated colormap entry.
  1378. .sp 3p
  1379. A client attempts to modify the access control list from other than the local 
  1380. (or otherwise authorized) host.
  1381. .sp 3p
  1382. A client attempts to select an event type that another client 
  1383. has already selected.
  1384. T}
  1385. .sp 3p
  1386. T{
  1387. .PN BadAlloc
  1388. T}    T{
  1389. The server fails to allocate the requested resource.
  1390. Note that the explicit listing of
  1391. .PN BadAlloc
  1392. errors in requests only covers allocation errors at a very coarse level
  1393. and is not intended to (nor can it in practice hope to) cover all cases of
  1394. a server running out of allocation space in the middle of service.
  1395. The semantics when a server runs out of allocation space are left unspecified,
  1396. but a server may generate a
  1397. .PN BadAlloc
  1398. error on any request for this reason,
  1399. and clients should be prepared to receive such errors and handle or discard
  1400. them.
  1401. T}
  1402. .sp 3p
  1403. T{
  1404. .PN BadAtom
  1405. T}    T{
  1406. A value for an atom argument does not name a defined atom.
  1407. T}
  1408. .sp 3p
  1409. T{
  1410. .PN BadColor
  1411. T}    T{
  1412. A value for a colormap argument does not name a defined colormap.
  1413. T}
  1414. .sp 3p
  1415. T{
  1416. .PN BadCursor
  1417. T}    T{
  1418. A value for a cursor argument does not name a defined cursor.
  1419. T}
  1420. .sp 3p
  1421. T{
  1422. .PN BadDrawable
  1423. T}    T{
  1424. A value for a drawable argument does not name a defined window or pixmap.
  1425. T}
  1426. .sp 3p
  1427. T{
  1428. .PN BadFont
  1429. T}    T{
  1430. A value for a font argument does not name a defined font (or, in some cases, 
  1431. .PN GContext ).
  1432. T}
  1433. .sp 3p
  1434. T{
  1435. .PN BadGC
  1436. T}    T{
  1437. A value for a 
  1438. .PN GContext 
  1439. argument does not name a defined 
  1440. .PN GContext .
  1441. T}
  1442. .sp 3p
  1443. T{
  1444. .PN BadIDChoice
  1445. T}    T{
  1446. The value chosen for a resource identifier either is not included in the 
  1447. range assigned to the client or is already in use.
  1448. Under normal circumstances,
  1449. this cannot occur and should be considered a server or Xlib error.
  1450. T}
  1451. .sp 3p
  1452. T{
  1453. .PN BadImplementation
  1454. T}    T{
  1455. The server does not implement some aspect of the request.
  1456. A server that generates this error for a core request is deficient.
  1457. As such, this error is not listed for any of the requests,
  1458. but clients should be prepared to receive such errors 
  1459. and handle or discard them.
  1460. T}
  1461. .sp 3p
  1462. T{
  1463. .PN BadLength
  1464. T}    T{
  1465. The length of a request is shorter or longer than that required to 
  1466. contain the arguments.
  1467. This is an internal Xlib or server error.
  1468. .sp 3p
  1469. The length of a request exceeds the maximum length accepted by the server.
  1470. T}
  1471. .sp 3p
  1472. T{
  1473. .PN BadMatch
  1474. T}    T{
  1475. In a graphics request,
  1476. the root and depth of the graphics context does not match that of the drawable.
  1477. .sp 3p
  1478. An 
  1479. .PN InputOnly 
  1480. window is used as a drawable.
  1481. .sp 3p
  1482. Some argument or pair of arguments has the correct type and range,
  1483. but it fails to match in some other way required by the request.
  1484. .sp 3p
  1485. An 
  1486. .PN InputOnly 
  1487. window lacks this attribute.
  1488. T}
  1489. .sp 3p
  1490. T{
  1491. .PN BadName
  1492. T}    T{
  1493. A font or color of the specified name does not exist.
  1494. T}
  1495. .sp 3p
  1496. T{
  1497. .PN BadPixmap
  1498. T}    T{
  1499. A value for a pixmap argument does not name a defined pixmap.
  1500. T}
  1501. .sp 3p
  1502. T{
  1503. .PN BadRequest
  1504. T}    T{
  1505. The major or minor opcode does not specify a valid request.
  1506. This usually is an Xlib or server error.
  1507. T}
  1508. .sp 3p
  1509. T{
  1510. .PN BadValue
  1511. T}    T{
  1512. Some numeric value falls outside of the range of values accepted 
  1513. by the request.  
  1514. Unless a specific range is specified for an argument,
  1515. the full range defined by the argument's type is accepted.
  1516. Any argument defined as a set of alternatives typically can generate
  1517. this error (due to the encoding).
  1518. T}
  1519. .sp 3p
  1520. T{
  1521. .PN BadWindow
  1522. T}    T{
  1523. A value for a window argument does not name a defined window.
  1524. T}
  1525. .sp 6p
  1526. _
  1527. .TE
  1528. .IN "BadImplementation" "" "@DEF@"
  1529. .IN "BadLength" "" "@DEF@"
  1530. .IN "BadMatch" "" "@DEF@"
  1531. .IN "BadName" "" "@DEF@"
  1532. .IN "BadPixmap" "" "@DEF@"
  1533. .IN "BadRequest" "" "@DEF@"
  1534. .IN "BadValue" "" "@DEF@"
  1535. .IN "BadWindow" "" "@DEF@"
  1536. .NT Note
  1537. The 
  1538. .PN BadAtom , 
  1539. .PN BadColor , 
  1540. .PN BadCursor , 
  1541. .PN BadDrawable , 
  1542. .PN BadFont , 
  1543. .PN BadGC , 
  1544. .PN BadPixmap , 
  1545. and 
  1546. .PN BadWindow
  1547. errors are also used when the argument type is extended by a set of
  1548. fixed alternatives.
  1549. .NE
  1550. .sp
  1551. .LP
  1552. To obtain textual descriptions of the specified error code, use 
  1553. .PN XGetErrorText .
  1554. .IN "XGetErrorText" "" "@DEF@"
  1555. .IN "Debugging" "error message strings"
  1556. .\" Start marker code here
  1557. .FD 0
  1558. .\" $Header: XErrDescrip.f,v 1.1 88/02/26 09:59:49 mento Exp $
  1559. XGetErrorText\^(\^\fIdisplay\fP, \fIcode\fP, \fIbuffer_return\fP, \fIlength\fP\^)
  1560. .br
  1561.       Display *\fIdisplay\fP\^;
  1562. .br
  1563.       int \fIcode\fP\^;
  1564. .br
  1565.       char *\fIbuffer_return\fP\^;
  1566. .br
  1567.       int \fIlength\fP\^;
  1568. .FN
  1569. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1570. .IP \fIdisplay\fP 1i
  1571. Specifies the connection to the X server.
  1572. .\" $Header: code.a,v 1.1 88/02/26 10:05:58 mento Exp $
  1573. .IP \fIcode\fP 1i
  1574. Specifies the error code for which you want to obtain a description.
  1575. .IP \fIbuffer_return\fP 1i
  1576. Returns the error description.
  1577. .IP \fIlength\fP 1i
  1578. Specifies the size of the buffer.
  1579. .\" End marker code here
  1580. .LP 
  1581. .\" $Header: XErrDescrip.d,v 1.3 88/08/21 07:02:39 mento Exp $
  1582. The
  1583. .PN XGetErrorText
  1584. function copies a null-terminated string describing the specified error code
  1585. into the specified buffer.
  1586. The returned text is in the encoding of the current locale.
  1587. It is recommended that you use this function to obtain an error description
  1588. because extensions to Xlib may define their own error codes
  1589. and error strings.
  1590. .LP
  1591. .sp
  1592. To obtain error messages from the error database, use
  1593. .PN XGetErrorDatabaseText .
  1594. .IN "XGetErrorDatabaseText" "" "@DEF@"
  1595. .\" Start marker code here
  1596. .FD 0
  1597. XGetErrorDatabaseText\^(\^\fIdisplay\fP, \fIname\fP, \fImessage\fP, \fIdefault_string\fP, \fIbuffer_return\fP, \fIlength\fP\^)
  1598. .br
  1599.       Display *\fIdisplay\fP\^;
  1600. .br
  1601.       char *\fIname\fP, *\fImessage\fP\^;
  1602. .br
  1603.       char *\fIdefault_string\fP\^;
  1604. .br
  1605.       char *\fIbuffer_return\fP\^;
  1606. .br
  1607.       int \fIlength\fP\^;
  1608. .FN
  1609. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1610. .IP \fIdisplay\fP 1i
  1611. Specifies the connection to the X server.
  1612. .\" $Header: name_err.a,v 1.1 88/02/26 10:29:07 mento Exp $
  1613. .IP \fIname\fP 1i
  1614. Specifies the name of the application.
  1615. .\" $Header: type_err.a,v 1.1 88/02/26 10:31:50 mento Exp $
  1616. .IP \fImessage\fP 1i
  1617. Specifies the type of the error message.
  1618. .IP \fIdefault_string\fP 1i
  1619. Specifies the default error message if none is found in the database.
  1620. .IP \fIbuffer_return\fP 1i
  1621. Returns the error description.
  1622. .IP \fIlength\fP 1i
  1623. Specifies the size of the buffer.
  1624. .\" End marker code here
  1625. .LP
  1626. The
  1627. .PN XGetErrorDatabaseText
  1628. function returns a null-terminated message
  1629. (or the default message) from the error message
  1630. database.
  1631. Xlib uses this function internally to look up its error messages.
  1632. The default_string is assumed to be in the encoding of the current locale.
  1633. The buffer_return text is in the encoding of the current locale.
  1634. .LP
  1635. The name argument should generally be the name of your application.
  1636. The message argument should indicate which type of error message you want.
  1637. If the name and message are not in the Host Portable Character Encoding
  1638. the result is implementation dependent.
  1639. Xlib uses three predefined ``application names'' to report errors
  1640. (uppercase and lowercase matter):
  1641. .IP XProtoError 1i
  1642. The protocol error number is used as a string for the message argument.
  1643. .IP XlibMessage 1i
  1644. These are the message strings that are used internally by the library.
  1645. .IP XRequest 1i
  1646. For a core protocol request,
  1647. the major request protocol number is used for the message argument.
  1648. For an extension request,
  1649. the extension name (as given by
  1650. .PN InitExtension )
  1651. followed by a period (\.) and the minor request protocol number 
  1652. is used for the message argument.
  1653. If no string is found in the error database,
  1654. the default_string is returned to the buffer argument.
  1655. .LP
  1656. .sp
  1657. To report an error to the user when the requested display does not exist, use
  1658. .PN XDisplayName .
  1659. .IN "XDisplayName" "" "@DEF@"
  1660. .\" Start marker code here
  1661. .FD 0
  1662. char *XDisplayName\^(\^\fIstring\fP\^)
  1663. .br
  1664.       char *\fIstring\fP\^;
  1665. .FN
  1666. .\" $Header: string.a,v 1.1 88/02/26 10:31:32 mento Exp $
  1667. .IP \fIstring\fP 1i
  1668. Specifies the character string.
  1669. .\" End marker code here
  1670. .LP
  1671. .\" $Header: XDispName.d,v 1.3 88/06/11 07:50:03 mento Exp $
  1672. The
  1673. .PN XDisplayName
  1674. function returns the name of the display that 
  1675. .PN XOpenDisplay
  1676. would attempt to use.
  1677. If a NULL string is specified,
  1678. .PN XDisplayName
  1679. looks in the environment for the display and returns the display name that
  1680. .PN XOpenDisplay
  1681. would attempt to use.
  1682. This makes it easier to report to the user precisely which display the
  1683. program attempted to open when the initial connection attempt failed.
  1684. .LP
  1685. .sp
  1686. To handle fatal I/O errors, use
  1687. .PN XSetIOErrorHandler .
  1688. .IN "XSetIOErrorHandler" "" "@DEF@"
  1689. .\" Start marker code here
  1690. .FD 0
  1691. .\" $Header: XIOErrHnd.f,v 1.1 88/02/26 10:01:07 mento Exp $
  1692. int (*XSetIOErrorHandler\^(\^\fIhandler\fP\^)\^)\^(\^)
  1693. .br
  1694.       int (\^*\^\fIhandler\fP\^)(Display *);
  1695. .FN
  1696. .\" $Header: handler.a,v 1.1 88/02/26 10:27:49 mento Exp $
  1697. .IP \fIhandler\fP 1i
  1698. Specifies the program's supplied error handler.
  1699. .\" End marker code here
  1700. .LP
  1701. .\" $Header: XIOErrHnd.d,v 1.3 88/08/20 09:36:21 mento Exp $
  1702. The
  1703. .PN XSetIOErrorHandler
  1704. sets the fatal I/O error handler.
  1705. Xlib calls the program's supplied error handler if any sort of system call
  1706. error occurs (for example, the connection to the server was lost).
  1707. This is assumed to be a fatal condition,
  1708. and the called routine should not return.
  1709. If the I/O error handler does return,
  1710. the client process exits.
  1711. .LP
  1712. Note that the previous error handler is returned.
  1713. .bp
  1714.