specs/libX11/CH10.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3           "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4 <chapter id='Events'>
   5 <title>Events</title>
   6
   7 <para>
   8 A client application communicates with the X server through the connection you establish with
   9 the XOpenDisplay function. A client application sends requests to the X server over this
  10 connection. These requests are made by the Xlib functions that are called in the client application.
  11 Many Xlib functions cause the X server to generate events, and the user’s typing or moving the
  12 pointer can generate events asynchronously. The X server returns events to the client on the same
  13 connection.
  14 </para>
  15 <para>
  16 This chapter discusses the following topics associated with events:
  17 </para>
  18
  19 <itemizedlist>
  20   <listitem><para>Event types</para></listitem>
  21   <listitem><para>Event structures</para></listitem>
  22   <listitem><para>Event masks</para></listitem>
  23   <listitem><para>Event processing</para></listitem>
  24 </itemizedlist>
  25
  26 <para>
  27 Functions for handling events are dealt with in
  28 <link linkend='Event_Handling_Functions'>the next chapter</link>.
  29 </para>
  30
  31 <sect1 id="Event_Types">
  32 <title>Event Types</title>
  33 <!-- .XS -->
  34 <!-- (SN Event Types  -->
  35 <!-- .XE -->
  36 <para>
  37 <!-- .LP -->
  38 <indexterm><primary>Event</primary><secondary>types</secondary></indexterm>
  39 An event is data generated asynchronously by the X server as a result of some
  40 device activity or as side effects of a request sent by an Xlib function.
  41 <indexterm><primary>Event</primary></indexterm>
  42 Device-related events propagate from the source window to ancestor windows
  43 until some client application has selected that event type
  44 or until the event is explicitly discarded.
  45 The X server generally sends an event to a client application
  46 only if the client has specifically asked to be informed of that event type,
  47 typically by setting the event-mask attribute of the window.
  48 The mask can also be set when you create a window
  49 or by changing the window's
  50 event-mask.
  51 You can also mask out events that would propagate to ancestor windows
  52 by manipulating the
  53 do-not-propagate mask of the window's attributes.
  54 However,
  55 <symbol>MappingNotify</symbol>
  56 events are always sent to all clients.
  57 <indexterm><primary>Input Control</primary></indexterm>
  58 <indexterm><primary>Output Control</primary></indexterm>
  59 </para>
  60 <para>
  61 <!-- .LP -->
  62 An event type describes a specific event generated by the X server.
  63 For each event type,
  64 a corresponding constant name is defined in
  65 <filename class="headerfile">&lt;X11/X.h&gt;</filename>,
  66 <indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
  67 <indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>
  68 <indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>
  69 which is used when referring to an event type.
  70 <indexterm><primary>Event</primary><secondary>categories</secondary></indexterm>
  71 The following table lists the event category
  72 and its associated event type or types.
  73 The processing associated with these events is discussed in section 10.5.
  74 </para>
  75 <para>
  76 <!-- .LP -->
  77 <!-- .\".CP T 1 -->
  78 <!-- .\"Event Categories and Event Types -->
  79 </para>
  80 <para>
  81 <!-- .LP -->
  82 <informaltable frame='topbot'>
  83   <?dbfo keep-together="always" ?>
  84   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
  85   <colspec colname='c1' colwidth='1.0*'/>
  86   <colspec colname='c2' colwidth='4.0*'/>
  87   <thead>
  88     <row rowsep='1'>
  89       <entry>Event Category</entry>
  90       <entry>Event Type</entry>
  91     </row>
  92   </thead>
  93   <tbody>
  94     <row>
  95       <entry>Keyboard events</entry>
  96       <entry><symbol>KeyPress</symbol>,
  97       <symbol>KeyRelease</symbol></entry>
  98     </row>
  99     <row>
 100       <entry>Pointer events</entry>
 101       <entry><symbol>ButtonPress</symbol>,
 102       <symbol>ButtonRelease</symbol>,
 103       <symbol>MotionNotify</symbol></entry>
 104     </row>
 105     <row>
 106       <entry>Window crossing events</entry>
 107       <entry><symbol>EnterNotify</symbol>,
 108       <symbol>LeaveNotify</symbol></entry>
 109     </row>
 110     <row>
 111       <entry>Input focus events</entry>
 112       <entry><symbol>FocusIn</symbol>,
 113       <symbol>FocusOut</symbol></entry>
 114     </row>
 115     <row>
 116       <entry>Keymap state notification event</entry>
 117       <entry><symbol>KeymapNotify</symbol></entry>
 118     </row>
 119     <row>
 120       <entry>Exposure events</entry>
 121       <entry><symbol>Expose</symbol>,
 122       <symbol>GraphicsExpose</symbol>,
 123       <symbol>NoExpose</symbol></entry>
 124     </row>
 125     <row>
 126       <entry>Structure control events</entry>
 127       <entry><symbol>CirculateRequest</symbol>,
 128       <symbol>ConfigureRequest</symbol>,
 129       <symbol>MapRequest</symbol>,
 130       <symbol>ResizeRequest</symbol></entry>
 131     </row>
 132     <row>
 133       <entry>Window state notification events</entry>
 134       <entry>
 135       <symbol>CirculateNotify</symbol>,
 136       <symbol>ConfigureNotify</symbol>,
 137       <symbol>CreateNotify</symbol>,
 138       <symbol>DestroyNotify</symbol>,
 139       <symbol>GravityNotify</symbol>,
 140       <symbol>MapNotify</symbol>,
 141       <symbol>MappingNotify</symbol>,
 142       <symbol>ReparentNotify</symbol>,
 143       <symbol>UnmapNotify</symbol>,
 144       <symbol>VisibilityNotify</symbol></entry>
 145     </row>
 146     <row>
 147       <entry>Colormap state notification event</entry>
 148       <entry><symbol>ColormapNotify</symbol></entry>
 149     </row>
 150     <row>
 151       <entry>Client communication events</entry>
 152       <entry><symbol>ClientMessage</symbol>,
 153       <symbol>PropertyNotify</symbol>,
 154       <symbol>SelectionClear</symbol>,
 155       <symbol>SelectionNotify</symbol>,
 156       <symbol>SelectionRequest</symbol></entry>
 157     </row>
 158   </tbody>
 159   </tgroup>
 160 </informaltable>
 161
 162 <!-- .\".LP -->
 163 <!-- .\"Table 8-1 lists the event types and the Xlib functions that could cause -->
 164 <!-- .\"the X server to generate that event type. -->
 165 <!-- .\"The event types are listed alphabetically. -->
 166 <!-- .\"Note that the error event is not listed in this table. -->
 167 <!-- .\"For a list of the constants associated with an error event, see the Handling -->
 168 <!-- .\"Errors section in this chapter. -->
 169 <!-- .\".LP -->
 170 <!-- .\".so eventtable -->
 171 </para>
 172 </sect1>
 173 <sect1 id="Event_Structures">
 174 <title>Event Structures</title>
 175 <!-- .XS -->
 176 <!-- (SN Event Structures  -->
 177 <!-- .XE -->
 178 <para>
 179 <!-- .LP -->
 180 For each event type,
 181 a corresponding structure is declared in
 182 <filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.
 183 <indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
 184 <indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
 185 <indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
 186 All the event structures have the following common members:
 187 </para>
 188 <para>
 189 <!-- .LP -->
 190 <indexterm significance="preferred"><primary>XAnyEvent</primary></indexterm>
 191 <!-- .sM -->
 192 <literallayout class="monospaced">
 193 <!-- .TA .5i 3i -->
 194 <!-- .ta .5i 3i -->
 195 typedef struct {
 196      int           type;
 197      unsigned long serial;     /* # of last request processed by server */
 198      Bool          send_event; /* true if this came from a SendEvent request */
 199      Display       *display;   /* Display the event was read from */
 200      Window        window;
 201 } XAnyEvent;
 202 </literallayout>
 203 </para>
 204 <para>
 205 <!-- .LP -->
 206 <!-- .eM -->
 207 The type member is set to the event type constant name that uniquely identifies
 208 it.
 209 For example, when the X server reports a
 210 <symbol>GraphicsExpose</symbol>
 211 event to a client application, it sends an
 212 <structname>XGraphicsExposeEvent</structname>
 213 structure with the type member set to
 214 <symbol>GraphicsExpose</symbol>.
 215 The display member is set to a pointer to the display the event was read on.
 216 The send_event member is set to
 217 <symbol>True</symbol>
 218 if the event came from a
 219 <systemitem>SendEvent</systemitem>
 220 protocol request.
 221 The serial member is set from the serial number reported in the protocol
 222 but expanded from the 16-bit least-significant bits to a full 32-bit value.
 223 The window member is set to the window that is most useful to toolkit
 224 dispatchers.
 225 </para>
 226 <para>
 227 <!-- .LP -->
 228 The X server can send events at any time in the input stream.
 229 Xlib stores any events received while waiting for a reply in an event queue
 230 for later use.
 231 Xlib also provides functions that allow you to check events in the event queue
 232 (see <link linkend="Event_Queue_Management">section 11.3</link>).
 233 </para>
 234 <para>
 235 <!-- .LP -->
 236 In addition to the individual structures declared for each event type, the
 237 <structname>XEvent</structname>
 238 structure is a union of the individual structures declared for each event type.
 239 Depending on the type,
 240 you should access members of each event by using the
 241 <structname>XEvent</structname>
 242 union.
 243 </para>
 244 <para>
 245 <!-- .LP -->
 246 <indexterm significance="preferred"><primary>XEvent</primary></indexterm>
 247 <!-- .sM -->
 248 </para>
 249 <literallayout class="monospaced">
 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 </literallayout>
 288
 289 <para>
 290 <!-- .LP -->
 291 <!-- .eM -->
 292 An
 293 <structname>XEvent</structname>
 294 structure's first entry always is the type member,
 295 which is set to the event type.
 296 The second member always is the serial number of the protocol request
 297 that generated the event.
 298 The third member always is send_event,
 299 which is a
 300 <type>Bool</type>
 301 that indicates if the event was sent by a different client.
 302 The fourth member always is a display,
 303 which is the display that the event was read from.
 304 Except for keymap events,
 305 the fifth member always is a window,
 306 which has been carefully selected to be useful to toolkit dispatchers.
 307 To avoid breaking toolkits,
 308 the order of these first five entries is not to change.
 309 Most events also contain a time member,
 310 which is the time at which an event occurred.
 311 In addition, a pointer to the generic event must be cast before it
 312 is used to access any other information in the structure.
 313 </para>
 314 </sect1>
 315 <sect1 id="Event_Masks">
 316 <title>Event Masks</title>
 317 <!-- .XS -->
 318 <!-- (SN Event Masks -->
 319 <!-- .XE -->
 320 <para>
 321 <!-- .LP -->
 322 <indexterm significance="preferred"><primary>Event mask</primary></indexterm>
 323 Clients select event reporting of most events relative to a window.
 324 To do this, pass an event mask to an Xlib event-handling
 325 function that takes an event_mask argument.
 326 The bits of the event mask are defined in
 327 <filename class="headerfile">&lt;X11/X.h&gt;</filename>.
 328 <indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
 329 <indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>
 330 <indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/X.h&gt;</filename></secondary></indexterm>
 331 Each bit in the event mask maps to an event mask name,
 332 which describes the event or events you want the X server to
 333 return to a client application.
 334 </para>
 335 <para>
 336 <!-- .LP -->
 337 Unless the client has specifically asked for them,
 338 most events are not reported to clients when they are generated.
 339 Unless the client suppresses them by setting graphics-exposures in the GC to
 340 <symbol>False</symbol>,
 341 <symbol>GraphicsExpose</symbol>
 342 and
 343 <symbol>NoExpose</symbol>
 344 are reported by default as a result of
 345 <xref linkend='XCopyPlane' xrefstyle='select: title'/>
 346 and
 347 <xref linkend='XCopyArea' xrefstyle='select: title'/>.
 348 <symbol>SelectionClear</symbol>,
 349 <symbol>SelectionRequest</symbol>,
 350 <symbol>SelectionNotify</symbol>,
 351 or
 352 <symbol>ClientMessage</symbol>
 353 cannot be masked.
 354 Selection-related events are only sent to clients cooperating
 355 with selections
 356 (see <link linkend="Obtaining_and_Changing_Window_Properties">section 4.5</link>).
 357 When the keyboard or pointer mapping is changed,
 358 <symbol>MappingNotify</symbol>
 359 is always sent to clients.
 360 </para>
 361 <para>
 362 <!-- .LP -->
 363 <!-- .\"Table 8-2  -->
 364 The following table
 365 lists the event mask constants you can pass to
 366 the event_mask argument and
 367 the circumstances in which you would want to specify the
 368 event mask:
 369 </para>
 370 <!-- .LP -->
 371 <!-- .\" .CP T 2 -->
 372 <!-- .\"Event Mask Definitions -->
 373 <informaltable frame='topbot'>
 374   <?dbfo keep-together="auto" ?>
 375   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 376   <colspec colname='c1' colwidth='1.0*'/>
 377   <colspec colname='c2' colwidth='2.5*'/>
 378   <thead>
 379     <row rowsep='1'>
 380       <entry>Event Mask</entry>
 381       <entry>Circumstances</entry>
 382     </row>
 383   </thead>
 384   <tbody>
 385     <row>
 386       <entry><symbol>NoEventMask</symbol></entry>
 387       <entry>No events wanted</entry>
 388     </row>
 389     <row>
 390       <entry><symbol>KeyPressMask</symbol></entry>
 391       <entry>Keyboard down events wanted</entry>
 392     </row>
 393     <row>
 394       <entry><symbol>KeyReleaseMask</symbol></entry>
 395       <entry>Keyboard up events wanted</entry>
 396     </row>
 397     <row>
 398       <entry><symbol>ButtonPressMask</symbol></entry>
 399       <entry>Pointer button down events wanted</entry>
 400     </row>
 401     <row>
 402       <entry><symbol>ButtonReleaseMask</symbol></entry>
 403       <entry>Pointer button up events wanted</entry>
 404     </row>
 405     <row>
 406       <entry><symbol>EnterWindowMask</symbol></entry>
 407       <entry>Pointer window entry events wanted</entry>
 408     </row>
 409     <row>
 410       <entry><symbol>LeaveWindowMask</symbol></entry>
 411       <entry>Pointer window leave events wanted</entry>
 412     </row>
 413     <row>
 414       <entry><symbol>PointerMotionMask</symbol></entry>
 415       <entry>Pointer motion events wanted</entry>
 416     </row>
 417     <row>
 418       <entry><symbol>PointerMotionHintMask</symbol></entry>
 419       <entry>Pointer motion hints wanted</entry>
 420     </row>
 421     <row>
 422       <entry><symbol>Button1MotionMask</symbol></entry>
 423       <entry>Pointer motion while button 1 down</entry>
 424     </row>
 425     <row>
 426       <entry><symbol>Button2MotionMask</symbol></entry>
 427       <entry>Pointer motion while button 2 down</entry>
 428     </row>
 429     <row>
 430       <entry><symbol>Button3MotionMask</symbol></entry>
 431       <entry>Pointer motion while button 3 down</entry>
 432     </row>
 433     <row>
 434       <entry><symbol>Button4MotionMask</symbol></entry>
 435       <entry>Pointer motion while button 4 down</entry>
 436     </row>
 437     <row>
 438       <entry><symbol>Button5MotionMask</symbol></entry>
 439       <entry>Pointer motion while button 5 down</entry>
 440     </row>
 441     <row>
 442       <entry><symbol>ButtonMotionMask</symbol></entry>
 443       <entry>Pointer motion while any button down</entry>
 444     </row>
 445     <row>
 446       <entry><symbol>KeymapStateMask</symbol></entry>
 447       <entry>Keyboard state wanted at window entry and focus in</entry>
 448     </row>
 449     <row>
 450       <entry><symbol>ExposureMask</symbol></entry>
 451       <entry>Any exposure wanted</entry>
 452     </row>
 453     <row>
 454       <entry><symbol>VisibilityChangeMask</symbol></entry>
 455       <entry>Any change in visibility wanted</entry>
 456     </row>
 457     <row>
 458       <entry><symbol>StructureNotifyMask</symbol></entry>
 459       <entry>Any change in window structure wanted</entry>
 460     </row>
 461     <row>
 462       <entry><symbol>ResizeRedirectMask</symbol></entry>
 463       <entry>Redirect resize of this window</entry>
 464     </row>
 465     <row>
 466       <entry><symbol>SubstructureNotifyMask</symbol></entry>
 467       <entry>Substructure notification wanted</entry>
 468     </row>
 469     <row>
 470       <entry><symbol>SubstructureRedirectMask</symbol></entry>
 471       <entry>Redirect structure requests on children</entry>
 472     </row>
 473     <row>
 474       <entry><symbol>FocusChangeMask</symbol></entry>
 475       <entry>Any change in input focus wanted</entry>
 476     </row>
 477     <row>
 478       <entry><symbol>PropertyChangeMask</symbol></entry>
 479       <entry>Any change in property wanted</entry>
 480     </row>
 481     <row>
 482       <entry><symbol>ColormapChangeMask</symbol></entry>
 483       <entry>Any change in colormap wanted</entry>
 484     </row>
 485     <row>
 486       <entry><symbol>OwnerGrabButtonMask</symbol></entry>
 487       <entry>Automatic grabs should activate with owner_events set to True</entry>
 488     </row>
 489   </tbody>
 490   </tgroup>
 491 </informaltable>
 492
 493 <para>
 494 <!-- .LP -->
 495 </para>
 496 </sect1>
 497 <sect1 id="Event_Processing_Overview">
 498 <title>Event Processing Overview</title>
 499 <!-- .XS -->
 500 <!-- (SN Event Processing Overview -->
 501 <!-- .XE -->
 502 <para>
 503 <!-- .LP -->
 504 The event reported to a client application during event processing
 505 depends on which event masks you provide as the event-mask attribute
 506 for a window.
 507 For some event masks, there is a one-to-one correspondence between
 508 the event mask constant and the event type constant.
 509 For example, if you pass the event mask
 510 <symbol>ButtonPressMask</symbol>,
 511 the X server sends back only
 512 <symbol>ButtonPress</symbol>
 513 events.
 514 <indexterm><primary>CurrentTime</primary></indexterm>
 515 Most events contain a time member,
 516 which is the time at which an event occurred.
 517 </para>
 518 <para>
 519 <!-- .LP -->
 520 In other cases, one event mask constant can map to several event type constants.
 521 For example, if you pass the event mask
 522 <symbol>SubstructureNotifyMask</symbol>,
 523 the X server can send back
 524 <symbol>CirculateNotify</symbol>,
 525 <symbol>ConfigureNotify</symbol>,
 526 <symbol>CreateNotify</symbol>,
 527 <symbol>DestroyNotify</symbol>,
 528 <symbol>GravityNotify</symbol>,
 529 <symbol>MapNotify</symbol>,
 530 <symbol>ReparentNotify</symbol>,
 531 or
 532 <symbol>UnmapNotify</symbol>
 533 events.
 534 </para>
 535 <para>
 536 <!-- .LP -->
 537 In another case,
 538 two event masks can map to one event type.
 539 For example,
 540 if you pass either
 541 <symbol>PointerMotionMask</symbol>
 542 or
 543 <symbol>ButtonMotionMask</symbol>,
 544 the X server sends back
 545 a
 546 <symbol>MotionNotify</symbol>
 547 event.
 548 </para>
 549 <para>
 550 <!-- .LP -->
 551 The following table
 552 lists the event mask,
 553 its associated event type or types,
 554 and the structure name associated with the event type.
 555 Some of these structures actually are typedefs to a generic structure
 556 that is shared between two event types.
 557 Note that N.A. appears in columns for which the information is not applicable.
 558 </para>
 559 <!-- .LP -->
 560 <!-- .ps 9 -->
 561 <!-- .nr PS 9 -->
 562 <informaltable frame='topbot'>
 563   <?dbfo keep-together="auto" ?>
 564   <tgroup cols='4' align='left' colsep='0' rowsep='0'>
 565   <colspec colname='c1' colwidth='1.2*'/>
 566   <colspec colname='c2' colwidth='1.0*'/>
 567   <colspec colname='c3' colwidth='1.2*'/>
 568   <colspec colname='c4' colwidth='1.0*'/>
 569   <thead>
 570     <row rowsep='1'>
 571       <entry>Event Mask</entry>
 572       <entry>Event Type</entry>
 573       <entry>Structure</entry>
 574       <entry>Generic Structure</entry>
 575     </row>
 576   </thead>
 577   <tbody>
 578     <row>
 579       <entry>
 580       <para>ButtonMotionMask</para>
 581       <para>Button1MotionMask</para>
 582       <para>Button2MotionMask</para>
 583       <para>Button3MotionMask</para>
 584       <para>Button4MotionMask</para>
 585       <para>Button5MotionMask</para>
 586       </entry>
 587       <entry>MotionNotify</entry>
 588       <entry>XPointerMovedEvent</entry>
 589       <entry>XMotionEvent</entry>
 590     </row>
 591     <row>
 592       <entry>ButtonPressMask</entry>
 593       <entry>ButtonPress</entry>
 594       <entry>XButtonPressedEvent</entry>
 595       <entry>XButtonEvent</entry>
 596     </row>
 597     <row>
 598       <entry>ButtonReleaseMask</entry>
 599       <entry>ButtonRelease</entry>
 600       <entry>XButtonReleasedEvent</entry>
 601       <entry>XButtonEvent</entry>
 602     </row>
 603     <row>
 604       <entry>ColormapChangeMask</entry>
 605       <entry>ColormapNotify</entry>
 606       <entry>XColormapEvent</entry>
 607     </row>
 608     <row>
 609       <entry>EnterWindowMask</entry>
 610       <entry>EnterNotify</entry>
 611       <entry>XEnterWindowEvent</entry>
 612       <entry>XCrossingEvent</entry>
 613     </row>
 614     <row>
 615       <entry>LeaveWindowMask</entry>
 616       <entry>LeaveNotify</entry>
 617       <entry>XLeaveWindowEvent</entry>
 618       <entry>XCrossingEvent</entry>
 619     </row>
 620     <row>
 621       <entry>ExposureMask</entry>
 622       <entry>Expose</entry>
 623       <entry>XExposeEvent </entry>
 624     </row>
 625     <row>
 626       <entry morerows='1'>GCGraphicsExposures in GC</entry>
 627       <entry>GraphicsExpose</entry>
 628       <entry>XGraphicsExposeEvent</entry>
 629     </row>
 630     <row>
 631       <entry>NoExpose</entry>
 632       <entry>XNoExposeEvent</entry>
 633     </row>
 634     <row>
 635       <entry morerows='1'>FocusChangeMask</entry>
 636       <entry>FocusIn</entry>
 637       <entry>XFocusInEvent</entry>
 638       <entry>XFocusChangeEvent</entry>
 639     </row>
 640     <row>
 641       <entry>FocusOut</entry>
 642       <entry>XFocusOutEvent</entry>
 643       <entry>XFocusChangeEvent</entry>
 644     </row>
 645     <row>
 646       <entry>KeymapStateMask</entry>
 647       <entry>KeymapNotify</entry>
 648       <entry>XKeymapEvent</entry>
 649     </row>
 650     <row>
 651       <entry>KeyPressMask</entry>
 652       <entry>KeyPress</entry>
 653       <entry>XKeyPressedEvent</entry>
 654       <entry>XKeyEvent</entry>
 655     </row>
 656     <row>
 657       <entry>KeyReleaseMask</entry>
 658       <entry>KeyRelease</entry>
 659       <entry>XKeyReleasedEvent</entry>
 660       <entry>XKeyEvent</entry>
 661     </row>
 662     <row>
 663       <entry>OwnerGrabButtonMask</entry>
 664       <entry>N.A.</entry>
 665       <entry>N.A.</entry>
 666     </row>
 667     <row>
 668       <entry>PointerMotionMask</entry>
 669       <entry>MotionNotify</entry>
 670       <entry>XPointerMovedEvent</entry>
 671       <entry>XMotionEvent</entry>
 672     </row>
 673     <row>
 674       <entry>PointerMotionHintMask</entry>
 675       <entry>N.A.</entry>
 676       <entry>N.A.</entry>
 677     </row>
 678     <row>
 679       <entry>PropertyChangeMask</entry>
 680       <entry>PropertyNotify</entry>
 681       <entry>XPropertyEvent</entry>
 682     </row>
 683     <row>
 684       <entry>ResizeRedirectMask</entry>
 685       <entry>ResizeRequest</entry>
 686       <entry>XResizeRequestEvent</entry>
 687     </row>
 688     <row>
 689       <entry morerows='6'>StructureNotifyMask</entry>
 690       <entry>CirculateNotify</entry>
 691       <entry>XCirculateEvent</entry>
 692     </row>
 693     <row>
 694       <entry>ConfigureNotify</entry>
 695       <entry>XConfigureEvent</entry>
 696     </row>
 697     <row>
 698       <entry>DestroyNotify</entry>
 699       <entry>XDestroyWindowEvent</entry>
 700     </row>
 701     <row>
 702       <entry>GravityNotify</entry>
 703       <entry>XGravityEvent</entry>
 704     </row>
 705     <row>
 706       <entry>MapNotify</entry>
 707       <entry>XMapEvent</entry>
 708     </row>
 709     <row>
 710       <entry>ReparentNotify</entry>
 711       <entry>XReparentEvent</entry>
 712     </row>
 713     <row>
 714       <entry>UnmapNotify</entry>
 715       <entry>XUnmapEvent</entry>
 716     </row>
 717     <row>
 718       <entry morerows='7'>SubstructureNotifyMask</entry>
 719       <entry>CirculateNotify</entry>
 720       <entry>XCirculateEvent</entry>
 721     </row>
 722     <row>
 723       <entry>ConfigureNotify</entry>
 724       <entry>XConfigureEvent</entry>
 725     </row>
 726     <row>
 727       <entry>CreateNotify</entry>
 728       <entry>XCreateWindowEvent</entry>
 729     </row>
 730     <row>
 731       <entry>DestroyNotify</entry>
 732       <entry>XDestroyWindowEvent</entry>
 733     </row>
 734     <row>
 735       <entry>GravityNotify</entry>
 736       <entry>XGravityEvent</entry>
 737     </row>
 738     <row>
 739       <entry>MapNotify</entry>
 740       <entry>XMapEvent</entry>
 741     </row>
 742     <row>
 743       <entry>ReparentNotify</entry>
 744       <entry>XReparentEvent</entry>
 745     </row>
 746     <row>
 747       <entry>UnmapNotify</entry>
 748       <entry>XUnmapEvent</entry>
 749     </row>
 750     <row>
 751       <entry morerows='2'>SubstructureRedirectMask</entry>
 752       <entry>CirculateRequest</entry>
 753       <entry>XCirculateRequestEvent</entry>
 754     </row>
 755     <row>
 756       <entry>ConfigureRequest</entry>
 757       <entry>XConfigureRequestEvent</entry>
 758     </row>
 759     <row>
 760       <entry>MapRequest</entry>
 761       <entry>XMapRequestEvent</entry>
 762     </row>
 763     <row>
 764       <entry>N.A.</entry>
 765       <entry>ClientMessage</entry>
 766       <entry>XClientMessageEvent</entry>
 767     </row>
 768     <row>
 769       <entry>N.A.</entry>
 770       <entry>MappingNotify</entry>
 771       <entry>XMappingEvent</entry>
 772     </row>
 773     <row>
 774       <entry>N.A.</entry>
 775       <entry>SelectionClear</entry>
 776       <entry>XSelectionClearEvent</entry>
 777     </row>
 778     <row>
 779       <entry>N.A.</entry>
 780       <entry>SelectionNotify</entry>
 781       <entry>XSelectionEvent</entry>
 782     </row>
 783     <row>
 784       <entry>N.A.</entry>
 785       <entry>SelectionRequest</entry>
 786       <entry>XSelectionRequestEvent</entry>
 787     </row>
 788     <row>
 789       <entry>VisibilityChangeMask</entry>
 790       <entry>VisibilityNotify</entry>
 791       <entry>XVisibilityEvent</entry>
 792     </row>
 793   </tbody>
 794   </tgroup>
 795 </informaltable>
 796
 797 <para>
 798 <!-- .LP -->
 799 The sections that follow describe the processing that occurs
 800 when you select the different event masks.
 801 The sections are organized according to these processing categories:
 802 </para>
 803 <itemizedlist>
 804   <listitem>
 805     <para>
 806 Keyboard and pointer events
 807     </para>
 808   </listitem>
 809   <listitem>
 810     <para>
 811 Window crossing events
 812     </para>
 813   </listitem>
 814   <listitem>
 815     <para>
 816 Input focus events
 817     </para>
 818   </listitem>
 819   <listitem>
 820     <para>
 821 Keymap state notification events
 822     </para>
 823   </listitem>
 824   <listitem>
 825     <para>
 826 Exposure events
 827     </para>
 828   </listitem>
 829   <listitem>
 830     <para>
 831 Window state notification events
 832     </para>
 833   </listitem>
 834   <listitem>
 835     <para>
 836 Structure control events
 837     </para>
 838   </listitem>
 839   <listitem>
 840     <para>
 841 Colormap state notification events
 842     </para>
 843   </listitem>
 844   <listitem>
 845     <para>
 846 Client communication events
 847     </para>
 848   </listitem>
 849 </itemizedlist>
 850
 851 </sect1>
 852
 853 <sect1 id="Keyboard_and_Pointer_Events">
 854 <title>Keyboard and Pointer Events</title>
 855 <!-- .XS -->
 856 <!-- (SN Keyboard and Pointer Events -->
 857 <!-- .XE -->
 858 <para>
 859 <!-- .LP -->
 860 This section discusses:
 861 </para>
 862 <itemizedlist>
 863   <listitem>
 864     <para>
 865 Pointer button events
 866     </para>
 867   </listitem>
 868   <listitem>
 869     <para>
 870 Keyboard and pointer events
 871     </para>
 872   </listitem>
 873 </itemizedlist>
 874 <sect2 id="Pointer_Button_Events">
 875 <title>Pointer Button Events</title>
 876 <!-- .XS -->
 877 <!-- (SN Pointer Button Events -->
 878 <!-- .XE -->
 879 <para>
 880 <!-- .LP -->
 881 The following describes the event processing that occurs when a pointer button
 882 press is processed with the pointer in some window w and
 883 when no active pointer grab is in progress.
 884 </para>
 885 <para>
 886 <!-- .LP -->
 887 The X server searches the ancestors of w from the root down,
 888 looking for a passive grab to activate.
 889 If no matching passive grab on the button exists,
 890 the X server automatically starts an active grab for the client receiving
 891 the event and sets the last-pointer-grab time to the current server time.
 892 The effect is essentially equivalent to an
 893 <xref linkend='XGrabButton' xrefstyle='select: title'/>
 894 with these client passed arguments:
 895 </para>
 896 <informaltable frame='topbot'>
 897   <?dbfo keep-together="always" ?>
 898   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
 899   <colspec colname='c1' colwidth='1.0*'/>
 900   <colspec colname='c2' colwidth='4.0*'/>
 901   <thead>
 902     <row rowsep='1'>
 903       <entry>Argument</entry>
 904       <entry>Value</entry>
 905     </row>
 906   </thead>
 907   <tbody>
 908     <row>
 909       <entry><emphasis remap='I'>w</emphasis></entry>
 910       <entry>The event window </entry>
 911     </row>
 912     <row>
 913       <entry><emphasis remap='I'>event_mask</emphasis></entry>
 914       <entry>The client's selected pointer events on the event window</entry>
 915     </row>
 916     <row>
 917       <entry><emphasis remap='I'>pointer_mode</emphasis></entry>
 918       <entry><symbol>GrabModeAsync</symbol></entry>
 919     </row>
 920     <row>
 921       <entry><emphasis remap='I'>keyboard_mode</emphasis></entry>
 922       <entry><symbol>GrabModeAsync</symbol></entry>
 923     </row>
 924     <row>
 925       <entry><emphasis remap='I'>owner_events</emphasis></entry>
 926       <entry><symbol>True</symbol>,
 927       if the client has selected
 928       <symbol>OwnerGrabButtonMask</symbol>
 929       on the event window,
 930       otherwise
 931       <symbol>False</symbol></entry>
 932     </row>
 933     <row>
 934       <entry><emphasis remap='I'>confine_to</emphasis></entry>
 935       <entry><symbol>None</symbol></entry>
 936     </row>
 937     <row>
 938       <entry><emphasis remap='I'>cursor</emphasis></entry>
 939       <entry><symbol>None</symbol></entry>
 940     </row>
 941   </tbody>
 942   </tgroup>
 943 </informaltable>
 944
 945 <para>
 946 <!-- .LP -->
 947 The active grab is automatically terminated when
 948 the logical state of the pointer has all buttons released.
 949 Clients can modify the active grab by calling
 950 <xref linkend='XUngrabPointer' xrefstyle='select: title'/>
 951 and
 952 <xref linkend='XChangeActivePointerGrab' xrefstyle='select: title'/>.
 953 </para>
 954 </sect2>
 955
 956 <sect2 id="Keyboard_and_Pointer_Events_b">
 957 <title>Keyboard and Pointer Events</title>
 958 <!-- .XS -->
 959 <!-- (SN Keyboard and Pointer Events -->
 960 <!-- .XE -->
 961 <para>
 962 <!-- .LP -->
 963 <indexterm><primary>Events</primary><secondary>ButtonPress</secondary></indexterm>
 964 <indexterm><primary>Events</primary><secondary>ButtonRelease</secondary></indexterm>
 965 <indexterm><primary>Events</primary><secondary>KeyPress</secondary></indexterm>
 966 <indexterm><primary>Events</primary><secondary>KeyRelease</secondary></indexterm>
 967 <indexterm><primary>Events</primary><secondary>MotionNotify</secondary></indexterm>
 968 This section discusses the processing that occurs for the
 969 keyboard events
 970 <symbol>KeyPress</symbol>
 971 and
 972 <symbol>KeyRelease</symbol>
 973 and the pointer events
 974 <symbol>ButtonPress</symbol>,
 975 <symbol>ButtonRelease</symbol>,
 976 and
 977 <symbol>MotionNotify</symbol>.
 978 For information about the keyboard event-handling utilities,
 979 see <link linkend='Event_Handling_Functions'>chapter 11</link>.
 980 </para>
 981 <para>
 982 <!-- .LP -->
 983 <indexterm significance="preferred"><primary>KeyPress</primary></indexterm>
 984 <indexterm significance="preferred"><primary>KeyRelease</primary></indexterm>
 985 The X server reports
 986 <symbol>KeyPress</symbol>
 987 or
 988 <symbol>KeyRelease</symbol>
 989 events to clients wanting information about keys that logically change state.
 990 Note that these events are generated for all keys,
 991 even those mapped to modifier bits.
 992 <indexterm significance="preferred"><primary>ButtonPress</primary></indexterm>
 993 <indexterm significance="preferred"><primary>ButtonRelease</primary></indexterm>
 994 The X server reports
 995 <symbol>ButtonPress</symbol>
 996 or
 997 <symbol>ButtonRelease</symbol>
 998 events to clients wanting information about buttons that logically change state.
 999 </para>
1000 <para>
1001 <!-- .LP -->
1002 <indexterm significance="preferred"><primary>MotionNotify</primary></indexterm>
1003 The X server reports
1004 <symbol>MotionNotify</symbol>
1005 events to clients wanting information about when the pointer logically moves.
1006 The X server generates this event whenever the pointer is moved
1007 and the pointer motion begins and ends in the window.
1008 The granularity of
1009 <symbol>MotionNotify</symbol>
1010 events is not guaranteed,
1011 but a client that selects this event type is guaranteed
1012 to receive at least one event when the pointer moves and then rests.
1013 </para>
1014 <para>
1015 <!-- .LP -->
1016 The generation of the logical changes lags the physical changes
1017 if device event processing is frozen.
1018 </para>
1019 <para>
1020 <!-- .LP -->
1021 To receive
1022 <symbol>KeyPress</symbol>,
1023 <symbol>KeyRelease</symbol>,
1024 <symbol>ButtonPress</symbol>,
1025 and
1026 <symbol>ButtonRelease</symbol>
1027 events, set
1028 <symbol>KeyPressMask</symbol>,
1029 <symbol>KeyReleaseMask</symbol>,
1030 <symbol>ButtonPressMask</symbol>,
1031 and
1032 <symbol>ButtonReleaseMask</symbol>
1033 bits in the event-mask attribute of the window.
1034 </para>
1035 <para>
1036 <!-- .LP -->
1037 To receive
1038 <symbol>MotionNotify</symbol>
1039 events, set one or more of the following event
1040 masks bits in the event-mask attribute of the window.
1041 </para>
1042 <itemizedlist>
1043   <listitem>
1044     <para>
1045 <symbol>Button1MotionMask</symbol> - <symbol>Button5MotionMask</symbol>
1046     </para>
1047   </listitem>
1048   <listitem>
1049     <para>
1050 The client application receives
1051 <symbol>MotionNotify</symbol>
1052 events only when one or more of the specified buttons is pressed.
1053     </para>
1054   </listitem>
1055   <listitem>
1056     <para>
1057 <symbol>ButtonMotionMask</symbol>
1058     </para>
1059   </listitem>
1060   <listitem>
1061     <para>
1062 The client application receives
1063 <symbol>MotionNotify</symbol>
1064 events only when at least one button is pressed.
1065     </para>
1066   </listitem>
1067   <listitem>
1068     <para>
1069 <symbol>PointerMotionMask</symbol>
1070     </para>
1071   </listitem>
1072   <listitem>
1073     <para>
1074 The client application receives
1075 <symbol>MotionNotify</symbol>
1076 events independent of the state of
1077 the pointer buttons.
1078     </para>
1079   </listitem>
1080   <listitem>
1081     <para>
1082 <symbol>PointerMotionHintMask</symbol>
1083     </para>
1084   </listitem>
1085   <listitem>
1086     <para>
1087 If
1088 <symbol>PointerMotionHintMask</symbol>
1089 is selected in combination with one or more of the above masks,
1090 the X server is free to send only one
1091 <symbol>MotionNotify</symbol>
1092 event (with the is_hint member  of the
1093 <type>XPointerMovedEvent</type>
1094 structure set to
1095 <symbol>NotifyHint</symbol>)
1096 to the client for the event window,
1097 until either the key or button state changes,
1098 the pointer leaves the event window, or the client calls
1099 <xref linkend='XQueryPointer' xrefstyle='select: title'/>
1100 or
1101 <xref linkend='XGetMotionEvents' xrefstyle='select: title'/>.
1102 The server still may send
1103 <symbol>MotionNotify</symbol>
1104 events without is_hint set to
1105 <symbol>NotifyHint</symbol>.
1106     </para>
1107   </listitem>
1108 </itemizedlist>
1109 <para>
1110 <!-- .LP -->
1111 The source of the event is the viewable window that the pointer is in.
1112 The window used by the X server to report these events depends on
1113 the window's position in the window hierarchy
1114 and whether any intervening window prohibits the generation of these events.
1115 Starting with the source window,
1116 the X server searches up the window hierarchy until it locates the first
1117 window specified by a client as having an interest in these events.
1118 If one of the intervening windows has its do-not-propagate-mask
1119 set to prohibit generation of the event type,
1120 the events of those types will be suppressed.
1121 Clients can modify the actual window used for reporting by performing
1122 active grabs and, in the case of keyboard events, by using the focus window.
1123 </para>
1124 <para>
1125 <!-- .LP -->
1126 The structures for these event types contain:
1127 </para>
1128 <literallayout class="monospaced">
1129 typedef struct {
1130      int            type;            /* ButtonPress or ButtonRelease */
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 it is 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      unsigned int   state;           /* key or button mask */
1141      unsigned int   button;          /* detail */
1142      Bool           same_screen;     /* same screen flag */
1143 } XButtonEvent;
1144 typedef XButtonEvent XButtonPressedEvent;
1145 typedef XButtonEvent XButtonReleasedEvent;
1146 </literallayout>
1147
1148 <literallayout class="monospaced">
1149 typedef struct {
1150      int            type;            /* KeyPress or KeyRelease */
1151      unsigned long  serial;          /* # of last request processed by server */
1152      Bool           send_event;      /* true if this came from a SendEvent request */
1153      Display        *display;        /* Display the event was read from */
1154      Window         window;          /* ``event'' window it is reported relative to */
1155      Window         root;            /* root window that the event occurred on */
1156      Window         subwindow;       /* child window */
1157      Time           time;            /* milliseconds */
1158      int            x, y;            /* pointer x, y coordinates in event window */
1159      int            x_root, y_root;  /* coordinates relative to root */
1160      unsigned int   state;           /* key or button mask */
1161      unsigned int   keycode;         /* detail */
1162      Bool           same_screen;     /* same screen flag */
1163 } XKeyEvent;
1164 typedef XKeyEvent XKeyPressedEvent;
1165 typedef XKeyEvent XKeyReleasedEvent;
1166 </literallayout>
1167
1168 <literallayout class="monospaced">
1169 typedef struct {
1170      int            type;              /* MotionNotify */
1171      unsigned long  serial;            /* # of last request processed by server */
1172      Bool           send_event;        /* true if this came from a SendEvent request */
1173      Display        *display;          /* Display the event was read from */
1174      Window         window;            /* ``event'' window reported relative to */
1175      Window         root;              /* root window that the event occurred on */
1176      Window         subwindow;         /* child window */
1177      Time           time;              /* milliseconds */
1178      int            x, y;              /* pointer x, y coordinates in event window */
1179      int            x_root, y_root;    /* coordinates relative to root */
1180      unsigned int   state;             /* key or button mask */
1181      char           is_hint;           /* detail */
1182      Bool           same_screen;       /* same screen flag */
1183 } XMotionEvent;
1184 typedef XMotionEvent XPointerMovedEvent;
1185 </literallayout>
1186
1187 <para>
1188 These structures have the following common members:
1189 window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen.
1190 The window member is set to the window on which the
1191 event was generated and is referred to as the event window.
1192 As long as the conditions previously discussed are met,
1193 this is the window used by the X server to report the event.
1194 The root member is set to the source window's root window.
1195 The x_root and y_root members are set to the pointer's coordinates
1196 relative to the root window's origin at the time of the event.
1197 </para>
1198
1199 <para>
1200 <!-- .LP -->
1201 The same_screen member is set to indicate whether the event
1202 window is on the same screen
1203 as the root window and can be either
1204 <symbol>True</symbol>
1205 or
1206 <symbol>False</symbol>.
1207 If
1208 <symbol>True</symbol>,
1209 the event and root windows are on the same screen.
1210 If
1211 <symbol>False</symbol>,
1212 the event and root windows are not on the same screen.
1213 </para>
1214 <para>
1215 <!-- .LP -->
1216 If the source window is an inferior of the event window,
1217 the subwindow member of the structure is set to the child of the event window
1218 that is the source window or the child of the event window that is
1219 an ancestor of the source window.
1220 Otherwise, the X server sets the subwindow member to
1221 <symbol>None</symbol>.
1222 The time member is set to the time when the event was generated
1223 and is expressed in milliseconds.
1224 </para>
1225 <para>
1226 <!-- .LP -->
1227 If the event window is on the same screen as the root window,
1228 the x and y members
1229 are set to the coordinates relative to the event window's origin.
1230 Otherwise, these members are set to zero.
1231 </para>
1232 <para>
1233 <!-- .LP -->
1234 The state member is set to indicate the logical state of the pointer buttons
1235 and modifier keys just prior to the event,
1236 which is the bitwise inclusive OR of one or more of the
1237 button or modifier key masks:
1238 <symbol>Button1Mask</symbol>,
1239 <symbol>Button2Mask</symbol>,
1240 <symbol>Button3Mask</symbol>,
1241 <symbol>Button4Mask</symbol>,
1242 <symbol>Button5Mask</symbol>,
1243 <symbol>ShiftMask</symbol>,
1244 <symbol>LockMask</symbol>,
1245 <symbol>ControlMask</symbol>,
1246 <symbol>Mod1Mask</symbol>,
1247 <symbol>Mod2Mask</symbol>,
1248 <symbol>Mod3Mask</symbol>,
1249 <symbol>Mod4Mask</symbol>,
1250 and
1251 <symbol>Mod5Mask</symbol>.
1252 </para>
1253 <para>
1254 <!-- .LP -->
1255 Each of these structures also has a member that indicates the detail.
1256 For the
1257 <type>XKeyPressedEvent</type>
1258 and
1259 <type>XKeyReleasedEvent</type>
1260 structures, this member is called a keycode.
1261 It is set to a number that represents a physical key on the keyboard.
1262 The keycode is an arbitrary representation for any key on the keyboard
1263 (see sections <link linkend="Manipulating_the_Keyboard_Encoding">12.7</link>
1264  and <link linkend="Using_Keyboard_Utility_Functions">16.1</link>).
1265 </para>
1266 <para>
1267 <!-- .LP -->
1268 For the
1269 <type>XButtonPressedEvent</type>
1270 and
1271 <type>XButtonReleasedEvent</type>
1272 structures, this member is called button.
1273 It represents the pointer button that changed state and can be the
1274 <symbol>Button1</symbol>,
1275 <symbol>Button2</symbol>,
1276 <symbol>Button3</symbol>,
1277 <symbol>Button4</symbol>,
1278 or
1279 <symbol>Button5</symbol>
1280 value.
1281 For the
1282 <type>XPointerMovedEvent</type>
1283 structure, this member is called is_hint.
1284 It can be set to
1285 <symbol>NotifyNormal</symbol>
1286 or
1287 <symbol>NotifyHint</symbol>.
1288 </para>
1289 <para>
1290 <!-- .LP -->
1291 Some of the symbols mentioned in this section have fixed values, as
1292 follows:
1293 </para>
1294 <informaltable frame='topbot'>
1295   <?dbfo keep-together="always" ?>
1296   <tgroup cols='2' align='left' colsep='0' rowsep='0'>
1297   <colspec colname='c1' colwidth='1.0*'/>
1298   <colspec colname='c2' colwidth='3.0*'/>
1299   <thead>
1300     <row rowsep='1'>
1301       <entry>Symbol</entry>
1302       <entry>Value</entry>
1303     </row>
1304   </thead>
1305   <tbody>
1306     <row>
1307       <entry><symbol>Button1MotionMask</symbol></entry>
1308       <entry>(1L&lt;&lt;8)</entry>
1309     </row>
1310     <row>
1311       <entry><symbol>Button2MotionMask</symbol></entry>
1312       <entry>(1L&lt;&lt;9)</entry>
1313     </row>
1314     <row>
1315       <entry><symbol>Button3MotionMask</symbol></entry>
1316       <entry>(1L&lt;&lt;10)</entry>
1317     </row>
1318     <row>
1319       <entry><symbol>Button4MotionMask</symbol></entry>
1320       <entry>(1L&lt;&lt;11)</entry>
1321     </row>
1322     <row>
1323       <entry><symbol>Button5MotionMask</symbol></entry>
1324       <entry>(1L&lt;&lt;12)</entry>
1325     </row>
1326     <row>
1327       <entry><symbol>Button1Mask</symbol></entry>
1328       <entry>(1&lt;&lt;8)</entry>
1329     </row>
1330     <row>
1331       <entry><symbol>Button2Mask</symbol></entry>
1332       <entry>(1&lt;&lt;9)</entry>
1333     </row>
1334     <row>
1335       <entry><symbol>Button3Mask</symbol></entry>
1336       <entry>(1&lt;&lt;10)</entry>
1337     </row>
1338     <row>
1339       <entry><symbol>Button4Mask</symbol></entry>
1340       <entry>(1&lt;&lt;11)</entry>
1341     </row>
1342     <row>
1343       <entry><symbol>Button5Mask</symbol></entry>
1344       <entry>(1&lt;&lt;12)</entry>
1345     </row>
1346     <row>
1347       <entry><symbol>ShiftMask</symbol></entry>
1348       <entry>(1&lt;&lt;0)</entry>
1349     </row>
1350     <row>
1351       <entry><symbol>LockMask</symbol></entry>
1352       <entry>(1&lt;&lt;1)</entry>
1353     </row>
1354     <row>
1355       <entry><symbol>ControlMask</symbol></entry>
1356       <entry>(1&lt;&lt;2)</entry>
1357     </row>
1358     <row>
1359       <entry><symbol>Mod1Mask</symbol></entry>
1360       <entry>(1&lt;&lt;3)</entry>
1361     </row>
1362     <row>
1363       <entry><symbol>Mod2Mask</symbol></entry>
1364       <entry>(1&lt;&lt;4)</entry>
1365     </row>
1366     <row>
1367       <entry><symbol>Mod3Mask</symbol></entry>
1368       <entry>(1&lt;&lt;5)</entry>
1369     </row>
1370     <row>
1371       <entry><symbol>Mod4Mask</symbol></entry>
1372       <entry>(1&lt;&lt;6)</entry>
1373     </row>
1374     <row>
1375       <entry><symbol>Mod5Mask</symbol></entry>
1376       <entry>(1&lt;&lt;7)</entry>
1377     </row>
1378     <row>
1379       <entry><symbol>Button1</symbol></entry>
1380       <entry>1</entry>
1381     </row>
1382     <row>
1383       <entry><symbol>Button2</symbol></entry>
1384       <entry>2</entry>
1385     </row>
1386     <row>
1387       <entry><symbol>Button3</symbol></entry>
1388       <entry>3</entry>
1389     </row>
1390     <row>
1391       <entry><symbol>Button4</symbol></entry>
1392       <entry>4</entry>
1393     </row>
1394     <row>
1395       <entry><symbol>Button5</symbol></entry>
1396       <entry>5</entry>
1397     </row>
1398   </tbody>
1399   </tgroup>
1400 </informaltable>
1401
1402 </sect2>
1403 </sect1>
1404 <sect1 id='Window_EntryExit_Events'>
1405 <title>Window Entry/Exit Events</title>
1406 <!-- .XS -->
1407 <!-- (SN Window Entry/Exit Events -->
1408 <!-- .XE -->
1409 <para>
1410 <!-- .LP -->
1411 <indexterm><primary>Events</primary><secondary>EnterNotify</secondary></indexterm>
1412 <indexterm><primary>Events</primary><secondary>LeaveNotify</secondary></indexterm>
1413 This section describes the processing that
1414 occurs for the window crossing events
1415 <symbol>EnterNotify</symbol>
1416 and
1417 <symbol>LeaveNotify</symbol>.
1418 <indexterm significance="preferred"><primary>EnterNotify</primary></indexterm>
1419 <indexterm significance="preferred"><primary>LeaveNotify</primary></indexterm>
1420 If a pointer motion or a window hierarchy change causes the
1421 pointer to be in a different window than before, the X server reports
1422 <symbol>EnterNotify</symbol>
1423 or
1424 <symbol>LeaveNotify</symbol>
1425 events to clients who have selected for these events.
1426 All
1427 <symbol>EnterNotify</symbol>
1428 and
1429 <symbol>LeaveNotify</symbol>
1430 events caused by a hierarchy change are
1431 generated after any hierarchy event
1432 (<symbol>UnmapNotify</symbol>,
1433 <symbol>MapNotify</symbol>,
1434 <symbol>ConfigureNotify</symbol>,
1435 <symbol>GravityNotify</symbol>,
1436 <symbol>CirculateNotify</symbol>)
1437 caused by that change;
1438 however, the X protocol does not constrain the ordering of
1439 <symbol>EnterNotify</symbol>
1440 and
1441 <symbol>LeaveNotify</symbol>
1442 events with respect to
1443 <symbol>FocusOut</symbol>,
1444 <symbol>VisibilityNotify</symbol>,
1445 and
1446 <symbol>Expose</symbol>
1447 events.
1448 </para>
1449 <para>
1450 <!-- .LP -->
1451 This contrasts with
1452 <symbol>MotionNotify</symbol>
1453 events, which are also generated when the pointer moves
1454 but only when the pointer motion begins and ends in a single window.
1455 An
1456 <symbol>EnterNotify</symbol>
1457 or
1458 <symbol>LeaveNotify</symbol>
1459 event also can be generated when some client application calls
1460 <xref linkend='XGrabPointer' xrefstyle='select: title'/>
1461 and
1462 <xref linkend='XUngrabPointer' xrefstyle='select: title'/>.
1463 </para>
1464 <para>
1465 <!-- .LP -->
1466 To receive
1467 <symbol>EnterNotify</symbol>
1468 or
1469 <symbol>LeaveNotify</symbol>
1470 events, set the
1471 <symbol>EnterWindowMask</symbol>
1472 or
1473 <symbol>LeaveWindowMask</symbol>
1474 bits of the event-mask attribute of the window.
1475 </para>
1476 <para>
1477 <!-- .LP -->
1478 The structure for these event types contains:
1479 </para>
1480 <!-- .LP -->
1481 <indexterm significance="preferred"><primary>XCrossingEvent</primary></indexterm>
1482 <indexterm significance="preferred"><primary>XEnterWindowEvent</primary></indexterm>
1483 <indexterm significance="preferred"><primary>XLeaveWindowEvent</primary></indexterm>
1484 <!-- .sM -->
1485 <literallayout class="monospaced">
1486 <!-- .TA .5i 3i -->
1487 <!-- .ta .5i 3i -->
1488 typedef struct {
1489      int           type;           /* EnterNotify or LeaveNotify */
1490      unsigned long serial;         /* # of last request processed by server */
1491      Bool          send_event;     /* true if this came from a SendEvent request */
1492      Display       *display;       /* Display the event was read from */
1493      Window        window;         /* ``event'' window reported relative to */
1494      Window        root;           /* root window that the event occurred on */
1495      Window        subwindow;      /* child window */
1496      Time          time;           /* milliseconds */
1497      int           x, y;           /* pointer x, y coordinates in event window */
1498      int           x_root, y_root; /* coordinates relative to root */
1499      int           mode;           /* NotifyNormal, NotifyGrab, NotifyUngrab */
1500      int           detail;
1501                    /*
1502                     * NotifyAncestor, NotifyVirtual, NotifyInferior,
1503                     * NotifyNonlinear,NotifyNonlinearVirtual
1504                     */
1505      Bool          same_screen;    /* same screen flag */
1506      Bool          focus;          /* boolean focus */
1507      unsigned int  state;          /* key or button mask */
1508 } XCrossingEvent;
1509 typedef XCrossingEvent XEnterWindowEvent;
1510 typedef XCrossingEvent XLeaveWindowEvent;
1511 </literallayout>
1512
1513 <para>
1514 <!-- .LP -->
1515 <!-- .eM -->
1516 The window member is set to the window on which the
1517 <symbol>EnterNotify</symbol>
1518 or
1519 <symbol>LeaveNotify</symbol>
1520 event was generated and is referred to as the event window.
1521 This is the window used by the X server to report the event,
1522 and is relative to the root
1523 window on which the event occurred.
1524 The root member is set to the root window of the screen
1525 on which the event occurred.
1526 </para>
1527 <para>
1528 <!-- .LP -->
1529 For a
1530 <symbol>LeaveNotify</symbol>
1531 event,
1532 if a child of the event window contains the initial position of the pointer,
1533 the subwindow component is set to that child.
1534 Otherwise, the X server sets the subwindow member to
1535 <symbol>None</symbol>.
1536 For an
1537 <symbol>EnterNotify</symbol>
1538 event, if a child of the event window contains the final pointer position,
1539 the subwindow component is set to that child or
1540 <symbol>None</symbol>.
1541 </para>
1542 <para>
1543 <!-- .LP -->
1544 The time member is set to the time when the event was generated
1545 and is expressed in milliseconds.
1546 The x and y members are set to the coordinates of the pointer position in
1547 the event window.
1548 This position is always the pointer's final position,
1549 not its initial position.
1550 If the event window is on the same
1551 screen as the root window, x and y are the pointer coordinates
1552 relative to the event window's origin.
1553 Otherwise, x and y are set to zero.
1554 The x_root and y_root members are set to the pointer's coordinates relative to the
1555 root window's origin at the time of the event.
1556 </para>
1557 <para>
1558 <!-- .LP -->
1559 The same_screen member is set to indicate whether the event window is on the same screen
1560 as the root window and can be either
1561 <symbol>True</symbol>
1562 or
1563 <symbol>False</symbol>.
1564 If
1565 <symbol>True</symbol>,
1566 the event and root windows are on the same screen.
1567 If
1568 <symbol>False</symbol>,
1569 the event and root windows are not on the same screen.
1570 </para>
1571 <para>
1572 <!-- .LP -->
1573 The focus member is set to indicate whether the event window is the focus window or an
1574 inferior of the focus window.
1575 The X server can set this member to either
1576 <symbol>True</symbol>
1577 or
1578 <symbol>False</symbol>.
1579 If
1580 <symbol>True</symbol>,
1581 the event window is the focus window or an inferior of the focus window.
1582 If
1583 <symbol>False</symbol>,
1584 the event window is not the focus window or an inferior of the focus window.
1585 </para>
1586 <para>
1587 <!-- .LP -->
1588 The state member is set to indicate the state of the pointer buttons and
1589 modifier keys just prior to the
1590 event.
1591 The X server can set this member to the bitwise inclusive OR of one
1592 or more of the button or modifier key masks:
1593 <symbol>Button1Mask</symbol>,
1594 <symbol>Button2Mask</symbol>,
1595 <symbol>Button3Mask</symbol>,
1596 <symbol>Button4Mask</symbol>,
1597 <symbol>Button5Mask</symbol>,
1598 <symbol>ShiftMask</symbol>,
1599 <symbol>LockMask</symbol>,
1600 <symbol>ControlMask</symbol>,
1601 <symbol>Mod1Mask</symbol>,
1602 <symbol>Mod2Mask</symbol>,
1603 <symbol>Mod3Mask</symbol>,
1604 <symbol>Mod4Mask</symbol>,
1605 <symbol>Mod5Mask</symbol>.
1606 </para>
1607 <para>
1608 <!-- .LP -->
1609 The mode member is set to indicate whether the events are normal events,
1610 pseudo-motion events
1611 when a grab activates, or pseudo-motion events when a grab deactivates.
1612 The X server can set this member to
1613 <symbol>NotifyNormal</symbol>,
1614 <symbol>NotifyGrab</symbol>,
1615 or
1616 <symbol>NotifyUngrab</symbol>.
1617 </para>
1618 <para>
1619 <!-- .LP -->
1620 The detail member is set to indicate the notify detail and can be
1621 <symbol>NotifyAncestor</symbol>,
1622 <symbol>NotifyVirtual</symbol>,
1623 <symbol>NotifyInferior</symbol>,
1624 <symbol>NotifyNonlinear</symbol>,
1625 or
1626 <symbol>NotifyNonlinearVirtual</symbol>.
1627 </para>
1628 <sect2 id='Normal_EntryExit_Events'>
1629 <title>Normal Entry/Exit Events</title>
1630 <!-- .XS -->
1631 <!-- (SN Normal Entry/Exit Events -->
1632 <!-- .XE -->
1633 <para>
1634 <!-- .LP -->
1635 <symbol>EnterNotify</symbol>
1636 and
1637 <symbol>LeaveNotify</symbol>
1638 events are generated when the pointer moves from
1639 one window to another window.
1640 Normal events are identified by
1641 <type>XEnterWindowEvent</type>
1642 or
1643 <type>XLeaveWindowEvent</type>
1644 structures whose mode member is set to
1645 <symbol>NotifyNormal</symbol>.
1646 </para>
1647 <itemizedlist>
1648   <listitem>
1649     <para>
1650 When the pointer moves from window A to window B and A is an inferior of B,
1651 the X server does the following:
1652 <!-- .RS -->
1653     </para>
1654   </listitem>
1655   <listitem>
1656     <para>
1657 It generates a
1658 <symbol>LeaveNotify</symbol>
1659 event on window A, with the detail member of the
1660 <type>XLeaveWindowEvent</type>
1661 structure set to
1662 <symbol>NotifyAncestor</symbol>.
1663     </para>
1664   </listitem>
1665   <listitem>
1666     <para>
1667 It generates a
1668 <symbol>LeaveNotify</symbol>
1669 event on each window between window A and window B, exclusive,
1670 with the detail member of each
1671 <type>XLeaveWindowEvent</type>
1672 structure set to
1673 <symbol>NotifyVirtual</symbol>.
1674     </para>
1675   </listitem>
1676   <listitem>
1677     <para>
1678 It generates an
1679 <symbol>EnterNotify</symbol>
1680 event on window B, with the detail member of the
1681 <type>XEnterWindowEvent</type>
1682 structure set to
1683 <symbol>NotifyInferior</symbol>.
1684 <!-- .RE -->
1685     </para>
1686   </listitem>
1687   <listitem>
1688     <para>
1689 When the pointer moves from window A to window B and B is an inferior of A,
1690 the X server does the following:
1691 <!-- .RS -->
1692     </para>
1693   </listitem>
1694   <listitem>
1695     <para>
1696 It generates a
1697 <symbol>LeaveNotify</symbol>
1698 event on window A,
1699 with the detail member of the
1700 <type>XLeaveWindowEvent</type>
1701 structure set to
1702 <symbol>NotifyInferior</symbol>.
1703     </para>
1704   </listitem>
1705   <listitem>
1706     <para>
1707 It generates an
1708 <symbol>EnterNotify</symbol>
1709 event on each window between window A and window B, exclusive, with the
1710 detail member of each
1711 <type>XEnterWindowEvent</type>
1712 structure set to
1713 <symbol>NotifyVirtual</symbol>.
1714     </para>
1715   </listitem>
1716   <listitem>
1717     <para>
1718 It generates an
1719 <symbol>EnterNotify</symbol>
1720 event on window B, with the detail member of the
1721 <type>XEnterWindowEvent</type>
1722 structure set to
1723 <symbol>NotifyAncestor</symbol>.
1724 <!-- .RE -->
1725     </para>
1726   </listitem>
1727   <listitem>
1728     <para>
1729 When the pointer moves from window A to window B
1730 and window C is their least common ancestor,
1731 the X server does the following:
1732 <!-- .RS -->
1733     </para>
1734   </listitem>
1735   <listitem>
1736     <para>
1737 It generates a
1738 <symbol>LeaveNotify</symbol>
1739 event on window A,
1740 with the detail member of the
1741 <type>XLeaveWindowEvent</type>
1742 structure set to
1743 <symbol>NotifyNonlinear</symbol>.
1744     </para>
1745   </listitem>
1746   <listitem>
1747     <para>
1748 It generates a
1749 <symbol>LeaveNotify</symbol>
1750 event on each window between window A and window C, exclusive,
1751 with the detail member of each
1752 <type>XLeaveWindowEvent</type>
1753 structure set to
1754 <symbol>NotifyNonlinearVirtual</symbol>.
1755     </para>
1756   </listitem>
1757   <listitem>
1758     <para>
1759 It generates an
1760 <symbol>EnterNotify</symbol>
1761 event on each window between window C and window B, exclusive,
1762 with the detail member of each
1763 <type>XEnterWindowEvent</type>
1764 structure set to
1765 <symbol>NotifyNonlinearVirtual</symbol>.
1766     </para>
1767   </listitem>
1768   <listitem>
1769     <para>
1770 It generates an
1771 <symbol>EnterNotify</symbol>
1772 event on window B, with the detail member of the
1773 <type>XEnterWindowEvent</type>
1774 structure set to
1775 <symbol>NotifyNonlinear</symbol>.
1776 <!-- .RE -->
1777     </para>
1778   </listitem>
1779   <listitem>
1780     <para>
1781 When the pointer moves from window A to window B on different screens,
1782 the X server does the following:
1783 <!-- .RS -->
1784     </para>
1785   </listitem>
1786   <listitem>
1787     <para>
1788 It generates a
1789 <symbol>LeaveNotify</symbol>
1790 event on window A,
1791 with the detail member of the
1792 <type>XLeaveWindowEvent</type>
1793 structure set to
1794 <symbol>NotifyNonlinear</symbol>.
1795     </para>
1796   </listitem>
1797   <listitem>
1798     <para>
1799 If window A is not a root window,
1800 it generates a
1801 <symbol>LeaveNotify</symbol>
1802 event on each window above window A up to and including its root,
1803 with the detail member of each
1804 <type>XLeaveWindowEvent</type>
1805 structure set to
1806 <symbol>NotifyNonlinearVirtual</symbol>.
1807     </para>
1808   </listitem>
1809   <listitem>
1810     <para>
1811 If window B is not a root window,
1812 it generates an
1813 <symbol>EnterNotify</symbol>
1814 event on each window from window B's root down to but not including
1815 window B, with the detail member of each
1816 <type>XEnterWindowEvent</type>
1817 structure set to
1818 <symbol>NotifyNonlinearVirtual</symbol>.
1819     </para>
1820   </listitem>
1821   <listitem>
1822     <para>
1823 It generates an
1824 <symbol>EnterNotify</symbol>
1825 event on window B, with the detail member of the
1826 <type>XEnterWindowEvent</type>
1827 structure set to
1828 <symbol>NotifyNonlinear</symbol>.
1829 <!-- .RE -->
1830 <!-- .\".SH 3 -->
1831     </para>
1832   </listitem>
1833 </itemizedlist>
1834 </sect2>
1835 <sect2 id='Grab_and_Ungrab_EntryExit_Events'>
1836 <title>Grab and Ungrab Entry/Exit Events</title>
1837 <!-- .XS -->
1838 <!-- (SN Grab and Ungrab Entry/Exit Events -->
1839 <!-- .XE -->
1840 <para>
1841 <!-- .LP -->
1842 Pseudo-motion mode
1843 <symbol>EnterNotify</symbol>
1844 and
1845 <symbol>LeaveNotify</symbol>
1846 events are generated when a pointer grab activates or deactivates.
1847 Events in which the pointer grab activates
1848 are identified by
1849 <type>XEnterWindowEvent</type>
1850 or
1851 <type>XLeaveWindowEvent</type>
1852 structures whose mode member is set to
1853 <symbol>NotifyGrab</symbol>.
1854 Events in which the pointer grab deactivates
1855 are identified by
1856 <type>XEnterWindowEvent</type>
1857 or
1858 <type>XLeaveWindowEvent</type>
1859 structures whose mode member is set to
1860 <symbol>NotifyUngrab</symbol>
1861 (see
1862 <xref linkend='XGrabPointer' xrefstyle='select: title'/>).
1863 </para>
1864 <itemizedlist>
1865   <listitem>
1866     <para>
1867 When a pointer grab activates after any initial warp into a confine_to
1868 window and before generating any actual
1869 <symbol>ButtonPress</symbol>
1870 event that activates the grab,
1871 G is the grab_window for the grab,
1872 and P is the window the pointer is in,
1873 the X server does the following:
1874 <!-- .RS -->
1875     </para>
1876   </listitem>
1877   <listitem>
1878     <para>
1879 It generates
1880 <symbol>EnterNotify</symbol>
1881 and
1882 <symbol>LeaveNotify</symbol>
1883 events (see <link linkend='Normal_EntryExit_Events'>section 10.6.1</link>)
1884 with the mode members of the
1885 <type>XEnterWindowEvent</type>
1886 and
1887 <type>XLeaveWindowEvent</type>
1888 structures set to
1889 <symbol>NotifyGrab</symbol>.
1890 These events are generated
1891 as if the pointer were to suddenly warp from
1892 its current position in P to some position in G.
1893 However, the pointer does not warp, and the X server uses the pointer position
1894 as both the initial and final positions for the events.
1895 <!-- .RE -->
1896     </para>
1897   </listitem>
1898   <listitem>
1899     <para>
1900 When a pointer grab deactivates after generating any actual
1901 <symbol>ButtonRelease</symbol>
1902 event that deactivates the grab,
1903 G is the grab_window for the grab,
1904 and P is the window the pointer is in,
1905 the X server does the following:
1906 <!-- .RS -->
1907     </para>
1908   </listitem>
1909   <listitem>
1910     <para>
1911 It generates
1912 <symbol>EnterNotify</symbol>
1913 and
1914 <symbol>LeaveNotify</symbol>
1915 events (see <link linkend='Normal_EntryExit_Events'>section 10.6.1</link>)
1916 with the mode members of the
1917 <type>XEnterWindowEvent</type>
1918 and
1919 <type>XLeaveWindowEvent</type>
1920 structures set to
1921 <symbol>NotifyUngrab</symbol>.
1922 These events are generated as if the pointer were to suddenly warp from
1923 some position in G to its current position in P.
1924 However, the pointer does not warp, and the X server uses the
1925 current pointer position as both the
1926 initial and final positions for the events.
1927 <!-- .RE -->
1928     </para>
1929   </listitem>
1930 </itemizedlist>
1931 </sect2>
1932 </sect1>
1933 <sect1 id="Input_Focus_Events">
1934 <title>Input Focus Events</title>
1935 <!-- .XS -->
1936 <!-- (SN Input Focus Events  -->
1937 <!-- .XE -->
1938 <para>
1939 <!-- .LP -->
1940 <indexterm><primary>Events</primary><secondary>FocusIn</secondary></indexterm>
1941 <indexterm><primary>Events</primary><secondary>FocusOut</secondary></indexterm>
1942 This section describes the processing that occurs for the input focus events
1943 <symbol>FocusIn</symbol>
1944 and
1945 <symbol>FocusOut</symbol>.
1946 <indexterm significance="preferred"><primary>FocusIn</primary></indexterm>
1947 <indexterm significance="preferred"><primary>FocusOut</primary></indexterm>
1948 The X server can report
1949 <symbol>FocusIn</symbol>
1950 or
1951 <symbol>FocusOut</symbol>
1952 events to clients wanting information about when the input focus changes.
1953 The keyboard is always attached to some window
1954 (typically, the root window or a top-level window),
1955 which is called the focus window.
1956 The focus window and the position of the pointer determine the window that
1957 receives keyboard input.
1958 Clients may need to know when the input focus changes
1959 to control highlighting of areas on the screen.
1960 </para>
1961 <para>
1962 <!-- .LP -->
1963 To receive
1964 <symbol>FocusIn</symbol>
1965 or
1966 <symbol>FocusOut</symbol>
1967 events, set the
1968 <symbol>FocusChangeMask</symbol>
1969 bit in the event-mask attribute of the window.
1970 </para>
1971 <para>
1972 <!-- .LP -->
1973 The structure for these event types contains:
1974 </para>
1975 <!-- .LP -->
1976 <indexterm significance="preferred"><primary>XFocusChangeEvent</primary></indexterm>
1977 <indexterm significance="preferred"><primary>XFocusInEvent</primary></indexterm>
1978 <indexterm significance="preferred"><primary>XFocusOutEvent</primary></indexterm>
1979 <!-- .sM -->
1980 <literallayout class="monospaced">
1981 <!-- .TA .5i 3i -->
1982 <!-- .ta .5i 3i -->
1983 typedef struct {
1984      int           type;       /* FocusIn or FocusOut */
1985      unsigned long serial;     /* # of last request processed by server */
1986      Bool          send_event; /* true if this came from a SendEvent request */
1987      Display       *display;   /* Display the event was read from */
1988      Window        window;     /* window of event */
1989      int           mode;       /* NotifyNormal, NotifyGrab, NotifyUngrab */
1990      int           detail;
1991                    /*
1992                     * NotifyAncestor, NotifyVirtual, NotifyInferior,
1993                     * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
1994                     * NotifyPointerRoot, NotifyDetailNone
1995                     */
1996 } XFocusChangeEvent;
1997 typedef XFocusChangeEvent XFocusInEvent;
1998 typedef XFocusChangeEvent XFocusOutEvent;
1999 </literallayout>
2000 <para>
2001 <!-- .LP -->
2002 <!-- .eM -->
2003 The window member is set to the window on which the
2004 <symbol>FocusIn</symbol>
2005 or
2006 <symbol>FocusOut</symbol>
2007 event was generated.
2008 This is the window used by the X server to report the event.
2009 The mode member is set to indicate whether the focus events
2010 are normal focus events,
2011 focus events while grabbed,
2012 focus events
2013 when a grab activates, or focus events when a grab deactivates.
2014 The X server can set the mode member to
2015 <symbol>NotifyNormal</symbol>,
2016 <symbol>NotifyWhileGrabbed</symbol>,
2017 <symbol>NotifyGrab</symbol>,
2018 or
2019 <symbol>NotifyUngrab</symbol>.
2020 </para>
2021 <para>
2022 <!-- .LP -->
2023 All
2024 <symbol>FocusOut</symbol>
2025 events caused by a window unmap are generated after any
2026 <symbol>UnmapNotify</symbol>
2027 event; however, the X protocol does not constrain the ordering of
2028 <symbol>FocusOut</symbol>
2029 events with respect to
2030 generated
2031 <symbol>EnterNotify</symbol>,
2032 <symbol>LeaveNotify</symbol>,
2033 <symbol>VisibilityNotify</symbol>,
2034 and
2035 <symbol>Expose</symbol>
2036 events.
2037 </para>
2038 <para>
2039 <!-- .LP -->
2040 Depending on the event mode,
2041 the detail member is set to indicate the notify detail and can be
2042 <symbol>NotifyAncestor</symbol>,
2043 <symbol>NotifyVirtual</symbol>,
2044 <symbol>NotifyInferior</symbol>,
2045 <symbol>NotifyNonlinear</symbol>,
2046 <symbol>NotifyNonlinearVirtual</symbol>,
2047 <symbol>NotifyPointer</symbol>,
2048 <symbol>NotifyPointerRoot</symbol>,
2049 or
2050 <symbol>NotifyDetailNone</symbol>.
2051 </para>
2052 <sect2 id='Normal_Focus_Events_and_Focus_Events_While_Grabbed'>
2053 <title>Normal Focus Events and Focus Events While Grabbed</title>
2054 <!-- .XS -->
2055 <!-- (SN Normal Focus Events and Focus Events While Grabbed  -->
2056 <!-- .XE -->
2057 <para>
2058 <!-- .LP -->
2059 Normal focus events are identified by
2060 <type>XFocusInEvent</type>
2061 or
2062 <type>XFocusOutEvent</type>
2063 structures whose mode member is set to
2064 <symbol>NotifyNormal</symbol>.
2065 Focus events while grabbed are identified by
2066 <type>XFocusInEvent</type>
2067 or
2068 <type>XFocusOutEvent</type>
2069 structures whose mode member is set to
2070 <symbol>NotifyWhileGrabbed</symbol>.
2071 The X server processes normal focus and focus events while grabbed according to
2072 the following:
2073 </para>
2074 <itemizedlist>
2075   <listitem>
2076     <para>
2077 When the focus moves from window A to window B, A is an inferior of B,
2078 and the pointer is in window P,
2079 the X server does the following:
2080 <!-- .RS -->
2081     </para>
2082   </listitem>
2083   <listitem>
2084     <para>
2085 It generates a
2086 <symbol>FocusOut</symbol>
2087 event on window A, with the detail member of the
2088 <type>XFocusOutEvent</type>
2089 structure set to
2090 <symbol>NotifyAncestor</symbol>.
2091     </para>
2092   </listitem>
2093   <listitem>
2094     <para>
2095 It generates a
2096 <symbol>FocusOut</symbol>
2097 event on each window between window A and window B, exclusive,
2098 with the detail member of each
2099 <type>XFocusOutEvent</type>
2100 structure set to
2101 <symbol>NotifyVirtual</symbol>.
2102     </para>
2103   </listitem>
2104   <listitem>
2105     <para>
2106 It generates a
2107 <symbol>FocusIn</symbol>
2108 event on window B, with the detail member of the
2109 <type>XFocusOutEvent</type>
2110 structure set to
2111 <symbol>NotifyInferior</symbol>.
2112     </para>
2113   </listitem>
2114   <listitem>
2115     <para>
2116 If window P is an inferior of window B
2117 but window P is not window A or an inferior or ancestor of window A,
2118 it generates a
2119 <symbol>FocusIn</symbol>
2120 event on each window below window B, down to and including window P,
2121 with the detail member of each
2122 <type>XFocusInEvent</type>
2123 structure set to
2124 <symbol>NotifyPointer</symbol>.
2125 <!-- .RE -->
2126     </para>
2127   </listitem>
2128   <listitem>
2129     <para>
2130 When the focus moves from window A to window B, B is an inferior of A,
2131 and the pointer is in window P,
2132 the X server does the following:
2133 <!-- .RS -->
2134     </para>
2135   </listitem>
2136   <listitem>
2137     <para>
2138 If window P is an inferior of window A
2139 but P is not an inferior of window B or an ancestor of B,
2140 it generates a
2141 <symbol>FocusOut</symbol>
2142 event on each window from window P up to but not including window A,
2143 with the detail member of each
2144 <type>XFocusOutEvent</type>
2145 structure set to
2146 <symbol>NotifyPointer</symbol>.
2147     </para>
2148   </listitem>
2149   <listitem>
2150     <para>
2151 It generates a
2152 <symbol>FocusOut</symbol>
2153 event on window A,
2154 with the detail member of the
2155 <type>XFocusOutEvent</type>
2156 structure set to
2157 <symbol>NotifyInferior</symbol>.
2158     </para>
2159   </listitem>
2160   <listitem>
2161     <para>
2162 It generates a
2163 <symbol>FocusIn</symbol>
2164 event on each window between window A and window B, exclusive, with the
2165 detail member of each
2166 <type>XFocusInEvent</type>
2167 structure set to
2168 <symbol>NotifyVirtual</symbol>.
2169     </para>
2170   </listitem>
2171   <listitem>
2172     <para>
2173 It generates a
2174 <symbol>FocusIn</symbol>
2175 event on window B, with the detail member of the
2176 <type>XFocusInEvent</type>
2177 structure set to
2178 <symbol>NotifyAncestor</symbol>.
2179 <!-- .RE -->
2180     </para>
2181   </listitem>
2182   <listitem>
2183     <para>
2184 When the focus moves from window A to window B,
2185 window C is their least common ancestor,
2186 and the pointer is in window P,
2187 the X server does the following:
2188 <!-- .RS -->
2189     </para>
2190   </listitem>
2191   <listitem>
2192     <para>
2193 If window P is an inferior of window A,
2194 it generates a
2195 <symbol>FocusOut</symbol>
2196 event on each window from window P up to but not including window A,
2197 with the detail member of the
2198 <type>XFocusOutEvent</type>
2199 structure set to
2200 <symbol>NotifyPointer</symbol>.
2201     </para>
2202   </listitem>
2203   <listitem>
2204     <para>
2205 It generates a
2206 <symbol>FocusOut</symbol>
2207 event on window A,
2208 with the detail member of the
2209 <type>XFocusOutEvent</type>
2210 structure set to
2211 <symbol>NotifyNonlinear</symbol>.
2212     </para>
2213   </listitem>
2214   <listitem>
2215     <para>
2216 It generates a
2217 <symbol>FocusOut</symbol>
2218 event on each window between window A and window C, exclusive,
2219 with the detail member of each
2220 <type>XFocusOutEvent</type>
2221 structure set to
2222 <symbol>NotifyNonlinearVirtual</symbol>.
2223     </para>
2224   </listitem>
2225   <listitem>
2226     <para>
2227 It generates a
2228 <symbol>FocusIn</symbol>
2229 event on each window between C and B, exclusive,
2230 with the detail member of each
2231 <type>XFocusInEvent</type>
2232 structure set to
2233 <symbol>NotifyNonlinearVirtual</symbol>.
2234     </para>
2235   </listitem>
2236   <listitem>
2237     <para>
2238 It generates a
2239 <symbol>FocusIn</symbol>
2240 event on window B, with the detail member of the
2241 <type>XFocusInEvent</type>
2242 structure set to
2243 <symbol>NotifyNonlinear</symbol>.
2244     </para>
2245   </listitem>
2246   <listitem>
2247     <para>
2248 If window P is an inferior of window B, it generates a
2249 <symbol>FocusIn</symbol>
2250 event on each window below window B down to and including window P,
2251 with the detail member of the
2252 <type>XFocusInEvent</type>
2253 structure set to
2254 <symbol>NotifyPointer</symbol>.
2255 <!-- .RE -->
2256     </para>
2257   </listitem>
2258   <listitem>
2259     <para>
2260 When the focus moves from window A to window B on different screens
2261 and the pointer is in window P,
2262 the X server does the following:
2263 <!-- .RS -->
2264     </para>
2265   </listitem>
2266   <listitem>
2267     <para>
2268 If window P is an inferior of window A, it generates a
2269 <symbol>FocusOut</symbol>
2270 event on each window from window P up to but not including window A,
2271 with the detail member of each
2272 <type>XFocusOutEvent</type>
2273 structure set to
2274 <symbol>NotifyPointer</symbol>.
2275     </para>
2276   </listitem>
2277   <listitem>
2278     <para>
2279 It generates a
2280 <symbol>FocusOut</symbol>
2281 event on window A,
2282 with the detail member of the
2283 <type>XFocusOutEvent</type>
2284 structure set to
2285 <symbol>NotifyNonlinear</symbol>.
2286     </para>
2287   </listitem>
2288   <listitem>
2289     <para>
2290 If window A is not a root window,
2291 it generates a
2292 <symbol>FocusOut</symbol>
2293 event on each window above window A up to and including its root,
2294 with the detail member of each
2295 <type>XFocusOutEvent</type>
2296 structure set to
2297 <symbol>NotifyNonlinearVirtual</symbol>.
2298     </para>
2299   </listitem>
2300   <listitem>
2301     <para>
2302 If window B is not a root window,
2303 it generates a
2304 <symbol>FocusIn</symbol>
2305 event on each window from window B's root down to but not including
2306 window B, with the detail member of each
2307 <type>XFocusInEvent</type>
2308 structure set to
2309 <symbol>NotifyNonlinearVirtual</symbol>.
2310     </para>
2311   </listitem>
2312   <listitem>
2313     <para>
2314 It generates a
2315 <symbol>FocusIn</symbol>
2316 event on window B, with the detail member of each
2317 <type>XFocusInEvent</type>
2318 structure set to
2319 <symbol>NotifyNonlinear</symbol>.
2320     </para>
2321   </listitem>
2322   <listitem>
2323     <para>
2324 If window P is an inferior of window B, it generates a
2325 <symbol>FocusIn</symbol>
2326 event on each window below window B down to and including window P,
2327 with the detail member of each
2328 <type>XFocusInEvent</type>
2329 structure set to
2330 <symbol>NotifyPointer</symbol>.
2331 <!-- .RE -->
2332     </para>
2333   </listitem>
2334   <listitem>
2335     <para>
2336 When the focus moves from window A to
2337 <symbol>PointerRoot</symbol>
2338 (events sent to the window under the pointer)
2339 or
2340 <symbol>None</symbol>
2341 (discard), and the pointer is in window P,
2342 the X server does the following:
2343 <!-- .RS -->
2344     </para>
2345   </listitem>
2346   <listitem>
2347     <para>
2348 If window P is an inferior of window A, it generates a
2349 <symbol>FocusOut</symbol>
2350 event on each window from window P up to but not including window A,
2351 with the detail member of each
2352 <type>XFocusOutEvent</type>
2353 structure set to
2354 <symbol>NotifyPointer</symbol>.
2355     </para>
2356   </listitem>
2357   <listitem>
2358     <para>
2359 It generates a
2360 <symbol>FocusOut</symbol>
2361 event on window A, with the detail member of the
2362 <type>XFocusOutEvent</type>
2363 structure set to
2364 <symbol>NotifyNonlinear</symbol>.
2365     </para>
2366   </listitem>
2367   <listitem>
2368     <para>
2369 If window A is not a root window,
2370 it generates a
2371 <symbol>FocusOut</symbol>
2372 event on each window above window A up to and including its root,
2373 with the detail member of each
2374 <type>XFocusOutEvent</type>
2375 structure set to
2376 <symbol>NotifyNonlinearVirtual</symbol>.
2377     </para>
2378   </listitem>
2379   <listitem>
2380     <para>
2381 It generates a
2382 <symbol>FocusIn</symbol>
2383 event on the root window of all screens, with the detail member of each
2384 <type>XFocusInEvent</type>
2385 structure set to
2386 <symbol>NotifyPointerRoot</symbol>
2387 (or
2388 <symbol>NotifyDetailNone</symbol>).
2389     </para>
2390   </listitem>
2391   <listitem>
2392     <para>
2393 If the new focus is
2394 <symbol>PointerRoot</symbol>,
2395 it generates a
2396 <symbol>FocusIn</symbol>
2397 event on each window from window P's root down to and including window P,
2398 with the detail member of each
2399 <type>XFocusInEvent</type>
2400 structure set to
2401 <symbol>NotifyPointer</symbol>.
2402 <!-- .RE -->
2403     </para>
2404   </listitem>
2405   <listitem>
2406     <para>
2407 When the focus moves from
2408 <symbol>PointerRoot</symbol>
2409 (events sent to the window under the pointer)
2410 or
2411 <symbol>None</symbol>
2412 to window A, and the pointer is in window P,
2413 the X server does the following:
2414 <!-- .RS -->
2415     </para>
2416   </listitem>
2417   <listitem>
2418     <para>
2419 If the old focus is
2420 <symbol>PointerRoot</symbol>,
2421 it generates a
2422 <symbol>FocusOut</symbol>
2423 event on each window from window P up to and including window P's root,
2424 with the detail member of each
2425 <type>XFocusOutEvent</type>
2426 structure set to
2427 <symbol>NotifyPointer</symbol>.
2428     </para>
2429   </listitem>
2430   <listitem>
2431     <para>
2432 It generates a
2433 <symbol>FocusOut</symbol>
2434 event on all root windows,
2435 with the detail member of each
2436 <type>XFocusOutEvent</type>
2437 structure set to
2438 <symbol>NotifyPointerRoot</symbol>
2439 (or
2440 <symbol>NotifyDetailNone</symbol>).
2441     </para>
2442   </listitem>
2443   <listitem>
2444     <para>
2445 If window A is not a root window,
2446 it generates a
2447 <symbol>FocusIn</symbol>
2448 event on each window from window A's root down to but not including window A,
2449 with the detail member of each
2450 <type>XFocusInEvent</type>
2451 structure set to
2452 <symbol>NotifyNonlinearVirtual</symbol>.
2453     </para>
2454   </listitem>
2455   <listitem>
2456     <para>
2457 It generates a
2458 <symbol>FocusIn</symbol>
2459 event on window A,
2460 with the detail member of the
2461 <type>XFocusInEvent</type>
2462 structure set to
2463 <symbol>NotifyNonlinear</symbol>.
2464     </para>
2465   </listitem>
2466   <listitem>
2467     <para>
2468 If window P is an inferior of window A, it generates a
2469 <symbol>FocusIn</symbol>
2470 event on each window below window A down to and including window P,
2471 with the detail member of each
2472 <type>XFocusInEvent</type>
2473 structure set to
2474 <symbol>NotifyPointer</symbol>.
2475 <!-- .RE -->
2476     </para>
2477   </listitem>
2478   <listitem>
2479     <para>
2480 When the focus moves from
2481 <symbol>PointerRoot</symbol>
2482 (events sent to the window under the pointer)
2483 to
2484 <symbol>None</symbol>
2485 (or vice versa), and the pointer is in window P,
2486 the X server does the following:
2487 <!-- .RS -->
2488     </para>
2489   </listitem>
2490   <listitem>
2491     <para>
2492 If the old focus is
2493 <symbol>PointerRoot</symbol>,
2494 it generates a
2495 <symbol>FocusOut</symbol>
2496 event on each window from window P up to and including window P's root,
2497 with the detail member of each
2498 <type>XFocusOutEvent</type>
2499 structure set to
2500 <symbol>NotifyPointer</symbol>.
2501     </para>
2502   </listitem>
2503   <listitem>
2504     <para>
2505 It generates a
2506 <symbol>FocusOut</symbol>
2507 event on all root windows,
2508 with the detail member of each
2509 <type>XFocusOutEvent</type>
2510 structure set to either
2511 <symbol>NotifyPointerRoot</symbol>
2512 or
2513 <symbol>NotifyDetailNone</symbol>.
2514     </para>
2515   </listitem>
2516   <listitem>
2517     <para>
2518 It generates a
2519 <symbol>FocusIn</symbol>
2520 event on all root windows,
2521 with the detail member of each
2522 <type>XFocusInEvent</type>
2523 structure set to
2524 <symbol>NotifyDetailNone</symbol>
2525 or
2526 <symbol>NotifyPointerRoot</symbol>.
2527     </para>
2528   </listitem>
2529   <listitem>
2530     <para>
2531 If the new focus is
2532 <symbol>PointerRoot</symbol>,
2533 it generates a
2534 <symbol>FocusIn</symbol>
2535 event on each window from window P's root down to and including window P,
2536 with the detail member of each
2537 <type>XFocusInEvent</type>
2538 structure set to
2539 <symbol>NotifyPointer</symbol>.
2540 <!-- .RE -->
2541 <!-- .\".SH 3 -->
2542     </para>
2543   </listitem>
2544 </itemizedlist>
2545 </sect2>
2546 <sect2 id="Focus_Events_Generated_by_Grabs">
2547 <title>Focus Events Generated by Grabs</title>
2548 <!-- .XS -->
2549 <!-- (SN Focus Events Generated by Grabs  -->
2550 <!-- .XE -->
2551 <para>
2552 <!-- .LP -->
2553 Focus events in which the keyboard grab activates
2554 are identified by
2555 <type>XFocusInEvent</type>
2556 or
2557 <type>XFocusOutEvent</type>
2558 structures whose mode member is set to
2559 <symbol>NotifyGrab</symbol>.
2560 Focus events in which the keyboard grab deactivates
2561 are identified by
2562 <type>XFocusInEvent</type>
2563 or
2564 <type>XFocusOutEvent</type>
2565 structures whose mode member is set to
2566 <symbol>NotifyUngrab</symbol>
2567 (see
2568 <xref linkend='XGrabKeyboard' xrefstyle='select: title'/>).
2569 </para>
2570 <itemizedlist>
2571   <listitem>
2572     <para>
2573 When a keyboard grab activates before generating any actual
2574 <symbol>KeyPress</symbol>
2575 event that activates the grab,
2576 G is the grab_window, and F is the current focus,
2577 the X server does the following:
2578 <!-- .RS -->
2579     </para>
2580   </listitem>
2581   <listitem>
2582     <para>
2583 It generates
2584 <symbol>FocusIn</symbol>
2585 and
2586 <symbol>FocusOut</symbol>
2587 events, with the mode members of the
2588 <type>XFocusInEvent</type>
2589 and
2590 <type>XFocusOutEvent</type>
2591 structures set to
2592 <symbol>NotifyGrab</symbol>.
2593 These events are generated
2594 as if the focus were to change from
2595 F to G.
2596 <!-- .RE -->
2597     </para>
2598   </listitem>
2599   <listitem>
2600     <para>
2601 When a keyboard grab deactivates after generating any actual
2602 <symbol>KeyRelease</symbol>
2603 event that deactivates the grab,
2604 G is the grab_window, and F is the current focus,
2605 the X server does the following:
2606 <!-- .RS -->
2607     </para>
2608   </listitem>
2609   <listitem>
2610     <para>
2611 It generates
2612 <symbol>FocusIn</symbol>
2613 and
2614 <symbol>FocusOut</symbol>
2615 events, with the mode members of the
2616 <type>XFocusInEvent</type>
2617 and
2618 <type>XFocusOutEvent</type>
2619 structures set to
2620 <symbol>NotifyUngrab</symbol>.
2621 These events are generated
2622 as if the focus were to change from
2623 G to F.
2624 <!-- .RE -->
2625     </para>
2626   </listitem>
2627 </itemizedlist>
2628 </sect2>
2629 </sect1>
2630 <sect1 id="Key_Map_State_Notification_Events">
2631 <title>Key Map State Notification Events</title>
2632 <!-- .XS -->
2633 <!-- (SN Key Map State Notification Events -->
2634 <!-- .XE -->
2635 <para>
2636 <!-- .LP -->
2637 <indexterm><primary>Events</primary><secondary>KeymapNotify</secondary></indexterm>
2638 <indexterm significance="preferred"><primary>KeymapNotify</primary></indexterm>
2639 The X server can report
2640 <symbol>KeymapNotify</symbol>
2641 events to clients that want information about changes in their keyboard state.
2642 </para>
2643 <para>
2644 <!-- .LP -->
2645 To receive
2646 <symbol>KeymapNotify</symbol>
2647 events, set the
2648 <symbol>KeymapStateMask</symbol>
2649 bit in the event-mask attribute of the window.
2650 The X server generates this event immediately after every
2651 <symbol>EnterNotify</symbol>
2652 and
2653 <symbol>FocusIn</symbol>
2654 event.
2655 </para>
2656 <para>
2657 <!-- .LP -->
2658 The structure for this event type contains:
2659 </para>
2660 <para>
2661 <!-- .LP -->
2662 <indexterm significance="preferred"><primary>XKeymapEvent</primary></indexterm>
2663 <!-- .sM -->
2664 <literallayout class="monospaced">
2665 <!-- .TA .5i 3i -->
2666 <!-- .ta .5i 3i -->
2667 /* generated on EnterWindow and FocusIn when KeymapState selected */
2668 typedef struct {
2669      int            type;           /* KeymapNotify */
2670      unsigned long  serial;         /* # of last request processed by server */
2671      Bool           send_event;     /* true if this came from a SendEvent request */
2672      Display        *display;       /* Display the event was read from */
2673      Window         window;
2674      char           key_vector[32];
2675 } XKeymapEvent;
2676 </literallayout>
2677 </para>
2678 <para>
2679 <!-- .LP -->
2680 <!-- .eM -->
2681 The window member is not used but is present to aid some toolkits.
2682 The key_vector member is set to the bit vector of the keyboard.
2683 Each bit set to 1 indicates that the corresponding key
2684 is currently pressed.
2685 The vector is represented as 32 bytes.
2686 Byte N (from 0) contains the bits for keys 8N to 8N + 7
2687 with the least significant bit in the byte representing key 8N.
2688 </para>
2689 </sect1>
2690 <sect1 id="Exposure_Events">
2691 <title>Exposure Events</title>
2692 <!-- .XS -->
2693 <!-- (SN Exposure Events -->
2694 <!-- .XE -->
2695 <para>
2696 <!-- .LP -->
2697 The X protocol does not guarantee to preserve the contents of window
2698 regions when
2699 the windows are obscured or reconfigured.
2700 Some implementations may preserve the contents of windows.
2701 Other implementations are free to destroy the contents of windows
2702 when exposed.
2703 X expects client applications to assume the responsibility for
2704 restoring the contents of an exposed window region.
2705 (An exposed window region describes a formerly obscured window whose
2706 region becomes visible.)
2707 Therefore, the X server sends
2708 <symbol>Expose</symbol>
2709 events describing the window and the region of the window that has been exposed.
2710 A naive client application usually redraws the entire window.
2711 A more sophisticated client application redraws only the exposed region.
2712 </para>
2713 <sect2 id="Expose_Events">
2714 <title>Expose Events</title>
2715 <!-- .XS -->
2716 <!-- (SN Expose Events -->
2717 <!-- .XE -->
2718 <para>
2719 <!-- .LP -->
2720 <indexterm><primary>Events</primary><secondary>Expose</secondary></indexterm>
2721 <indexterm significance="preferred"><primary>Expose</primary></indexterm>
2722 The X server can report
2723 <symbol>Expose</symbol>
2724 events to clients wanting information about when the contents of window regions
2725 have been lost.
2726 The circumstances in which the X server generates
2727 <symbol>Expose</symbol>
2728 events are not as definite as those for other events.
2729 However, the X server never generates
2730 <symbol>Expose</symbol>
2731 events on windows whose class you specified as
2732 <symbol>InputOnly</symbol>.
2733 The X server can generate
2734 <symbol>Expose</symbol>
2735 events when no valid contents are available for regions of a window
2736 and either the regions are visible,
2737 the regions are viewable and the server is (perhaps newly) maintaining
2738 backing store on the window,
2739 or the window is not viewable but the server is (perhaps newly) honoring the
2740 window's backing-store attribute of
2741 <symbol>Always</symbol>
2742 or
2743 <symbol>WhenMapped</symbol>.
2744 The regions decompose into an (arbitrary) set of rectangles,
2745 and an
2746 <symbol>Expose</symbol>
2747 event is generated for each rectangle.
2748 For any given window,
2749 the X server guarantees to report contiguously
2750 all of the regions exposed by some action that causes
2751 <symbol>Expose</symbol>
2752 events, such as raising a window.
2753 </para>
2754 <para>
2755 <!-- .LP -->
2756 To receive
2757 <symbol>Expose</symbol>
2758 events, set the
2759 <symbol>ExposureMask</symbol>
2760 bit in the event-mask attribute of the window.
2761 </para>
2762 <para>
2763 <!-- .LP -->
2764 The structure for this event type contains:
2765 </para>
2766 <para>
2767 <!-- .LP -->
2768 <indexterm significance="preferred"><primary>XExposeEvent</primary></indexterm>
2769 <!-- .sM -->
2770 <literallayout class="monospaced">
2771 <!-- .TA .5i 3i -->
2772 <!-- .ta .5i 3i -->
2773 typedef struct {
2774      int           type;           /* Expose */
2775      unsigned long serial;         /* # of last request processed by server */
2776      Bool          send_event;     /* true if this came from a SendEvent request */
2777      Display       *display;       /* Display the event was read from */
2778      Window        window;
2779      int           x, y;
2780      int           width, height;
2781      int           count;          /* if nonzero, at least this many more */
2782 } XExposeEvent;
2783 </literallayout>
2784 </para>
2785 <para>
2786 <!-- .LP -->
2787 <!-- .eM -->
2788 The window member is set to the exposed (damaged) window.
2789 The x and y members are set to the coordinates relative to the window's origin
2790 and indicate the upper-left corner of the rectangle.
2791 The width and height members are set to the size (extent) of the rectangle.
2792 The count member is set to the number of
2793 <symbol>Expose</symbol>
2794 events that are to follow.
2795 If count is zero, no more
2796 <symbol>Expose</symbol>
2797 events follow for this window.
2798 However, if count is nonzero, at least that number of
2799 <symbol>Expose</symbol>
2800 events (and possibly more) follow for this window.
2801 Simple applications that do not want to optimize redisplay by distinguishing
2802 between subareas of its window can just ignore all
2803 <symbol>Expose</symbol>
2804 events with nonzero counts and perform full redisplays
2805 on events with zero counts.
2806 </para>
2807 </sect2>
2808 <sect2 id="GraphicsExpose_and_NoExpose_Events">
2809 <title>GraphicsExpose and NoExpose Events</title>
2810 <!-- .XS -->
2811 <!-- (SN GraphicsExpose and NoExpose Events -->
2812 <!-- .XE -->
2813 <para>
2814 <!-- .LP -->
2815 <indexterm><primary>Events</primary><secondary>GraphicsExpose</secondary></indexterm>
2816 <indexterm><primary>Events</primary><secondary>NoExpose</secondary></indexterm>
2817 <indexterm significance="preferred"><primary>GraphicsExpose</primary></indexterm>
2818 The X server can report
2819 <symbol>GraphicsExpose</symbol>
2820 events to clients wanting information about when a destination region could not
2821 be computed during certain graphics requests:
2822 <xref linkend='XCopyArea' xrefstyle='select: title'/>
2823 or
2824 <xref linkend='XCopyPlane' xrefstyle='select: title'/>.
2825 The X server generates this event whenever a destination region could not be
2826 computed because of an obscured or out-of-bounds source region.
2827 In addition, the X server guarantees to report contiguously all of the regions exposed by
2828 some graphics request
2829 (for example, copying an area of a drawable to a destination
2830 drawable).
2831 </para>
2832 <para>
2833 <!-- .LP -->
2834 <indexterm significance="preferred"><primary>NoExpose</primary></indexterm>
2835 The X server generates a
2836 <symbol>NoExpose</symbol>
2837 event whenever a graphics request that might
2838 produce a
2839 <symbol>GraphicsExpose</symbol>
2840 event does not produce any.
2841 In other words, the client is really asking for a
2842 <symbol>GraphicsExpose</symbol>
2843 event but instead receives a
2844 <symbol>NoExpose</symbol>
2845 event.
2846 </para>
2847 <para>
2848 <!-- .LP -->
2849 To receive
2850 <symbol>GraphicsExpose</symbol>
2851 or
2852 <symbol>NoExpose</symbol>
2853 events, you must first set the graphics-exposure
2854 attribute of the graphics context to
2855 <symbol>True</symbol>.
2856 You also can set the graphics-expose attribute when creating a graphics
2857 context using
2858 <xref linkend='XCreateGC' xrefstyle='select: title'/>
2859 or by calling
2860 <xref linkend='XSetGraphicsExposures' xrefstyle='select: title'/>.
2861 </para>
2862 <para>
2863 <!-- .LP -->
2864 The structures for these event types contain:
2865 </para>
2866 <para>
2867 <!-- .LP -->
2868 <indexterm significance="preferred"><primary>XGraphicsExposeEvent</primary></indexterm>
2869 <!-- .sM -->
2870 <literallayout class="monospaced">
2871 <!-- .TA .5i 3i -->
2872 <!-- .ta .5i 3i -->
2873 typedef struct {
2874      int            type;           /* GraphicsExpose */
2875      unsigned long  serial;         /* # of last request processed by server */
2876      Bool           send_event;     /* true if this came from a SendEvent request */
2877      Display        *display;       /* Display the event was read from */
2878      Drawable       drawable;
2879      int            x, y;
2880      int            width, height;
2881      int            count;          /* if nonzero, at least this many more */
2882      int            major_code;     /* core is CopyArea or CopyPlane */
2883      int            minor_code;     /* not defined in the core */
2884 } XGraphicsExposeEvent;
2885 </literallayout>
2886 </para>
2887 <para>
2888 <!-- .LP -->
2889 <indexterm significance="preferred"><primary>XNoExposeEvent</primary></indexterm>
2890 <literallayout class="monospaced">
2891 <!-- .TA .5i 3i -->
2892 <!-- .ta .5i 3i -->
2893 typedef struct {
2894      int           type;         /* NoExpose */
2895      unsigned long serial;       /* # of last request processed by server */
2896      Bool          send_event;   /* true if this came from a SendEvent request */
2897      Display       *display;     /* Display the event was read from */
2898      Drawable      drawable;
2899      int           major_code;   /* core is CopyArea or CopyPlane */
2900      int           minor_code;   /* not defined in the core */
2901 } XNoExposeEvent;
2902 </literallayout>
2903 </para>
2904 <para>
2905 <!-- .LP -->
2906 <!-- .eM -->
2907 Both structures have these common members: drawable, major_code, and minor_code.
2908 The drawable member is set to the drawable of the destination region on
2909 which the graphics request was to be performed.
2910 The major_code member is set to the graphics request initiated by the client
2911 and can be either
2912 <symbol>X_CopyArea</symbol>
2913 or
2914 <symbol>X_CopyPlane</symbol>.
2915 If it is
2916 <symbol>X_CopyArea</symbol>,
2917 a call to
2918 <xref linkend='XCopyArea' xrefstyle='select: title'/>
2919 initiated the request.
2920 If it is
2921 <symbol>X_CopyPlane</symbol>,
2922 a call to
2923 <xref linkend='XCopyPlane' xrefstyle='select: title'/>
2924 initiated the request.
2925 These constants are defined in
2926 <filename class="headerfile">&lt;X11/Xproto.h&gt;</filename>.
2927 <indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm>
2928 <indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xproto.h&gt;</filename></secondary></indexterm>
2929 <indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xproto.h&gt;</filename></secondary></indexterm>
2930 The minor_code member,
2931 like the major_code member,
2932 indicates which graphics request was initiated by
2933 the client.
2934 However, the minor_code member is not defined by the core
2935 X protocol and will be zero in these cases,
2936 although it may be used by an extension.
2937 </para>
2938 <para>
2939 <!-- .LP -->
2940 The
2941 <structname>XGraphicsExposeEvent</structname>
2942 structure has these additional members: x, y, width, height, and count.
2943 The x and y members are set to the coordinates relative to the drawable's origin
2944 and indicate the upper-left corner of the rectangle.
2945 The width and height members are set to the size (extent) of the rectangle.
2946 The count member is set to the number of
2947 <symbol>GraphicsExpose</symbol>
2948 events to follow.
2949 If count is zero, no more
2950 <symbol>GraphicsExpose</symbol>
2951 events follow for this window.
2952 However, if count is nonzero, at least that number of
2953 <symbol>GraphicsExpose</symbol>
2954 events (and possibly more) are to follow for this window.
2955 </para>
2956 </sect2>
2957 </sect1>
2958 <sect1 id='Window_State_Change_Events'>
2959 <title>Window State Change Events</title>
2960 <!-- .XS -->
2961 <!-- (SN Window State Change Events -->
2962 <!-- .XE -->
2963 <para>
2964 <!-- .LP -->
2965 The following sections discuss:
2966 </para>
2967 <itemizedlist>
2968   <listitem>
2969     <para>
2970 <symbol>CirculateNotify</symbol>
2971 events
2972     </para>
2973   </listitem>
2974   <listitem>
2975     <para>
2976 <symbol>ConfigureNotify</symbol>
2977 events
2978     </para>
2979   </listitem>
2980   <listitem>
2981     <para>
2982 <symbol>CreateNotify</symbol>
2983 events
2984     </para>
2985   </listitem>
2986   <listitem>
2987     <para>
2988 <symbol>DestroyNotify</symbol>
2989 events
2990     </para>
2991   </listitem>
2992   <listitem>
2993     <para>
2994 <symbol>GravityNotify</symbol>
2995 events
2996     </para>
2997   </listitem>
2998   <listitem>
2999     <para>
3000 <symbol>MapNotify</symbol>
3001 events
3002     </para>
3003   </listitem>
3004   <listitem>
3005     <para>
3006 <symbol>MappingNotify</symbol>
3007 events
3008     </para>
3009   </listitem>
3010   <listitem>
3011     <para>
3012 <symbol>ReparentNotify</symbol>
3013 events
3014     </para>
3015   </listitem>
3016   <listitem>
3017     <para>
3018 <symbol>UnmapNotify</symbol>
3019 events
3020     </para>
3021   </listitem>
3022   <listitem>
3023     <para>
3024 <symbol>VisibilityNotify</symbol>
3025 events
3026 <!-- .\" .SH 3 -->
3027     </para>
3028   </listitem>
3029 </itemizedlist>
3030 <sect2 id="CirculateNotify_Events">
3031 <title>CirculateNotify Events</title>
3032 <!-- .XS -->
3033 <!-- (SN CirculateNotify Events -->
3034 <!-- .XE -->
3035 <para>
3036 <!-- .LP -->
3037 <indexterm><primary>Events</primary><secondary>CirculateNotify</secondary></indexterm>
3038 <indexterm significance="preferred"><primary>CirculateNotify</primary></indexterm>
3039 The X server can report
3040 <symbol>CirculateNotify</symbol>
3041 events to clients wanting information about when a window changes
3042 its position in the stack.
3043 The X server generates this event type whenever a window is actually restacked
3044 as a result of a client application calling
3045 <xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>,
3046 <xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>,
3047 or
3048 <xref linkend='XCirculateSubwindowsDown' xrefstyle='select: title'/>.
3049 </para>
3050 <para>
3051 <!-- .LP -->
3052 To receive
3053 <symbol>CirculateNotify</symbol>
3054 events, set the
3055 <symbol>StructureNotifyMask</symbol>
3056 bit in the event-mask attribute of the window
3057 or the
3058 <symbol>SubstructureNotifyMask</symbol>
3059 bit in the event-mask attribute of the parent window
3060 (in which case, circulating any child generates an event).
3061 </para>
3062 <para>
3063 <!-- .LP -->
3064 The structure for this event type contains:
3065 </para>
3066 <para>
3067 <!-- .LP -->
3068 <indexterm significance="preferred"><primary>XCirculateEvent</primary></indexterm>
3069 <!-- .sM -->
3070 <literallayout class="monospaced">
3071 <!-- .TA .5i 3i -->
3072 <!-- .ta .5i 3i -->
3073 typedef struct {
3074      int type;     /* CirculateNotify */
3075      unsigned long serial;     /* # of last request processed by server */
3076      Bool send_event;     /* true if this came from a SendEvent request */
3077      Display *display;     /* Display the event was read from */
3078      Window event;
3079      Window window;
3080      int place;     /* PlaceOnTop, PlaceOnBottom */
3081 } XCirculateEvent;
3082 </literallayout>
3083 </para>
3084 <para>
3085 <!-- .LP -->
3086 <!-- .eM -->
3087 The event member is set either to the restacked window or to its parent,
3088 depending on whether
3089 <systemitem class="event">StructureNotify</systemitem>
3090 or
3091 <systemitem class="event">SubstructureNotify</systemitem>
3092 was selected.
3093 The window member is set to the window that was restacked.
3094 The place member is set to the window's position after the restack occurs and
3095 is either
3096 <symbol>PlaceOnTop</symbol>
3097 or
3098 <symbol>PlaceOnBottom</symbol>.
3099 If it is
3100 <symbol>PlaceOnTop</symbol>,
3101 the window is now on top of all siblings.
3102 If it is
3103 <symbol>PlaceOnBottom</symbol>,
3104 the window is now below all siblings.
3105 </para>
3106 </sect2>
3107 <sect2 id="ConfigureNotify_Events">
3108 <title>ConfigureNotify Events</title>
3109 <!-- .XS -->
3110 <!-- (SN ConfigureNotify Events -->
3111 <!-- .XE -->
3112 <para>
3113 <!-- .LP -->
3114 <indexterm><primary>Events</primary><secondary>ConfigureNotify</secondary></indexterm>
3115 <indexterm significance="preferred"><primary>ConfigureNotify</primary></indexterm>
3116 The X server can report
3117 <symbol>ConfigureNotify</symbol>
3118 events to clients wanting information about actual changes to a window's
3119 state, such as size, position, border, and stacking order.
3120 The X server generates this event type whenever one of the following configure
3121 window requests made by a client application actually completes:
3122 </para>
3123 <itemizedlist>
3124   <listitem>
3125     <para>
3126 A window's size, position, border, and/or stacking order is reconfigured
3127 by calling
3128 <xref linkend='XConfigureWindow' xrefstyle='select: title'/>.
3129     </para>
3130   </listitem>
3131   <listitem>
3132     <para>
3133 The window's position in the stacking order is changed by calling
3134 <xref linkend='XLowerWindow' xrefstyle='select: title'/>,
3135 <xref linkend='XRaiseWindow' xrefstyle='select: title'/>,
3136 or
3137 <xref linkend='XRestackWindows' xrefstyle='select: title'/>.
3138     </para>
3139   </listitem>
3140   <listitem>
3141     <para>
3142 A window is moved by calling
3143 <xref linkend='XMoveWindow' xrefstyle='select: title'/>.
3144     </para>
3145   </listitem>
3146   <listitem>
3147     <para>
3148 A window's size is changed by calling
3149 <xref linkend='XResizeWindow' xrefstyle='select: title'/>.
3150     </para>
3151   </listitem>
3152   <listitem>
3153     <para>
3154 A window's size and location is changed by calling
3155 <xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>.
3156     </para>
3157   </listitem>
3158   <listitem>
3159     <para>
3160 A window is mapped and its position in the stacking order is changed
3161 by calling
3162 <xref linkend='XMapRaised' xrefstyle='select: title'/>.
3163     </para>
3164   </listitem>
3165   <listitem>
3166     <para>
3167 A window's border width is changed by calling
3168 <xref linkend='XSetWindowBorderWidth' xrefstyle='select: title'/>.
3169     </para>
3170   </listitem>
3171 </itemizedlist>
3172 <para>
3173 <!-- .LP -->
3174 To receive
3175 <symbol>ConfigureNotify</symbol>
3176 events, set the
3177 <symbol>StructureNotifyMask</symbol>
3178 bit in the event-mask attribute of the window or the
3179 <symbol>SubstructureNotifyMask</symbol>
3180 bit in the event-mask attribute of the parent window
3181 (in which case, configuring any child generates an event).
3182 </para>
3183 <para>
3184 <!-- .LP -->
3185 The structure for this event type contains:
3186 </para>
3187 <!-- .LP -->
3188 <indexterm significance="preferred"><primary>XConfigureEvent</primary></indexterm>
3189 <!-- .sM -->
3190 <literallayout class="monospaced">
3191 <!-- .TA .5i 3i -->
3192 <!-- .ta .5i 3i -->
3193 typedef struct {
3194      int           type;       /* ConfigureNotify */
3195      unsigned long serial;     /* # of last request processed by server */
3196      Bool          send_event; /* true if this came from a SendEvent request */
3197      Display       *display;   /* Display the event was read from */
3198      Window        event;
3199      Window        window;
3200      int           x, y;
3201      int           width, height;
3202      int           border_width;
3203      Window        above;
3204      Bool          override_redirect;
3205 } XConfigureEvent;
3206 </literallayout>
3207 <para>
3208 <!-- .LP -->
3209 <!-- .eM -->
3210 The event member is set either to the reconfigured window or to its parent,
3211 depending on whether
3212 <systemitem class="event">StructureNotify</systemitem>
3213 or
3214 <systemitem class="event">SubstructureNotify</systemitem>
3215 was selected.
3216 The window member is set to the window whose size, position,
3217 border, and/or stacking
3218 order was changed.
3219 </para>
3220 <para>
3221 <!-- .LP -->
3222 The x and y members are set to the coordinates relative to the parent window's
3223 origin and indicate the position of the upper-left outside corner of the window.
3224 The width and height members are set to the inside size of the window,
3225 not including
3226 the border.
3227 The border_width member is set to the width of the window's border, in pixels.
3228 </para>
3229 <para>
3230 <!-- .LP -->
3231 The above member is set to the sibling window and is used
3232 for stacking operations.
3233 If the X server sets this member to
3234 <symbol>None</symbol>,
3235 the window whose state was changed is on the bottom of the stack
3236 with respect to sibling windows.
3237 However, if this member is set to a sibling window,
3238 the window whose state was changed is placed on top of this sibling window.
3239 </para>
3240 <para>
3241 <!-- .LP -->
3242 The override_redirect member is set to the override-redirect attribute of the
3243 window.
3244 Window manager clients normally should ignore this window if the
3245 override_redirect member
3246 is
3247 <symbol>True</symbol>.
3248 </para>
3249 </sect2>
3250 <sect2 id="CreateNotify_Events">
3251 <title>CreateNotify Events</title>
3252 <!-- .XS -->
3253 <!-- (SN CreateNotify Events -->
3254 <!-- .XE -->
3255 <para>
3256 <!-- .LP -->
3257 <indexterm><primary>Events</primary><secondary>CreateNotify</secondary></indexterm>
3258 <indexterm significance="preferred"><primary>CreateNotify</primary></indexterm>
3259 The X server can report
3260 <symbol>CreateNotify</symbol>
3261 events to clients wanting information about creation of windows.
3262 The X server generates this event whenever a client
3263 application creates a window by calling
3264 <xref linkend='XCreateWindow' xrefstyle='select: title'/>
3265 or
3266 <xref linkend='XCreateSimpleWindow' xrefstyle='select: title'/>.
3267 </para>
3268 <para>
3269 <!-- .LP -->
3270 To receive
3271 <symbol>CreateNotify</symbol>
3272 events, set the
3273 <symbol>SubstructureNotifyMask</symbol>
3274 bit in the event-mask attribute of the window.
3275 Creating any children then generates an event.
3276 </para>
3277 <para>
3278 <!-- .LP -->
3279 The structure for the event type contains:
3280 </para>
3281 <para>
3282 <!-- .LP -->
3283 <indexterm significance="preferred"><primary>XCreateWindowEvent</primary></indexterm>
3284 <!-- .sM -->
3285 <literallayout class="monospaced">
3286 <!-- .TA .5i 3i -->
3287 <!-- .ta .5i 3i -->
3288 typedef struct {
3289      int           type;               /* CreateNotify */
3290      unsigned long serial;             /* # of last request processed by server */
3291      Bool          send_event;         /* true if this came from a SendEvent request */
3292      Display       *display;           /* Display the event was read from */
3293      Window        parent;             /* parent of the window */
3294      Window        window;             /* window id of window created */
3295      int           x, y;               /* window location */
3296      int           width, height;      /* size of window */
3297      int           border_width;       /* border width */
3298      Bool          override_redirect;  /* creation should be overridden */
3299 } XCreateWindowEvent;
3300 </literallayout>
3301 </para>
3302 <para>
3303 <!-- .LP -->
3304 <!-- .eM -->
3305 The parent member is set to the created window's parent.
3306 The window member specifies the created window.
3307 The x and y members are set to the created window's coordinates relative
3308 to the parent window's origin and indicate the position of the upper-left
3309 outside corner of the created window.
3310 The width and height members are set to the inside size of the created window
3311 (not including the border) and are always nonzero.
3312 The border_width member is set to the width of the created window's border, in pixels.
3313 The override_redirect member is set to the override-redirect attribute of the
3314 window.
3315 Window manager clients normally should ignore this window
3316 if the override_redirect member is
3317 <symbol>True</symbol>.
3318 </para>
3319 </sect2>
3320 <sect2 id="DestroyNotify_Events">
3321 <title>DestroyNotify Events</title>
3322 <!-- .XS -->
3323 <!-- (SN DestroyNotify Events -->
3324 <!-- .XE -->
3325 <para>
3326 <!-- .LP -->
3327 <indexterm><primary>Events</primary><secondary>DestroyNotify</secondary></indexterm>
3328 <indexterm significance="preferred"><primary>DestroyNotify</primary></indexterm>
3329 The X server can report
3330 <symbol>DestroyNotify</symbol>
3331 events to clients wanting information about which windows are destroyed.
3332 The X server generates this event whenever a client application destroys a
3333 window by calling
3334 <xref linkend='XDestroyWindow' xrefstyle='select: title'/>
3335 or
3336 <xref linkend='XDestroySubwindows' xrefstyle='select: title'/>.
3337 </para>
3338 <para>
3339 <!-- .LP -->
3340 The ordering of the
3341 <symbol>DestroyNotify</symbol>
3342 events is such that for any given window,
3343 <symbol>DestroyNotify</symbol>
3344 is generated on all inferiors of the window
3345 before being generated on the window itself.
3346 The X protocol does not constrain the ordering among
3347 siblings and across subhierarchies.
3348 </para>
3349 <para>
3350 <!-- .LP -->
3351 To receive
3352 <symbol>DestroyNotify</symbol>
3353 events, set the
3354 <symbol>StructureNotifyMask</symbol>
3355 bit in the event-mask attribute of the window or the
3356 <symbol>SubstructureNotifyMask</symbol>
3357 bit in the event-mask attribute of the parent window
3358 (in which case, destroying any child generates an event).
3359 </para>
3360 <para>
3361 <!-- .LP -->
3362 The structure for this event type contains:
3363 </para>
3364 <para>
3365 <!-- .LP -->
3366 <indexterm significance="preferred"><primary>XDestroyWindowEvent</primary></indexterm>
3367 <!-- .sM -->
3368 <literallayout class="monospaced">
3369 <!-- .TA .5i 3i -->
3370 <!-- .ta .5i 3i -->
3371 typedef struct {
3372      int           type;       /* DestroyNotify */
3373      unsigned long serial;     /* # of last request processed by server */
3374      Bool          send_event; /* true if this came from a SendEvent request */
3375      Display       *display;   /* Display the event was read from */
3376      Window        event;
3377      Window        window;
3378 } XDestroyWindowEvent;
3379 </literallayout>
3380 </para>
3381 <para>
3382 <!-- .LP -->
3383 <!-- .eM -->
3384 The event member is set either to the destroyed window or to its parent,
3385 depending on whether
3386 <systemitem class="event">StructureNotify</systemitem>
3387 or
3388 <systemitem class="event">SubstructureNotify</systemitem>
3389 was selected.
3390 The window member is set to the window that is destroyed.
3391 </para>
3392 </sect2>
3393 <sect2 id="GravityNotify_Events">
3394 <title>GravityNotify Events</title>
3395 <!-- .XS -->
3396 <!-- (SN GravityNotify Events -->
3397 <!-- .XE -->
3398 <para>
3399 <!-- .LP -->
3400 <indexterm><primary>Events</primary><secondary>GravityNotify</secondary></indexterm>
3401 <indexterm significance="preferred"><primary>GravityNotify</primary></indexterm>
3402 The X server can report
3403 <symbol>GravityNotify</symbol>
3404 events to clients wanting information about when a window is moved because of a
3405 change in the size of its parent.
3406 The X server generates this event whenever a client
3407 application actually moves a child window as a result of resizing its parent by calling
3408 <xref linkend='XConfigureWindow' xrefstyle='select: title'/>,
3409 <xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>,
3410 or
3411 <xref linkend='XResizeWindow' xrefstyle='select: title'/>.
3412 </para>
3413 <para>
3414 <!-- .LP -->
3415 To receive
3416 <symbol>GravityNotify</symbol>
3417 events, set the
3418 <symbol>StructureNotifyMask</symbol>
3419 bit in the event-mask attribute of the window or the
3420 <symbol>SubstructureNotifyMask</symbol>
3421 bit in the event-mask attribute of the parent window
3422 (in which case, any child that is moved because its parent has been resized
3423 generates an event).
3424 </para>
3425 <para>
3426 <!-- .LP -->
3427 The structure for this event type contains:
3428 </para>
3429 <para>
3430 <!-- .LP -->
3431 <indexterm significance="preferred"><primary>XGravityEvent</primary></indexterm>
3432 <!-- .sM -->
3433 <literallayout class="monospaced">
3434 <!-- .TA .5i 3i -->
3435 <!-- .ta .5i 3i -->
3436 typedef struct {
3437      int           type;       /* GravityNotify */
3438      unsigned long serial;     /* # of last request processed by server */
3439      Bool          send_event; /* true if this came from a SendEvent request */
3440      Display       *display;   /* Display the event was read from */
3441      Window        event;
3442      Window        window;
3443      int           x, y;
3444 } XGravityEvent;
3445 </literallayout>
3446 </para>
3447 <para>
3448 <!-- .LP -->
3449 <!-- .eM -->
3450 The event member is set either to the window that was moved or to its parent,
3451 depending on whether
3452 <systemitem class="event">StructureNotify</systemitem>
3453 or
3454 <systemitem class="event">SubstructureNotify</systemitem>
3455 was selected.
3456 The window member is set to the child window that was moved.
3457 The x and y members are set to the coordinates relative to the
3458 new parent window's origin
3459 and indicate the position of the upper-left outside corner of the
3460 window.
3461 </para>
3462 </sect2>
3463 <sect2 id="MapNotify_Events">
3464 <title>MapNotify Events</title>
3465 <!-- .XS -->
3466 <!-- (SN MapNotify Events -->
3467 <!-- .XE -->
3468 <para>
3469 <!-- .LP -->
3470 <indexterm><primary>Events</primary><secondary>MapNotify</secondary></indexterm>
3471 <indexterm significance="preferred"><primary>MapNotify</primary></indexterm>
3472 The X server can report
3473 <symbol>MapNotify</symbol>
3474 events to clients wanting information about which windows are mapped.
3475 The X server generates this event type whenever a client application changes the
3476 window's state from unmapped to mapped by calling
3477 <xref linkend='XMapWindow' xrefstyle='select: title'/>,
3478 <xref linkend='XMapRaised' xrefstyle='select: title'/>,
3479 <xref linkend='XMapSubwindows' xrefstyle='select: title'/>,
3480 <xref linkend='XReparentWindow' xrefstyle='select: title'/>,
3481 or as a result of save-set processing.
3482 </para>
3483 <para>
3484 <!-- .LP -->
3485 To receive
3486 <symbol>MapNotify</symbol>
3487 events, set the
3488 <symbol>StructureNotifyMask</symbol>
3489 bit in the event-mask attribute of the window or the
3490 <symbol>SubstructureNotifyMask</symbol>
3491 bit in the event-mask attribute of the parent window
3492 (in which case, mapping any child generates an event).
3493 </para>
3494 <para>
3495 <!-- .LP -->
3496 The structure for this event type contains:
3497 </para>
3498 <para>
3499 <!-- .LP -->
3500 <indexterm significance="preferred"><primary>XMapEvent</primary></indexterm>
3501 <!-- .sM -->
3502 <literallayout class="monospaced">
3503 <!-- .TA .5i 3i -->
3504 <!-- .ta .5i 3i -->
3505 typedef struct {
3506      int           type;                  /* MapNotify */
3507      unsigned long serial;                /* # of last request processed by server */
3508      Bool          send_event;            /* true if this came from a SendEvent request */
3509      Display       *display;              /* Display the event was read from */
3510      Window        event;
3511      Window        window;
3512      Bool          override_redirect;     /* boolean, is override set... */
3513 } XMapEvent;
3514 </literallayout>
3515 </para>
3516 <para>
3517 <!-- .LP -->
3518 <!-- .eM -->
3519 The event member is set either to the window that was mapped or to its parent,
3520 depending on whether
3521 <systemitem class="event">StructureNotify</systemitem>
3522 or
3523 <systemitem class="event">SubstructureNotify</systemitem>
3524 was selected.
3525 The window member is set to the window that was mapped.
3526 The override_redirect member is set to the override-redirect attribute
3527 of the window.
3528 Window manager clients normally should ignore this window
3529 if the override-redirect attribute is
3530 <symbol>True</symbol>,
3531 because these events usually are generated from pop-ups,
3532 which override structure control.
3533 </para>
3534 </sect2>
3535 <sect2 id="MappingNotify_Events">
3536 <title>MappingNotify Events</title>
3537 <!-- .XS -->
3538 <!-- (SN MappingNotify Events -->
3539 <!-- .XE -->
3540 <para>
3541 <!-- .LP -->
3542 <indexterm><primary>Events</primary><secondary>MappingNotify</secondary></indexterm>
3543 <indexterm significance="preferred"><primary>MappingNotify</primary></indexterm>
3544 The X server reports
3545 <symbol>MappingNotify</symbol>
3546 events to all clients.
3547 There is no mechanism to express disinterest in this event.
3548 The X server generates this event type whenever a client application
3549 successfully calls:
3550 </para>
3551 <itemizedlist>
3552   <listitem>
3553     <para>
3554 <xref linkend='XSetModifierMapping' xrefstyle='select: title'/>
3555 to indicate which KeyCodes are to be used as modifiers
3556     </para>
3557   </listitem>
3558   <listitem>
3559     <para>
3560 <xref linkend='XChangeKeyboardMapping' xrefstyle='select: title'/>
3561 to change the keyboard mapping
3562     </para>
3563   </listitem>
3564   <listitem>
3565     <para>
3566 <xref linkend='XSetPointerMapping' xrefstyle='select: title'/>
3567 to set the pointer mapping
3568     </para>
3569   </listitem>
3570 </itemizedlist>
3571 <para>
3572 <!-- .LP -->
3573 The structure for this event type contains:
3574 </para>
3575 <para>
3576 <!-- .LP -->
3577 <indexterm significance="preferred"><primary>XMappingEvent</primary></indexterm>
3578 <!-- .sM -->
3579 <literallayout class="monospaced">
3580 <!-- .TA .5i 3i -->
3581 <!-- .ta .5i 3i -->
3582 typedef struct {
3583      int           type;           /* MappingNotify */
3584      unsigned long serial;         /* # of last request processed by server */
3585      Bool          send_event;     /* true if this came from a SendEvent request */
3586      Display       *display;       /* Display the event was read from */
3587      Window        window;         /* unused */
3588      int           request;        /* one of MappingModifier, MappingKeyboard,
3589                    MappingPointer  */
3590      int           first_keycode;  /* first keycode */
3591      int           count;          /* defines range of change w. first_keycode*/
3592 } XMappingEvent;
3593 </literallayout>
3594 </para>
3595 <para>
3596 <!-- .LP -->
3597 <!-- .eM -->
3598 The request member is set to indicate the kind of mapping change that occurred
3599 and can be
3600 <symbol>MappingModifier</symbol>,
3601 <symbol>MappingKeyboard</symbol>,
3602 or
3603 <symbol>MappingPointer</symbol>.
3604 If it is
3605 <symbol>MappingModifier</symbol>,
3606 the modifier mapping was changed.
3607 If it is
3608 <symbol>MappingKeyboard</symbol>,
3609 the keyboard mapping was changed.
3610 If it is
3611 <symbol>MappingPointer</symbol>,
3612 the pointer button mapping was changed.
3613 The first_keycode and count members are set only
3614 if the request member was set to
3615 <symbol>MappingKeyboard</symbol>.
3616 The number in first_keycode represents the first number in the range
3617 of the altered mapping,
3618 and count represents the number of keycodes altered.
3619 </para>
3620 <para>
3621 <!-- .LP -->
3622 To update the client application's knowledge of the keyboard,
3623 you should call
3624 <xref linkend='XRefreshKeyboardMapping' xrefstyle='select: title'/>.
3625 </para>
3626 </sect2>
3627 <sect2 id="ReparentNotify_Events">
3628 <title>ReparentNotify Events</title>
3629 <!-- .XS -->
3630 <!-- (SN ReparentNotify Events -->
3631 <!-- .XE -->
3632 <para>
3633 <!-- .LP -->
3634 <indexterm><primary>Events</primary><secondary>ReparentNotify</secondary></indexterm>
3635 <indexterm significance="preferred"><primary>ReparentNotify</primary></indexterm>
3636 The X server can report
3637 <symbol>ReparentNotify</symbol>
3638 events to clients wanting information about changing a window's parent.
3639 The X server generates this event whenever a client
3640 application calls
3641 <xref linkend='XReparentWindow' xrefstyle='select: title'/>
3642 and the window is actually reparented.
3643 </para>
3644 <para>
3645 <!-- .LP -->
3646 To receive
3647 <symbol>ReparentNotify</symbol>
3648 events, set the
3649 <symbol>StructureNotifyMask</symbol>
3650 bit in the event-mask attribute of the window or the
3651 <symbol>SubstructureNotifyMask</symbol>
3652 bit in the event-mask attribute of either the old or the new parent window
3653 (in which case, reparenting any child generates an event).
3654 </para>
3655 <para>
3656 <!-- .LP -->
3657 The structure for this event type contains:
3658 </para>
3659 <para>
3660 <!-- .LP -->
3661 <indexterm significance="preferred"><primary>XReparentEvent</primary></indexterm>
3662 <!-- .sM -->
3663 <literallayout class="monospaced">
3664 <!-- .TA .5i 3i -->
3665 <!-- .ta .5i 3i -->
3666 typedef struct {
3667      int           type;       /* ReparentNotify */
3668      unsigned long serial;     /* # of last request processed by server */
3669      Bool          send_event; /* true if this came from a SendEvent request */
3670      Display       *display;   /* Display the event was read from */
3671      Window        event;
3672      Window        window;
3673      Window        parent;
3674      int           x, y;
3675      Bool          override_redirect;
3676 } XReparentEvent;
3677 </literallayout>
3678 </para>
3679 <para>
3680 <!-- .LP -->
3681 <!-- .eM -->
3682 The event member is set either to the reparented window
3683 or to the old or the new parent, depending on whether
3684 <systemitem class="event">StructureNotify</systemitem>
3685 or
3686 <systemitem class="event">SubstructureNotify</systemitem>
3687 was selected.
3688 The window member is set to the window that was reparented.
3689 The parent member is set to the new parent window.
3690 The x and y members are set to the reparented window's coordinates relative
3691 to the new parent window's
3692 origin and define the upper-left outer corner of the reparented window.
3693 The override_redirect member is set to the override-redirect attribute of the
3694 window specified by the window member.
3695 Window manager clients normally should ignore this window
3696 if the override_redirect member is
3697 <symbol>True</symbol>.
3698 </para>
3699 </sect2>
3700 <sect2 id="UnmapNotify_Events">
3701 <title>UnmapNotify Events</title>
3702 <!-- .XS -->
3703 <!-- (SN UnmapNotify Events -->
3704 <!-- .XE -->
3705 <para>
3706 <!-- .LP -->
3707 <indexterm><primary>Events</primary><secondary>UnmapNotify</secondary></indexterm>
3708 <indexterm significance="preferred"><primary>UnmapNotify</primary></indexterm>
3709 The X server can report
3710 <symbol>UnmapNotify</symbol>
3711 events to clients wanting information about which windows are unmapped.
3712 The X server generates this event type whenever a client application changes the
3713 window's state from mapped to unmapped.
3714 </para>
3715 <para>
3716 <!-- .LP -->
3717 To receive
3718 <symbol>UnmapNotify</symbol>
3719 events, set the
3720 <symbol>StructureNotifyMask</symbol>
3721 bit in the event-mask attribute of the window or the
3722 <symbol>SubstructureNotifyMask</symbol>
3723 bit in the event-mask attribute of the parent window
3724 (in which case, unmapping any child window generates an event).
3725 </para>
3726 <para>
3727 <!-- .LP -->
3728 The structure for this event type contains:
3729 </para>
3730 <para>
3731 <!-- .LP -->
3732 <indexterm significance="preferred"><primary>XUnmapEvent</primary></indexterm>
3733 <!-- .sM -->
3734 <literallayout class="monospaced">
3735 <!-- .TA .5i 3i -->
3736 <!-- .ta .5i 3i -->
3737 typedef struct {
3738      int           type;       /* UnmapNotify */
3739      unsigned long serial;     /* # of last request processed by server */
3740      Bool          send_event; /* true if this came from a SendEvent request */
3741      Display       *display;   /* Display the event was read from */
3742      Window        event;
3743      Window        window;
3744      Bool          from_configure;
3745 } XUnmapEvent;
3746 </literallayout>
3747 </para>
3748 <para>
3749 <!-- .LP -->
3750 <!-- .eM -->
3751 The event member is set either to the unmapped window or to its parent,
3752 depending on whether
3753 <systemitem class="event">StructureNotify</systemitem>
3754 or
3755 <systemitem class="event">SubstructureNotify</systemitem>
3756 was selected.
3757 This is the window used by the X server to report the event.
3758 The window member is set to the window that was unmapped.
3759 The from_configure member is set to
3760 <symbol>True</symbol>
3761 if the event was generated as a result of a resizing of the window's parent when
3762 the window itself had a win_gravity of
3763 <symbol>UnmapGravity</symbol>.
3764 </para>
3765 </sect2>
3766 <sect2 id="VisibilityNotify_Events">
3767 <title>VisibilityNotify Events</title>
3768 <!-- .XS -->
3769 <!-- (SN VisibilityNotify Events -->
3770 <!-- .XE -->
3771 <para>
3772 <!-- .LP -->
3773 <indexterm><primary>Events</primary><secondary>VisibilityNotify</secondary></indexterm>
3774 <indexterm significance="preferred"><primary>VisibilityNotify</primary></indexterm>
3775 The X server can report
3776 <symbol>VisibilityNotify</symbol>
3777 events to clients wanting any change in the visibility of the specified window.
3778 A region of a window is visible if someone looking at the screen can
3779 actually see it.
3780 The X server generates this event whenever the visibility changes state.
3781 However, this event is never generated for windows whose class is
3782 <symbol>InputOnly</symbol>.
3783 </para>
3784 <para>
3785 <!-- .LP -->
3786 All
3787 <symbol>VisibilityNotify</symbol>
3788 events caused by a hierarchy change are generated
3789 after any hierarchy event
3790 (<symbol>UnmapNotify</symbol>,
3791 <symbol>MapNotify</symbol>,
3792 <symbol>ConfigureNotify</symbol>,
3793 <symbol>GravityNotify</symbol>,
3794 <symbol>CirculateNotify</symbol>)
3795 caused by that change.  Any
3796 <symbol>VisibilityNotify</symbol>
3797 event on a given window is generated before any
3798 <symbol>Expose</symbol>
3799 events on that window, but it is not required that all
3800 <symbol>VisibilityNotify</symbol>
3801 events on all windows be generated before all
3802 <symbol>Expose</symbol>
3803 events on all windows.
3804 The X protocol does not constrain the ordering of
3805 <symbol>VisibilityNotify</symbol>
3806 events with
3807 respect to
3808 <symbol>FocusOut</symbol>,
3809 <symbol>EnterNotify</symbol>,
3810 and
3811 <symbol>LeaveNotify</symbol>
3812 events.
3813 </para>
3814 <para>
3815 <!-- .LP -->
3816 To receive
3817 <symbol>VisibilityNotify</symbol>
3818 events, set the
3819 <symbol>VisibilityChangeMask</symbol>
3820 bit in the event-mask attribute of the window.
3821 </para>
3822 <para>
3823 <!-- .LP -->
3824 The structure for this event type contains:
3825 </para>
3826 <para>
3827 <!-- .LP -->
3828 <indexterm significance="preferred"><primary>XVisibilityEvent</primary></indexterm>
3829 <!-- .sM -->
3830 <literallayout class="monospaced">
3831 <!-- .TA .5i 3i -->
3832 <!-- .ta .5i 3i -->
3833 typedef struct {
3834      int           type;       /* VisibilityNotify */
3835      unsigned long serial;     /* # of last request processed by server */
3836      Bool          send_event; /* true if this came from a SendEvent request */
3837      Display       *display;   /* Display the event was read from */
3838      Window        window;
3839      int           state;
3840 } XVisibilityEvent;
3841 </literallayout>
3842 </para>
3843 <para>
3844 <!-- .LP -->
3845 <!-- .eM -->
3846 The window member is set to the window whose visibility state changes.
3847 The state member is set to the state of the window's visibility and can be
3848 <symbol>VisibilityUnobscured</symbol>,
3849 <symbol>VisibilityPartiallyObscured</symbol>,
3850 or
3851 <symbol>VisibilityFullyObscured</symbol>.
3852 The X server ignores all of a window's subwindows
3853 when determining the visibility state of the window and processes
3854 <symbol>VisibilityNotify</symbol>
3855 events according to the following:
3856 </para>
3857 <itemizedlist>
3858   <listitem>
3859     <para>
3860 When the window changes state from partially obscured, fully obscured,
3861 or not viewable to viewable and completely unobscured,
3862 the X server generates the event with the state member of the
3863 <structname>XVisibilityEvent</structname>
3864 structure set to
3865 <symbol>VisibilityUnobscured</symbol>.
3866     </para>
3867   </listitem>
3868   <listitem>
3869     <para>
3870 When the window changes state from viewable and completely unobscured or
3871 not viewable to viewable and partially obscured,
3872 the X server generates the event with the state member of the
3873 <structname>XVisibilityEvent</structname>
3874 structure set to
3875 <symbol>VisibilityPartiallyObscured</symbol>.
3876     </para>
3877   </listitem>
3878   <listitem>
3879     <para>
3880 When the window changes state from viewable and completely unobscured,
3881 viewable and partially obscured, or not viewable to viewable and
3882 fully obscured,
3883 the X server generates the event with the state member of the
3884 <structname>XVisibilityEvent</structname>
3885 structure set to
3886 <symbol>VisibilityFullyObscured</symbol>.
3887     </para>
3888   </listitem>
3889 </itemizedlist>
3890 </sect2>
3891 </sect1>
3892 <sect1 id="Structure_Control_Events">
3893 <title>Structure Control Events</title>
3894 <!-- .XS -->
3895 <!-- (SN Structure Control Events -->
3896 <!-- .XE -->
3897 <para>
3898 <!-- .LP -->
3899 This section discusses:
3900 </para>
3901 <itemizedlist>
3902   <listitem>
3903     <para>
3904 <symbol>CirculateRequest</symbol>
3905 events
3906     </para>
3907   </listitem>
3908   <listitem>
3909     <para>
3910 <symbol>ConfigureRequest</symbol>
3911 events
3912     </para>
3913   </listitem>
3914   <listitem>
3915     <para>
3916 <symbol>MapRequest</symbol>
3917 events
3918     </para>
3919   </listitem>
3920   <listitem>
3921     <para>
3922 <symbol>ResizeRequest</symbol>
3923 events
3924     </para>
3925   </listitem>
3926 </itemizedlist>
3927 <sect2 id="CirculateRequest_Events">
3928 <title>CirculateRequest Events</title>
3929 <!-- .XS -->
3930 <!-- (SN CirculateRequest Events -->
3931 <!-- .XE -->
3932 <para>
3933 <!-- .LP -->
3934 <indexterm><primary>Events</primary><secondary>CirculateRequest</secondary></indexterm>
3935 <indexterm significance="preferred"><primary>CirculateRequest</primary></indexterm>
3936 The X server can report
3937 <symbol>CirculateRequest</symbol>
3938 events to clients wanting information about
3939 when another client initiates a circulate window request
3940 on a specified window.
3941 The X server generates this event type whenever a client initiates a circulate
3942 window request on a window and a subwindow actually needs to be restacked.
3943 The client initiates a circulate window request on the window by calling
3944 <xref linkend='XCirculateSubwindows' xrefstyle='select: title'/>,
3945 <xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>,
3946 or
3947 <xref linkend='XCirculateSubwindowsDown' xrefstyle='select: title'/>.
3948 </para>
3949 <para>
3950 <!-- .LP -->
3951 To receive
3952 <symbol>CirculateRequest</symbol>
3953 events, set the
3954 <symbol>SubstructureRedirectMask</symbol>
3955 in the event-mask attribute of the window.
3956 Then, in the future,
3957 the circulate window request for the specified window is not executed,
3958 and thus, any subwindow's position in the stack is not changed.
3959 For example, suppose a client application calls
3960 <xref linkend='XCirculateSubwindowsUp' xrefstyle='select: title'/>
3961 to raise a subwindow to the top of the stack.
3962 If you had selected
3963 <symbol>SubstructureRedirectMask</symbol>
3964 on the window, the X server reports to you a
3965 <symbol>CirculateRequest</symbol>
3966 event and does not raise the subwindow to the top of the stack.
3967 </para>
3968 <para>
3969 <!-- .LP -->
3970 The structure for this event type contains:
3971 </para>
3972 <para>
3973 <!-- .LP -->
3974 <indexterm significance="preferred"><primary>XCirculateRequestEvent</primary></indexterm>
3975 <!-- .sM -->
3976 <literallayout class="monospaced">
3977 <!-- .TA .5i 3i -->
3978 <!-- .ta .5i 3i -->
3979 typedef struct {
3980      int           type;       /* CirculateRequest */
3981      unsigned long serial;     /* # of last request processed by server */
3982      Bool          send_event; /* true if this came from a SendEvent request */
3983      Display       *display;   /* Display the event was read from */
3984      Window        parent;
3985      Window        window;
3986      int place;                /* PlaceOnTop, PlaceOnBottom */
3987 } XCirculateRequestEvent;
3988 </literallayout>
3989 </para>
3990 <para>
3991 <!-- .LP -->
3992 <!-- .eM -->
3993 The parent member is set to the parent window.
3994 The window member is set to the subwindow to be restacked.
3995 The place member is set to what the new position in the stacking order should be
3996 and is either
3997 <symbol>PlaceOnTop</symbol>
3998 or
3999 <symbol>PlaceOnBottom</symbol>.
4000 If it is
4001 <symbol>PlaceOnTop</symbol>,
4002 the subwindow should be on top of all siblings.
4003 If it is
4004 <symbol>PlaceOnBottom</symbol>,
4005 the subwindow should be below all siblings.
4006 </para>
4007 </sect2>
4008 <sect2 id="ConfigureRequest_Events">
4009 <title>ConfigureRequest Events</title>
4010 <!-- .XS -->
4011 <!-- (SN ConfigureRequest Events -->
4012 <!-- .XE -->
4013 <para>
4014 <!-- .LP -->
4015 <indexterm><primary>Events</primary><secondary>ConfigureRequest</secondary></indexterm>
4016 <indexterm significance="preferred"><primary>ConfigureRequest</primary></indexterm>
4017 The X server can report
4018 <symbol>ConfigureRequest</symbol>
4019 events to clients wanting information about when a different client initiates
4020 a configure window request on any child of a specified window.
4021 The configure window request attempts to
4022 reconfigure a window's size, position, border, and stacking order.
4023 The X server generates this event whenever a different client initiates
4024 a configure window request on a window by calling
4025 <xref linkend='XConfigureWindow' xrefstyle='select: title'/>,
4026 <xref linkend='XLowerWindow' xrefstyle='select: title'/>,
4027 <xref linkend='XRaiseWindow' xrefstyle='select: title'/>,
4028 <xref linkend='XMapRaised' xrefstyle='select: title'/>,
4029 <xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>,
4030 <xref linkend='XMoveWindow' xrefstyle='select: title'/>,
4031 <xref linkend='XResizeWindow' xrefstyle='select: title'/>,
4032 <xref linkend='XRestackWindows' xrefstyle='select: title'/>,
4033 or
4034 <xref linkend='XSetWindowBorderWidth' xrefstyle='select: title'/>.
4035 </para>
4036 <para>
4037 <!-- .LP -->
4038 To receive
4039 <symbol>ConfigureRequest</symbol>
4040 events, set the
4041 <symbol>SubstructureRedirectMask</symbol>
4042 bit in the event-mask attribute of the window.
4043 <symbol>ConfigureRequest</symbol>
4044 events are generated when a
4045 <systemitem>ConfigureWindow</systemitem>
4046 protocol request is issued on a child window by another client.
4047 For example, suppose a client application calls
4048 <xref linkend='XLowerWindow' xrefstyle='select: title'/>
4049 to lower a window.
4050 If you had selected
4051 <symbol>SubstructureRedirectMask</symbol>
4052 on the parent window and if the override-redirect attribute
4053 of the window is set to
4054 <symbol>False</symbol>,
4055 the X server reports a
4056 <symbol>ConfigureRequest</symbol>
4057 event to you and does not lower the specified window.
4058 </para>
4059 <para>
4060 <!-- .LP -->
4061 The structure for this event type contains:
4062 </para>
4063 <para>
4064 <!-- .LP -->
4065 <indexterm significance="preferred"><primary>XConfigureRequestEvent</primary></indexterm>
4066 <!-- .sM -->
4067 <literallayout class="monospaced">
4068 <!-- .TA .5i 3i -->
4069 <!-- .ta .5i 3i -->
4070 typedef struct {
4071      int           type;         /* ConfigureRequest */
4072      unsigned long serial;       /* # of last request processed by server */
4073      Bool          send_event;   /* true if this came from a SendEvent request */
4074      Display       *display;     /* Display the event was read from */
4075      Window        parent;
4076      Window        window;
4077      int           x, y;
4078      int           width, height;
4079      int           border_width;
4080      Window        above;
4081      int           detail;       /* Above, Below, TopIf, BottomIf, Opposite */
4082      unsigned long value_mask;
4083 } XConfigureRequestEvent;
4084 </literallayout>
4085 </para>
4086 <para>
4087 <!-- .LP -->
4088 <!-- .eM -->
4089 The parent member is set to the parent window.
4090 The window member is set to the window whose size, position, border width,
4091 and/or stacking order is to be reconfigured.
4092 The value_mask member indicates which components were specified in the
4093 <systemitem>ConfigureWindow</systemitem>
4094 protocol request.
4095 The corresponding values are reported as given in the request.
4096 The remaining values are filled in from the current geometry of the window,
4097 except in the case of above (sibling) and detail (stack-mode),
4098 which are reported as
4099 <symbol>None</symbol>
4100 and
4101 <symbol>Above</symbol>,
4102 respectively, if they are not given in the request.
4103 </para>
4104 </sect2>
4105 <sect2 id="MapRequest_Events">
4106 <title>MapRequest Events</title>
4107 <!-- .XS -->
4108 <!-- (SN MapRequest Events -->
4109 <!-- .XE -->
4110 <para>
4111 <!-- .LP -->
4112 <indexterm><primary>Events</primary><secondary>MapRequest</secondary></indexterm>
4113 <indexterm significance="preferred"><primary>MapRequest</primary></indexterm>
4114 The X server can report
4115 <symbol>MapRequest</symbol>
4116 events to clients wanting information about a different client's desire
4117 to map windows.
4118 A window is considered mapped when a map window request completes.
4119 The X server generates this event whenever a different client initiates
4120 a map window request on an unmapped window whose override_redirect member
4121 is set to
4122 <symbol>False</symbol>.
4123 Clients initiate map window requests by calling
4124 <xref linkend='XMapWindow' xrefstyle='select: title'/>,
4125 <xref linkend='XMapRaised' xrefstyle='select: title'/>,
4126 or
4127 <xref linkend='XMapSubwindows' xrefstyle='select: title'/>.
4128 </para>
4129 <para>
4130 <!-- .LP -->
4131 To receive
4132 <symbol>MapRequest</symbol>
4133 events, set the
4134 <symbol>SubstructureRedirectMask</symbol>
4135 bit in the event-mask attribute of the window.
4136 This means another client's attempts to map a child window by calling one of
4137 the map window request functions is intercepted, and you are sent a
4138 <symbol>MapRequest</symbol>
4139 instead.
4140 For example, suppose a client application calls
4141 <xref linkend='XMapWindow' xrefstyle='select: title'/>
4142 to map a window.
4143 If you (usually a window manager) had selected
4144 <symbol>SubstructureRedirectMask</symbol>
4145 on the parent window and if the override-redirect attribute
4146 of the window is set to
4147 <symbol>False</symbol>,
4148 the X server reports a
4149 <symbol>MapRequest</symbol>
4150 event to you
4151 and does not map the specified window.
4152 Thus, this event gives your window manager client the ability
4153 to control the placement of subwindows.
4154 </para>
4155 <para>
4156 <!-- .LP -->
4157 The structure for this event type contains:
4158 </para>
4159 <para>
4160 <!-- .LP -->
4161 <indexterm significance="preferred"><primary>XMapRequestEvent</primary></indexterm>
4162 <!-- .sM -->
4163 <literallayout class="monospaced">
4164 <!-- .TA .5i 3i -->
4165 <!-- .ta .5i 3i -->
4166 typedef struct {
4167      int           type;       /* MapRequest */
4168      unsigned long serial;     /* # of last request processed by server */
4169      Bool          send_event; /* true if this came from a SendEvent request */
4170      Display       *display;   /* Display the event was read from */
4171      Window        parent;
4172      Window        window;
4173 } XMapRequestEvent;
4174 </literallayout>
4175 </para>
4176 <para>
4177 <!-- .LP -->
4178 <!-- .eM -->
4179 The parent member is set to the parent window.
4180 The window member is set to the window to be mapped.
4181 </para>
4182 </sect2>
4183 <sect2 id="ResizeRequest_Events">
4184 <title>ResizeRequest Events</title>
4185 <!-- .XS -->
4186 <!-- (SN ResizeRequest Events -->
4187 <!-- .XE -->
4188 <para>
4189 <!-- .LP -->
4190 <indexterm><primary>Events</primary><secondary>ResizeRequest</secondary></indexterm>
4191 <indexterm significance="preferred"><primary>ResizeRequest</primary></indexterm>
4192 The X server can report
4193 <symbol>ResizeRequest</symbol>
4194 events to clients wanting information about another client's attempts to change the
4195 size of a window.
4196 The X server generates this event whenever some other client attempts to change
4197 the size of the specified window by calling
4198 <xref linkend='XConfigureWindow' xrefstyle='select: title'/>,
4199 <xref linkend='XResizeWindow' xrefstyle='select: title'/>,
4200 or
4201 <xref linkend='XMoveResizeWindow' xrefstyle='select: title'/>.
4202 </para>
4203 <para>
4204 <!-- .LP -->
4205 To receive
4206 <symbol>ResizeRequest</symbol>
4207 events, set the
4208 <symbol>ResizeRedirect</symbol>
4209 bit in the event-mask attribute of the window.
4210 Any attempts to change the size by other clients are then redirected.
4211 </para>
4212 <para>
4213 <!-- .LP -->
4214 The structure for this event type contains:
4215 </para>
4216 <para>
4217 <!-- .LP -->
4218 <indexterm significance="preferred"><primary>XResizeRequestEvent</primary></indexterm>
4219 <!-- .sM -->
4220 <literallayout class="monospaced">
4221 <!-- .TA .5i 3i -->
4222 <!-- .ta .5i 3i -->
4223 typedef struct {
4224      int           type;        /* ResizeRequest */
4225      unsigned long serial;      /* # of last request processed by server */
4226      Bool          send_event;  /* true if this came from a SendEvent request */
4227      Display       *display;    /* Display the event was read from */
4228      Window        window;
4229      int           width, height;
4230 } XResizeRequestEvent;
4231 </literallayout>
4232 </para>
4233 <para>
4234 <!-- .LP -->
4235 <!-- .eM -->
4236 The window member is set to the window whose size another
4237 client attempted to change.
4238 The width and height members are set to the inside size of the window,
4239 excluding the border.
4240 </para>
4241 </sect2>
4242 </sect1>
4243 <sect1 id="Colormap_State_Change_Events">
4244 <title>Colormap State Change Events</title>
4245 <!-- .XS -->
4246 <!-- (SN Colormap State Change Events -->
4247 <!-- .XE -->
4248 <para>
4249 <!-- .LP -->
4250 <indexterm><primary>Events</primary><secondary>ColormapNotify</secondary></indexterm>
4251 <indexterm significance="preferred"><primary>ColormapNotify</primary></indexterm>
4252 The X server can report
4253 <symbol>ColormapNotify</symbol>
4254 events to clients wanting information about when the colormap changes
4255 and when a colormap is installed or uninstalled.
4256 The X server generates this event type whenever a client application:
4257 </para>
4258 <itemizedlist>
4259   <listitem>
4260     <para>
4261 Changes the colormap member of the
4262 <structname>XSetWindowAttributes</structname>
4263 structure by
4264 calling
4265 <xref linkend='XChangeWindowAttributes' xrefstyle='select: title'/>,
4266 <xref linkend='XFreeColormap' xrefstyle='select: title'/>,
4267 or
4268 <xref linkend='XSetWindowColormap' xrefstyle='select: title'/>
4269     </para>
4270   </listitem>
4271   <listitem>
4272     <para>
4273 Installs or uninstalls the colormap by calling
4274 <xref linkend='XInstallColormap' xrefstyle='select: title'/>
4275 or
4276 <xref linkend='XUninstallColormap' xrefstyle='select: title'/>
4277     </para>
4278   </listitem>
4279 </itemizedlist>
4280 <para>
4281 <!-- .LP -->
4282 To receive
4283 <symbol>ColormapNotify</symbol>
4284 events, set the
4285 <symbol>ColormapChangeMask</symbol>
4286 bit in the event-mask attribute of the window.
4287 </para>
4288 <para>
4289 <!-- .LP -->
4290 The structure for this event type contains:
4291 </para>
4292 <para>
4293 <!-- .LP -->
4294 <indexterm significance="preferred"><primary>XColormapEvent</primary></indexterm>
4295 <!-- .sM -->
4296 <literallayout class="monospaced">
4297 <!-- .TA .5i 3i -->
4298 <!-- .ta .5i 3i -->
4299 typedef struct {
4300      int           type;       /* ColormapNotify */
4301      unsigned long serial;     /* # of last request processed by server */
4302      Bool          send_event; /* true if this came from a SendEvent request */
4303      Display       *display;   /* Display the event was read from */
4304      Window        window;
4305      Colormap      colormap;   /* colormap or None */
4306      Bool          new;
4307      int           state;      /* ColormapInstalled, ColormapUninstalled */
4308 } XColormapEvent;
4309 </literallayout>
4310 </para>
4311 <para>
4312 <!-- .LP -->
4313 <!-- .eM -->
4314 The window member is set to the window whose associated
4315 colormap is changed, installed, or uninstalled.
4316 For a colormap that is changed, installed, or uninstalled,
4317 the colormap member is set to the colormap associated with the window.
4318 For a colormap that is changed by a call to
4319 <xref linkend='XFreeColormap' xrefstyle='select: title'/>,
4320 the colormap member is set to
4321 <symbol>None</symbol>.
4322 The new member is set to indicate whether the colormap
4323 for the specified window was changed or installed or uninstalled
4324 and can be
4325 <symbol>True</symbol>
4326 or
4327 <symbol>False</symbol>.
4328 If it is
4329 <symbol>True</symbol>,
4330 the colormap was changed.
4331 If it is
4332 <symbol>False</symbol>,
4333 the colormap was installed or uninstalled.
4334 The state member is always set to indicate whether the colormap is installed or
4335 uninstalled and can be
4336 <symbol>ColormapInstalled</symbol>
4337 or
4338 <symbol>ColormapUninstalled</symbol>.
4339 </para>
4340 </sect1>
4341 <sect1 id="Client_Communication_Events">
4342 <title>Client Communication Events</title>
4343 <!-- .XS -->
4344 <!-- (SN Client Communication Events -->
4345 <!-- .XE -->
4346 <para>
4347 <!-- .LP -->
4348 This section discusses:
4349 </para>
4350 <itemizedlist>
4351   <listitem>
4352     <para>
4353 <symbol>ClientMessage</symbol>
4354 events
4355     </para>
4356   </listitem>
4357   <listitem>
4358     <para>
4359 <symbol>PropertyNotify</symbol>
4360 events
4361     </para>
4362   </listitem>
4363   <listitem>
4364     <para>
4365 <symbol>SelectionClear</symbol>
4366 events
4367     </para>
4368   </listitem>
4369   <listitem>
4370     <para>
4371 <symbol>SelectionNotify</symbol>
4372 events
4373     </para>
4374   </listitem>
4375   <listitem>
4376     <para>
4377 <symbol>SelectionRequest</symbol>
4378 events
4379     </para>
4380   </listitem>
4381 </itemizedlist>
4382 <sect2 id="ClientMessage_Events">
4383 <title>ClientMessage Events</title>
4384 <!-- .XS -->
4385 <!-- (SN ClientMessage Events -->
4386 <!-- .XE -->
4387 <para>
4388 <!-- .LP -->
4389 <indexterm><primary>Events</primary><secondary>ClientMessage</secondary></indexterm>
4390 <indexterm significance="preferred"><primary>ClientMessage</primary></indexterm>
4391 The X server generates
4392 <symbol>ClientMessage</symbol>
4393 events only when a client calls the function
4394 <xref linkend='XSendEvent' xrefstyle='select: title'/>.
4395 </para>
4396 <para>
4397 <!-- .LP -->
4398 The structure for this event type contains:
4399 </para>
4400 <para>
4401 <!-- .LP -->
4402 <indexterm significance="preferred"><primary>XClientMessageEvent</primary></indexterm>
4403 <!-- .sM -->
4404 <literallayout class="monospaced">
4405 <!-- .TA .5i 1i 3i -->
4406 <!-- .ta .5i 1i 3i -->
4407 typedef struct {
4408      int           type;           /* ClientMessage */
4409      unsigned long serial;         /* # of last request processed by server */
4410      Bool          send_event;     /* true if this came from a SendEvent request */
4411      Display       *display;       /* Display the event was read from */
4412      Window        window;
4413      Atom          message_type;
4414      int           format;
4415      union         {
4416                      char  b[20];
4417                      short s[10];
4418                      long  l[5];
4419                    } data;
4420 } XClientMessageEvent;
4421 </literallayout>
4422 </para>
4423 <para>
4424 <!-- .LP -->
4425 <!-- .eM -->
4426 The message_type member is set to an atom that indicates how the data
4427 should be interpreted by the receiving client.
4428 The format member is set to 8, 16, or 32 and specifies whether the data
4429 should be viewed as a list of bytes, shorts, or longs.
4430 The data member is a union that contains the members b, s, and l.
4431 The b, s, and l members represent data of twenty 8-bit values,
4432 ten 16-bit values, and five 32-bit values.
4433 Particular message types might not make use of all these values.
4434 The X server places no interpretation on the values in the window,
4435 message_type, or data members.
4436 </para>
4437 </sect2>
4438 <sect2 id="PropertyNotify_Events">
4439 <title>PropertyNotify Events</title>
4440 <!-- .XS -->
4441 <!-- (SN PropertyNotify Events -->
4442 <!-- .XE -->
4443 <para>
4444 <!-- .LP -->
4445 <indexterm><primary>Events</primary><secondary>PropertyNotify</secondary></indexterm>
4446 <indexterm significance="preferred"><primary>PropertyNotify</primary></indexterm>
4447 The X server can report
4448 <symbol>PropertyNotify</symbol>
4449 events to clients wanting information about property changes
4450 for a specified window.
4451 </para>
4452 <para>
4453 <!-- .LP -->
4454 To receive
4455 <symbol>PropertyNotify</symbol>
4456 events, set the
4457 <symbol>PropertyChangeMask</symbol>
4458 bit in the event-mask attribute of the window.
4459 </para>
4460 <para>
4461 <!-- .LP -->
4462 The structure for this event type contains:
4463 </para>
4464 <para>
4465 <!-- .LP -->
4466 <indexterm significance="preferred"><primary>XPropertyEvent</primary></indexterm>
4467 <!-- .sM -->
4468 <literallayout class="monospaced">
4469 <!-- .TA .5i 3i -->
4470 <!-- .ta .5i 3i -->
4471 typedef struct {
4472      int           type;       /* PropertyNotify */
4473      unsigned long serial;     /* # of last request processed by server */
4474      Bool          send_event; /* true if this came from a SendEvent request */
4475      Display       *display;   /* Display the event was read from */
4476      Window        window;
4477      Atom atom;
4478      Time time;
4479      int state;                /* PropertyNewValue or PropertyDelete */
4480 } XPropertyEvent;
4481 </literallayout>
4482 </para>
4483 <para>
4484 <!-- .LP -->
4485 <!-- .eM -->
4486 The window member is set to the window whose associated
4487 property was changed.
4488 The atom member is set to the property's atom and indicates which
4489 property was changed or desired.
4490 The time member is set to the server time when the property was changed.
4491 The state member is set to indicate whether the property was changed
4492 to a new value or deleted and can be
4493 <symbol>PropertyNewValue</symbol>
4494 or
4495 <symbol>PropertyDelete</symbol>.
4496 The state member is set to
4497 <symbol>PropertyNewValue</symbol>
4498 when a property of the window is changed using
4499 <xref linkend='XChangeProperty' xrefstyle='select: title'/>
4500 or
4501 <xref linkend='XRotateWindowProperties' xrefstyle='select: title'/>
4502 (even when adding zero-length data using
4503 <xref linkend='XChangeProperty' xrefstyle='select: title'/>)
4504 and when replacing all or part of a property with identical data using
4505 <xref linkend='XChangeProperty' xrefstyle='select: title'/>
4506 or
4507 <xref linkend='XRotateWindowProperties' xrefstyle='select: title'/>.
4508 The state member is set to
4509 <symbol>PropertyDelete</symbol>
4510 when a property of the window is deleted using
4511 <xref linkend='XDeleteProperty' xrefstyle='select: title'/>
4512 or, if the delete argument is
4513 <symbol>True</symbol>,
4514 <xref linkend='XGetWindowProperty' xrefstyle='select: title'/>.
4515 </para>
4516 </sect2>
4517 <sect2 id="SelectionClear_Events">
4518 <title>SelectionClear Events</title>
4519 <!-- .XS -->
4520 <!-- (SN SelectionClear Events -->
4521 <!-- .XE -->
4522 <para>
4523 <!-- .LP -->
4524 <indexterm ><primary>Events</primary><secondary>SelectionClear</secondary></indexterm>
4525 <indexterm significance="preferred"><primary>SelectionClear</primary></indexterm>
4526 The X server reports
4527 <symbol>SelectionClear</symbol>
4528 events to the client losing ownership of a selection.
4529 The X server generates this event type when another client
4530 asserts ownership of the selection by calling
4531 <xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>.
4532 </para>
4533 <para>
4534 <!-- .LP -->
4535 The structure for this event type contains:
4536 </para>
4537 <para>
4538 <!-- .LP -->
4539 <indexterm significance="preferred"><primary>XSelectionClearEvent</primary></indexterm>
4540 <!-- .sM -->
4541 <literallayout class="monospaced">
4542 <!-- .TA .5i 3i -->
4543 <!-- .ta .5i 3i -->
4544 typedef struct {
4545      int           type;       /* SelectionClear */
4546      unsigned long serial;     /* # of last request processed by server */
4547      Bool          send_event; /* true if this came from a SendEvent request */
4548      Display       *display;   /* Display the event was read from */
4549      Window        window;
4550      Atom          selection;
4551      Time          time;
4552 } XSelectionClearEvent;
4553 </literallayout>
4554 </para>
4555 <para>
4556 <!-- .LP -->
4557 <!-- .eM -->
4558 The selection member is set to the selection atom.
4559 The time member is set to the last change time recorded for the
4560 selection.
4561 The window member is the window that was specified by the current owner
4562 (the owner losing the selection) in its
4563 <xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>
4564 call.
4565 </para>
4566 </sect2>
4567 <sect2 id="SelectionRequest_Events">
4568 <title>SelectionRequest Events</title>
4569 <!-- .XS -->
4570 <!-- (SN SelectionRequest Events -->
4571 <!-- .XE -->
4572 <para>
4573 <!-- .LP -->
4574 <indexterm><primary>Events</primary><secondary>SelectionRequest</secondary></indexterm>
4575 <indexterm significance="preferred"><primary>SelectionRequest</primary></indexterm>
4576 The X server reports
4577 <symbol>SelectionRequest</symbol>
4578 events to the owner of a selection.
4579 The X server generates this event whenever a client
4580 requests a selection conversion by calling
4581 <xref linkend='XConvertSelection' xrefstyle='select: title'/>
4582 for the owned selection.
4583 </para>
4584 <para>
4585 <!-- .LP -->
4586 The structure for this event type contains:
4587 </para>
4588 <para>
4589 <!-- .LP -->
4590 <indexterm significance="preferred"><primary>XSelectionRequestEvent</primary></indexterm>
4591 <!-- .sM -->
4592 <literallayout class="monospaced">
4593 <!-- .TA .5i 3i -->
4594 <!-- .ta .5i 3i -->
4595 typedef struct {
4596      int           type;       /* SelectionRequest */
4597      unsigned long serial;     /* # of last request processed by server */
4598      Bool          send_event; /* true if this came from a SendEvent request */
4599      Display       *display;   /* Display the event was read from */
4600      Window        owner;
4601      Window        requestor;
4602      Atom          selection;
4603      Atom          target;
4604      Atom          property;
4605      Time          time;
4606 } XSelectionRequestEvent;
4607 </literallayout>
4608 </para>
4609 <para>
4610 <!-- .LP -->
4611 <!-- .eM -->
4612 The owner member is set to the window
4613 that was specified by the current owner in its
4614 <xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>
4615 call.
4616 The requestor member is set to the window requesting the selection.
4617 The selection member is set to the atom that names the selection.
4618 For example, PRIMARY is used to indicate the primary selection.
4619 The target member is set to the atom that indicates the type
4620 the selection is desired in.
4621 The property member can be a property name or
4622 <symbol>None</symbol>.
4623 The time member is set to the timestamp or
4624 <symbol>CurrentTime</symbol>
4625 value from the
4626 <systemitem>ConvertSelection</systemitem>
4627 request.
4628 </para>
4629 <para>
4630 <!-- .LP -->
4631 The owner should convert the selection based on the specified target type
4632 and send a
4633 <symbol>SelectionNotify</symbol>
4634 event back to the requestor.
4635 A <olink targetdoc='icccm'
4636 targetptr='Peer_to_Peer_Communication_by_Means_of_Selections'>complete
4637 specification for using selections</olink> is given in the X Consortium
4638 standard <citetitle>Inter-Client Communication Conventions Manual</citetitle>.
4639 </para>
4640 </sect2>
4641 <sect2 id="SelectionNotify_Events">
4642 <title>SelectionNotify Events</title>
4643 <!-- .XS -->
4644 <!-- (SN SelectionNotify Events -->
4645 <!-- .XE -->
4646 <para>
4647 <!-- .LP -->
4648 <indexterm><primary>Events</primary><secondary>SelectionNotify</secondary></indexterm>
4649 <indexterm significance="preferred"><primary>SelectionNotify</primary></indexterm>
4650 This event is generated by the X server in response to a
4651 <systemitem>ConvertSelection</systemitem>
4652 protocol request when there is no owner for the selection.
4653 When there is an owner, it should be generated by the owner
4654 of the selection by using
4655 <xref linkend='XSendEvent' xrefstyle='select: title'/>.
4656 The owner of a selection should send this event to a requestor when a selection
4657 has been converted and stored as a property
4658 or when a selection conversion could
4659 not be performed (which is indicated by setting the property member to
4660 <symbol>None</symbol>).
4661 </para>
4662 <para>
4663 <!-- .LP -->
4664 If
4665 <symbol>None</symbol>
4666 is specified as the property in the
4667 <systemitem>ConvertSelection</systemitem>
4668 protocol request, the owner should choose a property name,
4669 store the result as that property on the requestor window,
4670 and then send a
4671 <symbol>SelectionNotify</symbol>
4672 giving that actual property name.
4673 </para>
4674 <para>
4675 <!-- .LP -->
4676 The structure for this event type contains:
4677 </para>
4678 <para>
4679 <!-- .LP -->
4680 <indexterm significance="preferred"><primary>XSelectionEvent</primary></indexterm>
4681 <!-- .sM -->
4682 <literallayout class="monospaced">
4683 <!-- .TA .5i 3i -->
4684 <!-- .ta .5i 3i -->
4685 typedef struct {
4686      int           type;       /* SelectionNotify */
4687      unsigned long serial;     /* # of last request processed by server */
4688      Bool          send_event; /* true if this came from a SendEvent request */
4689      Display       *display;   /* Display the event was read from */
4690      Window        requestor;
4691      Atom          selection;
4692      Atom          target;
4693      Atom          property;   /* atom or None */
4694      Time          time;
4695 } XSelectionEvent;
4696 </literallayout>
4697 </para>
4698 <para>
4699 <!-- .LP -->
4700 <!-- .eM -->
4701 The requestor member is set to the window associated with
4702 the requestor of the selection.
4703 The selection member is set to the atom that indicates the selection.
4704 For example, PRIMARY is used for the primary selection.
4705 The target member is set to the atom that indicates the converted type.
4706 For example, PIXMAP is used for a pixmap.
4707 The property member is set to the atom that indicates which
4708 property the result was stored on.
4709 If the conversion failed,
4710 the property member is set to
4711 <symbol>None</symbol>.
4712 The time member is set to the time the conversion took place and
4713 can be a timestamp or
4714 <symbol>CurrentTime</symbol>.
4715 <!-- .bp -->
4716
4717
4718 </para>
4719 </sect2>
4720 </sect1>
4721 </chapter>