home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH10 < prev    next >
Encoding:
Text File  |  1991-08-22  |  94.4 KB  |  3,711 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 10\fP\s-1
  5.  
  6. \s+1\fBEvents\fP\s-1
  7. .sp 2
  8. .nr H1 10
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 10: Events
  17. .XE
  18. A client application communicates with the X server through the connection you
  19. establish with the 
  20. .PN XOpenDisplay 
  21. .IN "XOpenDisplay"
  22. function.
  23. A client application sends requests to the X server over this connection.
  24. .IN "Requests" "" "@DEF@"
  25. These requests are made by the Xlib functions that are 
  26. called in the client application.
  27. Many Xlib functions cause the X server to generate events,
  28. and the user's typing or moving the pointer can generate events asynchronously.
  29. The X server returns events to the client on the same connection.
  30. .LP
  31. This chapter discusses the following topics associated with events:
  32. .IP \(bu 5
  33. Event types
  34. .IP \(bu 5
  35. Event structures
  36. .IP \(bu 5
  37. Event mask
  38. .IP \(bu 5
  39. Event processing
  40. .LP
  41. Functions for handling events are dealt with in the next chapter.
  42. .NH 2
  43. Event Types
  44. .XS
  45. \*(SN Event Types 
  46. .XE
  47. .LP
  48. .IN "Event" "types"
  49. An event is data generated asynchronously by the X server as a result of some 
  50. device activity or as side effects of a request sent by an Xlib function.
  51. .IN "Event" 
  52. Device-related events propagate from the source window to ancestor windows
  53. until some client application has selected that event type 
  54. or until the event is explicitly discarded.
  55. The X server generally sends an event to a client application
  56. only if the client has specifically asked to be informed of that event type, 
  57. typically by setting the event-mask attribute of the window.
  58. The mask can also be set when you create a window
  59. or by changing the window's
  60. event-mask.
  61. You can also mask out events that would propagate to ancestor windows
  62. by manipulating the
  63. do-not-propagate mask of the window's attributes.
  64. However,
  65. .PN MappingNotify
  66. events are always sent to all clients.
  67. .IN "Input Control"
  68. .IN "Output Control"
  69. .LP
  70. An event type describes a specific event generated by the X server.
  71. For each event type, 
  72. a corresponding constant name is defined in
  73. .Pn < X11/X.h >,
  74. which is used when referring to an event type.
  75. .IN "Event" "categories"
  76. The following table lists the event category 
  77. and its associated event type or types. 
  78. The processing associated with these events is discussed in section 10.5.
  79. .LP
  80. .\".CP T 1
  81. .\"Event Categories and Event Types
  82. .LP
  83. .TS H
  84. lw(2.25i) lw(3.5i).
  85. _
  86. .sp 6p
  87. .B
  88. Event Category    Event Type
  89. .sp 6p
  90. _
  91. .sp 6p
  92. .TH
  93. .R
  94. T{
  95. Keyboard events
  96. T}    T{
  97. .PN KeyPress ,
  98. .PN KeyRelease
  99. T}
  100. .sp 6p
  101. T{
  102. Pointer events
  103. T}    T{
  104. .PN ButtonPress , 
  105. .PN ButtonRelease  ,
  106. .PN MotionNotify
  107. T}
  108. .sp 6p
  109. T{
  110. Window crossing events
  111. T}    T{
  112. .PN EnterNotify , 
  113. .PN LeaveNotify
  114. T}
  115. .sp 6p
  116. T{
  117. Input focus events
  118. T}    T{
  119. .PN FocusIn , 
  120. .PN FocusOut
  121. T}
  122. .sp 6p
  123. T{
  124. Keymap state notification event
  125. T}    T{
  126. .PN KeymapNotify
  127. T}
  128. .sp 6p
  129. T{
  130. Exposure events    
  131. T}    T{
  132. .PN Expose , 
  133. .PN GraphicsExpose , 
  134. .PN NoExpose
  135. T}
  136. .sp 6p
  137. T{
  138. Structure control events
  139. T}    T{
  140. .PN CirculateRequest , 
  141. .PN ConfigureRequest , 
  142. .PN MapRequest ,
  143. .PN ResizeRequest
  144. T}
  145. .sp 6p
  146. T{
  147. Window state notification events
  148. T}    T{
  149. .PN CirculateNotify , 
  150. .PN ConfigureNotify , 
  151. .PN CreateNotify , 
  152. .PN DestroyNotify , 
  153. .PN GravityNotify , 
  154. .PN MapNotify ,
  155. .PN MappingNotify , 
  156. .PN ReparentNotify , 
  157. .PN UnmapNotify , 
  158. .PN VisibilityNotify
  159. T}
  160. .sp 6p
  161. T{
  162. Colormap state notification event
  163. T}    T{
  164. .PN ColormapNotify
  165. T}
  166. .sp 6p
  167. T{
  168. Client communication events
  169. T}    T{
  170. .PN ClientMessage , 
  171. .PN PropertyNotify , 
  172. .PN SelectionClear , 
  173. .PN SelectionNotify , 
  174. .PN SelectionRequest
  175. T}
  176. .sp 6p
  177. _
  178. .TE
  179. .\".LP
  180. .\"Table 8-1 lists the event types and the Xlib functions that could cause
  181. .\"the X server to generate that event type.
  182. .\"The event types are listed alphabetically.
  183. .\"Note that the error event is not listed in this table.
  184. .\"For a list of the constants associated with an error event, see the Handling
  185. .\"Errors section in this chapter.
  186. .\".LP
  187. .\".so eventtable
  188. .NH 2
  189. Event Structures
  190. .XS
  191. \*(SN Event Structures 
  192. .XE
  193. .LP
  194. For each event type,
  195. a corresponding structure is declared in
  196. .Pn < X11/Xlib.h >.
  197. All the event structures have the following common members:
  198. .LP
  199. .IN "XAnyEvent" "" "@DEF@"
  200. .\" Start marker code here
  201. .Ds 0
  202. .TA .5i 3i
  203. .ta .5i 3i
  204. typedef struct {
  205.     int type;
  206.     unsigned long serial;    /* # of last request processed by server */
  207.     Bool send_event;    /* true if this came from a SendEvent request */
  208.     Display *display;    /* Display the event was read from */
  209.     Window window;
  210. } XAnyEvent;
  211. .De
  212. .\" End marker code here
  213. .LP
  214. The type member is set to the event type constant name that uniquely identifies
  215. it.
  216. For example, when the X server reports a
  217. .PN GraphicsExpose
  218. event to a client application, it sends an
  219. .PN XGraphicsExposeEvent
  220. structure with the type member set to
  221. .PN GraphicsExpose .
  222. The display member is set to a pointer to the display the event was read on.
  223. The send_event member is set to
  224. .PN True
  225. if the event came from a
  226. .PN SendEvent
  227. protocol request.
  228. The serial member is set from the serial number reported in the protocol
  229. but expanded from the 16-bit least-significant bits to a full 32-bit value.
  230. The window member is set to the window that is most useful to toolkit
  231. dispatchers.
  232. .LP
  233. The X server can send events at any time in the input stream. 
  234. Xlib stores any events received while waiting for a reply in an event queue 
  235. for later use.
  236. Xlib also provides functions that allow you to check events 
  237. in the event queue (see section 11.3).
  238. .LP
  239. In addition to the individual structures declared for each event type, the
  240. .PN XEvent
  241. structure is a union of the individual structures declared for each event type.
  242. Depending on the type,
  243. you should access members of each event by using the 
  244. .PN XEvent
  245. union.
  246. .LP
  247. .IN "XEvent" "" "@DEF@"
  248. .\" Start marker code here
  249. .Ds 0
  250. .TA .5i 3i
  251. .ta .5i 3i
  252. typedef union _XEvent {
  253.     int type;    /* must not be changed */
  254.     XAnyEvent xany;
  255.     XKeyEvent xkey;
  256.     XButtonEvent xbutton;
  257.     XMotionEvent xmotion;
  258.     XCrossingEvent xcrossing;
  259.     XFocusChangeEvent xfocus;
  260.     XExposeEvent xexpose;
  261.     XGraphicsExposeEvent xgraphicsexpose;
  262.     XNoExposeEvent xnoexpose;
  263.     XVisibilityEvent xvisibility;
  264.     XCreateWindowEvent xcreatewindow;
  265.     XDestroyWindowEvent xdestroywindow;
  266.     XUnmapEvent xunmap;
  267.     XMapEvent xmap;
  268.     XMapRequestEvent xmaprequest;
  269.     XReparentEvent xreparent;
  270.     XConfigureEvent xconfigure;
  271.     XGravityEvent xgravity;
  272.     XResizeRequestEvent xresizerequest;
  273.     XConfigureRequestEvent xconfigurerequest;
  274.     XCirculateEvent xcirculate;
  275.     XCirculateRequestEvent xcirculaterequest;
  276.     XPropertyEvent xproperty;
  277.     XSelectionClearEvent xselectionclear;
  278.     XSelectionRequestEvent xselectionrequest;
  279.     XSelectionEvent xselection;
  280.     XColormapEvent xcolormap;
  281.     XClientMessageEvent xclient;
  282.     XMappingEvent xmapping;
  283.     XErrorEvent xerror;
  284.     XKeymapEvent xkeymap;
  285.     long pad[24];
  286. } XEvent;
  287. .De
  288. .\" End marker code here
  289. .LP
  290. An
  291. .PN XEvent
  292. structure's first entry always is the type member,
  293. which is set to the event type.
  294. The second member always is the serial number of the protocol request
  295. that generated the event.
  296. The third member always is send_event,
  297. which is a
  298. .PN Bool
  299. that indicates if the event was sent by a different client.
  300. The fourth member always is a display,
  301. which is the display that the event was read from.
  302. Except for keymap events,
  303. the fifth member always is a window,
  304. which has been carefully selected to be useful to toolkit dispatchers.
  305. To avoid breaking toolkits,
  306. the order of these first five entries is not to change.
  307. Most events also contain a time member,
  308. which is the time at which an event occurred.
  309. In addition, a pointer to the generic event must be cast before it
  310. is used to access any other information in the structure.
  311. .NH 2
  312. Event Masks
  313. .XS
  314. \*(SN Event Masks
  315. .XE
  316. .LP
  317. .IN "event mask" "" "@DEF@"
  318. Clients select event reporting of most events relative to a window.
  319. To do this, pass an event mask to an Xlib event-handling
  320. function that takes an event_mask argument.
  321. The bits of the event mask are defined in
  322. .Pn < X11/X.h >.
  323. Each bit in the event mask maps to an event mask name,
  324. which describes the event or events you want the X server to
  325. return to a client application.
  326. .LP
  327. Unless the client has specifically asked for them,
  328. most events are not reported to clients when they are generated. 
  329. Unless the client suppresses them by setting graphics-exposures in the GC to
  330. .PN False ,
  331. .PN GraphicsExpose 
  332. and 
  333. .PN NoExpose 
  334. are reported by default as a result of
  335. .PN XCopyPlane
  336. and
  337. .PN XCopyArea .
  338. .PN SelectionClear ,
  339. .PN SelectionRequest ,
  340. .PN SelectionNotify ,
  341. or
  342. .PN ClientMessage
  343. cannot be masked.
  344. Selection related events are only sent to clients cooperating
  345. with selections (see section 4.5).
  346. When the keyboard or pointer mapping is changed,
  347. .PN MappingNotify
  348. is always sent to clients.
  349. .LP
  350. .\"Table 8-2 
  351. The following table 
  352. lists the event mask constants you can pass to
  353. the event_mask argument and
  354. the circumstances in which you would want to specify the
  355. event mask:
  356. .LP
  357. .\" .CP T 2
  358. .\"Event Mask Definitions
  359. .TS H
  360. lw(2i) lw(3.5i).
  361. _
  362. .sp 6p
  363. .B
  364. Event Mask    Circumstances
  365. .sp 6p
  366. _
  367. .sp 6p
  368. .TH
  369. .R
  370. T{
  371. .PN NoEventMask
  372. T}    T{
  373. No events wanted
  374. T}
  375. T{
  376. .PN KeyPressMask
  377. T}    T{
  378. Keyboard down events wanted
  379. T}
  380. T{
  381. .PN KeyReleaseMask
  382. T}    T{
  383. Keyboard up events wanted
  384. T}
  385. T{
  386. .PN ButtonPressMask
  387. T}    T{
  388. Pointer button down events wanted
  389. T}
  390. T{
  391. .PN ButtonReleaseMask
  392. T}    T{
  393. Pointer button up events wanted
  394. T}
  395. T{
  396. .PN EnterWindowMask
  397. T}    T{
  398. Pointer window entry events wanted
  399. T}
  400. T{
  401. .PN LeaveWindowMask
  402. T}    T{
  403. Pointer window leave events wanted
  404. T}
  405. T{
  406. .PN PointerMotionMask
  407. T}    T{
  408. Pointer motion events wanted
  409. T}
  410. T{
  411. .PN PointerMotionHintMask
  412. T}    T{
  413. Pointer motion hints wanted
  414. T}
  415. T{
  416. .PN Button1MotionMask
  417. T}    T{
  418. Pointer motion while button 1 down
  419. T}
  420. T{
  421. .PN Button2MotionMask
  422. T}    T{
  423. Pointer motion while button 2 down
  424. T}
  425. T{
  426. .PN Button3MotionMask
  427. T}    T{
  428. Pointer motion while button 3 down
  429. T}
  430. T{
  431. .PN Button4MotionMask
  432. T}    T{
  433. Pointer motion while button 4 down
  434. T}
  435. T{
  436. .PN Button5MotionMask
  437. T}    T{
  438. Pointer motion while button 5 down
  439. T}
  440. T{
  441. .PN ButtonMotionMask
  442. T}    T{
  443. Pointer motion while any button down
  444. T}
  445. T{
  446. .PN KeymapStateMask
  447. T}    T{
  448. Keyboard state wanted at window entry and focus in
  449. T}
  450. T{
  451. .PN ExposureMask
  452. T}    T{
  453. Any exposure wanted
  454. T}
  455. T{
  456. .PN VisibilityChangeMask
  457. T}    T{
  458. Any change in visibility wanted
  459. T}
  460. T{
  461. .PN StructureNotifyMask
  462. T}    T{
  463. Any change in window structure wanted
  464. T}
  465. T{
  466. .PN ResizeRedirectMask
  467. T}    T{
  468. Redirect resize of this window
  469. T}
  470. T{
  471. .PN SubstructureNotifyMask
  472. T}    T{
  473. Substructure notification wanted
  474. T}
  475. T{
  476. .PN SubstructureRedirectMask
  477. T}    T{
  478. Redirect structure requests on children
  479. T}
  480. T{
  481. .PN FocusChangeMask
  482. T}    T{
  483. Any change in input focus wanted
  484. T}
  485. T{
  486. .PN PropertyChangeMask
  487. T}    T{
  488. Any change in property wanted
  489. T}
  490. T{
  491. .PN ColormapChangeMask
  492. T}    T{
  493. Any change in colormap wanted
  494. T}
  495. T{
  496. .PN OwnerGrabButtonMask
  497. T}    T{
  498. Automatic grabs should activate with owner_events set to 
  499. .PN True
  500. T}
  501. .sp 6p
  502. _
  503. .TE
  504. .LP
  505. .NH 2
  506. Event Processing Overview
  507. .XS
  508. \*(SN Event Processing Overview
  509. .XE
  510. .LP
  511. The event reported to a client application during event processing
  512. depends on which event masks you provide as the event-mask attribute 
  513. for a window.
  514. For some event masks, there is a one-to-one correspondence between
  515. the event mask constant and the event type constant.
  516. For example, if you pass the event mask
  517. .PN ButtonPressMask ,
  518. the X server sends back only
  519. .PN ButtonPress
  520. events.
  521. .IN "CurrentTime"
  522. Most events contain a time member,
  523. which is the time at which an event occurred.
  524. .LP
  525. In other cases, one event mask constant can map to several event type constants.
  526. For example, if you pass the event mask
  527. .PN SubstructureNotifyMask ,
  528. the X server can send back
  529. .PN CirculateNotify ,
  530. .PN ConfigureNotify ,
  531. .PN CreateNotify ,
  532. .PN DestroyNotify ,
  533. .PN GravityNotify ,
  534. .PN MapNotify ,
  535. .PN ReparentNotify ,
  536. or
  537. .PN UnmapNotify
  538. events.
  539. .LP
  540. In another case, 
  541. two event masks can map to one event type.
  542. For example, 
  543. if you pass either
  544. .PN PointerMotionMask 
  545. or
  546. .PN ButtonMotionMask ,
  547. the X server sends back
  548. a
  549. .PN MotionNotify
  550. event.
  551. .LP
  552. The following table 
  553. lists the event mask, 
  554. its associated event type or types, 
  555. and the structure name associated with the event type.
  556. Some of these structures actually are typedefs to a generic structure
  557. that is shared between two event types.
  558. Note that N.A. appears in columns for which the information is not applicable.
  559. .LP
  560. .ps 9
  561. .nr PS 9
  562. .TS H
  563. lw(1.5i) lw(1i) lw(1.5i) lw(1.5i).
  564. _
  565. .sp 6p
  566. .B
  567. Event Mask    Event Type    Structure    Generic Structure
  568. .sp 6p
  569. _
  570. .sp 6p
  571. .TH
  572. .R
  573. ButtonMotionMask    MotionNotify    XPointerMovedEvent    XMotionEvent
  574. Button1MotionMask        
  575. Button2MotionMask        
  576. Button3MotionMask        
  577. Button4MotionMask        
  578. Button5MotionMask        
  579. .sp 6p
  580. ButtonPressMask    ButtonPress    XButtonPressedEvent    XButtonEvent
  581. .sp 6p
  582. ButtonReleaseMask    ButtonRelease    XButtonReleasedEvent    XButtonEvent
  583. .sp 6p
  584. ColormapChangeMask    ColormapNotify    XColormapEvent
  585. .sp 6p
  586. EnterWindowMask    EnterNotify    XEnterWindowEvent    XCrossingEvent
  587. .sp 6p
  588. LeaveWindowMask    LeaveNotify    XLeaveWindowEvent    XCrossingEvent
  589. .sp 6p
  590. ExposureMask    Expose    XExposeEvent 
  591. GCGraphicsExposures in GC    GraphicsExpose    XGraphicsExposeEvent
  592.     NoExpose    XNoExposeEvent
  593. .sp 6p
  594. FocusChangeMask    FocusIn    XFocusInEvent    XFocusChangeEvent
  595.     FocusOut    XFocusOutEvent    XFocusChangeEvent
  596. .sp 6p
  597. KeymapStateMask    KeymapNotify    XKeymapEvent
  598. .sp 6p
  599. KeyPressMask    KeyPress    XKeyPressedEvent    XKeyEvent
  600. KeyReleaseMask    KeyRelease    XKeyReleasedEvent    XKeyEvent
  601. .sp 6p
  602. OwnerGrabButtonMask    N.A.    N.A.
  603. .sp 6p
  604. PointerMotionMask    MotionNotify    XPointerMovedEvent    XMotionEvent
  605. PointerMotionHintMask    N.A.    N.A.
  606. .sp 6p
  607. PropertyChangeMask    PropertyNotify    XPropertyEvent
  608. .sp 6p
  609. ResizeRedirectMask    ResizeRequest    XResizeRequestEvent
  610. .sp 6p
  611. StructureNotifyMask    CirculateNotify    XCirculateEvent
  612.     ConfigureNotify    XConfigureEvent
  613.     DestroyNotify    XDestroyWindowEvent
  614.     GravityNotify    XGravityEvent
  615.     MapNotify    XMapEvent
  616.     ReparentNotify    XReparentEvent
  617.     UnmapNotify    XUnmapEvent
  618. .sp 6p
  619. SubstructureNotifyMask    CirculateNotify    XCirculateEvent
  620.     ConfigureNotify    XConfigureEvent
  621.     CreateNotify    XCreateWindowEvent
  622.     DestroyNotify    XDestroyWindowEvent
  623.     GravityNotify    XGravityEvent
  624.     MapNotify    XMapEvent
  625.     ReparentNotify    XReparentEvent
  626.     UnmapNotify    XUnmapEvent
  627. .sp 6p
  628. SubstructureRedirectMask    CirculateRequest    XCirculateRequestEvent
  629.     ConfigureRequest    XConfigureRequestEvent
  630.     MapRequest    XMapRequestEvent
  631. .sp 6p
  632. N.A.    ClientMessage    XClientMessageEvent
  633. .sp 6p
  634. N.A.    MappingNotify    XMappingEvent
  635. .sp 6p
  636. N.A.    SelectionClear    XSelectionClearEvent
  637. .sp 6p
  638. N.A.    SelectionNotify    XSelectionEvent
  639. .sp 6p
  640. N.A.    SelectionRequest    XSelectionRequestEvent
  641. .sp 6p
  642. VisibilityChangeMask    VisibilityNotify    XVisibilityEvent
  643. .sp 6p
  644. _
  645. .TE
  646. .ps 11
  647. .nr PS 11
  648. .LP
  649. The sections that follow describe the processing that occurs 
  650. when you select the different event masks.
  651. The sections are organized according to these processing categories:
  652. .IP \(bu 5
  653. Keyboard and pointer events
  654. .IP \(bu 5
  655. Window crossing events
  656. .IP \(bu 5
  657. Input focus events
  658. .IP \(bu 5
  659. Keymap state notification events
  660. .IP \(bu 5
  661. Exposure events
  662. .IP \(bu 5
  663. Window state notification events
  664. .IP \(bu 5
  665. Structure control events
  666. .IP \(bu 5
  667. Colormap state notification events
  668. .IP \(bu 5
  669. Client communication events
  670. .NH 2
  671. Keyboard and Pointer Events
  672. .XS
  673. \*(SN Keyboard and Pointer Events
  674. .XE
  675. .LP
  676. This section discusses:
  677. .IP \(bu 5
  678. Pointer button events
  679. .IP \(bu 5
  680. Keyboard and pointer events
  681. .NH 3
  682. Pointer Button Events
  683. .XS
  684. \*(SN Pointer Button Events
  685. .XE
  686. .LP
  687. The following describes the event processing that occurs when a pointer button 
  688. press is processed with the pointer in some window w and 
  689. when no active pointer grab is in progress.
  690. .LP
  691. The X server searches the ancestors of w from the root down,
  692. looking for a passive grab to activate.
  693. If no matching passive grab on the button exists,
  694. the X server automatically starts an active grab for the client receiving
  695. the event and sets the last-pointer-grab time to the current server time.
  696. The effect is essentially equivalent to an
  697. .PN XGrabButton
  698. with these client passed arguments:
  699. .TS H
  700. lw(1.5i) lw(3.5i).
  701. _
  702. .sp 6p
  703. .B
  704. Argument    Value
  705. .sp 6p
  706. _
  707. .sp 6p
  708. .TH
  709. .R
  710. T{
  711. \fIw\fP
  712. T}    T{
  713. The event window 
  714. T}
  715. T{
  716. \fIevent_mask\fP
  717. T}    T{
  718. The client's selected pointer events on the event window
  719. T}
  720. T{
  721. \fIpointer_mode\fP
  722. T}    T{
  723. .PN GrabModeAsync
  724. T}
  725. T{
  726. \fIkeyboard_mode\fP
  727. T}    T{
  728. .PN GrabModeAsync 
  729. T}
  730. T{
  731. \fIowner_events\fP
  732. T}    T{
  733. .PN True ,
  734. if the client has selected
  735. .PN OwnerGrabButtonMask
  736. on the event window,
  737. otherwise
  738. .PN False 
  739. T}
  740. T{
  741. \fIconfine_to\fP
  742. T}    T{
  743. .PN None 
  744. T}
  745. T{
  746. \fIcursor\fP
  747. T}    T{
  748. .PN None 
  749. T}
  750. .sp 6p
  751. _
  752. .TE
  753. .LP
  754. The active grab is automatically terminated when 
  755. the logical state of the pointer has all buttons released.
  756. Clients can modify the active grab by calling
  757. .PN XUngrabPointer
  758. and
  759. .PN XChangeActivePointerGrab .
  760. .NH 3
  761. Keyboard and Pointer Events
  762. .XS
  763. \*(SN Keyboard and Pointer Events
  764. .XE
  765. .LP
  766. .IN "Events" "ButtonPress"
  767. .IN "Events" "ButtonRelease"
  768. .IN "Events" "KeyPress"
  769. .IN "Events" "KeyRelease"
  770. .IN "Events" "MotionNotify"
  771. This section discusses the processing that occurs for the
  772. keyboard events
  773. .PN KeyPress
  774. and 
  775. .PN KeyRelease 
  776. and the pointer events
  777. .PN ButtonPress ,
  778. .PN ButtonRelease ,
  779. and
  780. .PN MotionNotify .
  781. For information about the keyboard event-handling utilities,
  782. see chapter 11.
  783. .LP
  784. .IN "KeyPress" "" "@DEF@"
  785. .IN "KeyRelease" "" "@DEF@"
  786. The X server reports
  787. .PN KeyPress
  788. or
  789. .PN KeyRelease
  790. events to clients wanting information about keys that logically change state.
  791. Note that these events are generated for all keys, 
  792. even those mapped to modifier bits.
  793. .IN "ButtonPress" "" "@DEF@"
  794. .IN "ButtonRelease" "" "@DEF@"
  795. The X server reports
  796. .PN ButtonPress
  797. or
  798. .PN ButtonRelease
  799. events to clients wanting information about buttons that logically change state.
  800. .LP
  801. .IN "MotionNotify" "" "@DEF@"
  802. The X server reports
  803. .PN MotionNotify
  804. events to clients wanting information about when the pointer logically moves.
  805. The X server generates this event whenever the pointer is moved 
  806. and the pointer motion begins and ends in the window.
  807. The granularity of
  808. .PN MotionNotify
  809. events is not guaranteed, 
  810. but a client that selects this event type is guaranteed
  811. to receive at least one event when the pointer moves and then rests.
  812. .LP
  813. The generation of the logical changes lags the physical changes 
  814. if device event processing is frozen.
  815. .LP
  816. To receive
  817. .PN KeyPress ,
  818. .PN KeyRelease ,
  819. .PN ButtonPress ,
  820. and
  821. .PN ButtonRelease 
  822. events, set 
  823. .PN KeyPressMask ,
  824. .PN KeyReleaseMask ,
  825. .PN ButtonPressMask ,
  826. and
  827. .PN ButtonReleaseMask 
  828. bits in the event-mask attribute of the window.
  829. .LP
  830. To receive 
  831. .PN MotionNotify
  832. events, set one or more of the following event 
  833. masks bits in the event-mask attribute of the window.
  834. .IP \(bu 5
  835. .PN Button1MotionMask \ \-
  836. .PN Button5MotionMask
  837. .IP
  838. The client application receives
  839. .PN MotionNotify
  840. events only when one or more of the specified buttons is pressed.
  841. .IP \(bu 5
  842. .PN ButtonMotionMask
  843. .IP
  844. The client application receives
  845. .PN MotionNotify
  846. events only when at least one button is pressed.
  847. .IP \(bu 5
  848. .PN PointerMotionMask
  849. .IP
  850. The client application receives 
  851. .PN MotionNotify
  852. events independent of the state of
  853. the pointer buttons.
  854. .IP \(bu 5
  855. .PN PointerMotionHintMask
  856. .IP
  857. If
  858. .PN PointerMotionHintMask
  859. is selected in combination with one or more of the above masks, 
  860. the X server is free to send only one
  861. .PN MotionNotify
  862. event (with the is_hint member  of the
  863. .PN XPointerMovedEvent
  864. structure set to
  865. .PN NotifyHint )
  866. to the client for the event window, 
  867. until either the key or button state changes,
  868. the pointer leaves the event window, or the client calls
  869. .PN XQueryPointer
  870. or
  871. .PN XGetMotionEvents .
  872. The server still may send
  873. .PN MotionNotify
  874. events without is_hint set to
  875. .PN NotifyHint .
  876. .LP
  877. The source of the event is the viewable window that the pointer is in.
  878. The window used by the X server to report these events depends on 
  879. the window's position in the window hierarchy 
  880. and whether any intervening window prohibits the generation of these events.
  881. Starting with the source window, 
  882. the X server searches up the window hierarchy until it locates the first 
  883. window specified by a client as having an interest in these events.
  884. If one of the intervening windows has its do-not-propagate-mask
  885. set to prohibit generation of the event type,
  886. the events of those types will be suppressed.
  887. Clients can modify the actual window used for reporting by performing
  888. active grabs and, in the case of keyboard events, by using the focus window.
  889. .LP
  890. The structures for these event types contain:
  891. .LP
  892. .IN "XButtonEvent" "" "@DEF@"
  893. .IN "XButtonPressedEvent" "" "@DEF@"
  894. .IN "XButtonReleasedEvent" "" "@DEF@"
  895. .\" Start marker code here
  896. .Ds 0
  897. .TA .5i 3i
  898. .ta .5i 3i
  899. typedef struct {
  900.     int type;    /* ButtonPress or ButtonRelease */
  901.     unsigned long serial;    /* # of last request processed by server */
  902.     Bool send_event;    /* true if this came from a SendEvent request */
  903.     Display *display;    /* Display the event was read from */
  904.     Window window;    /* ``event'' window it is reported relative to */
  905.     Window root;    /* root window that the event occurred on */
  906.     Window subwindow;    /* child window */
  907.     Time time;    /* milliseconds */
  908.     int x, y;    /* pointer x, y coordinates in event window */
  909.     int x_root, y_root;    /* coordinates relative to root */
  910.     unsigned int state;    /* key or button mask */
  911.     unsigned int button;    /* detail */
  912.     Bool same_screen;    /* same screen flag */
  913. } XButtonEvent;
  914. typedef XButtonEvent XButtonPressedEvent;
  915. typedef XButtonEvent XButtonReleasedEvent;
  916. .De
  917. .LP
  918. .IN "XKeyEvent" "" "@DEF@"
  919. .IN "XKeyPressedEvent" "" "@DEF@"
  920. .IN "XKeyReleasedEvent" "" "@DEF@"
  921. .Ds 0
  922. .TA .5i 3i
  923. .ta .5i 3i
  924. typedef struct {
  925.     int type;    /* KeyPress or KeyRelease */
  926.     unsigned long serial;    /* # of last request processed by server */
  927.     Bool send_event;    /* true if this came from a SendEvent request */
  928.     Display *display;    /* Display the event was read from */
  929.     Window window;    /* ``event'' window it is reported relative to */
  930.     Window root;    /* root window that the event occurred on */
  931.     Window subwindow;    /* child window */
  932.     Time time;    /* milliseconds */
  933.     int x, y;    /* pointer x, y coordinates in event window */
  934.     int x_root, y_root;    /* coordinates relative to root */
  935.     unsigned int state;    /* key or button mask */
  936.     unsigned int keycode;    /* detail */
  937.     Bool same_screen;    /* same screen flag */
  938. } XKeyEvent;
  939. typedef XKeyEvent XKeyPressedEvent;
  940. typedef XKeyEvent XKeyReleasedEvent;
  941. .De
  942. .LP
  943. .IN "XMotionEvent" "" "@DEF@"
  944. .IN "XPointerMovedEvent" "" "@DEF@"
  945. .Ds 0
  946. .TA .5i 3i
  947. .ta .5i 3i
  948. typedef struct {
  949.     int type;    /* MotionNotify */
  950.     unsigned long serial;    /* # of last request processed by server */
  951.     Bool send_event;    /* true if this came from a SendEvent request */
  952.     Display *display;    /* Display the event was read from */
  953.     Window window;    /* ``event'' window reported relative to */
  954.     Window root;    /* root window that the event occurred on */
  955.     Window subwindow;    /* child window */
  956.     Time time;    /* milliseconds */
  957.     int x, y;    /* pointer x, y coordinates in event window */
  958.     int x_root, y_root;    /* coordinates relative to root */
  959.     unsigned int state;    /* key or button mask */
  960.     char is_hint;    /* detail */
  961.     Bool same_screen;    /* same screen flag */
  962. } XMotionEvent;
  963. typedef XMotionEvent XPointerMovedEvent;
  964. .De
  965. .\" End marker code here
  966. .LP
  967. These structures have the following common members:
  968. window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.
  969. The window member is set to the window on which the
  970. event was generated and is referred to as the event window. 
  971. As long as the conditions previously discussed are met,
  972. this is the window used by the X server to report the event.
  973. The root member is set to the source window's root window.
  974. The x_root and y_root members are set to the pointer's coordinates
  975. relative to the root window's origin at the time of the event.
  976. .LP
  977. The same_screen member is set to indicate whether the event 
  978. window is on the same screen
  979. as the root window and can be either
  980. .PN True 
  981. or
  982. .PN False .
  983. If
  984. .PN True ,
  985. the event and root windows are on the same screen.
  986. If
  987. .PN False ,
  988. the event and root windows are not on the same screen.
  989. .LP
  990. If the source window is an inferior of the event window, 
  991. the subwindow member of the structure is set to the child of the event window
  992. that is the source window or the child of the event window that is
  993. an ancestor of the source window.
  994. Otherwise, the X server sets the subwindow member to
  995. .PN None .
  996. The time member is set to the time when the event was generated 
  997. and is expressed in milliseconds.
  998. .LP
  999. If the event window is on the same screen as the root window, 
  1000. the x and y members
  1001. are set to the coordinates relative to the event window's origin.
  1002. Otherwise, these members are set to zero.
  1003. .LP
  1004. The state member is set to indicate the logical state of the pointer buttons 
  1005. and modifier keys just prior to the event,
  1006. which is the bitwise inclusive OR of one or more of the
  1007. button or modifier key masks:
  1008. .PN Button1Mask ,
  1009. .PN Button2Mask ,
  1010. .PN Button3Mask ,
  1011. .PN Button4Mask ,
  1012. .PN Button5Mask ,
  1013. .PN ShiftMask ,
  1014. .PN LockMask ,
  1015. .PN ControlMask ,
  1016. .PN Mod1Mask ,
  1017. .PN Mod2Mask ,
  1018. .PN Mod3Mask ,
  1019. .PN Mod4Mask ,
  1020. and
  1021. .PN Mod5Mask .
  1022. .LP
  1023. Each of these structures also has a member that indicates the detail.
  1024. For the
  1025. .PN XKeyPressedEvent
  1026. and
  1027. .PN XKeyReleasedEvent
  1028. structures, this member is called keycode.
  1029. It is set to a number that represents a physical key on the keyboard.
  1030. The keycode is an arbitrary representation for any key on the keyboard
  1031. (see sections 12.7 and 16.1).
  1032. .LP
  1033. For the
  1034. .PN XButtonPressedEvent
  1035. and
  1036. .PN XButtonReleasedEvent
  1037. structures, this member is called button.
  1038. It represents the pointer button that changed state and can be the
  1039. .PN Button1 ,
  1040. .PN Button2 ,
  1041. .PN Button3 ,
  1042. .PN Button4 ,
  1043. or
  1044. .PN Button5 
  1045. value.
  1046. For the
  1047. .PN XPointerMovedEvent
  1048. structure, this member is called is_hint.
  1049. It can be set to 
  1050. .PN NotifyNormal
  1051. or
  1052. .PN NotifyHint .
  1053. .NH 2
  1054. Window Entry/Exit Events
  1055. .XS
  1056. \*(SN Window Entry/Exit Events
  1057. .XE
  1058. .LP
  1059. .IN "Events" "EnterNotify"
  1060. .IN "Events" "LeaveNotify"
  1061. This section describes the processing that 
  1062. occurs for the window crossing events
  1063. .PN EnterNotify
  1064. and
  1065. .PN LeaveNotify .
  1066. .IN "EnterNotify" "" "@DEF@"
  1067. .IN "LeaveNotify" "" "@DEF@"
  1068. If a pointer motion or a window hierarchy change causes the
  1069. pointer to be in a different window than before, the X server reports
  1070. .PN EnterNotify
  1071. or
  1072. .PN LeaveNotify
  1073. events to clients who have selected for these events.
  1074. All 
  1075. .PN EnterNotify
  1076. and 
  1077. .PN LeaveNotify
  1078. events caused by a hierarchy change are
  1079. generated after any hierarchy event
  1080. .Pn ( UnmapNotify ,
  1081. .PN MapNotify ,
  1082. .PN ConfigureNotify ,
  1083. .PN GravityNotify ,
  1084. .PN CirculateNotify )
  1085. caused by that change;
  1086. however, the X protocol does not constrain the ordering of 
  1087. .PN EnterNotify 
  1088. and 
  1089. .PN LeaveNotify 
  1090. events with respect to
  1091. .PN FocusOut , 
  1092. .PN VisibilityNotify ,
  1093. and 
  1094. .PN Expose 
  1095. events.
  1096. .LP
  1097. This contrasts with
  1098. .PN MotionNotify
  1099. events, which are also generated when the pointer moves
  1100. but only when the pointer motion begins and ends in a single window.
  1101. An
  1102. .PN EnterNotify
  1103. or
  1104. .PN LeaveNotify
  1105. event also can be generated when some client application calls
  1106. .PN XGrabPointer
  1107. and
  1108. .PN XUngrabPointer .
  1109. .LP
  1110. To receive
  1111. .PN EnterNotify
  1112. or
  1113. .PN LeaveNotify
  1114. events, set the
  1115. .PN EnterWindowMask
  1116. or
  1117. .PN LeaveWindowMask
  1118. bits of the event-mask attribute of the window.
  1119. .LP
  1120. The structure for these event types contains:
  1121. .LP
  1122. .IN "XCrossingEvent" "" "@DEF@"
  1123. .IN "XEnterWindowEvent" "" "@DEF@"
  1124. .IN "XLeaveWindowEvent" "" "@DEF@"
  1125. .\" Start marker code here
  1126. .Ds 0
  1127. .TA .5i 3i
  1128. .ta .5i 3i
  1129. typedef struct {
  1130.     int type;    /* EnterNotify or LeaveNotify */
  1131.     unsigned long serial;    /* # of last request processed by server */
  1132.     Bool send_event;    /* true if this came from a SendEvent request */
  1133.     Display *display;    /* Display the event was read from */
  1134.     Window window;    /* ``event'' window reported relative to */
  1135.     Window root;    /* root window that the event occurred on */
  1136.     Window subwindow;    /* child window */
  1137.     Time time;    /* milliseconds */
  1138.     int x, y;    /* pointer x, y coordinates in event window */
  1139.     int x_root, y_root;    /* coordinates relative to root */
  1140.     int mode;    /* NotifyNormal, NotifyGrab, NotifyUngrab */
  1141.     int detail;
  1142.         /*
  1143.          * NotifyAncestor, NotifyVirtual, NotifyInferior, 
  1144.          * NotifyNonlinear,NotifyNonlinearVirtual
  1145.          */
  1146.     Bool same_screen;    /* same screen flag */
  1147.     Bool focus;    /* boolean focus */
  1148.     unsigned int state;    /* key or button mask */
  1149. } XCrossingEvent;
  1150. typedef XCrossingEvent XEnterWindowEvent;
  1151. typedef XCrossingEvent XLeaveWindowEvent;
  1152. .De
  1153. .\" End marker code here
  1154. .LP
  1155. The window member is set to the window on which the
  1156. .PN EnterNotify
  1157. or
  1158. .PN LeaveNotify
  1159. event was generated and is referred to as the event window. 
  1160. This is the window used by the X server to report the event, 
  1161. and is relative to the root
  1162. window on which the event occurred. 
  1163. The root member is set to the root window of the screen
  1164. on which the event occurred.
  1165. .LP
  1166. For a
  1167. .PN LeaveNotify 
  1168. event,
  1169. if a child of the event window contains the initial position of the pointer,
  1170. the subwindow component is set to that child.
  1171. Otherwise, the X server sets the subwindow member to
  1172. .PN None .
  1173. For an
  1174. .PN EnterNotify 
  1175. event, if a child of the event window contains the final pointer position, 
  1176. the subwindow component is set to that child or
  1177. .PN None .
  1178. .LP
  1179. The time member is set to the time when the event was generated
  1180. and is expressed in milliseconds.
  1181. The x and y members are set to the coordinates of the pointer position in 
  1182. the event window.
  1183. This position is always the pointer's final position,
  1184. not its initial position.
  1185. If the event window is on the same
  1186. screen as the root window, x and y are the pointer coordinates
  1187. relative to the event window's origin. 
  1188. Otherwise, x and y are set to zero.
  1189. The x_root and y_root members are set to the pointer's coordinates relative to the
  1190. root window's origin at the time of the event.
  1191. .LP
  1192. The same_screen member is set to indicate whether the event window is on the same screen
  1193. as the root window and can be either
  1194. .PN True 
  1195. or
  1196. .PN False .
  1197. If
  1198. .PN True ,
  1199. the event and root windows are on the same screen.
  1200. If
  1201. .PN False ,
  1202. the event and root windows are not on the same screen.
  1203. .LP
  1204. The focus member is set to indicate whether the event window is the focus window or an
  1205. inferior of the focus window.
  1206. The X server can set this member to either
  1207. .PN True 
  1208. or
  1209. .PN False .
  1210. If
  1211. .PN True ,
  1212. the event window is the focus window or an inferior of the focus window.
  1213. If
  1214. .PN False ,
  1215. the event window is not the focus window or an inferior of the focus window.
  1216. .LP
  1217. The state member is set to indicate the state of the pointer buttons and
  1218. modifier keys just prior to the
  1219. event.
  1220. The X server can set this member to the bitwise inclusive OR of one 
  1221. or more of the button or modifier key masks:
  1222. .PN Button1Mask ,
  1223. .PN Button2Mask ,
  1224. .PN Button3Mask ,
  1225. .PN Button4Mask ,
  1226. .PN Button5Mask ,
  1227. .PN ShiftMask ,
  1228. .PN LockMask ,
  1229. .PN ControlMask ,
  1230. .PN Mod1Mask ,
  1231. .PN Mod2Mask ,
  1232. .PN Mod3Mask ,
  1233. .PN Mod4Mask ,
  1234. .PN Mod5Mask .
  1235. .LP
  1236. The mode member is set to indicate whether the events are normal events, 
  1237. pseudo-motion events
  1238. when a grab activates, or pseudo-motion events when a grab deactivates.
  1239. The X server can set this member to 
  1240. .PN NotifyNormal ,
  1241. .PN NotifyGrab ,
  1242. or
  1243. .PN NotifyUngrab .
  1244. .LP
  1245. The detail member is set to indicate the notify detail and can be
  1246. .PN NotifyAncestor ,
  1247. .PN NotifyVirtual ,
  1248. .PN NotifyInferior ,
  1249. .PN NotifyNonlinear ,
  1250. or
  1251. .PN NotifyNonlinearVirtual .
  1252. .NH 3 
  1253. Normal Entry/Exit Events
  1254. .XS
  1255. \*(SN Normal Entry/Exit Events
  1256. .XE
  1257. .LP
  1258. .PN EnterNotify
  1259. and
  1260. .PN LeaveNotify
  1261. events are generated when the pointer moves from
  1262. one window to another window.
  1263. Normal events are identified by
  1264. .PN XEnterWindowEvent
  1265. or
  1266. .PN XLeaveWindowEvent
  1267. structures whose mode member is set to
  1268. .PN NotifyNormal .
  1269. .IP \(bu 5
  1270. When the pointer moves from window A to window B and A is an inferior of B, 
  1271. the X server does the following:
  1272. .RS
  1273. .IP \- 5
  1274. It generates a
  1275. .PN LeaveNotify
  1276. event on window A, with the detail member of the
  1277. .PN XLeaveWindowEvent
  1278. structure set to
  1279. .PN NotifyAncestor .
  1280. .IP \- 5
  1281. It generates a
  1282. .PN LeaveNotify
  1283. event on each window between window A and window B, exclusive,
  1284. with the detail member of each
  1285. .PN XLeaveWindowEvent
  1286. structure set to
  1287. .PN NotifyVirtual .
  1288. .IP \- 5
  1289. It generates an
  1290. .PN EnterNotify
  1291. event on window B, with the detail member of the 
  1292. .PN XEnterWindowEvent
  1293. structure set to
  1294. .PN NotifyInferior .
  1295. .RE
  1296. .IP \(bu 5
  1297. When the pointer moves from window A to window B and B is an inferior of A,
  1298. the X server does the following:
  1299. .RS
  1300. .IP \- 5
  1301. It generates a
  1302. .PN LeaveNotify
  1303. event on window A,
  1304. with the detail member of the
  1305. .PN XLeaveWindowEvent
  1306. structure set to
  1307. .PN NotifyInferior .
  1308. .IP \- 5
  1309. It generates an
  1310. .PN EnterNotify
  1311. event on each window between window A and window B, exclusive, with the 
  1312. detail member of each 
  1313. .PN XEnterWindowEvent
  1314. structure set to
  1315. .PN NotifyVirtual . 
  1316. .IP \- 5
  1317. It generates an
  1318. .PN EnterNotify
  1319. event on window B, with the detail member of the 
  1320. .PN XEnterWindowEvent
  1321. structure set to
  1322. .PN NotifyAncestor .
  1323. .RE
  1324. .IP \(bu 5
  1325. When the pointer moves from window A to window B 
  1326. and window C is their least common ancestor, 
  1327. the X server does the following:
  1328. .RS
  1329. .IP \- 5
  1330. It generates a
  1331. .PN LeaveNotify
  1332. event on window A,
  1333. with the detail member of the
  1334. .PN XLeaveWindowEvent
  1335. structure set to 
  1336. .PN NotifyNonlinear .
  1337. .IP \- 5
  1338. It generates a
  1339. .PN LeaveNotify
  1340. event on each window between window A and window C, exclusive,
  1341. with the detail member of each
  1342. .PN XLeaveWindowEvent
  1343. structure set to
  1344. .PN NotifyNonlinearVirtual .
  1345. .IP \- 5
  1346. It generates an
  1347. .PN EnterNotify
  1348. event on each window between window C and window B, exclusive, 
  1349. with the detail member of each
  1350. .PN XEnterWindowEvent
  1351. structure set to
  1352. .PN NotifyNonlinearVirtual .
  1353. .IP \- 5
  1354. It generates an
  1355. .PN EnterNotify
  1356. event on window B, with the detail member of the 
  1357. .PN XEnterWindowEvent
  1358. structure set to 
  1359. .PN NotifyNonlinear .
  1360. .RE
  1361. .IP \(bu 5
  1362. When the pointer moves from window A to window B on different screens, 
  1363. the X server does the following:
  1364. .RS
  1365. .IP \- 5
  1366. It generates a
  1367. .PN LeaveNotify
  1368. event on window A,
  1369. with the detail member of the
  1370. .PN XLeaveWindowEvent
  1371. structure set to 
  1372. .PN NotifyNonlinear .
  1373. .IP \- 5
  1374. If window A is not a root window,
  1375. it generates a
  1376. .PN LeaveNotify
  1377. event on each window above window A up to and including its root,
  1378. with the detail member of each
  1379. .PN XLeaveWindowEvent
  1380. structure set to 
  1381. .PN NotifyNonlinearVirtual .
  1382. .IP \- 5
  1383. If window B is not a root window,
  1384. it generates an
  1385. .PN EnterNotify
  1386. event on each window from window B's root down to but not including
  1387. window B, with the detail member of each
  1388. .PN XEnterWindowEvent
  1389. structure set to 
  1390. .PN NotifyNonlinearVirtual .
  1391. .IP \- 5
  1392. It generates an
  1393. .PN EnterNotify
  1394. event on window B, with the detail member of the
  1395. .PN XEnterWindowEvent
  1396. structure set to 
  1397. .PN NotifyNonlinear .
  1398. .RE
  1399. .\".SH 3
  1400. .NH 3 
  1401. Grab and Ungrab Entry/Exit Events
  1402. .XS
  1403. \*(SN Grab and Ungrab Entry/Exit Events
  1404. .XE
  1405. .LP
  1406. Pseudo-motion mode
  1407. .PN EnterNotify
  1408. and
  1409. .PN LeaveNotify
  1410. events are generated when a pointer grab activates or deactivates.
  1411. Events in which the pointer grab activates
  1412. are identified by
  1413. .PN XEnterWindowEvent
  1414. or
  1415. .PN XLeaveWindowEvent
  1416. structures whose mode member is set to 
  1417. .PN NotifyGrab .
  1418. Events in which the pointer grab deactivates
  1419. are identified by
  1420. .PN XEnterWindowEvent
  1421. or
  1422. .PN XLeaveWindowEvent
  1423. structures whose mode member is set to 
  1424. .PN NotifyUngrab
  1425. (see
  1426. .PN XGrabPointer ).
  1427. .IP \(bu 5
  1428. When a pointer grab activates after any initial warp into a confine_to
  1429. window and before generating any actual
  1430. .PN ButtonPress
  1431. event that activates the grab, 
  1432. G is the grab_window for the grab, 
  1433. and P is the window the pointer is in, 
  1434. the X server does the following:
  1435. .RS
  1436. .IP \- 5
  1437. It generates
  1438. .PN EnterNotify
  1439. and
  1440. .PN LeaveNotify
  1441. events (see section 10.6.1)
  1442. with the mode members of the 
  1443. .PN XEnterWindowEvent
  1444. and
  1445. .PN XLeaveWindowEvent
  1446. structures set to 
  1447. .PN NotifyGrab .
  1448. These events are generated
  1449. as if the pointer were to suddenly warp from
  1450. its current position in P to some position in G.
  1451. However, the pointer does not warp, and the X server uses the pointer position 
  1452. as both the initial and final positions for the events.
  1453. .RE
  1454. .IP \(bu 5
  1455. When a pointer grab deactivates after generating any actual
  1456. .PN ButtonRelease
  1457. event that deactivates the grab, 
  1458. G is the grab_window for the grab,
  1459. and P is the window the pointer is in, 
  1460. the X server does the following:
  1461. .RS
  1462. .IP \- 5
  1463. It generates
  1464. .PN EnterNotify
  1465. and
  1466. .PN LeaveNotify
  1467. events (see section 10.6.1)
  1468. with the mode members of the
  1469. .PN XEnterWindowEvent
  1470. and
  1471. .PN XLeaveWindowEvent
  1472. structures set to 
  1473. .PN NotifyUngrab .
  1474. These events are generated as if the pointer were to suddenly warp from
  1475. some position in G to its current position in P.
  1476. However, the pointer does not warp, and the X server uses the
  1477. current pointer position as both the
  1478. initial and final positions for the events.
  1479. .RE
  1480. .NH 2
  1481. Input Focus Events
  1482. .XS
  1483. \*(SN Input Focus Events 
  1484. .XE
  1485. .LP
  1486. .IN "Events" "FocusIn"
  1487. .IN "Events" "FocusOut"
  1488. This section describes the processing that occurs for the input focus events
  1489. .PN FocusIn
  1490. and
  1491. .PN FocusOut .
  1492. .IN "FocusIn" "" "@DEF@"
  1493. .IN "FocusOut" "" "@DEF@"
  1494. The X server can report
  1495. .PN FocusIn
  1496. or
  1497. .PN FocusOut
  1498. events to clients wanting information about when the input focus changes.
  1499. The keyboard is always attached to some window 
  1500. (typically, the root window or a top-level window), 
  1501. which is called the focus window.
  1502. The focus window and the position of the pointer determine the window that
  1503. receives keyboard input.
  1504. Clients may need to know when the input focus changes
  1505. to control highlighting of areas on the screen.
  1506. .LP
  1507. To receive
  1508. .PN FocusIn
  1509. or
  1510. .PN FocusOut
  1511. events, set the
  1512. .PN FocusChangeMask
  1513. bit in the event-mask attribute of the window. 
  1514. .LP
  1515. The structure for these event types contains:
  1516. .LP
  1517. .IN "XFocusChangeEvent" "" "@DEF@"
  1518. .IN "XFocusInEvent" "" "@DEF@"
  1519. .IN "XFocusOutEvent" "" "@DEF@"
  1520. .\" Start marker code here
  1521. .Ds 0
  1522. .TA .5i 3i
  1523. .ta .5i 3i
  1524. typedef struct {
  1525.     int type;    /* FocusIn or FocusOut */
  1526.     unsigned long serial;    /* # of last request processed by server */
  1527.     Bool send_event;    /* true if this came from a SendEvent request */
  1528.     Display *display;    /* Display the event was read from */
  1529.     Window window;    /* window of event */
  1530.     int mode;    /* NotifyNormal, NotifyGrab, NotifyUngrab */
  1531.     int detail;
  1532.         /*
  1533.          * NotifyAncestor, NotifyVirtual, NotifyInferior, 
  1534.          * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
  1535.          * NotifyPointerRoot, NotifyDetailNone 
  1536.          */
  1537. } XFocusChangeEvent;
  1538. typedef XFocusChangeEvent XFocusInEvent;
  1539. typedef XFocusChangeEvent XFocusOutEvent;
  1540. .De
  1541. .\" End marker code here
  1542. .LP
  1543. The window member is set to the window on which the
  1544. .PN FocusIn
  1545. or
  1546. .PN FocusOut
  1547. event was generated.
  1548. This is the window used by the X server to report the event. 
  1549. The mode member is set to indicate whether the focus events 
  1550. are normal focus events, 
  1551. focus events while grabbed,
  1552. focus events
  1553. when a grab activates, or focus events when a grab deactivates.
  1554. The X server can set the mode member to 
  1555. .PN NotifyNormal ,
  1556. .PN NotifyWhileGrabbed ,
  1557. .PN NotifyGrab ,
  1558. or
  1559. .PN NotifyUngrab .
  1560. .LP
  1561. All 
  1562. .PN FocusOut
  1563. events caused by a window unmap are generated after any
  1564. .PN UnmapNotify
  1565. event; however, the X protocol does not constrain the ordering of 
  1566. .PN FocusOut
  1567. events with respect to
  1568. generated 
  1569. .PN EnterNotify ,
  1570. .PN LeaveNotify ,
  1571. .PN VisibilityNotify ,
  1572. and
  1573. .PN Expose
  1574. events.
  1575. .LP
  1576. Depending on the event mode,
  1577. the detail member is set to indicate the notify detail and can be
  1578. .PN NotifyAncestor ,
  1579. .PN NotifyVirtual ,
  1580. .PN NotifyInferior ,
  1581. .PN NotifyNonlinear ,
  1582. .PN NotifyNonlinearVirtual ,
  1583. .PN NotifyPointer ,
  1584. .PN NotifyPointerRoot ,
  1585. or
  1586. .PN NotifyDetailNone .
  1587. .NH 3 
  1588. Normal Focus Events and Focus Events While Grabbed 
  1589. .XS
  1590. \*(SN Normal Focus Events and Focus Events While Grabbed 
  1591. .XE
  1592. .LP
  1593. Normal focus events are identified by
  1594. .PN XFocusInEvent
  1595. or
  1596. .PN XFocusOutEvent
  1597. structures whose mode member is set to 
  1598. .PN NotifyNormal .
  1599. Focus events while grabbed are identified by
  1600. .PN XFocusInEvent
  1601. or
  1602. .PN XFocusOutEvent
  1603. structures whose mode member is set to 
  1604. .PN NotifyWhileGrabbed .
  1605. The X server processes normal focus and focus events while grabbed according to 
  1606. the following:
  1607. .IP \(bu 5
  1608. When the focus moves from window A to window B, A is an inferior of B, 
  1609. and the pointer is in window P, 
  1610. the X server does the following:
  1611. .RS
  1612. .IP \- 5
  1613. It generates a
  1614. .PN FocusOut
  1615. event on window A, with the detail member of the
  1616. .PN XFocusOutEvent
  1617. structure set to 
  1618. .PN NotifyAncestor . 
  1619. .IP \- 5
  1620. It generates a
  1621. .PN FocusOut
  1622. event on each window between window A and window B, exclusive,
  1623. with the detail member of each
  1624. .PN XFocusOutEvent
  1625. structure set to 
  1626. .PN NotifyVirtual .
  1627. .IP \- 5
  1628. It generates a
  1629. .PN FocusIn
  1630. event on window B, with the detail member of the 
  1631. .PN XFocusOutEvent
  1632. structure set to 
  1633. .PN NotifyInferior .
  1634. .IP \- 5
  1635. If window P is an inferior of window B
  1636. but window P is not window A or an inferior or ancestor of window A,
  1637. it generates a
  1638. .PN FocusIn
  1639. event on each window below window B, down to and including window P, 
  1640. with the detail member of each 
  1641. .PN XFocusInEvent
  1642. structure set to 
  1643. .PN NotifyPointer .
  1644. .RE
  1645. .IP \(bu 5
  1646. When the focus moves from window A to window B, B is an inferior of A, 
  1647. and the pointer is in window P, 
  1648. the X server does the following:
  1649. .RS
  1650. .IP \- 5
  1651. If window P is an inferior of window A
  1652. but P is not an inferior of window B or an ancestor of B,
  1653. it generates a
  1654. .PN FocusOut
  1655. event on each window from window P up to but not including window A,
  1656. with the detail member of each 
  1657. .PN XFocusOutEvent
  1658. structure set to  
  1659. .PN NotifyPointer .
  1660. .IP \- 5
  1661. It generates a
  1662. .PN FocusOut
  1663. event on window A,
  1664. with the detail member of the
  1665. .PN XFocusOutEvent
  1666. structure set to  
  1667. .PN NotifyInferior . 
  1668. .IP \- 5
  1669. It generates a
  1670. .PN FocusIn
  1671. event on each window between window A and window B, exclusive, with the 
  1672. detail member of each 
  1673. .PN XFocusInEvent
  1674. structure set to  
  1675. .PN NotifyVirtual . 
  1676. .IP \- 5
  1677. It generates a
  1678. .PN FocusIn
  1679. event on window B, with the detail member of the 
  1680. .PN XFocusInEvent
  1681. structure set to  
  1682. .PN NotifyAncestor .
  1683. .RE
  1684. .IP \(bu 5
  1685. When the focus moves from window A to window B, 
  1686. window C is their least common ancestor, 
  1687. and the pointer is in window P, 
  1688. the X server does the following:
  1689. .RS
  1690. .IP \- 5
  1691. If window P is an inferior of window A,
  1692. it generates a
  1693. .PN FocusOut
  1694. event on each window from window P up to but not including window A, 
  1695. with the detail member of the 
  1696. .PN XFocusOutEvent
  1697. structure set to  
  1698. .PN NotifyPointer .
  1699. .IP \- 5
  1700. It generates a
  1701. .PN FocusOut
  1702. event on window A,
  1703. with the detail member of the
  1704. .PN XFocusOutEvent
  1705. structure set to  
  1706. .PN NotifyNonlinear .
  1707. .IP \- 5
  1708. It generates a
  1709. .PN FocusOut
  1710. event on each window between window A and window C, exclusive,
  1711. with the detail member of each
  1712. .PN XFocusOutEvent
  1713. structure set to  
  1714. .PN NotifyNonlinearVirtual .
  1715. .IP \- 5
  1716. It generates a
  1717. .PN FocusIn
  1718. event on each window between C and B, exclusive,
  1719. with the detail member of each
  1720. .PN XFocusInEvent
  1721. structure set to  
  1722. .PN NotifyNonlinearVirtual .
  1723. .IP \- 5
  1724. It generates a
  1725. .PN FocusIn
  1726. event on window B, with the detail member of the 
  1727. .PN XFocusInEvent
  1728. structure set to  
  1729. .PN NotifyNonlinear .
  1730. .IP \- 5
  1731. If window P is an inferior of window B, it generates a
  1732. .PN FocusIn
  1733. event on each window below window B down to and including window P, 
  1734. with the detail member of the 
  1735. .PN XFocusInEvent
  1736. structure set to  
  1737. .PN NotifyPointer .
  1738. .RE
  1739. .IP \(bu 5
  1740. When the focus moves from window A to window B on different screens 
  1741. and the pointer is in window P, 
  1742. the X server does the following:
  1743. .RS
  1744. .IP \- 5
  1745. If window P is an inferior of window A, it generates a
  1746. .PN FocusOut
  1747. event on each window from window P up to but not including window A, 
  1748. with the detail member of each 
  1749. .PN XFocusOutEvent
  1750. structure set to  
  1751. .PN NotifyPointer .
  1752. .IP \- 5
  1753. It generates a
  1754. .PN FocusOut
  1755. event on window A,
  1756. with the detail member of the
  1757. .PN XFocusOutEvent
  1758. structure set to  
  1759. .PN NotifyNonlinear .
  1760. .IP \- 5
  1761. If window A is not a root window,
  1762. it generates a
  1763. .PN FocusOut
  1764. event on each window above window A up to and including its root, 
  1765. with the detail member of each
  1766. .PN XFocusOutEvent
  1767. structure set to  
  1768. .PN NotifyNonlinearVirtual .
  1769. .IP \- 5
  1770. If window B is not a root window,
  1771. it generates a
  1772. .PN FocusIn
  1773. event on each window from window B's root down to but not including
  1774. window B, with the detail member of each
  1775. .PN XFocusInEvent
  1776. structure set to  
  1777. .PN NotifyNonlinearVirtual .
  1778. .IP \- 5
  1779. It generates a
  1780. .PN FocusIn
  1781. event on window B, with the detail member of each 
  1782. .PN XFocusInEvent
  1783. structure set to  
  1784. .PN NotifyNonlinear .
  1785. .IP \- 5
  1786. If window P is an inferior of window B, it generates a
  1787. .PN FocusIn
  1788. event on each window below window B down to and including window P, 
  1789. with the detail member of each 
  1790. .PN XFocusInEvent
  1791. structure set to  
  1792. .PN NotifyPointer .
  1793. .RE
  1794. .IP \(bu 5
  1795. When the focus moves from window A to 
  1796. .PN PointerRoot
  1797. (events sent to the window under the pointer)
  1798. or
  1799. .PN None 
  1800. (discard), and the pointer is in window P,
  1801. the X server does the following:
  1802. .RS
  1803. .IP \- 5
  1804. If window P is an inferior of window A, it generates a
  1805. .PN FocusOut
  1806. event on each window from window P up to but not including window A, 
  1807. with the detail member of each 
  1808. .PN XFocusOutEvent
  1809. structure set to  
  1810. .PN NotifyPointer .
  1811. .IP \- 5
  1812. It generates a
  1813. .PN FocusOut
  1814. event on window A, with the detail member of the
  1815. .PN XFocusOutEvent
  1816. structure set to
  1817. .PN NotifyNonlinear .
  1818. .IP \- 5
  1819. If window A is not a root window,
  1820. it generates a
  1821. .PN FocusOut
  1822. event on each window above window A up to and including its root, 
  1823. with the detail member of each
  1824. .PN XFocusOutEvent
  1825. structure set to
  1826. .PN NotifyNonlinearVirtual .
  1827. .IP \- 5
  1828. It generates a
  1829. .PN FocusIn
  1830. event on the root window of all screens, with the detail member of each
  1831. .PN XFocusInEvent
  1832. structure set to
  1833. .PN NotifyPointerRoot
  1834. (or
  1835. .PN NotifyDetailNone ).
  1836. .IP \- 5
  1837. If the new focus is
  1838. .PN PointerRoot ,
  1839. it generates a
  1840. .PN FocusIn
  1841. event on each window from window P's root down to and including window P, 
  1842. with the detail member of each
  1843. .PN XFocusInEvent
  1844. structure set to
  1845. .PN NotifyPointer .
  1846. .RE
  1847. .IP \(bu 5
  1848. When the focus moves from 
  1849. .PN PointerRoot
  1850. (events sent to the window under the pointer)
  1851. or
  1852. .PN None 
  1853. to window A, and the pointer is in window P, 
  1854. the X server does the following: 
  1855. .RS
  1856. .IP \- 5
  1857. If the old focus is
  1858. .PN PointerRoot ,
  1859. it generates a
  1860. .PN FocusOut
  1861. event on each window from window P up to and including window P's root, 
  1862. with the detail member of each
  1863. .PN XFocusOutEvent
  1864. structure set to
  1865. .PN NotifyPointer .
  1866. .IP \- 5
  1867. It generates a
  1868. .PN FocusOut
  1869. event on all root windows,
  1870. with the detail member of each
  1871. .PN XFocusOutEvent
  1872. structure set to
  1873. .PN NotifyPointerRoot
  1874. (or
  1875. .PN NotifyDetailNone ).
  1876. .IP \- 5
  1877. If window A is not a root window,
  1878. it generates a
  1879. .PN FocusIn
  1880. event on each window from window A's root down to but not including window A,
  1881. with the detail member of each
  1882. .PN XFocusInEvent
  1883. structure set to
  1884. .PN NotifyNonlinearVirtual .
  1885. .IP \- 5
  1886. It generates a
  1887. .PN FocusIn
  1888. event on window A,
  1889. with the detail member of the 
  1890. .PN XFocusInEvent
  1891. structure set to  
  1892. .PN NotifyNonlinear .
  1893. .IP \- 5
  1894. If window P is an inferior of window A, it generates a
  1895. .PN FocusIn
  1896. event on each window below window A down to and including window P, 
  1897. with the detail member of each 
  1898. .PN XFocusInEvent
  1899. structure set to  
  1900. .PN NotifyPointer .
  1901. .RE
  1902. .IP \(bu 5
  1903. When the focus moves from 
  1904. .PN PointerRoot
  1905. (events sent to the window under the pointer)
  1906. to
  1907. .PN None
  1908. (or vice versa), and the pointer is in window P, 
  1909. the X server does the following:
  1910. .RS
  1911. .IP \- 5
  1912. If the old focus is
  1913. .PN PointerRoot ,
  1914. it generates a
  1915. .PN FocusOut
  1916. event on each window from window P up to and including window P's root, 
  1917. with the detail member of each
  1918. .PN XFocusOutEvent
  1919. structure set to
  1920. .PN NotifyPointer .
  1921. .IP \- 5
  1922. It generates a
  1923. .PN FocusOut
  1924. event on all root windows,
  1925. with the detail member of each 
  1926. .PN XFocusOutEvent
  1927. structure set to either
  1928. .PN NotifyPointerRoot
  1929. or
  1930. .PN NotifyDetailNone . 
  1931. .IP \- 5
  1932. It generates a
  1933. .PN FocusIn
  1934. event on all root windows,
  1935. with the detail member of each
  1936. .PN XFocusInEvent
  1937. structure set to
  1938. .PN NotifyDetailNone 
  1939. or
  1940. .PN NotifyPointerRoot .
  1941. .IP \- 5
  1942. If the new focus is
  1943. .PN PointerRoot ,
  1944. it generates a
  1945. .PN FocusIn
  1946. event on each window from window P's root down to and including window P, 
  1947. with the detail member of each
  1948. .PN XFocusInEvent
  1949. structure set to
  1950. .PN NotifyPointer .
  1951. .RE
  1952. .\".SH 3
  1953. .NH 3 
  1954. Focus Events Generated by Grabs
  1955. .XS
  1956. \*(SN Focus Events Generated by Grabs 
  1957. .XE
  1958. .LP
  1959. Focus events in which the keyboard grab activates
  1960. are identified by
  1961. .PN XFocusInEvent
  1962. or
  1963. .PN XFocusOutEvent
  1964. structures whose mode member is set to 
  1965. .PN NotifyGrab .
  1966. Focus events in which the keyboard grab deactivates
  1967. are identified by
  1968. .PN XFocusInEvent
  1969. or
  1970. .PN XFocusOutEvent
  1971. structures whose mode member is set to 
  1972. .PN NotifyUngrab 
  1973. (see 
  1974. .PN XGrabKeyboard ).
  1975. .IP \(bu 5
  1976. When a keyboard grab activates before generating any actual 
  1977. .PN KeyPress
  1978. event that activates the grab,
  1979. G is the grab_window, and F is the current focus, 
  1980. the X server does the following:
  1981. .RS
  1982. .IP \- 5
  1983. It generates 
  1984. .PN FocusIn
  1985. and
  1986. .PN FocusOut
  1987. events, with the mode members of the 
  1988. .PN XFocusInEvent
  1989. and
  1990. .PN XFocusOutEvent
  1991. structures set to 
  1992. .PN NotifyGrab .
  1993. These events are generated
  1994. as if the focus were to change from
  1995. F to G.
  1996. .RE
  1997. .IP \(bu 5
  1998. When a keyboard grab deactivates after generating any actual
  1999. .PN KeyRelease
  2000. event that deactivates the grab,
  2001. G is the grab_window, and F is the current focus,
  2002. the X server does the following:
  2003. .RS
  2004. .IP \- 5
  2005. It generates 
  2006. .PN FocusIn
  2007. and
  2008. .PN FocusOut
  2009. events, with the mode members of the 
  2010. .PN XFocusInEvent
  2011. and
  2012. .PN XFocusOutEvent
  2013. structures set to
  2014. .PN NotifyUngrab .
  2015. These events are generated
  2016. as if the focus were to change from
  2017. G to F.
  2018. .RE
  2019. .NH 2
  2020. Key Map State Notification Events
  2021. .XS
  2022. \*(SN Key Map State Notification Events
  2023. .XE
  2024. .LP
  2025. .IN "Events" "KeymapNotify"
  2026. .IN "KeymapNotify" "" "@DEF@"
  2027. The X server can report
  2028. .PN KeymapNotify
  2029. events to clients that want information about changes in their keyboard state.
  2030. .LP
  2031. To receive
  2032. .PN KeymapNotify
  2033. events, set the
  2034. .PN KeymapStateMask
  2035. bit in the event-mask attribute of the window. 
  2036. The X server generates this event immediately after every
  2037. .PN EnterNotify
  2038. and
  2039. .PN FocusIn
  2040. event.
  2041. .LP
  2042. The structure for this event type contains:
  2043. .LP
  2044. .IN "XKeymapEvent" "" "@DEF@"
  2045. .\" Start marker code here
  2046. .Ds 0
  2047. .TA .5i 3i
  2048. .ta .5i 3i
  2049. /* generated on EnterWindow and FocusIn when KeymapState selected */
  2050. typedef struct {
  2051.     int type;    /* KeymapNotify */
  2052.     unsigned long serial;    /* # of last request processed by server */
  2053.     Bool send_event;    /* true if this came from a SendEvent request */
  2054.     Display *display;    /* Display the event was read from */
  2055.     Window window;
  2056.     char key_vector[32];
  2057. } XKeymapEvent;    
  2058. .De
  2059. .\" End marker code here
  2060. .LP
  2061. The window member is not used but is present to aid some toolkits.
  2062. The key_vector member is set to the bit vector of the keyboard.
  2063. Each bit set to 1 indicates that the corresponding key 
  2064. is currently pressed.
  2065. The vector is represented as 32 bytes.
  2066. Byte N (from 0) contains the bits for keys 8N to 8N + 7 
  2067. with the least-significant bit in the byte representing key 8N.
  2068. .NH 2
  2069. Exposure Events
  2070. .XS
  2071. \*(SN Exposure Events
  2072. .XE
  2073. .LP
  2074. The X protocol does not guarantee to preserve the contents of window 
  2075. regions when
  2076. the windows are obscured or reconfigured.
  2077. Some implementations may preserve the contents of windows.
  2078. Other implementations are free to destroy the contents of windows
  2079. when exposed.
  2080. X expects client applications to assume the responsibility for
  2081. restoring the contents of an exposed window region. 
  2082. (An exposed window region describes a formerly obscured window whose 
  2083. region becomes visible.) 
  2084. Therefore, the X server sends 
  2085. .PN Expose 
  2086. events describing the window and the region of the window that has been exposed.
  2087. A naive client application usually redraws the entire window. 
  2088. A more sophisticated client application redraws only the exposed region.
  2089. .NH 3
  2090. Expose Events
  2091. .XS
  2092. \*(SN Expose Events
  2093. .XE
  2094. .LP
  2095. .IN "Events" "Expose"
  2096. .IN "Expose" "" "@DEF@"
  2097. The X server can report
  2098. .PN Expose
  2099. events to clients wanting information about when the contents of window regions
  2100. have been lost.
  2101. The circumstances in which the X server generates
  2102. .PN Expose
  2103. events are not as definite as those for other events.
  2104. However, the X server never generates
  2105. .PN Expose
  2106. events on windows whose class you specified as
  2107. .PN InputOnly .
  2108. The X server can generate
  2109. .PN Expose
  2110. events when no valid contents are available for regions of a window
  2111. and either the regions are visible, 
  2112. the regions are viewable and the server is (perhaps newly) maintaining 
  2113. backing store on the window,
  2114. or the window is not viewable but the server is (perhaps newly) honoring the
  2115. window's backing-store attribute of
  2116. .PN Always
  2117. or
  2118. .PN WhenMapped .
  2119. The regions decompose into an (arbitrary) set of rectangles,
  2120. and an
  2121. .PN Expose
  2122. event is generated for each rectangle.
  2123. For any given window,
  2124. the X server guarantees to report contiguously 
  2125. all of the regions exposed by some action that causes 
  2126. .PN Expose 
  2127. events, such as raising a window.
  2128. .LP
  2129. To receive
  2130. .PN Expose
  2131. events, set the
  2132. .PN ExposureMask
  2133. bit in the event-mask attribute of the window. 
  2134. .LP
  2135. The structure for this event type contains:
  2136. .LP
  2137. .IN "XExposeEvent" "" "@DEF@"
  2138. .\" Start marker code here
  2139. .Ds 0
  2140. .TA .5i 3i
  2141. .ta .5i 3i
  2142. typedef struct {
  2143.     int type;    /* Expose */
  2144.     unsigned long serial;    /* # of last request processed by server */
  2145.     Bool send_event;    /* true if this came from a SendEvent request */
  2146.     Display *display;    /* Display the event was read from */
  2147.     Window window;
  2148.     int x, y;
  2149.     int width, height;
  2150.     int count;    /* if nonzero, at least this many more */
  2151. } XExposeEvent;
  2152. .De
  2153. .\" End marker code here
  2154. .LP
  2155. The window member is set to the exposed (damaged) window.
  2156. The x and y members are set to the coordinates relative to the window's origin
  2157. and indicate the upper-left corner of the rectangle.
  2158. The width and height members are set to the size (extent) of the rectangle.
  2159. The count member is set to the number of
  2160. .PN Expose
  2161. events that are to follow.
  2162. If count is zero, no more
  2163. .PN Expose
  2164. events follow for this window.
  2165. However, if count is nonzero, at least that number of 
  2166. .PN Expose 
  2167. events (and possibly more) follow for this window.
  2168. Simple applications that do not want to optimize redisplay by distinguishing
  2169. between subareas of its window can just ignore all
  2170. .PN Expose
  2171. events with nonzero counts and perform full redisplays
  2172. on events with zero counts.
  2173. .NH 3
  2174. GraphicsExpose and NoExpose Events
  2175. .XS
  2176. \*(SN GraphicsExpose and NoExpose Events
  2177. .XE
  2178. .LP
  2179. .IN "Events" "GraphicsExpose"
  2180. .IN "Events" "NoExpose"
  2181. .IN "GraphicsExpose" "" "@DEF@"
  2182. The X server can report
  2183. .PN GraphicsExpose
  2184. events to clients wanting information about when a destination region could not
  2185. be computed during certain graphics requests:
  2186. .PN XCopyArea
  2187. or
  2188. .PN XCopyPlane .
  2189. The X server generates this event whenever a destination region could not be
  2190. computed due to an obscured or out-of-bounds source region.
  2191. In addition, the X server guarantees to report contiguously all of the regions exposed by
  2192. some graphics request 
  2193. (for example, copying an area of a drawable to a destination
  2194. drawable).
  2195. .LP
  2196. .IN "NoExpose" "" "@DEF@"
  2197. The X server generates a
  2198. .PN NoExpose
  2199. event whenever a graphics request that might
  2200. produce a
  2201. .PN GraphicsExpose
  2202. event does not produce any.
  2203. In other words, the client is really asking for a
  2204. .PN GraphicsExpose
  2205. event but instead receives a
  2206. .PN NoExpose
  2207. event.
  2208. .LP
  2209. To receive
  2210. .PN GraphicsExpose
  2211. or
  2212. .PN NoExpose
  2213. events, you must first set the graphics-exposure 
  2214. attribute of the graphics context to
  2215. .PN True .
  2216. You also can set the graphics-expose attribute when creating a graphics
  2217. context using
  2218. .PN XCreateGC 
  2219. or by calling
  2220. .PN XSetGraphicsExposures .
  2221. .LP
  2222. The structures for these event types contain:
  2223. .LP
  2224. .IN "XGraphicsExposeEvent" "" "@DEF@"
  2225. .\" Start marker code here
  2226. .Ds 0
  2227. .TA .5i 3i
  2228. .ta .5i 3i
  2229. typedef struct {
  2230.     int type;    /* GraphicsExpose */
  2231.     unsigned long serial;    /* # of last request processed by server */
  2232.     Bool send_event;    /* true if this came from a SendEvent request */
  2233.     Display *display;    /* Display the event was read from */
  2234.     Drawable drawable;
  2235.     int x, y;
  2236.     int width, height;
  2237.     int count;    /* if nonzero, at least this many more */
  2238.     int major_code;    /* core is CopyArea or CopyPlane */
  2239.     int minor_code;    /* not defined in the core */
  2240. } XGraphicsExposeEvent;
  2241. .De
  2242. .LP
  2243. .IN "XNoExposeEvent" "" "@DEF@"
  2244. .Ds 0
  2245. .TA .5i 3i
  2246. .ta .5i 3i
  2247. typedef struct {
  2248.     int type;    /* NoExpose */
  2249.     unsigned long serial;    /* # of last request processed by server */
  2250.     Bool send_event;    /* true if this came from a SendEvent request */
  2251.     Display *display;    /* Display the event was read from */
  2252.     Drawable drawable;
  2253.     int major_code;    /* core is CopyArea or CopyPlane */
  2254.     int minor_code;    /* not defined in the core */
  2255. } XNoExposeEvent;
  2256. .De
  2257. .\" End marker code here
  2258. .LP
  2259. Both structures have these common members: drawable, major_code, and minor_code.
  2260. The drawable member is set to the drawable of the destination region on 
  2261. which the graphics request was to be performed.
  2262. The major_code member is set to the graphics request initiated by the client
  2263. and can be either
  2264. .PN X_CopyArea
  2265. or
  2266. .PN X_CopyPlane .
  2267. If it is
  2268. .PN X_CopyArea ,
  2269. a call to
  2270. .PN XCopyArea
  2271. initiated the request.
  2272. If it is
  2273. .PN X_CopyPlane ,
  2274. a call to
  2275. .PN XCopyPlane
  2276. initiated the request.
  2277. These constants are defined in 
  2278. .Pn < X11/Xproto.h >.
  2279. The minor_code member,
  2280. like the major_code member, 
  2281. indicates which graphics request was initiated by
  2282. the client. 
  2283. However, the minor_code member is not defined by the core
  2284. X protocol and will be zero in these cases, 
  2285. although it may be used by an extension.
  2286. .LP
  2287. The 
  2288. .PN XGraphicsExposeEvent
  2289. structure has these additional members: x, y, width, height, and count. 
  2290. The x and y members are set to the coordinates relative to the drawable's origin
  2291. and indicate the upper-left corner of the rectangle.
  2292. The width and height members are set to the size (extent) of the rectangle.
  2293. The count member is set to the number of
  2294. .PN GraphicsExpose
  2295. events to follow.
  2296. If count is zero, no more
  2297. .PN GraphicsExpose
  2298. events follow for this window.
  2299. However, if count is nonzero, at least that number of
  2300. .PN GraphicsExpose
  2301. events (and possibly more) are to follow for this window.
  2302. .NH 2
  2303. Window State Change Events 
  2304. .XS
  2305. \*(SN Window State Change Events
  2306. .XE
  2307. .LP
  2308. The following sections discuss:
  2309. .IP \(bu 5
  2310. .PN CirculateNotify
  2311. events
  2312. .IP \(bu 5
  2313. .PN ConfigureNotify
  2314. events
  2315. .IP \(bu 5
  2316. .PN CreateNotify 
  2317. events
  2318. .IP \(bu 5
  2319. .PN DestroyNotify
  2320. events
  2321. .IP \(bu 5
  2322. .PN GravityNotify
  2323. events
  2324. .IP \(bu 5
  2325. .PN MapNotify
  2326. events
  2327. .IP \(bu 5
  2328. .PN MappingNotify
  2329. events
  2330. .IP \(bu 5
  2331. .PN ReparentNotify 
  2332. events
  2333. .IP \(bu 5
  2334. .PN UnmapNotify
  2335. events
  2336. .IP \(bu 5
  2337. .PN VisibilityNotify
  2338. events
  2339. .\" .SH 3
  2340. .NH 3
  2341. CirculateNotify Events
  2342. .XS
  2343. \*(SN CirculateNotify Events
  2344. .XE
  2345. .LP
  2346. .IN "Events" "CirculateNotify"
  2347. .IN "CirculateNotify" "" "@DEF@"
  2348. The X server can report
  2349. .PN CirculateNotify
  2350. events to clients wanting information about when a window changes 
  2351. its position in the stack.
  2352. The X server generates this event type whenever a window is actually restacked 
  2353. as a result of a client application calling
  2354. .PN XCirculateSubwindows ,
  2355. .PN XCirculateSubwindowsUp ,
  2356. or
  2357. .PN XCirculateSubwindowsDown .
  2358. .LP
  2359. To receive 
  2360. .PN CirculateNotify
  2361. events, set the
  2362. .PN StructureNotifyMask
  2363. bit in the event-mask attribute of the window
  2364. or the
  2365. .PN SubstructureNotifyMask
  2366. bit in the event-mask attribute of the parent window
  2367. (in which case, circulating any child generates an event).
  2368. .LP
  2369. The structure for this event type contains:
  2370. .LP
  2371. .IN "XCirculateEvent" "" "@DEF@"
  2372. .\" Start marker code here
  2373. .Ds 0
  2374. .TA .5i 3i
  2375. .ta .5i 3i
  2376. typedef struct {
  2377.     int type;    /* CirculateNotify */
  2378.     unsigned long serial;    /* # of last request processed by server */
  2379.     Bool send_event;    /* true if this came from a SendEvent request */
  2380.     Display *display;    /* Display the event was read from */
  2381.     Window event;
  2382.     Window window;
  2383.     int place;    /* PlaceOnTop, PlaceOnBottom */
  2384. } XCirculateEvent;
  2385. .De
  2386. .\" End marker code here
  2387. .LP
  2388. The event member is set either to the restacked window or to its parent,
  2389. depending on whether
  2390. .PN StructureNotify
  2391. or
  2392. .PN SubstructureNotify
  2393. was selected.
  2394. The window member is set to the window that was restacked.
  2395. The place member is set to the window's position after the restack occurs and
  2396. is either
  2397. .PN PlaceOnTop
  2398. or
  2399. .PN PlaceOnBottom .
  2400. If it is
  2401. .PN PlaceOnTop ,
  2402. the window is now on top of all siblings.
  2403. If it is
  2404. .PN PlaceOnBottom ,
  2405. the window is now below all siblings.
  2406. .NH 3
  2407. ConfigureNotify Events
  2408. .XS
  2409. \*(SN ConfigureNotify Events
  2410. .XE
  2411. .LP
  2412. .IN "Events" "ConfigureNotify"
  2413. .IN "ConfigureNotify" "" "@DEF@"
  2414. The X server can report
  2415. .PN ConfigureNotify
  2416. events to clients wanting information about actual changes to a window's
  2417. state, such as size, position, border, and stacking order.
  2418. The X server generates this event type whenever one of the following configure 
  2419. window requests made by a client application actually completes:
  2420. .IP \(bu 5
  2421. A window's size, position, border, and/or stacking order is reconfigured 
  2422. by calling
  2423. .PN XConfigureWindow .
  2424. .IP \(bu 5
  2425. The window's position in the stacking order is changed by calling
  2426. .PN XLowerWindow ,
  2427. .PN XRaiseWindow ,
  2428. or
  2429. .PN XRestackWindows .
  2430. .IP \(bu 5
  2431. A window is moved by calling
  2432. .PN XMoveWindow .
  2433. .IP \(bu 5
  2434. A window's size is changed by calling
  2435. .PN XResizeWindow .
  2436. .IP \(bu 5
  2437. A window's size and location is changed by calling
  2438. .PN XMoveResizeWindow .
  2439. .IP \(bu 5
  2440. A window is mapped and its position in the stacking order is changed
  2441. by calling
  2442. .PN XMapRaised .
  2443. .IP \(bu 5
  2444. A window's border width is changed by calling
  2445. .PN XSetWindowBorderWidth .
  2446. .LP
  2447. To receive 
  2448. .PN ConfigureNotify
  2449. events, set the
  2450. .PN StructureNotifyMask
  2451. bit in the event-mask attribute of the window or the
  2452. .PN SubstructureNotifyMask
  2453. bit in the event-mask attribute of the parent window
  2454. (in which case, configuring any child generates an event).
  2455. .LP
  2456. The structure for this event type contains:
  2457. .LP
  2458. .IN "XConfigureEvent" "" "@DEF@"
  2459. .\" Start marker code here
  2460. .Ds 0
  2461. .TA .5i 3i
  2462. .ta .5i 3i
  2463. typedef struct {
  2464.     int type;    /* ConfigureNotify */
  2465.     unsigned long serial;    /* # of last request processed by server */
  2466.     Bool send_event;    /* true if this came from a SendEvent request */
  2467.     Display *display;    /* Display the event was read from */
  2468.     Window event;
  2469.     Window window;
  2470.     int x, y;
  2471.     int width, height;
  2472.     int border_width;
  2473.     Window above;
  2474.     Bool override_redirect;
  2475. } XConfigureEvent;
  2476. .De
  2477. .\" End marker code here
  2478. .LP
  2479. The event member is set either to the reconfigured window or to its parent,
  2480. depending on whether
  2481. .PN StructureNotify
  2482. or
  2483. .PN SubstructureNotify
  2484. was selected.
  2485. The window member is set to the window whose size, position, 
  2486. border, and/or stacking
  2487. order was changed.
  2488. .LP
  2489. The x and y members are set to the coordinates relative to the parent window's 
  2490. origin and indicate the position of the upper-left outside corner of the window.
  2491. The width and height members are set to the inside size of the window, 
  2492. not including
  2493. the border.
  2494. The border_width member is set to the width of the window's border, in pixels.
  2495. .LP
  2496. The above member is set to the sibling window and is used 
  2497. for stacking operations.
  2498. If the X server sets this member to
  2499. .PN None ,
  2500. the window whose state was changed is on the bottom of the stack
  2501. with respect to sibling windows.
  2502. However, if this member is set to a sibling window, 
  2503. the window whose state was changed is placed on top of this sibling window.
  2504. .LP
  2505. The override_redirect member is set to the override-redirect attribute of the
  2506. window.
  2507. Window manager clients normally should ignore this window if the 
  2508. override_redirect member
  2509. is
  2510. .PN True .
  2511. .NH 3
  2512. CreateNotify Events
  2513. .XS
  2514. \*(SN CreateNotify Events
  2515. .XE
  2516. .LP
  2517. .IN "Events" "CreateNotify"
  2518. .IN "CreateNotify" "" "@DEF@"
  2519. The X server can report
  2520. .PN CreateNotify
  2521. events to clients wanting information about creation of windows.
  2522. The X server generates this event whenever a client
  2523. application creates a window by calling
  2524. .PN XCreateWindow
  2525. or
  2526. .PN XCreateSimpleWindow .
  2527. .LP
  2528. To receive 
  2529. .PN CreateNotify
  2530. events, set the
  2531. .PN SubstructureNotifyMask
  2532. bit in the event-mask attribute of the window.
  2533. Creating any children then generates an event.
  2534. .LP
  2535. The structure for the event type contains:
  2536. .LP
  2537. .IN "XCreateWindowEvent" "" "@DEF@"
  2538. .\" Start marker code here
  2539. .Ds 0
  2540. .TA .5i 3i
  2541. .ta .5i 3i
  2542. typedef struct {
  2543.     int type;    /* CreateNotify */
  2544.     unsigned long serial;    /* # of last request processed by server */
  2545.     Bool send_event;    /* true if this came from a SendEvent request */
  2546.     Display *display;    /* Display the event was read from */
  2547.     Window parent;    /* parent of the window */
  2548.     Window window;    /* window id of window created */
  2549.     int x, y;    /* window location */
  2550.     int width, height;    /* size of window */
  2551.     int border_width;    /* border width */
  2552.     Bool override_redirect;    /* creation should be overridden */
  2553. } XCreateWindowEvent;
  2554. .De
  2555. .\" End marker code here
  2556. .LP
  2557. The parent member is set to the created window's parent.
  2558. The window member specifies the created window.
  2559. The x and y members are set to the created window's coordinates relative 
  2560. to the parent window's origin and indicate the position of the upper-left 
  2561. outside corner of the created window.
  2562. The width and height members are set to the inside size of the created window 
  2563. (not including the border) and are always nonzero.
  2564. The border_width member is set to the width of the created window's border, in pixels.
  2565. The override_redirect member is set to the override-redirect attribute of the
  2566. window.
  2567. Window manager clients normally should ignore this window 
  2568. if the override_redirect member is
  2569. .PN True .
  2570. .NH 3
  2571. DestroyNotify Events
  2572. .XS
  2573. \*(SN DestroyNotify Events
  2574. .XE
  2575. .LP
  2576. .IN "Events" "DestroyNotify"
  2577. .IN "DestroyNotify" "" "@DEF@"
  2578. The X server can report
  2579. .PN DestroyNotify
  2580. events to clients wanting information about which windows are destroyed.
  2581. The X server generates this event whenever a client application destroys a 
  2582. window by calling
  2583. .PN XDestroyWindow
  2584. or
  2585. .PN XDestroySubwindows .
  2586. .LP
  2587. The ordering of the 
  2588. .PN DestroyNotify 
  2589. events is such that for any given window, 
  2590. .PN DestroyNotify
  2591. is generated on all inferiors of the window
  2592. before being generated on the window itself.  
  2593. The X protocol does not constrain the ordering among
  2594. siblings and across subhierarchies.
  2595. .LP
  2596. To receive 
  2597. .PN DestroyNotify
  2598. events, set the
  2599. .PN StructureNotifyMask
  2600. bit in the event-mask attribute of the window or the
  2601. .PN SubstructureNotifyMask
  2602. bit in the event-mask attribute of the parent window
  2603. (in which case, destroying any child generates an event).
  2604. .LP
  2605. The structure for this event type contains:
  2606. .LP
  2607. .IN "XDestroyWindowEvent" "" "@DEF@"
  2608. .\" Start marker code here
  2609. .Ds 0
  2610. .TA .5i 3i
  2611. .ta .5i 3i
  2612. typedef struct {
  2613.     int type;    /* DestroyNotify */
  2614.     unsigned long serial;    /* # of last request processed by server */
  2615.     Bool send_event;    /* true if this came from a SendEvent request */
  2616.     Display *display;    /* Display the event was read from */
  2617.     Window event;
  2618.     Window window;
  2619. } XDestroyWindowEvent;
  2620. .De
  2621. .\" End marker code here
  2622. .LP
  2623. The event member is set either to the destroyed window or to its parent,
  2624. depending on whether
  2625. .PN StructureNotify
  2626. or 
  2627. .PN SubstructureNotify
  2628. was selected.
  2629. The window member is set to the window that is destroyed.
  2630. .NH 3
  2631. GravityNotify Events
  2632. .XS
  2633. \*(SN GravityNotify Events
  2634. .XE
  2635. .LP
  2636. .IN "Events" "GravityNotify"
  2637. .IN "GravityNotify" "" "@DEF@"
  2638. The X server can report
  2639. .PN GravityNotify
  2640. events to clients wanting information about when a window is moved because of a
  2641. change in the size of its parent.
  2642. The X server generates this event whenever a client
  2643. application actually moves a child window as a result of resizing its parent by calling
  2644. .PN XConfigureWindow ,
  2645. .PN XMoveResizeWindow ,
  2646. or
  2647. .PN XResizeWindow . 
  2648. .LP
  2649. To receive 
  2650. .PN GravityNotify
  2651. events, set the
  2652. .PN StructureNotifyMask
  2653. bit in the event-mask attribute of the window or the
  2654. .PN SubstructureNotifyMask
  2655. bit in the event-mask attribute of the parent window
  2656. (in which case, any child that is moved because its parent has been resized
  2657. generates an event).
  2658. .LP
  2659. The structure for this event type contains:
  2660. .LP
  2661. .IN "XGravityEvent" "" "@DEF@"
  2662. .\" Start marker code here
  2663. .Ds 0
  2664. .TA .5i 3i
  2665. .ta .5i 3i
  2666. typedef struct {
  2667.     int type;    /* GravityNotify */
  2668.     unsigned long serial;    /* # of last request processed by server */
  2669.     Bool send_event;    /* true if this came from a SendEvent request */
  2670.     Display *display;    /* Display the event was read from */
  2671.     Window event;
  2672.     Window window;
  2673.     int x, y;
  2674. } XGravityEvent;
  2675. .De
  2676. .\" End marker code here
  2677. .LP
  2678. The event member is set either to the window that was moved or to its parent,
  2679. depending on whether
  2680. .PN StructureNotify
  2681. or
  2682. .PN SubstructureNotify
  2683. was selected.
  2684. The window member is set to the child window that was moved.
  2685. The x and y members are set to the coordinates relative to the 
  2686. new parent window's origin
  2687. and indicate the position of the upper-left outside corner of the 
  2688. window.
  2689. .NH 3
  2690. MapNotify Events
  2691. .XS
  2692. \*(SN MapNotify Events
  2693. .XE
  2694. .LP
  2695. .IN "Events" "MapNotify"
  2696. .IN "MapNotify" "" "@DEF@"
  2697. The X server can report
  2698. .PN MapNotify
  2699. events to clients wanting information about which windows are mapped.
  2700. The X server generates this event type whenever a client application changes the
  2701. window's state from unmapped to mapped by calling
  2702. .PN XMapWindow ,
  2703. .PN XMapRaised ,
  2704. .PN XMapSubwindows ,
  2705. .PN XReparentWindow ,
  2706. or as a result of save-set processing.
  2707. .LP
  2708. To receive 
  2709. .PN MapNotify
  2710. events, set the
  2711. .PN StructureNotifyMask
  2712. bit in the event-mask attribute of the window or the
  2713. .PN SubstructureNotifyMask
  2714. bit in the event-mask attribute of the parent window
  2715. (in which case, mapping any child generates an event).
  2716. .LP
  2717. The structure for this event type contains:
  2718. .LP
  2719. .IN "XMapEvent" "" "@DEF@"
  2720. .\" Start marker code here
  2721. .Ds 0
  2722. .TA .5i 3i
  2723. .ta .5i 3i
  2724. typedef struct {
  2725.     int type;    /* MapNotify */
  2726.     unsigned long serial;    /* # of last request processed by server */
  2727.     Bool send_event;    /* true if this came from a SendEvent request */
  2728.     Display *display;    /* Display the event was read from */
  2729.     Window event;
  2730.     Window window;
  2731.     Bool override_redirect;    /* boolean, is override set... */
  2732. } XMapEvent;
  2733. .De
  2734. .\" End marker code here
  2735. .LP
  2736. The event member is set either to the window that was mapped or to its parent,
  2737. depending on whether
  2738. .PN StructureNotify
  2739. or
  2740. .PN SubstructureNotify
  2741. was selected.
  2742. The window member is set to the window that was mapped.
  2743. The override_redirect member is set to the override-redirect attribute
  2744. of the window.
  2745. Window manager clients normally should ignore this window 
  2746. if the override-redirect attribute is
  2747. .PN True ,
  2748. because these events usually are generated from pop-ups,
  2749. which override structure control.
  2750. .NH 3
  2751. MappingNotify Events
  2752. .XS
  2753. \*(SN MappingNotify Events
  2754. .XE
  2755. .LP
  2756. .IN "Events" "MappingNotify"
  2757. .IN "MappingNotify" "" "@DEF@"
  2758. The X server reports
  2759. .PN MappingNotify
  2760. events to all clients.
  2761. There is no mechanism to express disinterest in this event.
  2762. The X server generates this event type whenever a client application 
  2763. successfully calls:
  2764. .IP \(bu 5
  2765. .PN XSetModifierMapping
  2766. to indicate which KeyCodes are to be used as modifiers
  2767. .IP \(bu 5
  2768. .PN XChangeKeyboardMapping
  2769. to change the keyboard mapping
  2770. .IP \(bu 5
  2771. .PN XSetPointerMapping
  2772. to set the pointer mapping
  2773. .LP
  2774. The structure for this event type contains:
  2775. .LP
  2776. .IN "XMappingEvent" "" "@DEF@"
  2777. .\" Start marker code here
  2778. .Ds 0
  2779. .TA .5i 3i
  2780. .ta .5i 3i
  2781. typedef struct {
  2782.     int type;    /* MappingNotify */
  2783.     unsigned long serial;    /* # of last request processed by server */
  2784.     Bool send_event;    /* true if this came from a SendEvent request */
  2785.     Display *display;    /* Display the event was read from */
  2786.     Window window;    /* unused */
  2787.     int request;    /* one of MappingModifier, MappingKeyboard,
  2788.            MappingPointer */
  2789.     int first_keycode;    /* first keycode */
  2790.     int count;    /* defines range of change w. first_keycode*/
  2791. } XMappingEvent;
  2792. .De
  2793. .\" End marker code here
  2794. .LP
  2795. The request member is set to indicate the kind of mapping change that occurred
  2796. and can be
  2797. .PN MappingModifier ,
  2798. .PN MappingKeyboard ,
  2799. .PN MappingPointer .
  2800. If it is
  2801. .PN MappingModifier ,
  2802. the modifier mapping was changed.
  2803. If it is
  2804. .PN MappingKeyboard ,
  2805. the keyboard mapping was changed.
  2806. If it is
  2807. .PN MappingPointer ,
  2808. the pointer button mapping was changed. 
  2809. The first_keycode and count members are set only 
  2810. if the request member was set to
  2811. .PN MappingKeyboard .
  2812. The number in first_keycode represents the first number in the range 
  2813. of the altered mapping, 
  2814. and count represents the number of keycodes altered.
  2815. .LP
  2816. To update the client application's knowledge of the keyboard,
  2817. you should call
  2818. .PN XRefreshKeyboardMapping . 
  2819. .NH 3
  2820. ReparentNotify Events
  2821. .XS
  2822. \*(SN ReparentNotify Events
  2823. .XE
  2824. .LP
  2825. .IN "Events" "ReparentNotify"
  2826. .IN "ReparentNotify" "" "@DEF@"
  2827. The X server can report
  2828. .PN ReparentNotify
  2829. events to clients wanting information about changing a window's parent.
  2830. The X server generates this event whenever a client
  2831. application calls
  2832. .PN XReparentWindow 
  2833. and the window is actually reparented.
  2834. .LP
  2835. To receive 
  2836. .PN ReparentNotify
  2837. events, set the
  2838. .PN StructureNotifyMask
  2839. bit in the event-mask attribute of the window or the
  2840. .PN SubstructureNotifyMask
  2841. bit in the event-mask attribute of either the old or the new parent window
  2842. (in which case, reparenting any child generates an event).
  2843. .LP
  2844. The structure for this event type contains:
  2845. .LP
  2846. .IN "XReparentEvent" "" "@DEF@"
  2847. .\" Start marker code here
  2848. .Ds 0
  2849. .TA .5i 3i
  2850. .ta .5i 3i
  2851. typedef struct {
  2852.     int type;    /* ReparentNotify */
  2853.     unsigned long serial;    /* # of last request processed by server */
  2854.     Bool send_event;    /* true if this came from a SendEvent request */
  2855.     Display *display;    /* Display the event was read from */
  2856.     Window event;
  2857.     Window window;
  2858.     Window parent;
  2859.     int x, y;
  2860.     Bool override_redirect;
  2861. } XReparentEvent;
  2862. .De
  2863. .\" End marker code here
  2864. .LP
  2865. The event member is set either to the reparented window
  2866. or to the old or the new parent, depending on whether
  2867. .PN StructureNotify
  2868. or
  2869. .PN SubstructureNotify
  2870. was selected. 
  2871. The window member is set to the window that was reparented.
  2872. The parent member is set to the new parent window.
  2873. The x and y members are set to the reparented window's coordinates relative 
  2874. to the new parent window's
  2875. origin and define the upper-left outer corner of the reparented window.
  2876. The override_redirect member is set to the override-redirect attribute of the
  2877. window specified by the window member.
  2878. Window manager clients normally should ignore this window 
  2879. if the override_redirect member is
  2880. .PN True .
  2881. .NH 3
  2882. UnmapNotify Events
  2883. .XS
  2884. \*(SN UnmapNotify Events
  2885. .XE
  2886. .LP
  2887. .IN "Events" "UnmapNotify"
  2888. .IN "UnmapNotify" "" "@DEF@"
  2889. The X server can report
  2890. .PN UnmapNotify
  2891. events to clients wanting information about which windows are unmapped.
  2892. The X server generates this event type whenever a client application changes the
  2893. window's state from mapped to unmapped.
  2894. .LP
  2895. To receive 
  2896. .PN UnmapNotify
  2897. events, set the
  2898. .PN StructureNotifyMask
  2899. bit in the event-mask attribute of the window or the
  2900. .PN SubstructureNotifyMask
  2901. bit in the event-mask attribute of the parent window
  2902. (in which case, unmapping any child window generates an event).
  2903. .LP
  2904. The structure for this event type contains:
  2905. .LP
  2906. .IN "XUnmapEvent" "" "@DEF@"
  2907. .\" Start marker code here
  2908. .Ds 0
  2909. .TA .5i 3i
  2910. .ta .5i 3i
  2911. typedef struct {
  2912.     int type;    /* UnmapNotify */
  2913.     unsigned long serial;    /* # of last request processed by server */
  2914.     Bool send_event;    /* true if this came from a SendEvent request */
  2915.     Display *display;    /* Display the event was read from */
  2916.     Window event;
  2917.     Window window;
  2918.     Bool from_configure;
  2919. } XUnmapEvent;
  2920. .De
  2921. .\" End marker code here
  2922. .LP
  2923. The event member is set either to the unmapped window or to its parent,
  2924. depending on whether
  2925. .PN StructureNotify
  2926. or
  2927. .PN SubstructureNotify
  2928. was selected.
  2929. This is the window used by the X server to report the event.
  2930. The window member is set to the window that was unmapped.
  2931. The from_configure member is set to
  2932. .PN True 
  2933. if the event was generated as a result of a resizing of the window's parent when
  2934. the window itself had a win_gravity of
  2935. .PN UnmapGravity .
  2936. .NH 3
  2937. VisibilityNotify Events
  2938. .XS
  2939. \*(SN VisibilityNotify Events
  2940. .XE
  2941. .LP
  2942. .IN "Events" "VisibilityNotify"
  2943. .IN "VisibilityNotify" "" "@DEF@"
  2944. The X server can report
  2945. .PN VisibilityNotify
  2946. events to clients wanting any change in the visibility of the specified window.
  2947. A region of a window is visible if someone looking at the screen can
  2948. actually see it.
  2949. The X server generates this event whenever the visibility changes state. 
  2950. However, this event is never generated for windows whose class is
  2951. .PN InputOnly .
  2952. .LP
  2953. All 
  2954. .PN VisibilityNotify
  2955. events caused by a hierarchy change are generated
  2956. after any hierarchy event
  2957. .Pn ( UnmapNotify , 
  2958. .PN MapNotify , 
  2959. .PN ConfigureNotify ,
  2960. .PN GravityNotify ,
  2961. .PN CirculateNotify )
  2962. caused by that change.  Any
  2963. .PN VisibilityNotify
  2964. event on a given window is generated before any
  2965. .PN Expose 
  2966. events on that window, but it is not required that all
  2967. .PN VisibilityNotify
  2968. events on all windows be generated before all 
  2969. .PN Expose
  2970. events on all windows.  
  2971. The X protocol does not constrain the ordering of 
  2972. .PN VisibilityNotify
  2973. events with
  2974. respect to 
  2975. .PN FocusOut , 
  2976. .PN EnterNotify ,
  2977. and 
  2978. .PN LeaveNotify
  2979. events.
  2980. .LP
  2981. To receive 
  2982. .PN VisibilityNotify
  2983. events, set the
  2984. .PN VisibilityChangeMask
  2985. bit in the event-mask attribute of the window. 
  2986. .LP
  2987. The structure for this event type contains:
  2988. .LP
  2989. .IN "XVisibilityEvent" "" "@DEF@"
  2990. .\" Start marker code here
  2991. .Ds 0
  2992. .TA .5i 3i
  2993. .ta .5i 3i
  2994. typedef struct {
  2995.     int type;    /* VisibiltyNotify */
  2996.     unsigned long serial;    /* # of last request processed by server */
  2997.     Bool send_event;    /* true if this came from a SendEvent request */
  2998.     Display *display;    /* Display the event was read from */
  2999.     Window window;
  3000.     int state;
  3001. } XVisibilityEvent;
  3002. .De
  3003. .\" End marker code here
  3004. .LP
  3005. The window member is set to the window whose visibility state changes.
  3006. The state member is set to the state of the window's visibility and can be
  3007. .PN VisibilityUnobscured ,
  3008. .PN VisibilityPartiallyObscured ,
  3009. or
  3010. .PN VisibilityFullyObscured .
  3011. The X server ignores all of a window's subwindows
  3012. when determining the visibility state of the window and processes 
  3013. .PN VisibilityNotify
  3014. events according to the following:
  3015. .IP \(bu 5
  3016. When the window changes state from partially obscured, fully obscured,
  3017. or not viewable to viewable and completely unobscured,
  3018. the X server generates the event with the state member of the
  3019. .PN XVisibilityEvent
  3020. structure set to
  3021. .PN VisibilityUnobscured .
  3022. .IP \(bu 5
  3023. When the window changes state from viewable and completely unobscured or 
  3024. not viewable to viewable and partially obscured,
  3025. the X server generates the event with the state member of the
  3026. .PN XVisibilityEvent
  3027. structure set to
  3028. .PN VisibilityPartiallyObscured .
  3029. .IP \(bu 5
  3030. When the window changes state from viewable and completely unobscured, 
  3031. viewable and partially obscured, or not viewable to viewable and 
  3032. fully obscured,
  3033. the X server generates the event with the state member of the
  3034. .PN XVisibilityEvent
  3035. structure set to
  3036. .PN VisibilityFullyObscured .
  3037. .NH 2
  3038. Structure Control Events
  3039. .XS
  3040. \*(SN Structure Control Events
  3041. .XE
  3042. .LP
  3043. This section discusses:
  3044. .IP \(bu 5
  3045. .PN CirculateRequest
  3046. events
  3047. .IP \(bu 5
  3048. .PN ConfigureRequest
  3049. events
  3050. .IP \(bu 5
  3051. .PN MapRequest 
  3052. events
  3053. .IP \(bu 5
  3054. .PN ResizeRequest 
  3055. events
  3056. .NH 3 
  3057. CirculateRequest Events
  3058. .XS
  3059. \*(SN CirculateRequest Events
  3060. .XE
  3061. .LP
  3062. .IN "Events" "CirculateRequest"
  3063. .IN "CirculateRequest" "" "@DEF@"
  3064. The X server can report
  3065. .PN CirculateRequest
  3066. events to clients wanting information about 
  3067. when another client initiates a circulate window request 
  3068. on a specified window.
  3069. The X server generates this event type whenever a client initiates a circulate
  3070. window request on a window and a subwindow actually needs to be restacked. 
  3071. The client initiates a circulate window request on the window by calling
  3072. .PN XCirculateSubwindows ,
  3073. .PN XCirculateSubwindowsUp ,
  3074. or
  3075. .PN XCirculateSubwindowsDown .
  3076. .LP
  3077. To receive
  3078. .PN CirculateRequest
  3079. events, set the
  3080. .PN SubstructureRedirectMask
  3081. in the event-mask attribute of the window. 
  3082. Then, in the future,
  3083. the circulate window request for the specified window is not executed,
  3084. and thus, any subwindow's position in the stack is not changed.
  3085. For example, suppose a client application calls
  3086. .PN XCirculateSubwindowsUp
  3087. to raise a subwindow to the top of the stack.
  3088. If you had selected
  3089. .PN SubstructureRedirectMask
  3090. on the window, the X server reports to you a
  3091. .PN CirculateRequest
  3092. event and does not raise the subwindow to the top of the stack.
  3093. .LP
  3094. The structure for this event type contains:
  3095. .LP
  3096. .IN "XCirculateRequestEvent" "" "@DEF@"
  3097. .\" Start marker code here
  3098. .Ds 0
  3099. .TA .5i 3i
  3100. .ta .5i 3i
  3101. typedef struct {
  3102.     int type;    /* CirculateRequest */
  3103.     unsigned long serial;    /* # of last request processed by server */
  3104.     Bool send_event;    /* true if this came from a SendEvent request */
  3105.     Display *display;    /* Display the event was read from */
  3106.     Window parent;
  3107.     Window window;
  3108.     int place;    /* PlaceOnTop, PlaceOnBottom */
  3109. } XCirculateRequestEvent;
  3110. .De
  3111. .\" End marker code here
  3112. .LP
  3113. The parent member is set to the parent window.
  3114. The window member is set to the subwindow to be restacked.
  3115. The place member is set to what the new position in the stacking order should be
  3116. and is either
  3117. .PN PlaceOnTop
  3118. or
  3119. .PN PlaceOnBottom .
  3120. If it is
  3121. .PN PlaceOnTop ,
  3122. the subwindow should be on top of all siblings.
  3123. If it is
  3124. .PN PlaceOnBottom ,
  3125. the subwindow should be below all siblings.
  3126. .NH 3
  3127. ConfigureRequest Events
  3128. .XS
  3129. \*(SN ConfigureRequest Events
  3130. .XE
  3131. .LP
  3132. .IN "Events" "ConfigureRequest"
  3133. .IN "ConfigureRequest" "" "@DEF@"
  3134. The X server can report
  3135. .PN ConfigureRequest
  3136. events to clients wanting information about when a different client initiates 
  3137. a configure window request on any child of a specified window. 
  3138. The configure window request attempts to 
  3139. reconfigure a window's size, position, border, and stacking order.
  3140. The X server generates this event whenever a different client initiates
  3141. a configure window request on a window by calling
  3142. .PN XConfigureWindow ,
  3143. .PN XLowerWindow ,
  3144. .PN XRaiseWindow ,
  3145. .PN XMapRaised ,
  3146. .PN XMoveResizeWindow ,
  3147. .PN XMoveWindow ,
  3148. .PN XResizeWindow ,
  3149. .PN XRestackWindows ,
  3150. or
  3151. .PN XSetWindowBorderWidth .
  3152. .LP
  3153. To receive
  3154. .PN ConfigureRequest
  3155. events, set the
  3156. .PN SubstructureRedirectMask
  3157. bit in the event-mask attribute of the window. 
  3158. .PN ConfigureRequest
  3159. events are generated when a
  3160. .PN ConfigureWindow
  3161. protocol request is issued on a child window by another client.
  3162. For example, suppose a client application calls
  3163. .PN XLowerWindow
  3164. to lower a window.
  3165. If you had selected
  3166. .PN SubstructureRedirectMask 
  3167. on the parent window and if the override-redirect attribute 
  3168. of the window is set to
  3169. .PN False ,
  3170. the X server reports a
  3171. .PN ConfigureRequest
  3172. event to you and does not lower the specified window.
  3173. .LP
  3174. The structure for this event type contains:
  3175. .LP
  3176. .IN "XConfigureRequestEvent" "" "@DEF@"
  3177. .\" Start marker code here
  3178. .Ds 0
  3179. .TA .5i 3i
  3180. .ta .5i 3i
  3181. typedef struct {
  3182.     int type;    /* ConfigureRequest */
  3183.     unsigned long serial;    /* # of last request processed by server */
  3184.     Bool send_event;    /* true if this came from a SendEvent request */
  3185.     Display *display;    /* Display the event was read from */
  3186.     Window parent;
  3187.     Window window;
  3188.     int x, y;
  3189.     int width, height;
  3190.     int border_width;
  3191.     Window above;
  3192.     int detail;    /* Above, Below, TopIf, BottomIf, Opposite */
  3193.     unsigned long value_mask;
  3194. } XConfigureRequestEvent;
  3195. .De
  3196. .\" End marker code here
  3197. .LP
  3198. The parent member is set to the parent window.
  3199. The window member is set to the window whose size, position, border width, 
  3200. and/or stacking order is to be reconfigured.
  3201. The value_mask member indicates which components were specified in the
  3202. .PN ConfigureWindow 
  3203. protocol request.
  3204. The corresponding values are reported as given in the request.
  3205. The remaining values are filled in from the current geometry of the window,
  3206. except in the case of above (sibling) and detail (stack-mode),
  3207. which are reported as
  3208. .PN Above
  3209. and
  3210. .PN None ,
  3211. respectively, if they are not given in the request.
  3212. .NH 3
  3213. MapRequest Events
  3214. .XS
  3215. \*(SN MapRequest Events
  3216. .XE
  3217. .LP
  3218. .IN "Events" "MapRequest"
  3219. .IN "MapRequest" "" "@DEF@"
  3220. The X server can report
  3221. .PN MapRequest
  3222. events to clients wanting information about a different client's desire 
  3223. to map windows.
  3224. A window is considered mapped when a map window request completes.
  3225. The X server generates this event whenever a different client initiates 
  3226. a map window request on an unmapped window whose override_redirect member 
  3227. is set to
  3228. .PN False .
  3229. Clients initiate map window requests by calling
  3230. .PN XMapWindow ,
  3231. .PN XMapRaised ,
  3232. or
  3233. .PN XMapSubwindows .
  3234. .LP
  3235. To receive
  3236. .PN MapRequest
  3237. events, set the
  3238. .PN SubstructureRedirectMask
  3239. bit in the event-mask attribute of the window. 
  3240. This means another client's attempts to map a child window by calling one of
  3241. the map window request functions is intercepted, and you are sent a 
  3242. .PN MapRequest
  3243. instead.
  3244. For example, suppose a client application calls
  3245. .PN XMapWindow
  3246. to map a window.
  3247. If you (usually a window manager) had selected
  3248. .PN SubstructureRedirectMask 
  3249. on the parent window and if the override-redirect attribute 
  3250. of the window is set to
  3251. .PN False ,
  3252. the X server reports a
  3253. .PN MapRequest
  3254. event to you 
  3255. and does not map the specified window.
  3256. Thus, this event gives your window manager client the ability 
  3257. to control the placement of subwindows.
  3258. .LP
  3259. The structure for this event type contains:
  3260. .LP
  3261. .IN "XMapRequestEvent" "" "@DEF@"
  3262. .\" Start marker code here
  3263. .Ds 0
  3264. .TA .5i 3i
  3265. .ta .5i 3i
  3266. typedef struct {
  3267.     int type;    /* MapRequest */
  3268.     unsigned long serial;    /* # of last request processed by server */
  3269.     Bool send_event;    /* true if this came from a SendEvent request */
  3270.     Display *display;    /* Display the event was read from */
  3271.     Window parent;
  3272.     Window window;
  3273. } XMapRequestEvent;
  3274. .De
  3275. .\" End marker code here
  3276. .LP
  3277. The parent member is set to the parent window.
  3278. The window member is set to the window to be mapped.
  3279. .NH 3
  3280. ResizeRequest Events
  3281. .XS
  3282. \*(SN ResizeRequest Events
  3283. .XE
  3284. .LP
  3285. .IN "Events" "ResizeRequest"
  3286. .IN "ResizeRequest" "" "@DEF@"
  3287. The X server can report
  3288. .PN ResizeRequest
  3289. events to clients wanting information about another client's attempts to change the
  3290. size of a window.
  3291. The X server generates this event whenever some other client attempts to change
  3292. the size of the specified window by calling
  3293. .PN XConfigureWindow ,
  3294. .PN XResizeWindow ,
  3295. or
  3296. .PN XMoveResizeWindow .
  3297. .LP
  3298. To receive
  3299. .PN ResizeRequest
  3300. events, set the
  3301. .PN ResizeRedirect
  3302. bit in the event-mask attribute of the window. 
  3303. Any attempts to change the size by other clients are then redirected.
  3304. .LP
  3305. The structure for this event type contains:
  3306. .LP
  3307. .IN "XResizeRequestEvent" "" "@DEF@"
  3308. .\" Start marker code here
  3309. .Ds 0
  3310. .TA .5i 3i
  3311. .ta .5i 3i
  3312. typedef struct {
  3313.     int type;    /* ResizeRequest */
  3314.     unsigned long serial;    /* # of last request processed by server */
  3315.     Bool send_event;    /* true if this came from a SendEvent request */
  3316.     Display *display;    /* Display the event was read from */
  3317.     Window window;
  3318.     int width, height;
  3319. } XResizeRequestEvent;
  3320. .De
  3321. .\" End marker code here
  3322. .LP
  3323. The window member is set to the window whose size another 
  3324. client attempted to change.
  3325. The width and height members are set to the inside size of the window, 
  3326. excluding the border.
  3327. .NH 2
  3328. Colormap State Change Events
  3329. .XS
  3330. \*(SN Colormap State Change Events
  3331. .XE
  3332. .LP
  3333. .IN "Events" "ColormapNotify"
  3334. .IN "ColormapNotify" "" "@DEF@"
  3335. The X server can report
  3336. .PN ColormapNotify
  3337. events to clients wanting information about when the colormap changes 
  3338. and when a colormap is installed or uninstalled. 
  3339. The X server generates this event type whenever a client application:
  3340. .IP \(bu 5
  3341. Changes the colormap member of the
  3342. .PN XSetWindowAttributes
  3343. structure by 
  3344. calling
  3345. .PN XChangeWindowAttributes ,
  3346. .PN XFreeColormap ,
  3347. or
  3348. .PN XSetWindowColormap 
  3349. .IP \(bu 5
  3350. Installs or uninstalls the colormap by calling
  3351. .PN XInstallColormap
  3352. or
  3353. .PN XUninstallColormap 
  3354. .LP
  3355. To receive 
  3356. .PN ColormapNotify 
  3357. events, set the
  3358. .PN ColormapChangeMask
  3359. bit in the event-mask attribute of the window. 
  3360. .LP
  3361. The structure for this event type contains:
  3362. .LP
  3363. .IN "XColormapEvent" "" "@DEF@"
  3364. .\" Start marker code here
  3365. .Ds 0
  3366. .TA .5i 3i
  3367. .ta .5i 3i
  3368. typedef struct {
  3369.     int type;    /* ColormapNotify */
  3370.     unsigned long serial;    /* # of last request processed by server */
  3371.     Bool send_event;    /* true if this came from a SendEvent request */
  3372.     Display *display;    /* Display the event was read from */
  3373.     Window window;
  3374.     Colormap colormap;    /* colormap or None */
  3375.     Bool new;
  3376.     int state;    /* ColormapInstalled, ColormapUninstalled */
  3377. } XColormapEvent;
  3378. .De
  3379. .\" End marker code here
  3380. .LP
  3381. The window member is set to the window whose associated 
  3382. colormap is changed, installed, or uninstalled.
  3383. For a colormap that is changed, installed, or uninstalled,
  3384. the colormap member is set to the colormap associated with the window. 
  3385. For a colormap that is changed by a call to
  3386. .PN XFreeColormap ,
  3387. the colormap member is set to
  3388. .PN None .
  3389. The new member is set to indicate whether the colormap 
  3390. for the specified window was changed or installed or uninstalled
  3391. and can be 
  3392. .PN True
  3393. or
  3394. .PN False .
  3395. If it is
  3396. .PN True ,
  3397. the colormap was changed.
  3398. If it is
  3399. .PN False ,
  3400. the colormap was installed or uninstalled.
  3401. The state member is always set to indicate whether the colormap is installed or
  3402. uninstalled and can be 
  3403. .PN ColormapInstalled
  3404. or
  3405. .PN ColormapUninstalled .
  3406. .NH 2
  3407. Client Communication Events
  3408. .XS
  3409. \*(SN Client Communication Events
  3410. .XE
  3411. .LP
  3412. This section discusses:
  3413. .IP \(bu 5
  3414. .PN ClientMessage 
  3415. events
  3416. .IP \(bu 5
  3417. .PN PropertyNotify
  3418. events
  3419. .IP \(bu 5
  3420. .PN SelectionClear
  3421. events
  3422. .IP \(bu 5
  3423. .PN SelectionNotify
  3424. events
  3425. .IP \(bu 5
  3426. .PN SelectionRequest
  3427. events
  3428. .NH 3
  3429. ClientMessage Events
  3430. .XS
  3431. \*(SN ClientMessage Events
  3432. .XE
  3433. .LP
  3434. .IN "Events" "ClientMessage"
  3435. .IN "ClientMessage" "" "@DEF@"
  3436. The X server generates
  3437. .PN ClientMessage
  3438. events only when a client calls the function
  3439. .PN XSendEvent .
  3440. .LP
  3441. The structure for this event type contains:
  3442. .LP
  3443. .IN "XClientMessageEvent" "" "@DEF@"
  3444. .\" Start marker code here
  3445. .Ds 0
  3446. .TA .5i 1i 3i
  3447. .ta .5i 1i 3i
  3448. typedef struct {
  3449.     int type;    /* ClientMessage */
  3450.     unsigned long serial;        /* # of last request processed by server */
  3451.     Bool send_event;        /* true if this came from a SendEvent request */
  3452.     Display *display;        /* Display the event was read from */
  3453.     Window window;
  3454.     Atom message_type;
  3455.     int format;
  3456.     union {
  3457.         char b[20];
  3458.         short s[10];
  3459.         long l[5];
  3460.             } data;
  3461. } XClientMessageEvent;
  3462. .De
  3463. .\" End marker code here
  3464. .LP
  3465. The message_type member is set to an atom that indicates how the data 
  3466. should be interpreted by the receiving client.
  3467. The format member is set to 8, 16, or 32 and specifies whether the data
  3468. should be viewed as a list of bytes, shorts, or longs.
  3469. The data member is a union that contains the members b, s, and l.
  3470. The b, s, and l members represent data of 20 8-bit values, 
  3471. 10 16-bit values, and 5 32-bit values.
  3472. Particular message types might not make use of all these values.
  3473. The X server places no interpretation on the values in the window,
  3474. message_type, or data members.
  3475. .NH 3
  3476. PropertyNotify Events
  3477. .XS
  3478. \*(SN PropertyNotify Events
  3479. .XE
  3480. .LP
  3481. .IN "Events" "PropertyNotify"
  3482. .IN "PropertyNotify" "" "@DEF@"
  3483. The X server can report
  3484. .PN PropertyNotify
  3485. events to clients wanting information about property changes 
  3486. for a specified window.
  3487. .LP
  3488. To receive
  3489. .PN PropertyNotify
  3490. events, set the
  3491. .PN PropertyChangeMask
  3492. bit in the event-mask attribute of the window. 
  3493. .LP
  3494. The structure for this event type contains:
  3495. .LP
  3496. .IN "XPropertyEvent" "" "@DEF@"
  3497. .\" Start marker code here
  3498. .Ds 0
  3499. .TA .5i 3i
  3500. .ta .5i 3i
  3501. typedef struct {
  3502.     int type;    /* PropertyNotify */
  3503.     unsigned long serial;    /* # of last request processed by server */
  3504.     Bool send_event;    /* true if this came from a SendEvent request */
  3505.     Display *display;    /* Display the event was read from */
  3506.     Window window;
  3507.     Atom atom;
  3508.     Time time;
  3509.     int state;    /* PropertyNewValue or PropertyDelete */
  3510. } XPropertyEvent;
  3511. .De
  3512. .\" End marker code here
  3513. .LP
  3514. The window member is set to the window whose associated 
  3515. property was changed.
  3516. The atom member is set to the property's atom and indicates which
  3517. property was changed or desired.
  3518. The time member is set to the server time when the property was changed.
  3519. The state member is set to indicate whether the property was changed 
  3520. to a new value or deleted and can be
  3521. .PN PropertyNewValue
  3522. or
  3523. .PN PropertyDelete .
  3524. The state member is set to
  3525. .PN PropertyNewValue
  3526. when a property of the window is changed using
  3527. .PN XChangeProperty
  3528. or
  3529. .PN XRotateWindowProperties
  3530. (even when adding zero-length data using
  3531. .PN XChangeProperty )
  3532. and when replacing all or part of a property with identical data using
  3533. .PN XChangeProperty
  3534. or 
  3535. .PN XRotateWindowProperties .
  3536. The state member is set to
  3537. .PN PropertyDelete
  3538. when a property of the window is deleted using
  3539. .PN XDeleteProperty
  3540. or, if the delete argument is 
  3541. .PN True ,
  3542. .PN XGetWindowProperty .
  3543. .NH 3
  3544. SelectionClear Events
  3545. .XS
  3546. \*(SN SelectionClear Events
  3547. .XE
  3548. .LP
  3549. .IN "Events" "SelectionClear" 
  3550. .IN "SelectionClear" "" "@DEF@"
  3551. The X server reports
  3552. .PN SelectionClear
  3553. events to the client losing ownership of a selection.
  3554. The X server generates this event type when another client
  3555. asserts ownership of the selection by calling
  3556. .PN XSetSelectionOwner .
  3557. .LP
  3558. The structure for this event type contains:
  3559. .LP
  3560. .IN "XSelectionClearEvent" "" "@DEF@"
  3561. .\" Start marker code here
  3562. .Ds 0
  3563. .TA .5i 3i
  3564. .ta .5i 3i
  3565. typedef struct {
  3566.     int type;    /* SelectionClear */
  3567.     unsigned long serial;    /* # of last request processed by server */
  3568.     Bool send_event;    /* true if this came from a SendEvent request */
  3569.     Display *display;    /* Display the event was read from */
  3570.     Window window;
  3571.     Atom selection;
  3572.     Time time;
  3573. } XSelectionClearEvent;
  3574. .De
  3575. .\" End marker code here
  3576. .LP
  3577. The selection member is set to the selection atom.
  3578. The time member is set to the last change time recorded for the 
  3579. selection.
  3580. The window member is the window that was specified by the current owner
  3581. (the owner losing the selection) in its
  3582. .PN XSetSelectionOwner
  3583. call.
  3584. .NH 3
  3585. SelectionRequest Events
  3586. .XS
  3587. \*(SN SelectionRequest Events
  3588. .XE
  3589. .LP
  3590. .IN "Events" "SelectionRequest"
  3591. .IN "SelectionRequest" "" "@DEF@"
  3592. The X server reports
  3593. .PN SelectionRequest
  3594. events to the owner of a selection.
  3595. The X server generates this event whenever a client 
  3596. requests a selection conversion by calling 
  3597. .PN XConvertSelection 
  3598. for the owned selection.
  3599. .LP
  3600. The structure for this event type contains:
  3601. .LP
  3602. .IN "XSelectionRequestEvent" "" "@DEF@"
  3603. .\" Start marker code here
  3604. .Ds 0
  3605. .TA .5i 3i
  3606. .ta .5i 3i
  3607. typedef struct {
  3608.     int type;    /* SelectionRequest */
  3609.     unsigned long serial;    /* # of last request processed by server */
  3610.     Bool send_event;    /* true if this came from a SendEvent request */
  3611.     Display *display;    /* Display the event was read from */
  3612.     Window owner;
  3613.     Window requestor;
  3614.     Atom selection;
  3615.     Atom target;
  3616.     Atom property;
  3617.     Time time;
  3618. } XSelectionRequestEvent;
  3619. .De
  3620. .\" End marker code here
  3621. .LP
  3622. The owner member is set to the window
  3623. that was specified by the current owner in its
  3624. .PN XSetSelectionOwner
  3625. call.
  3626. The requestor member is set to the window requesting the selection.
  3627. The selection member is set to the atom that names the selection.
  3628. For example, PRIMARY is used to indicate the primary selection.
  3629. The target member is set to the atom that indicates the type
  3630. the selection is desired in.
  3631. The property member can be a property name or 
  3632. .PN None .
  3633. The time member is set to the timestamp or 
  3634. .PN CurrentTime 
  3635. value from the
  3636. .PN ConvertSelection
  3637. request.
  3638. .LP
  3639. The owner should convert the selection based on the specified target type
  3640. and send a
  3641. .PN SelectionNotify
  3642. event back to the requestor.
  3643. A complete specification for using selections is given in the X Consortium
  3644. standard \fIInter-Client Communication Conventions Manual\fP.
  3645. .NH 3
  3646. SelectionNotify Events
  3647. .XS
  3648. \*(SN SelectionNotify Events
  3649. .XE
  3650. .LP
  3651. .IN "Events" "SelectionNotify"
  3652. .IN "SelectionNotify" "" "@DEF@"
  3653. This event is generated by the X server in response to a
  3654. .PN ConvertSelection 
  3655. protocol request when there is no owner for the selection.
  3656. When there is an owner, it should be generated by the owner
  3657. of the selection by using
  3658. .PN XSendEvent .
  3659. The owner of a selection should send this event to a requestor when a selection
  3660. has been converted and stored as a property
  3661. or when a selection conversion could
  3662. not be performed (which is indicated by setting the property member to
  3663. .PN None ).
  3664. .LP
  3665. If
  3666. .PN None
  3667. is specified as the property in the 
  3668. .PN ConvertSelection
  3669. protocol request, the owner should choose a property name,
  3670. store the result as that property on the requestor window,
  3671. and then send a 
  3672. .PN SelectionNotify
  3673. giving that actual property name.
  3674. .LP
  3675. The structure for this event type contains:
  3676. .LP
  3677. .IN "XSelectionEvent" "" "@DEF@"
  3678. .\" Start marker code here
  3679. .Ds 0
  3680. .TA .5i 3i
  3681. .ta .5i 3i
  3682. typedef struct {
  3683.     int type;    /* SelectionNotify */
  3684.     unsigned long serial;    /* # of last request processed by server */
  3685.     Bool send_event;    /* true if this came from a SendEvent request */
  3686.     Display *display;    /* Display the event was read from */
  3687.     Window requestor;
  3688.     Atom selection;
  3689.     Atom target;
  3690.     Atom property;    /* atom or None */
  3691.     Time time;
  3692. } XSelectionEvent;
  3693. .De
  3694. .\" End marker code here
  3695. .LP
  3696. The requestor member is set to the window associated with
  3697. the requestor of the selection.
  3698. The selection member is set to the atom that indicates the selection.
  3699. For example, PRIMARY is used for the primary selection.
  3700. The target member is set to the atom that indicates the converted type.
  3701. For example, PIXMAP is used for a pixmap.
  3702. The property member is set to the atom that indicates which
  3703. property the result was stored on.
  3704. If the conversion failed, 
  3705. the property member is set to
  3706. .PN None .
  3707. The time member is set to the time the conversion took place and
  3708. can be a timestamp or
  3709. .PN CurrentTime .
  3710. .bp
  3711.