diff options
Diffstat (limited to 'specs/libX11/CH10.xml')
| -rw-r--r-- | specs/libX11/CH10.xml | 4725 |
1 files changed, 4725 insertions, 0 deletions
diff --git a/specs/libX11/CH10.xml b/specs/libX11/CH10.xml new file mode 100644 index 00000000..0e77485c --- /dev/null +++ b/specs/libX11/CH10.xml @@ -0,0 +1,4725 @@ +<chapter id="events"> +<title>Events</title> + +<para> +A client application communicates with the X server through the connection you establish with +the XOpenDisplay function. A client application sends requests to the X server over this con- +nection. These requests are made by the Xlib functions that are called in the client application. +Many Xlib functions cause the X server to generate events, and the user’s typing or moving the +pointer can generate events asynchronously. The X server returns events to the client on the same +connection. +</para> +<para> +This chapter discusses the following topics associated with events: +</para> + +<itemizedlist> + <listitem><para>Event types</para></listitem> + <listitem><para>Event structures</para></listitem> + <listitem><para>Event masks</para></listitem> + <listitem><para>Event processing</para></listitem> +</itemizedlist> + +<para> +Functions for handling events are dealt with in the next chapter. +</para> + +<sect1 id="Event_Types"> +<title>Event Types</title> +<!-- .XS --> +<!-- (SN Event Types --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Event" "types" --> +An event is data generated asynchronously by the X server as a result of some +device activity or as side effects of a request sent by an Xlib function. +<!-- .IN "Event" --> +Device-related events propagate from the source window to ancestor windows +until some client application has selected that event type +or until the event is explicitly discarded. +The X server generally sends an event to a client application +only if the client has specifically asked to be informed of that event type, +typically by setting the event-mask attribute of the window. +The mask can also be set when you create a window +or by changing the window's +event-mask. +You can also mask out events that would propagate to ancestor windows +by manipulating the +do-not-propagate mask of the window's attributes. +However, +<function>MappingNotify</function> +events are always sent to all clients. +<!-- .IN "Input Control" --> +<!-- .IN "Output Control" --> +</para> +<para> +<!-- .LP --> +An event type describes a specific event generated by the X server. +For each event type, +a corresponding constant name is defined in +<!-- .hN X11/X.h , --> +which is used when referring to an event type. +<!-- .IN "Event" "categories" --> +The following table lists the event category +and its associated event type or types. +The processing associated with these events is discussed in section 10.5. +</para> +<para> +<!-- .LP --> +<!-- .\".CP T 1 --> +<!-- .\"Event Categories and Event Types --> +</para> +<para> +<!-- .LP --> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Event Category</entry> + <entry>Event Type</entry> + </row> + </thead> + <tbody> + <row> + <entry>Keyboard events</entry> + <entry><function>KeyPress ,</function> + <function>KeyRelease</function></entry> + </row> + <row> + <entry>Pointer events</entry> + <entry><function>ButtonPress , </function> + <function>ButtonRelease ,</function> + <function>MotionNotify</function></entry> + </row> + <row> + <entry>Window crossing events</entry> + <entry><function>EnterNotify , </function> + <function>LeaveNotify</function></entry> + </row> + <row> + <entry>Input focus events</entry> + <entry><function>FocusIn , </function> + <function>FocusOut</function></entry> + </row> + <row> + <entry>Keymap state notification event</entry> + <entry><function>KeymapNotify</function></entry> + </row> + <row> + <entry>Exposure events</entry> + <entry><function>Expose , </function> + <function>GraphicsExpose , </function> + <function>NoExpose</function></entry> + </row> + <row> + <entry>Structure control events</entry> + <entry><function>CirculateRequest , </function> + <function>ConfigureRequest , </function> + <function>MapRequest ,</function> + <function>ResizeRequest</function></entry> + </row> + <row> + <entry>Window state notification events</entry> + <entry> + <function>CirculateNotify , </function> + <function>ConfigureNotify , </function> + <function>CreateNotify , </function> + <function>DestroyNotify , </function> + <function>GravityNotify , </function> + <function>MapNotify ,</function> + <function>MappingNotify , </function> + <function>ReparentNotify , </function> + <function>UnmapNotify , </function> + <function>VisibilityNotify</function></entry> + </row> + <row> + <entry>Colormap state notification event</entry> + <entry><function>ColormapNotify</function></entry> + </row> + <row> + <entry>Client communication events</entry> + <entry><function>ClientMessage , </function> + <function>PropertyNotify , </function> + <function>SelectionClear , </function> + <function>SelectionNotify , </function> + <function>SelectionRequest</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<!-- .\".LP --> +<!-- .\"Table 8-1 lists the event types and the Xlib functions that could cause --> +<!-- .\"the X server to generate that event type. --> +<!-- .\"The event types are listed alphabetically. --> +<!-- .\"Note that the error event is not listed in this table. --> +<!-- .\"For a list of the constants associated with an error event, see the Handling --> +<!-- .\"Errors section in this chapter. --> +<!-- .\".LP --> +<!-- .\".so eventtable --> +</para> +</sect1> +<sect1 id="Event_Structures"> +<title>Event Structures</title> +<!-- .XS --> +<!-- (SN Event Structures --> +<!-- .XE --> +<para> +<!-- .LP --> +For each event type, +a corresponding structure is declared in +<!-- .hN X11/Xlib.h . --> +All the event structures have the following common members: +</para> +<para> +<!-- .LP --> +<!-- .IN "XAnyEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; +} XAnyEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The type member is set to the event type constant name that uniquely identifies +it. +For example, when the X server reports a +<function>GraphicsExpose</function> +event to a client application, it sends an +<function>XGraphicsExposeEvent</function> +structure with the type member set to +<function>GraphicsExpose .</function> +The display member is set to a pointer to the display the event was read on. +The send_event member is set to +<function>True</function> +if the event came from a +<function>SendEvent</function> +protocol request. +The serial member is set from the serial number reported in the protocol +but expanded from the 16-bit least-significant bits to a full 32-bit value. +The window member is set to the window that is most useful to toolkit +dispatchers. +</para> +<para> +<!-- .LP --> +The X server can send events at any time in the input stream. +Xlib stores any events received while waiting for a reply in an event queue +for later use. +Xlib also provides functions that allow you to check events +in the event queue (see section 11.3). +</para> +<para> +<!-- .LP --> +In addition to the individual structures declared for each event type, the +<function>XEvent</function> +structure is a union of the individual structures declared for each event type. +Depending on the type, +you should access members of each event by using the +<function>XEvent</function> +union. +</para> +<para> +<!-- .LP --> +<!-- .IN "XEvent" "" "@DEF@" --> +<!-- .sM --> +</para> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef union _XEvent { + int type; /* must not be changed */ + XAnyEvent xany; + XKeyEvent xkey; + XButtonEvent xbutton; + XMotionEvent xmotion; + XCrossingEvent xcrossing; + XFocusChangeEvent xfocus; + XExposeEvent xexpose; + XGraphicsExposeEvent xgraphicsexpose; + XNoExposeEvent xnoexpose; + XVisibilityEvent xvisibility; + XCreateWindowEvent xcreatewindow; + XDestroyWindowEvent xdestroywindow; + XUnmapEvent xunmap; + XMapEvent xmap; + XMapRequestEvent xmaprequest; + XReparentEvent xreparent; + XConfigureEvent xconfigure; + XGravityEvent xgravity; + XResizeRequestEvent xresizerequest; + XConfigureRequestEvent xconfigurerequest; + XCirculateEvent xcirculate; + XCirculateRequestEvent xcirculaterequest; + XPropertyEvent xproperty; + XSelectionClearEvent xselectionclear; + XSelectionRequestEvent xselectionrequest; + XSelectionEvent xselection; + XColormapEvent xcolormap; + XClientMessageEvent xclient; + XMappingEvent xmapping; + XErrorEvent xerror; + XKeymapEvent xkeymap; + long pad[24]; +} XEvent; +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +An +<function>XEvent</function> +structure's first entry always is the type member, +which is set to the event type. +The second member always is the serial number of the protocol request +that generated the event. +The third member always is send_event, +which is a +<function>Bool</function> +that indicates if the event was sent by a different client. +The fourth member always is a display, +which is the display that the event was read from. +Except for keymap events, +the fifth member always is a window, +which has been carefully selected to be useful to toolkit dispatchers. +To avoid breaking toolkits, +the order of these first five entries is not to change. +Most events also contain a time member, +which is the time at which an event occurred. +In addition, a pointer to the generic event must be cast before it +is used to access any other information in the structure. +</para> +</sect1> +<sect1 id="Event_Masks"> +<title>Event Masks</title> +<!-- .XS --> +<!-- (SN Event Masks --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Event mask" "" "@DEF@" --> +Clients select event reporting of most events relative to a window. +To do this, pass an event mask to an Xlib event-handling +function that takes an event_mask argument. +The bits of the event mask are defined in +<!-- .hN X11/X.h . --> +Each bit in the event mask maps to an event mask name, +which describes the event or events you want the X server to +return to a client application. +</para> +<para> +<!-- .LP --> +Unless the client has specifically asked for them, +most events are not reported to clients when they are generated. +Unless the client suppresses them by setting graphics-exposures in the GC to +<function>False ,</function> +<function>GraphicsExpose </function> +and +<function>NoExpose </function> +are reported by default as a result of +<function>XCopyPlane</function> +and +<function>XCopyArea .</function> +<function>SelectionClear ,</function> +<function>SelectionRequest ,</function> +<function>SelectionNotify ,</function> +or +<function>ClientMessage</function> +cannot be masked. +Selection-related events are only sent to clients cooperating +with selections (see section 4.5). +When the keyboard or pointer mapping is changed, +<function>MappingNotify</function> +is always sent to clients. +</para> +<para> +<!-- .LP --> +<!-- .\"Table 8-2 --> +The following table +lists the event mask constants you can pass to +the event_mask argument and +the circumstances in which you would want to specify the +event mask: +</para> +<!-- .LP --> +<!-- .\" .CP T 2 --> +<!-- .\"Event Mask Definitions --> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Event Mask</entry> + <entry>Circumstances</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>NoEventMask</function></entry> + <entry>No events wanted</entry> + </row> + <row> + <entry><function>KeyPressMask</function></entry> + <entry>Keyboard down events wanted</entry> + </row> + <row> + <entry><function>KeyReleaseMask</function></entry> + <entry>Keyboard up events wanted</entry> + </row> + <row> + <entry><function>ButtonPressMask</function></entry> + <entry>Pointer button down events wanted</entry> + </row> + <row> + <entry><function>ButtonReleaseMask</function></entry> + <entry>Pointer button up events wanted</entry> + </row> + <row> + <entry><function>EnterWindowMask</function></entry> + <entry>Pointer window entry events wanted</entry> + </row> + <row> + <entry><function>LeaveWindowMask</function></entry> + <entry>Pointer window leave events wanted</entry> + </row> + <row> + <entry><function>PointerMotionMask</function></entry> + <entry>Pointer motion events wanted</entry> + </row> + <row> + <entry><function>PointerMotionHintMask</function></entry> + <entry>Pointer motion hints wanted</entry> + </row> + <row> + <entry><function>Button1MotionMask</function></entry> + <entry>Pointer motion while button 1 down</entry> + </row> + <row> + <entry><function>Button2MotionMask</function></entry> + <entry>Pointer motion while button 2 down</entry> + </row> + <row> + <entry><function>Button3MotionMask</function></entry> + <entry>Pointer motion while button 3 down</entry> + </row> + <row> + <entry><function>Button4MotionMask</function></entry> + <entry>Pointer motion while button 4 down</entry> + </row> + <row> + <entry><function>Button5MotionMask</function></entry> + <entry>Pointer motion while button 5 down</entry> + </row> + <row> + <entry><function>ButtonMotionMask</function></entry> + <entry>Pointer motion while any button down</entry> + </row> + <row> + <entry><function>KeymapStateMask</function></entry> + <entry>Keyboard state wanted at window entry and focus in</entry> + </row> + <row> + <entry><function>ExposureMask</function></entry> + <entry>Any exposure wanted</entry> + </row> + <row> + <entry><function>VisibilityChangeMask</function></entry> + <entry>Any change in visibility wanted</entry> + </row> + <row> + <entry><function>StructureNotifyMask</function></entry> + <entry>Any change in window structure wanted</entry> + </row> + <row> + <entry><function>ResizeRedirectMask</function></entry> + <entry>Redirect resize of this window</entry> + </row> + <row> + <entry><function>SubstructureNotifyMask</function></entry> + <entry>Substructure notification wanted</entry> + </row> + <row> + <entry><function>SubstructureRedirectMask</function></entry> + <entry>Redirect structure requests on children</entry> + </row> + <row> + <entry><function>FocusChangeMask</function></entry> + <entry>Any change in input focus wanted</entry> + </row> + <row> + <entry><function>PropertyChangeMask</function></entry> + <entry>Any change in property wanted</entry> + </row> + <row> + <entry><function>ColormapChangeMask</function></entry> + <entry>Any change in colormap wanted</entry> + </row> + <row> + <entry><function>OwnerGrabButtonMask</function></entry> + <entry>Automatic grabs should activate with owner_events set to True</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +</para> +</sect1> +<sect1 id="Event_Processing_Overview"> +<title>Event Processing Overview</title> +<!-- .XS --> +<!-- (SN Event Processing Overview --> +<!-- .XE --> +<para> +<!-- .LP --> +The event reported to a client application during event processing +depends on which event masks you provide as the event-mask attribute +for a window. +For some event masks, there is a one-to-one correspondence between +the event mask constant and the event type constant. +For example, if you pass the event mask +<function>ButtonPressMask ,</function> +the X server sends back only +<function>ButtonPress</function> +events. +<!-- .IN "CurrentTime" --> +Most events contain a time member, +which is the time at which an event occurred. +</para> +<para> +<!-- .LP --> +In other cases, one event mask constant can map to several event type constants. +For example, if you pass the event mask +<function>SubstructureNotifyMask ,</function> +the X server can send back +<function>CirculateNotify ,</function> +<function>ConfigureNotify ,</function> +<function>CreateNotify ,</function> +<function>DestroyNotify ,</function> +<function>GravityNotify ,</function> +<function>MapNotify ,</function> +<function>ReparentNotify ,</function> +or +<function>UnmapNotify</function> +events. +</para> +<para> +<!-- .LP --> +In another case, +two event masks can map to one event type. +For example, +if you pass either +<function>PointerMotionMask </function> +or +<function>ButtonMotionMask ,</function> +the X server sends back +a +<function>MotionNotify</function> +event. +</para> +<para> +<!-- .LP --> +The following table +lists the event mask, +its associated event type or types, +and the structure name associated with the event type. +Some of these structures actually are typedefs to a generic structure +that is shared between two event types. +Note that N.A. appears in columns for which the information is not applicable. +</para> +<!-- .LP --> +<!-- .ps 9 --> +<!-- .nr PS 9 --> +<informaltable> + <tgroup cols='4' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry>Event Mask</entry> + <entry>Event Type</entry> + <entry>Structure</entry> + <entry>Generic Structure</entry> + </row> + </thead> + <tbody> + <row> + <entry>ButtonMotionMask</entry> + <entry>MotionNotify</entry> + <entry>XPointerMovedEvent</entry> + <entry>XMotionEvent</entry> + </row> + <row> + <entry>Button1MotionMask</entry> + </row> + <row> + <entry>Button2MotionMask</entry> + </row> + <row> + <entry>Button3MotionMask</entry> + </row> + <row> + <entry>Button4MotionMask</entry> + </row> + <row> + <entry>Button5MotionMask</entry> + </row> + <row> + <entry>ButtonPressMask</entry> + <entry>ButtonPress</entry> + <entry>XButtonPressedEvent</entry> + <entry>XButtonEvent</entry> + </row> + <row> + <entry>ButtonReleaseMask</entry> + <entry>ButtonRelease</entry> + <entry>XButtonReleasedEvent</entry> + <entry>XButtonEvent</entry> + </row> + <row> + <entry>ColormapChangeMask</entry> + <entry>ColormapNotify</entry> + <entry>XColormapEvent</entry> + </row> + <row> + <entry>EnterWindowMask</entry> + <entry>EnterNotify</entry> + <entry>XEnterWindowEvent</entry> + <entry>XCrossingEvent</entry> + </row> + <row> + <entry>LeaveWindowMask</entry> + <entry>LeaveNotify</entry> + <entry>XLeaveWindowEvent</entry> + <entry>XCrossingEvent</entry> + </row> + <row> + <entry>ExposureMask</entry> + <entry>Expose</entry> + <entry>XExposeEvent </entry> + </row> + <row> + <entry>GCGraphicsExposures in GC</entry> + <entry>GraphicsExpose</entry> + <entry>XGraphicsExposeEvent</entry> + </row> + <row> + <entry></entry> + <entry>NoExpose</entry> + <entry>XNoExposeEvent</entry> + </row> + <row> + <entry>FocusChangeMask</entry> + <entry>FocusIn</entry> + <entry>XFocusInEvent</entry> + <entry>XFocusChangeEvent</entry> + </row> + <row> + <entry></entry> + <entry>FocusOut</entry> + <entry>XFocusOutEvent</entry> + <entry>XFocusChangeEvent</entry> + </row> + <row> + <entry>KeymapStateMask</entry> + <entry>KeymapNotify</entry> + <entry>XKeymapEvent</entry> + </row> + <row> + <entry>KeyPressMask</entry> + <entry>KeyPress</entry> + <entry>XKeyPressedEvent</entry> + <entry>XKeyEvent</entry> + </row> + <row> + <entry>KeyReleaseMask</entry> + <entry>KeyRelease</entry> + <entry>XKeyReleasedEvent</entry> + <entry>XKeyEvent</entry> + </row> + <row> + <entry>OwnerGrabButtonMask</entry> + <entry>N.A.</entry> + <entry>N.A.</entry> + </row> + <row> + <entry>PointerMotionMask</entry> + <entry>MotionNotify</entry> + <entry>XPointerMovedEvent</entry> + <entry>XMotionEvent</entry> + </row> + <row> + <entry>PointerMotionHintMask</entry> + <entry>N.A.</entry> + <entry>N.A.</entry> + </row> + <row> + <entry>PropertyChangeMask</entry> + <entry>PropertyNotify</entry> + <entry>XPropertyEvent</entry> + </row> + <row> + <entry>ResizeRedirectMask</entry> + <entry>ResizeRequest</entry> + <entry>XResizeRequestEvent</entry> + </row> + <row> + <entry>StructureNotifyMask</entry> + <entry>CirculateNotify</entry> + <entry>XCirculateEvent</entry> + </row> + <row> + <entry></entry> + <entry>ConfigureNotify</entry> + <entry>XConfigureEvent</entry> + </row> + <row> + <entry></entry> + <entry>DestroyNotify</entry> + <entry>XDestroyWindowEvent</entry> + </row> + <row> + <entry></entry> + <entry>GravityNotify</entry> + <entry>XGravityEvent</entry> + </row> + <row> + <entry></entry> + <entry>MapNotify</entry> + <entry>XMapEvent</entry> + </row> + <row> + <entry></entry> + <entry>ReparentNotify</entry> + <entry>XReparentEvent</entry> + </row> + <row> + <entry></entry> + <entry>UnmapNotify</entry> + <entry>XUnmapEvent</entry> + </row> + <row> + <entry>SubstructureNotifyMask</entry> + <entry>CirculateNotify</entry> + <entry>XCirculateEvent</entry> + </row> + <row> + <entry></entry> + <entry>ConfigureNotify</entry> + <entry>XConfigureEvent</entry> + </row> + <row> + <entry></entry> + <entry>CreateNotify</entry> + <entry>XCreateWindowEvent</entry> + </row> + <row> + <entry></entry> + <entry>DestroyNotify</entry> + <entry>XDestroyWindowEvent</entry> + </row> + <row> + <entry></entry> + <entry>GravityNotify</entry> + <entry>XGravityEvent</entry> + </row> + <row> + <entry></entry> + <entry>MapNotify</entry> + <entry>XMapEvent</entry> + </row> + <row> + <entry></entry> + <entry>ReparentNotify</entry> + <entry>XReparentEvent</entry> + </row> + <row> + <entry></entry> + <entry>UnmapNotify</entry> + <entry>XUnmapEvent</entry> + </row> + <row> + <entry>SubstructureRedirectMask</entry> + <entry>CirculateRequest</entry> + <entry>XCirculateRequestEvent</entry> + </row> + <row> + <entry></entry> + <entry>ConfigureRequest</entry> + <entry>XConfigureRequestEvent</entry> + </row> + <row> + <entry></entry> + <entry>MapRequest</entry> + <entry>XMapRequestEvent</entry> + </row> + <row> + <entry>N.A.</entry> + <entry>ClientMessage</entry> + <entry>XClientMessageEvent</entry> + </row> + <row> + <entry>N.A.</entry> + <entry>MappingNotify</entry> + <entry>XMappingEvent</entry> + </row> + <row> + <entry>N.A.</entry> + <entry>SelectionClear</entry> + <entry>XSelectionClearEvent</entry> + </row> + <row> + <entry>N.A.</entry> + <entry>SelectionNotify</entry> + <entry>XSelectionEvent</entry> + </row> + <row> + <entry>N.A.</entry> + <entry>SelectionRequest</entry> + <entry>XSelectionRequestEvent</entry> + </row> + <row> + <entry>VisibilityChangeMask</entry> + <entry>VisibilityNotify</entry> + <entry>XVisibilityEvent</entry> + </row> + <row> + <entry>_</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +The sections that follow describe the processing that occurs +when you select the different event masks. +The sections are organized according to these processing categories: +</para> +<itemizedlist> + <listitem> + <para> +Keyboard and pointer events + </para> + </listitem> + <listitem> + <para> +Window crossing events + </para> + </listitem> + <listitem> + <para> +Input focus events + </para> + </listitem> + <listitem> + <para> +Keymap state notification events + </para> + </listitem> + <listitem> + <para> +Exposure events + </para> + </listitem> + <listitem> + <para> +Window state notification events + </para> + </listitem> + <listitem> + <para> +Structure control events + </para> + </listitem> + <listitem> + <para> +Colormap state notification events + </para> + </listitem> + <listitem> + <para> +Client communication events + </para> + </listitem> +</itemizedlist> + +</sect1> + +<sect1 id="Keyboard_and_Pointer_Events"> +<title>Keyboard and Pointer Events</title> +<!-- .XS --> +<!-- (SN Keyboard and Pointer Events --> +<!-- .XE --> +<para> +<!-- .LP --> +This section discusses: +</para> +<itemizedlist> + <listitem> + <para> +Pointer button events + </para> + </listitem> + <listitem> + <para> +Keyboard and pointer events + </para> + </listitem> +</itemizedlist> +<sect2 id="Pointer_Button_Events"> +<title>Pointer Button Events</title> +<!-- .XS --> +<!-- (SN Pointer Button Events --> +<!-- .XE --> +<para> +<!-- .LP --> +The following describes the event processing that occurs when a pointer button +press is processed with the pointer in some window w and +when no active pointer grab is in progress. +</para> +<para> +<!-- .LP --> +The X server searches the ancestors of w from the root down, +looking for a passive grab to activate. +If no matching passive grab on the button exists, +the X server automatically starts an active grab for the client receiving +the event and sets the last-pointer-grab time to the current server time. +The effect is essentially equivalent to an +<function>XGrabButton</function> +with these client passed arguments: +</para> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Argument</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry><emphasis remap='I'>w</emphasis></entry> + <entry>The event window </entry> + </row> + <row> + <entry><emphasis remap='I'>event_mask</emphasis></entry> + <entry>The client's selected pointer events on the event window</entry> + </row> + <row> + <entry><emphasis remap='I'>pointer_mode</emphasis></entry> + <entry><function>GrabModeAsync</function></entry> + </row> + <row> + <entry><emphasis remap='I'>keyboard_mode</emphasis></entry> + <entry><function>GrabModeAsync </function></entry> + </row> + <row> + <entry><emphasis remap='I'>owner_events</emphasis></entry> + <entry><function>True ,</function> + if the client has selected + <function>OwnerGrabButtonMask</function> + on the event window, + otherwise + <function>False </function></entry> + </row> + <row> + <entry><emphasis remap='I'>confine_to</emphasis></entry> + <entry><function>None </function></entry> + </row> + <row> + <entry><emphasis remap='I'>cursor</emphasis></entry> + <entry><function>None </function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +<para> +<!-- .LP --> +The active grab is automatically terminated when +the logical state of the pointer has all buttons released. +Clients can modify the active grab by calling +<function>XUngrabPointer</function> +and +<function>XChangeActivePointerGrab .</function> +</para> +</sect2> + +<sect2 id="Keyboard_and_Pointer_Events_b"> +<title>Keyboard and Pointer Events</title> +<!-- .XS --> +<!-- (SN Keyboard and Pointer Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "ButtonPress" --> +<!-- .IN "Events" "ButtonRelease" --> +<!-- .IN "Events" "KeyPress" --> +<!-- .IN "Events" "KeyRelease" --> +<!-- .IN "Events" "MotionNotify" --> +This section discusses the processing that occurs for the +keyboard events +<function>KeyPress</function> +and +<function>KeyRelease </function> +and the pointer events +<function>ButtonPress ,</function> +<function>ButtonRelease ,</function> +and +<function>MotionNotify .</function> +For information about the keyboard event-handling utilities, +see chapter 11. +</para> +<para> +<!-- .LP --> +<!-- .IN "KeyPress" "" "@DEF@" --> +<!-- .IN "KeyRelease" "" "@DEF@" --> +The X server reports +<function>KeyPress</function> +or +<function>KeyRelease</function> +events to clients wanting information about keys that logically change state. +Note that these events are generated for all keys, +even those mapped to modifier bits. +<!-- .IN "ButtonPress" "" "@DEF@" --> +<!-- .IN "ButtonRelease" "" "@DEF@" --> +The X server reports +<function>ButtonPress</function> +or +<function>ButtonRelease</function> +events to clients wanting information about buttons that logically change state. +</para> +<para> +<!-- .LP --> +<!-- .IN "MotionNotify" "" "@DEF@" --> +The X server reports +<function>MotionNotify</function> +events to clients wanting information about when the pointer logically moves. +The X server generates this event whenever the pointer is moved +and the pointer motion begins and ends in the window. +The granularity of +<function>MotionNotify</function> +events is not guaranteed, +but a client that selects this event type is guaranteed +to receive at least one event when the pointer moves and then rests. +</para> +<para> +<!-- .LP --> +The generation of the logical changes lags the physical changes +if device event processing is frozen. +</para> +<para> +<!-- .LP --> +To receive +<function>KeyPress ,</function> +<function>KeyRelease ,</function> +<function>ButtonPress ,</function> +and +<function>ButtonRelease </function> +events, set +<function>KeyPressMask ,</function> +<function>KeyReleaseMask ,</function> +<function>ButtonPressMask ,</function> +and +<function>ButtonReleaseMask </function> +bits in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +To receive +<function>MotionNotify</function> +events, set one or more of the following event +masks bits in the event-mask attribute of the window. +</para> +<itemizedlist> + <listitem> + <para> +<function>Button1MotionMask \ \-</function> +<function>Button5MotionMask</function> + </para> + </listitem> + <listitem> + <para> +The client application receives +<function>MotionNotify</function> +events only when one or more of the specified buttons is pressed. + </para> + </listitem> + <listitem> + <para> +<function>ButtonMotionMask</function> + </para> + </listitem> + <listitem> + <para> +The client application receives +<function>MotionNotify</function> +events only when at least one button is pressed. + </para> + </listitem> + <listitem> + <para> +<function>PointerMotionMask</function> + </para> + </listitem> + <listitem> + <para> +The client application receives +<function>MotionNotify</function> +events independent of the state of +the pointer buttons. + </para> + </listitem> + <listitem> + <para> +<function>PointerMotionHintMask</function> + </para> + </listitem> + <listitem> + <para> +If +<function>PointerMotionHintMask</function> +is selected in combination with one or more of the above masks, +the X server is free to send only one +<function>MotionNotify</function> +event (with the is_hint member of the +<function>XPointerMovedEvent</function> +structure set to +<function>NotifyHint )</function> +to the client for the event window, +until either the key or button state changes, +the pointer leaves the event window, or the client calls +<function>XQueryPointer</function> +or +<function>XGetMotionEvents .</function> +The server still may send +<function>MotionNotify</function> +events without is_hint set to +<function>NotifyHint .</function> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The source of the event is the viewable window that the pointer is in. +The window used by the X server to report these events depends on +the window's position in the window hierarchy +and whether any intervening window prohibits the generation of these events. +Starting with the source window, +the X server searches up the window hierarchy until it locates the first +window specified by a client as having an interest in these events. +If one of the intervening windows has its do-not-propagate-mask +set to prohibit generation of the event type, +the events of those types will be suppressed. +Clients can modify the actual window used for reporting by performing +active grabs and, in the case of keyboard events, by using the focus window. +</para> +<para> +<!-- .LP --> +The structures for these event types contain: +</para> +<literallayout class="monospaced"> +typedef struct { + int type; /* ButtonPress or ButtonRelease */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window it is reported relative to */ + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event window */ + int x_root, y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int button; /* detail */ + Bool same_screen; /* same screen flag */ +} XButtonEvent; +typedef XButtonEvent XButtonPressedEvent; +typedef XButtonEvent XButtonReleasedEvent; +</literallayout> + +<literallayout class="monospaced"> +typedef struct { + int type; /* KeyPress or KeyRelease */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window it is reported relative to */ + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event window */ + int x_root, y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int keycode; /* detail */ + Bool same_screen; /* same screen flag */ +} XKeyEvent; +typedef XKeyEvent XKeyPressedEvent; +typedef XKeyEvent XKeyReleasedEvent; +</literallayout> + +<literallayout class="monospaced"> +typedef struct { + int type; /* MotionNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window reported relative to */ + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event window */ + int x_root, y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + char is_hint; /* detail */ + Bool same_screen; /* same screen flag */ +} XMotionEvent; +typedef XMotionEvent XPointerMovedEvent; +</literallayout> + +<para> +These structures have the following common members: +window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen. +The window member is set to the window on which the +event was generated and is referred to as the event window. +As long as the conditions previously discussed are met, +this is the window used by the X server to report the event. +The root member is set to the source window's root window. +The x_root and y_root members are set to the pointer's coordinates +relative to the root window's origin at the time of the event. +</para> + +<para> +<!-- .LP --> +The same_screen member is set to indicate whether the event +window is on the same screen +as the root window and can be either +<function>True </function> +or +<function>False .</function> +If +<function>True ,</function> +the event and root windows are on the same screen. +If +<function>False ,</function> +the event and root windows are not on the same screen. +</para> +<para> +<!-- .LP --> +If the source window is an inferior of the event window, +the subwindow member of the structure is set to the child of the event window +that is the source window or the child of the event window that is +an ancestor of the source window. +Otherwise, the X server sets the subwindow member to +<function>None .</function> +The time member is set to the time when the event was generated +and is expressed in milliseconds. +</para> +<para> +<!-- .LP --> +If the event window is on the same screen as the root window, +the x and y members +are set to the coordinates relative to the event window's origin. +Otherwise, these members are set to zero. +</para> +<para> +<!-- .LP --> +The state member is set to indicate the logical state of the pointer buttons +and modifier keys just prior to the event, +which is the bitwise inclusive OR of one or more of the +button or modifier key masks: +<function>Button1Mask ,</function> +<function>Button2Mask ,</function> +<function>Button3Mask ,</function> +<function>Button4Mask ,</function> +<function>Button5Mask ,</function> +<function>ShiftMask ,</function> +<function>LockMask ,</function> +<function>ControlMask ,</function> +<function>Mod1Mask ,</function> +<function>Mod2Mask ,</function> +<function>Mod3Mask ,</function> +<function>Mod4Mask ,</function> +and +<function>Mod5Mask .</function> +</para> +<para> +<!-- .LP --> +Each of these structures also has a member that indicates the detail. +For the +<function>XKeyPressedEvent</function> +and +<function>XKeyReleasedEvent</function> +structures, this member is called a keycode. +It is set to a number that represents a physical key on the keyboard. +The keycode is an arbitrary representation for any key on the keyboard +(see sections 12.7 and 16.1). +</para> +<para> +<!-- .LP --> +For the +<function>XButtonPressedEvent</function> +and +<function>XButtonReleasedEvent</function> +structures, this member is called button. +It represents the pointer button that changed state and can be the +<function>Button1 ,</function> +<function>Button2 ,</function> +<function>Button3 ,</function> +<function>Button4 ,</function> +or +<function>Button5 </function> +value. +For the +<function>XPointerMovedEvent</function> +structure, this member is called is_hint. +It can be set to +<function>NotifyNormal</function> +or +<function>NotifyHint .</function> +</para> +<para> +<!-- .LP --> +Some of the symbols mentioned in this section have fixed values, as +follows: +</para> +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Symbol</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry><function>Button1MotionMask</function></entry> + <entry>(1L<<8)</entry> + </row> + <row> + <entry><function>Button2MotionMask</function></entry> + <entry>(1L<<9)</entry> + </row> + <row> + <entry><function>Button3MotionMask</function></entry> + <entry>(1L<<10)</entry> + </row> + <row> + <entry><function>Button4MotionMask</function></entry> + <entry>(1L<<11)</entry> + </row> + <row> + <entry><function>Button5MotionMask</function></entry> + <entry>(1L<<12)</entry> + </row> + <row> + <entry><function>Button1Mask</function></entry> + <entry>(1<<8)</entry> + </row> + <row> + <entry><function>Button2Mask</function></entry> + <entry>(1<<9)</entry> + </row> + <row> + <entry><function>Button3Mask</function></entry> + <entry>(1<<10)</entry> + </row> + <row> + <entry><function>Button4Mask</function></entry> + <entry>(1<<11)</entry> + </row> + <row> + <entry><function>Button5Mask</function></entry> + <entry>(1<<12)</entry> + </row> + <row> + <entry><function>ShiftMask</function></entry> + <entry>(1<<0)</entry> + </row> + <row> + <entry><function>LockMask</function></entry> + <entry>(1<<1)</entry> + </row> + <row> + <entry><function>ControlMask</function></entry> + <entry>(1<<2)</entry> + </row> + <row> + <entry><function>Mod1Mask</function></entry> + <entry>(1<<3)</entry> + </row> + <row> + <entry><function>Mod2Mask</function></entry> + <entry>(1<<4)</entry> + </row> + <row> + <entry><function>Mod3Mask</function></entry> + <entry>(1<<5)</entry> + </row> + <row> + <entry><function>Mod4Mask</function></entry> + <entry>(1<<6)</entry> + </row> + <row> + <entry><function>Mod5Mask</function></entry> + <entry>(1<<7)</entry> + </row> + <row> + <entry><function>Button1</function></entry> + <entry>1</entry> + </row> + <row> + <entry><function>Button2</function></entry> + <entry>2</entry> + </row> + <row> + <entry><function>Button3</function></entry> + <entry>3</entry> + </row> + <row> + <entry><function>Button4</function></entry> + <entry>4</entry> + </row> + <row> + <entry><function>Button5</function></entry> + <entry>5</entry> + </row> + </tbody> + </tgroup> +</informaltable> + +</sect2> +</sect1> +<sect1 id="Window_Entry_Exit_Events"> +<title>Window Entry/Exit Events</title> +<!-- .XS --> +<!-- (SN Window Entry/Exit Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "EnterNotify" --> +<!-- .IN "Events" "LeaveNotify" --> +This section describes the processing that +occurs for the window crossing events +<function>EnterNotify</function> +and +<function>LeaveNotify .</function> +<!-- .IN "EnterNotify" "" "@DEF@" --> +<!-- .IN "LeaveNotify" "" "@DEF@" --> +If a pointer motion or a window hierarchy change causes the +pointer to be in a different window than before, the X server reports +<function>EnterNotify</function> +or +<function>LeaveNotify</function> +events to clients who have selected for these events. +All +<function>EnterNotify</function> +and +<function>LeaveNotify</function> +events caused by a hierarchy change are +generated after any hierarchy event +<function>( UnmapNotify ,</function> +<function>MapNotify ,</function> +<function>ConfigureNotify ,</function> +<function>GravityNotify ,</function> +<function>CirculateNotify )</function> +caused by that change; +however, the X protocol does not constrain the ordering of +<function>EnterNotify </function> +and +<function>LeaveNotify </function> +events with respect to +<function>FocusOut , </function> +<function>VisibilityNotify ,</function> +and +<function>Expose </function> +events. +</para> +<para> +<!-- .LP --> +This contrasts with +<function>MotionNotify</function> +events, which are also generated when the pointer moves +but only when the pointer motion begins and ends in a single window. +An +<function>EnterNotify</function> +or +<function>LeaveNotify</function> +event also can be generated when some client application calls +<function>XGrabPointer</function> +and +<function>XUngrabPointer .</function> +</para> +<para> +<!-- .LP --> +To receive +<function>EnterNotify</function> +or +<function>LeaveNotify</function> +events, set the +<function>EnterWindowMask</function> +or +<function>LeaveWindowMask</function> +bits of the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for these event types contains: +</para> +<!-- .LP --> +<!-- .IN "XCrossingEvent" "" "@DEF@" --> +<!-- .IN "XEnterWindowEvent" "" "@DEF@" --> +<!-- .IN "XLeaveWindowEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* EnterNotify or LeaveNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* ``event'' window reported relative to */ + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* pointer x, y coordinates in event window */ + int x_root, y_root; /* coordinates relative to root */ + int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ + int detail; + /* + * NotifyAncestor, NotifyVirtual, NotifyInferior, + * NotifyNonlinear,NotifyNonlinearVirtual + */ + Bool same_screen; /* same screen flag */ + Bool focus; /* boolean focus */ + unsigned int state; /* key or button mask */ +} XCrossingEvent; +typedef XCrossingEvent XEnterWindowEvent; +typedef XCrossingEvent XLeaveWindowEvent; +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +The window member is set to the window on which the +<function>EnterNotify</function> +or +<function>LeaveNotify</function> +event was generated and is referred to as the event window. +This is the window used by the X server to report the event, +and is relative to the root +window on which the event occurred. +The root member is set to the root window of the screen +on which the event occurred. +</para> +<para> +<!-- .LP --> +For a +<function>LeaveNotify </function> +event, +if a child of the event window contains the initial position of the pointer, +the subwindow component is set to that child. +Otherwise, the X server sets the subwindow member to +<function>None .</function> +For an +<function>EnterNotify </function> +event, if a child of the event window contains the final pointer position, +the subwindow component is set to that child or +<function>None .</function> +</para> +<para> +<!-- .LP --> +The time member is set to the time when the event was generated +and is expressed in milliseconds. +The x and y members are set to the coordinates of the pointer position in +the event window. +This position is always the pointer's final position, +not its initial position. +If the event window is on the same +screen as the root window, x and y are the pointer coordinates +relative to the event window's origin. +Otherwise, x and y are set to zero. +The x_root and y_root members are set to the pointer's coordinates relative to the +root window's origin at the time of the event. +</para> +<para> +<!-- .LP --> +The same_screen member is set to indicate whether the event window is on the same screen +as the root window and can be either +<function>True </function> +or +<function>False .</function> +If +<function>True ,</function> +the event and root windows are on the same screen. +If +<function>False ,</function> +the event and root windows are not on the same screen. +</para> +<para> +<!-- .LP --> +The focus member is set to indicate whether the event window is the focus window or an +inferior of the focus window. +The X server can set this member to either +<function>True </function> +or +<function>False .</function> +If +<function>True ,</function> +the event window is the focus window or an inferior of the focus window. +If +<function>False ,</function> +the event window is not the focus window or an inferior of the focus window. +</para> +<para> +<!-- .LP --> +The state member is set to indicate the state of the pointer buttons and +modifier keys just prior to the +event. +The X server can set this member to the bitwise inclusive OR of one +or more of the button or modifier key masks: +<function>Button1Mask ,</function> +<function>Button2Mask ,</function> +<function>Button3Mask ,</function> +<function>Button4Mask ,</function> +<function>Button5Mask ,</function> +<function>ShiftMask ,</function> +<function>LockMask ,</function> +<function>ControlMask ,</function> +<function>Mod1Mask ,</function> +<function>Mod2Mask ,</function> +<function>Mod3Mask ,</function> +<function>Mod4Mask ,</function> +<function>Mod5Mask .</function> +</para> +<para> +<!-- .LP --> +The mode member is set to indicate whether the events are normal events, +pseudo-motion events +when a grab activates, or pseudo-motion events when a grab deactivates. +The X server can set this member to +<function>NotifyNormal ,</function> +<function>NotifyGrab ,</function> +or +<function>NotifyUngrab .</function> +</para> +<para> +<!-- .LP --> +The detail member is set to indicate the notify detail and can be +<function>NotifyAncestor ,</function> +<function>NotifyVirtual ,</function> +<function>NotifyInferior ,</function> +<function>NotifyNonlinear ,</function> +or +<function>NotifyNonlinearVirtual .</function> +</para> +<sect2 id="Normal_Entry_Exit_Events"> +<title>Normal Entry/Exit Events</title> +<!-- .XS --> +<!-- (SN Normal Entry/Exit Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<function>EnterNotify</function> +and +<function>LeaveNotify</function> +events are generated when the pointer moves from +one window to another window. +Normal events are identified by +<function>XEnterWindowEvent</function> +or +<function>XLeaveWindowEvent</function> +structures whose mode member is set to +<function>NotifyNormal .</function> +</para> +<itemizedlist> + <listitem> + <para> +When the pointer moves from window A to window B and A is an inferior of B, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>LeaveNotify</function> +event on window A, with the detail member of the +<function>XLeaveWindowEvent</function> +structure set to +<function>NotifyAncestor .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>LeaveNotify</function> +event on each window between window A and window B, exclusive, +with the detail member of each +<function>XLeaveWindowEvent</function> +structure set to +<function>NotifyVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates an +<function>EnterNotify</function> +event on window B, with the detail member of the +<function>XEnterWindowEvent</function> +structure set to +<function>NotifyInferior .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the pointer moves from window A to window B and B is an inferior of A, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>LeaveNotify</function> +event on window A, +with the detail member of the +<function>XLeaveWindowEvent</function> +structure set to +<function>NotifyInferior .</function> + </para> + </listitem> + <listitem> + <para> +It generates an +<function>EnterNotify</function> +event on each window between window A and window B, exclusive, with the +detail member of each +<function>XEnterWindowEvent</function> +structure set to +<function>NotifyVirtual . </function> + </para> + </listitem> + <listitem> + <para> +It generates an +<function>EnterNotify</function> +event on window B, with the detail member of the +<function>XEnterWindowEvent</function> +structure set to +<function>NotifyAncestor .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the pointer moves from window A to window B +and window C is their least common ancestor, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>LeaveNotify</function> +event on window A, +with the detail member of the +<function>XLeaveWindowEvent</function> +structure set to +<function>NotifyNonlinear .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>LeaveNotify</function> +event on each window between window A and window C, exclusive, +with the detail member of each +<function>XLeaveWindowEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates an +<function>EnterNotify</function> +event on each window between window C and window B, exclusive, +with the detail member of each +<function>XEnterWindowEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates an +<function>EnterNotify</function> +event on window B, with the detail member of the +<function>XEnterWindowEvent</function> +structure set to +<function>NotifyNonlinear .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the pointer moves from window A to window B on different screens, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>LeaveNotify</function> +event on window A, +with the detail member of the +<function>XLeaveWindowEvent</function> +structure set to +<function>NotifyNonlinear .</function> + </para> + </listitem> + <listitem> + <para> +If window A is not a root window, +it generates a +<function>LeaveNotify</function> +event on each window above window A up to and including its root, +with the detail member of each +<function>XLeaveWindowEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +If window B is not a root window, +it generates an +<function>EnterNotify</function> +event on each window from window B's root down to but not including +window B, with the detail member of each +<function>XEnterWindowEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates an +<function>EnterNotify</function> +event on window B, with the detail member of the +<function>XEnterWindowEvent</function> +structure set to +<function>NotifyNonlinear .</function> +<!-- .RE --> +<!-- .\".SH 3 --> + </para> + </listitem> +</itemizedlist> +</sect2> +<sect2 id="Grab_and_Ungrab_Entry_Exit_Events"> +<title>Grab and Ungrab Entry/Exit Events</title> +<!-- .XS --> +<!-- (SN Grab and Ungrab Entry/Exit Events --> +<!-- .XE --> +<para> +<!-- .LP --> +Pseudo-motion mode +<function>EnterNotify</function> +and +<function>LeaveNotify</function> +events are generated when a pointer grab activates or deactivates. +Events in which the pointer grab activates +are identified by +<function>XEnterWindowEvent</function> +or +<function>XLeaveWindowEvent</function> +structures whose mode member is set to +<function>NotifyGrab .</function> +Events in which the pointer grab deactivates +are identified by +<function>XEnterWindowEvent</function> +or +<function>XLeaveWindowEvent</function> +structures whose mode member is set to +<function>NotifyUngrab</function> +(see +<function>XGrabPointer ).</function> +</para> +<itemizedlist> + <listitem> + <para> +When a pointer grab activates after any initial warp into a confine_to +window and before generating any actual +<function>ButtonPress</function> +event that activates the grab, +G is the grab_window for the grab, +and P is the window the pointer is in, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates +<function>EnterNotify</function> +and +<function>LeaveNotify</function> +events (see section 10.6.1) +with the mode members of the +<function>XEnterWindowEvent</function> +and +<function>XLeaveWindowEvent</function> +structures set to +<function>NotifyGrab .</function> +These events are generated +as if the pointer were to suddenly warp from +its current position in P to some position in G. +However, the pointer does not warp, and the X server uses the pointer position +as both the initial and final positions for the events. +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When a pointer grab deactivates after generating any actual +<function>ButtonRelease</function> +event that deactivates the grab, +G is the grab_window for the grab, +and P is the window the pointer is in, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates +<function>EnterNotify</function> +and +<function>LeaveNotify</function> +events (see section 10.6.1) +with the mode members of the +<function>XEnterWindowEvent</function> +and +<function>XLeaveWindowEvent</function> +structures set to +<function>NotifyUngrab .</function> +These events are generated as if the pointer were to suddenly warp from +some position in G to its current position in P. +However, the pointer does not warp, and the X server uses the +current pointer position as both the +initial and final positions for the events. +<!-- .RE --> + </para> + </listitem> +</itemizedlist> +</sect2> +</sect1> +<sect1 id="Input_Focus_Events"> +<title>Input Focus Events</title> +<!-- .XS --> +<!-- (SN Input Focus Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "FocusIn" --> +<!-- .IN "Events" "FocusOut" --> +This section describes the processing that occurs for the input focus events +<function>FocusIn</function> +and +<function>FocusOut .</function> +<!-- .IN "FocusIn" "" "@DEF@" --> +<!-- .IN "FocusOut" "" "@DEF@" --> +The X server can report +<function>FocusIn</function> +or +<function>FocusOut</function> +events to clients wanting information about when the input focus changes. +The keyboard is always attached to some window +(typically, the root window or a top-level window), +which is called the focus window. +The focus window and the position of the pointer determine the window that +receives keyboard input. +Clients may need to know when the input focus changes +to control highlighting of areas on the screen. +</para> +<para> +<!-- .LP --> +To receive +<function>FocusIn</function> +or +<function>FocusOut</function> +events, set the +<function>FocusChangeMask</function> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for these event types contains: +</para> +<!-- .LP --> +<!-- .IN "XFocusChangeEvent" "" "@DEF@" --> +<!-- .IN "XFocusInEvent" "" "@DEF@" --> +<!-- .IN "XFocusOutEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* FocusIn or FocusOut */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* window of event */ + int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ + int detail; + /* + * NotifyAncestor, NotifyVirtual, NotifyInferior, + * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer, + * NotifyPointerRoot, NotifyDetailNone + */ +} XFocusChangeEvent; +typedef XFocusChangeEvent XFocusInEvent; +typedef XFocusChangeEvent XFocusOutEvent; +</literallayout> +<para> +<!-- .LP --> +<!-- .eM --> +The window member is set to the window on which the +<function>FocusIn</function> +or +<function>FocusOut</function> +event was generated. +This is the window used by the X server to report the event. +The mode member is set to indicate whether the focus events +are normal focus events, +focus events while grabbed, +focus events +when a grab activates, or focus events when a grab deactivates. +The X server can set the mode member to +<function>NotifyNormal ,</function> +<function>NotifyWhileGrabbed ,</function> +<function>NotifyGrab ,</function> +or +<function>NotifyUngrab .</function> +</para> +<para> +<!-- .LP --> +All +<function>FocusOut</function> +events caused by a window unmap are generated after any +<function>UnmapNotify</function> +event; however, the X protocol does not constrain the ordering of +<function>FocusOut</function> +events with respect to +generated +<function>EnterNotify ,</function> +<function>LeaveNotify ,</function> +<function>VisibilityNotify ,</function> +and +<function>Expose</function> +events. +</para> +<para> +<!-- .LP --> +Depending on the event mode, +the detail member is set to indicate the notify detail and can be +<function>NotifyAncestor ,</function> +<function>NotifyVirtual ,</function> +<function>NotifyInferior ,</function> +<function>NotifyNonlinear ,</function> +<function>NotifyNonlinearVirtual ,</function> +<function>NotifyPointer ,</function> +<function>NotifyPointerRoot ,</function> +or +<function>NotifyDetailNone .</function> +</para> +<sect2 id="Normal_Focus_Events_and_Focus_Events_While_Grabbed_"> +<title>Normal Focus Events and Focus Events While Grabbed </title> +<!-- .XS --> +<!-- (SN Normal Focus Events and Focus Events While Grabbed --> +<!-- .XE --> +<para> +<!-- .LP --> +Normal focus events are identified by +<function>XFocusInEvent</function> +or +<function>XFocusOutEvent</function> +structures whose mode member is set to +<function>NotifyNormal .</function> +Focus events while grabbed are identified by +<function>XFocusInEvent</function> +or +<function>XFocusOutEvent</function> +structures whose mode member is set to +<function>NotifyWhileGrabbed .</function> +The X server processes normal focus and focus events while grabbed according to +the following: +</para> +<itemizedlist> + <listitem> + <para> +When the focus moves from window A to window B, A is an inferior of B, +and the pointer is in window P, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on window A, with the detail member of the +<function>XFocusOutEvent</function> +structure set to +<function>NotifyAncestor . </function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on each window between window A and window B, exclusive, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on window B, with the detail member of the +<function>XFocusOutEvent</function> +structure set to +<function>NotifyInferior .</function> + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window B +but window P is not window A or an inferior or ancestor of window A, +it generates a +<function>FocusIn</function> +event on each window below window B, down to and including window P, +with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyPointer .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from window A to window B, B is an inferior of A, +and the pointer is in window P, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window A +but P is not an inferior of window B or an ancestor of B, +it generates a +<function>FocusOut</function> +event on each window from window P up to but not including window A, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyPointer .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on window A, +with the detail member of the +<function>XFocusOutEvent</function> +structure set to +<function>NotifyInferior . </function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on each window between window A and window B, exclusive, with the +detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyVirtual . </function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on window B, with the detail member of the +<function>XFocusInEvent</function> +structure set to +<function>NotifyAncestor .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from window A to window B, +window C is their least common ancestor, +and the pointer is in window P, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window A, +it generates a +<function>FocusOut</function> +event on each window from window P up to but not including window A, +with the detail member of the +<function>XFocusOutEvent</function> +structure set to +<function>NotifyPointer .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on window A, +with the detail member of the +<function>XFocusOutEvent</function> +structure set to +<function>NotifyNonlinear .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on each window between window A and window C, exclusive, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on each window between C and B, exclusive, +with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on window B, with the detail member of the +<function>XFocusInEvent</function> +structure set to +<function>NotifyNonlinear .</function> + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window B, it generates a +<function>FocusIn</function> +event on each window below window B down to and including window P, +with the detail member of the +<function>XFocusInEvent</function> +structure set to +<function>NotifyPointer .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from window A to window B on different screens +and the pointer is in window P, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window A, it generates a +<function>FocusOut</function> +event on each window from window P up to but not including window A, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyPointer .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on window A, +with the detail member of the +<function>XFocusOutEvent</function> +structure set to +<function>NotifyNonlinear .</function> + </para> + </listitem> + <listitem> + <para> +If window A is not a root window, +it generates a +<function>FocusOut</function> +event on each window above window A up to and including its root, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +If window B is not a root window, +it generates a +<function>FocusIn</function> +event on each window from window B's root down to but not including +window B, with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on window B, with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyNonlinear .</function> + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window B, it generates a +<function>FocusIn</function> +event on each window below window B down to and including window P, +with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyPointer .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from window A to +<function>PointerRoot</function> +(events sent to the window under the pointer) +or +<function>None </function> +(discard), and the pointer is in window P, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window A, it generates a +<function>FocusOut</function> +event on each window from window P up to but not including window A, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyPointer .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on window A, with the detail member of the +<function>XFocusOutEvent</function> +structure set to +<function>NotifyNonlinear .</function> + </para> + </listitem> + <listitem> + <para> +If window A is not a root window, +it generates a +<function>FocusOut</function> +event on each window above window A up to and including its root, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on the root window of all screens, with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyPointerRoot</function> +(or +<function>NotifyDetailNone ).</function> + </para> + </listitem> + <listitem> + <para> +If the new focus is +<function>PointerRoot ,</function> +it generates a +<function>FocusIn</function> +event on each window from window P's root down to and including window P, +with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyPointer .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from +<function>PointerRoot</function> +(events sent to the window under the pointer) +or +<function>None </function> +to window A, and the pointer is in window P, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +If the old focus is +<function>PointerRoot ,</function> +it generates a +<function>FocusOut</function> +event on each window from window P up to and including window P's root, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyPointer .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on all root windows, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyPointerRoot</function> +(or +<function>NotifyDetailNone ).</function> + </para> + </listitem> + <listitem> + <para> +If window A is not a root window, +it generates a +<function>FocusIn</function> +event on each window from window A's root down to but not including window A, +with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyNonlinearVirtual .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on window A, +with the detail member of the +<function>XFocusInEvent</function> +structure set to +<function>NotifyNonlinear .</function> + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window A, it generates a +<function>FocusIn</function> +event on each window below window A down to and including window P, +with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyPointer .</function> +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from +<function>PointerRoot</function> +(events sent to the window under the pointer) +to +<function>None</function> +(or vice versa), and the pointer is in window P, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +If the old focus is +<function>PointerRoot ,</function> +it generates a +<function>FocusOut</function> +event on each window from window P up to and including window P's root, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to +<function>NotifyPointer .</function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusOut</function> +event on all root windows, +with the detail member of each +<function>XFocusOutEvent</function> +structure set to either +<function>NotifyPointerRoot</function> +or +<function>NotifyDetailNone . </function> + </para> + </listitem> + <listitem> + <para> +It generates a +<function>FocusIn</function> +event on all root windows, +with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyDetailNone </function> +or +<function>NotifyPointerRoot .</function> + </para> + </listitem> + <listitem> + <para> +If the new focus is +<function>PointerRoot ,</function> +it generates a +<function>FocusIn</function> +event on each window from window P's root down to and including window P, +with the detail member of each +<function>XFocusInEvent</function> +structure set to +<function>NotifyPointer .</function> +<!-- .RE --> +<!-- .\".SH 3 --> + </para> + </listitem> +</itemizedlist> +</sect2> +<sect2 id="Focus_Events_Generated_by_Grabs"> +<title>Focus Events Generated by Grabs</title> +<!-- .XS --> +<!-- (SN Focus Events Generated by Grabs --> +<!-- .XE --> +<para> +<!-- .LP --> +Focus events in which the keyboard grab activates +are identified by +<function>XFocusInEvent</function> +or +<function>XFocusOutEvent</function> +structures whose mode member is set to +<function>NotifyGrab .</function> +Focus events in which the keyboard grab deactivates +are identified by +<function>XFocusInEvent</function> +or +<function>XFocusOutEvent</function> +structures whose mode member is set to +<function>NotifyUngrab </function> +(see +<function>XGrabKeyboard ).</function> +</para> +<itemizedlist> + <listitem> + <para> +When a keyboard grab activates before generating any actual +<function>KeyPress</function> +event that activates the grab, +G is the grab_window, and F is the current focus, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates +<function>FocusIn</function> +and +<function>FocusOut</function> +events, with the mode members of the +<function>XFocusInEvent</function> +and +<function>XFocusOutEvent</function> +structures set to +<function>NotifyGrab .</function> +These events are generated +as if the focus were to change from +F to G. +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When a keyboard grab deactivates after generating any actual +<function>KeyRelease</function> +event that deactivates the grab, +G is the grab_window, and F is the current focus, +the X server does the following: +<!-- .RS --> + </para> + </listitem> + <listitem> + <para> +It generates +<function>FocusIn</function> +and +<function>FocusOut</function> +events, with the mode members of the +<function>XFocusInEvent</function> +and +<function>XFocusOutEvent</function> +structures set to +<function>NotifyUngrab .</function> +These events are generated +as if the focus were to change from +G to F. +<!-- .RE --> + </para> + </listitem> +</itemizedlist> +</sect2> +</sect1> +<sect1 id="Key_Map_State_Notification_Events"> +<title>Key Map State Notification Events</title> +<!-- .XS --> +<!-- (SN Key Map State Notification Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "KeymapNotify" --> +<!-- .IN "KeymapNotify" "" "@DEF@" --> +The X server can report +<function>KeymapNotify</function> +events to clients that want information about changes in their keyboard state. +</para> +<para> +<!-- .LP --> +To receive +<function>KeymapNotify</function> +events, set the +<function>KeymapStateMask</function> +bit in the event-mask attribute of the window. +The X server generates this event immediately after every +<function>EnterNotify</function> +and +<function>FocusIn</function> +event. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XKeymapEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +/* generated on EnterWindow and FocusIn when KeymapState selected */ +typedef struct { + int type; /* KeymapNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + char key_vector[32]; +} XKeymapEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The window member is not used but is present to aid some toolkits. +The key_vector member is set to the bit vector of the keyboard. +Each bit set to 1 indicates that the corresponding key +is currently pressed. +The vector is represented as 32 bytes. +Byte N (from 0) contains the bits for keys 8N to 8N + 7 +with the least significant bit in the byte representing key 8N. +</para> +</sect1> +<sect1 id="Exposure_Events"> +<title>Exposure Events</title> +<!-- .XS --> +<!-- (SN Exposure Events --> +<!-- .XE --> +<para> +<!-- .LP --> +The X protocol does not guarantee to preserve the contents of window +regions when +the windows are obscured or reconfigured. +Some implementations may preserve the contents of windows. +Other implementations are free to destroy the contents of windows +when exposed. +X expects client applications to assume the responsibility for +restoring the contents of an exposed window region. +(An exposed window region describes a formerly obscured window whose +region becomes visible.) +Therefore, the X server sends +<function>Expose </function> +events describing the window and the region of the window that has been exposed. +A naive client application usually redraws the entire window. +A more sophisticated client application redraws only the exposed region. +</para> +<sect2 id="Expose_Events"> +<title>Expose Events</title> +<!-- .XS --> +<!-- (SN Expose Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "Expose" --> +<!-- .IN "Expose" "" "@DEF@" --> +The X server can report +<function>Expose</function> +events to clients wanting information about when the contents of window regions +have been lost. +The circumstances in which the X server generates +<function>Expose</function> +events are not as definite as those for other events. +However, the X server never generates +<function>Expose</function> +events on windows whose class you specified as +<function>InputOnly .</function> +The X server can generate +<function>Expose</function> +events when no valid contents are available for regions of a window +and either the regions are visible, +the regions are viewable and the server is (perhaps newly) maintaining +backing store on the window, +or the window is not viewable but the server is (perhaps newly) honoring the +window's backing-store attribute of +<function>Always</function> +or +<function>WhenMapped .</function> +The regions decompose into an (arbitrary) set of rectangles, +and an +<function>Expose</function> +event is generated for each rectangle. +For any given window, +the X server guarantees to report contiguously +all of the regions exposed by some action that causes +<function>Expose </function> +events, such as raising a window. +</para> +<para> +<!-- .LP --> +To receive +<function>Expose</function> +events, set the +<function>ExposureMask</function> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XExposeEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* Expose */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + int x, y; + int width, height; + int count; /* if nonzero, at least this many more */ +} XExposeEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The window member is set to the exposed (damaged) window. +The x and y members are set to the coordinates relative to the window's origin +and indicate the upper-left corner of the rectangle. +The width and height members are set to the size (extent) of the rectangle. +The count member is set to the number of +<function>Expose</function> +events that are to follow. +If count is zero, no more +<function>Expose</function> +events follow for this window. +However, if count is nonzero, at least that number of +<function>Expose </function> +events (and possibly more) follow for this window. +Simple applications that do not want to optimize redisplay by distinguishing +between subareas of its window can just ignore all +<function>Expose</function> +events with nonzero counts and perform full redisplays +on events with zero counts. +</para> +</sect2> +<sect2 id="GraphicsExpose_and_NoExpose_Events"> +<title>GraphicsExpose and NoExpose Events</title> +<!-- .XS --> +<!-- (SN GraphicsExpose and NoExpose Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "GraphicsExpose" --> +<!-- .IN "Events" "NoExpose" --> +<!-- .IN "GraphicsExpose" "" "@DEF@" --> +The X server can report +<function>GraphicsExpose</function> +events to clients wanting information about when a destination region could not +be computed during certain graphics requests: +<function>XCopyArea</function> +or +<function>XCopyPlane .</function> +The X server generates this event whenever a destination region could not be +computed because of an obscured or out-of-bounds source region. +In addition, the X server guarantees to report contiguously all of the regions exposed by +some graphics request +(for example, copying an area of a drawable to a destination +drawable). +</para> +<para> +<!-- .LP --> +<!-- .IN "NoExpose" "" "@DEF@" --> +The X server generates a +<function>NoExpose</function> +event whenever a graphics request that might +produce a +<function>GraphicsExpose</function> +event does not produce any. +In other words, the client is really asking for a +<function>GraphicsExpose</function> +event but instead receives a +<function>NoExpose</function> +event. +</para> +<para> +<!-- .LP --> +To receive +<function>GraphicsExpose</function> +or +<function>NoExpose</function> +events, you must first set the graphics-exposure +attribute of the graphics context to +<function>True .</function> +You also can set the graphics-expose attribute when creating a graphics +context using +<function>XCreateGC </function> +or by calling +<function>XSetGraphicsExposures .</function> +</para> +<para> +<!-- .LP --> +The structures for these event types contain: +</para> +<para> +<!-- .LP --> +<!-- .IN "XGraphicsExposeEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* GraphicsExpose */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Drawable drawable; + int x, y; + int width, height; + int count; /* if nonzero, at least this many more */ + int major_code; /* core is CopyArea or CopyPlane */ + int minor_code; /* not defined in the core */ +} XGraphicsExposeEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .IN "XNoExposeEvent" "" "@DEF@" --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* NoExpose */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Drawable drawable; + int major_code; /* core is CopyArea or CopyPlane */ + int minor_code; /* not defined in the core */ +} XNoExposeEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Both structures have these common members: drawable, major_code, and minor_code. +The drawable member is set to the drawable of the destination region on +which the graphics request was to be performed. +The major_code member is set to the graphics request initiated by the client +and can be either +<function>X_CopyArea</function> +or +<function>X_CopyPlane .</function> +If it is +<function>X_CopyArea ,</function> +a call to +<function>XCopyArea</function> +initiated the request. +If it is +<function>X_CopyPlane ,</function> +a call to +<function>XCopyPlane</function> +initiated the request. +These constants are defined in +<!-- .hN X11/Xproto.h . --> +The minor_code member, +like the major_code member, +indicates which graphics request was initiated by +the client. +However, the minor_code member is not defined by the core +X protocol and will be zero in these cases, +although it may be used by an extension. +</para> +<para> +<!-- .LP --> +The +<function>XGraphicsExposeEvent</function> +structure has these additional members: x, y, width, height, and count. +The x and y members are set to the coordinates relative to the drawable's origin +and indicate the upper-left corner of the rectangle. +The width and height members are set to the size (extent) of the rectangle. +The count member is set to the number of +<function>GraphicsExpose</function> +events to follow. +If count is zero, no more +<function>GraphicsExpose</function> +events follow for this window. +However, if count is nonzero, at least that number of +<function>GraphicsExpose</function> +events (and possibly more) are to follow for this window. +</para> +</sect2> +</sect1> +<sect1 id="Window_State_Change_Events_"> +<title>Window State Change Events </title> +<!-- .XS --> +<!-- (SN Window State Change Events --> +<!-- .XE --> +<para> +<!-- .LP --> +The following sections discuss: +</para> +<itemizedlist> + <listitem> + <para> +<function>CirculateNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>ConfigureNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>CreateNotify </function> +events + </para> + </listitem> + <listitem> + <para> +<function>DestroyNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>GravityNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>MapNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>MappingNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>ReparentNotify </function> +events + </para> + </listitem> + <listitem> + <para> +<function>UnmapNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>VisibilityNotify</function> +events +<!-- .\" .SH 3 --> + </para> + </listitem> +</itemizedlist> +<sect2 id="CirculateNotify_Events"> +<title>CirculateNotify Events</title> +<!-- .XS --> +<!-- (SN CirculateNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "CirculateNotify" --> +<!-- .IN "CirculateNotify" "" "@DEF@" --> +The X server can report +<function>CirculateNotify</function> +events to clients wanting information about when a window changes +its position in the stack. +The X server generates this event type whenever a window is actually restacked +as a result of a client application calling +<function>XCirculateSubwindows ,</function> +<function>XCirculateSubwindowsUp ,</function> +or +<function>XCirculateSubwindowsDown .</function> +</para> +<para> +<!-- .LP --> +To receive +<function>CirculateNotify</function> +events, set the +<function>StructureNotifyMask</function> +bit in the event-mask attribute of the window +or the +<function>SubstructureNotifyMask</function> +bit in the event-mask attribute of the parent window +(in which case, circulating any child generates an event). +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XCirculateEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* CirculateNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int place; /* PlaceOnTop, PlaceOnBottom */ +} XCirculateEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The event member is set either to the restacked window or to its parent, +depending on whether +<function>StructureNotify</function> +or +<function>SubstructureNotify</function> +was selected. +The window member is set to the window that was restacked. +The place member is set to the window's position after the restack occurs and +is either +<function>PlaceOnTop</function> +or +<function>PlaceOnBottom .</function> +If it is +<function>PlaceOnTop ,</function> +the window is now on top of all siblings. +If it is +<function>PlaceOnBottom ,</function> +the window is now below all siblings. +</para> +</sect2> +<sect2 id="ConfigureNotify_Events"> +<title>ConfigureNotify Events</title> +<!-- .XS --> +<!-- (SN ConfigureNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "ConfigureNotify" --> +<!-- .IN "ConfigureNotify" "" "@DEF@" --> +The X server can report +<function>ConfigureNotify</function> +events to clients wanting information about actual changes to a window's +state, such as size, position, border, and stacking order. +The X server generates this event type whenever one of the following configure +window requests made by a client application actually completes: +</para> +<itemizedlist> + <listitem> + <para> +A window's size, position, border, and/or stacking order is reconfigured +by calling +<function>XConfigureWindow .</function> + </para> + </listitem> + <listitem> + <para> +The window's position in the stacking order is changed by calling +<function>XLowerWindow ,</function> +<function>XRaiseWindow ,</function> +or +<function>XRestackWindows .</function> + </para> + </listitem> + <listitem> + <para> +A window is moved by calling +<function>XMoveWindow .</function> + </para> + </listitem> + <listitem> + <para> +A window's size is changed by calling +<function>XResizeWindow .</function> + </para> + </listitem> + <listitem> + <para> +A window's size and location is changed by calling +<function>XMoveResizeWindow .</function> + </para> + </listitem> + <listitem> + <para> +A window is mapped and its position in the stacking order is changed +by calling +<function>XMapRaised .</function> + </para> + </listitem> + <listitem> + <para> +A window's border width is changed by calling +<function>XSetWindowBorderWidth .</function> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +To receive +<function>ConfigureNotify</function> +events, set the +<function>StructureNotifyMask</function> +bit in the event-mask attribute of the window or the +<function>SubstructureNotifyMask</function> +bit in the event-mask attribute of the parent window +(in which case, configuring any child generates an event). +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<!-- .LP --> +<!-- .IN "XConfigureEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* ConfigureNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int x, y; + int width, height; + int border_width; + Window above; + Bool override_redirect; +} XConfigureEvent; +</literallayout> +<para> +<!-- .LP --> +<!-- .eM --> +The event member is set either to the reconfigured window or to its parent, +depending on whether +<function>StructureNotify</function> +or +<function>SubstructureNotify</function> +was selected. +The window member is set to the window whose size, position, +border, and/or stacking +order was changed. +</para> +<para> +<!-- .LP --> +The x and y members are set to the coordinates relative to the parent window's +origin and indicate the position of the upper-left outside corner of the window. +The width and height members are set to the inside size of the window, +not including +the border. +The border_width member is set to the width of the window's border, in pixels. +</para> +<para> +<!-- .LP --> +The above member is set to the sibling window and is used +for stacking operations. +If the X server sets this member to +<function>None ,</function> +the window whose state was changed is on the bottom of the stack +with respect to sibling windows. +However, if this member is set to a sibling window, +the window whose state was changed is placed on top of this sibling window. +</para> +<para> +<!-- .LP --> +The override_redirect member is set to the override-redirect attribute of the +window. +Window manager clients normally should ignore this window if the +override_redirect member +is +<function>True .</function> +</para> +</sect2> +<sect2 id="CreateNotify_Events"> +<title>CreateNotify Events</title> +<!-- .XS --> +<!-- (SN CreateNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "CreateNotify" --> +<!-- .IN "CreateNotify" "" "@DEF@" --> +The X server can report +<function>CreateNotify</function> +events to clients wanting information about creation of windows. +The X server generates this event whenever a client +application creates a window by calling +<function>XCreateWindow</function> +or +<function>XCreateSimpleWindow .</function> +</para> +<para> +<!-- .LP --> +To receive +<function>CreateNotify</function> +events, set the +<function>SubstructureNotifyMask</function> +bit in the event-mask attribute of the window. +Creating any children then generates an event. +</para> +<para> +<!-- .LP --> +The structure for the event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XCreateWindowEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* CreateNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window parent; /* parent of the window */ + Window window; /* window id of window created */ + int x, y; /* window location */ + int width, height; /* size of window */ + int border_width; /* border width */ + Bool override_redirect; /* creation should be overridden */ +} XCreateWindowEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The parent member is set to the created window's parent. +The window member specifies the created window. +The x and y members are set to the created window's coordinates relative +to the parent window's origin and indicate the position of the upper-left +outside corner of the created window. +The width and height members are set to the inside size of the created window +(not including the border) and are always nonzero. +The border_width member is set to the width of the created window's border, in pixels. +The override_redirect member is set to the override-redirect attribute of the +window. +Window manager clients normally should ignore this window +if the override_redirect member is +<function>True .</function> +</para> +</sect2> +<sect2 id="DestroyNotify_Events"> +<title>DestroyNotify Events</title> +<!-- .XS --> +<!-- (SN DestroyNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "DestroyNotify" --> +<!-- .IN "DestroyNotify" "" "@DEF@" --> +The X server can report +<function>DestroyNotify</function> +events to clients wanting information about which windows are destroyed. +The X server generates this event whenever a client application destroys a +window by calling +<function>XDestroyWindow</function> +or +<function>XDestroySubwindows .</function> +</para> +<para> +<!-- .LP --> +The ordering of the +<function>DestroyNotify </function> +events is such that for any given window, +<function>DestroyNotify</function> +is generated on all inferiors of the window +before being generated on the window itself. +The X protocol does not constrain the ordering among +siblings and across subhierarchies. +</para> +<para> +<!-- .LP --> +To receive +<function>DestroyNotify</function> +events, set the +<function>StructureNotifyMask</function> +bit in the event-mask attribute of the window or the +<function>SubstructureNotifyMask</function> +bit in the event-mask attribute of the parent window +(in which case, destroying any child generates an event). +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XDestroyWindowEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* DestroyNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; +} XDestroyWindowEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The event member is set either to the destroyed window or to its parent, +depending on whether +<function>StructureNotify</function> +or +<function>SubstructureNotify</function> +was selected. +The window member is set to the window that is destroyed. +</para> +</sect2> +<sect2 id="GravityNotify_Events"> +<title>GravityNotify Events</title> +<!-- .XS --> +<!-- (SN GravityNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "GravityNotify" --> +<!-- .IN "GravityNotify" "" "@DEF@" --> +The X server can report +<function>GravityNotify</function> +events to clients wanting information about when a window is moved because of a +change in the size of its parent. +The X server generates this event whenever a client +application actually moves a child window as a result of resizing its parent by calling +<function>XConfigureWindow ,</function> +<function>XMoveResizeWindow ,</function> +or +<function>XResizeWindow . </function> +</para> +<para> +<!-- .LP --> +To receive +<function>GravityNotify</function> +events, set the +<function>StructureNotifyMask</function> +bit in the event-mask attribute of the window or the +<function>SubstructureNotifyMask</function> +bit in the event-mask attribute of the parent window +(in which case, any child that is moved because its parent has been resized +generates an event). +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XGravityEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* GravityNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + int x, y; +} XGravityEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The event member is set either to the window that was moved or to its parent, +depending on whether +<function>StructureNotify</function> +or +<function>SubstructureNotify</function> +was selected. +The window member is set to the child window that was moved. +The x and y members are set to the coordinates relative to the +new parent window's origin +and indicate the position of the upper-left outside corner of the +window. +</para> +</sect2> +<sect2 id="MapNotify_Events"> +<title>MapNotify Events</title> +<!-- .XS --> +<!-- (SN MapNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "MapNotify" --> +<!-- .IN "MapNotify" "" "@DEF@" --> +The X server can report +<function>MapNotify</function> +events to clients wanting information about which windows are mapped. +The X server generates this event type whenever a client application changes the +window's state from unmapped to mapped by calling +<function>XMapWindow ,</function> +<function>XMapRaised ,</function> +<function>XMapSubwindows ,</function> +<function>XReparentWindow ,</function> +or as a result of save-set processing. +</para> +<para> +<!-- .LP --> +To receive +<function>MapNotify</function> +events, set the +<function>StructureNotifyMask</function> +bit in the event-mask attribute of the window or the +<function>SubstructureNotifyMask</function> +bit in the event-mask attribute of the parent window +(in which case, mapping any child generates an event). +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XMapEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* MapNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + Bool override_redirect; /* boolean, is override set... */ +} XMapEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The event member is set either to the window that was mapped or to its parent, +depending on whether +<function>StructureNotify</function> +or +<function>SubstructureNotify</function> +was selected. +The window member is set to the window that was mapped. +The override_redirect member is set to the override-redirect attribute +of the window. +Window manager clients normally should ignore this window +if the override-redirect attribute is +<function>True ,</function> +because these events usually are generated from pop-ups, +which override structure control. +</para> +</sect2> +<sect2 id="MappingNotify_Events"> +<title>MappingNotify Events</title> +<!-- .XS --> +<!-- (SN MappingNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "MappingNotify" --> +<!-- .IN "MappingNotify" "" "@DEF@" --> +The X server reports +<function>MappingNotify</function> +events to all clients. +There is no mechanism to express disinterest in this event. +The X server generates this event type whenever a client application +successfully calls: +</para> +<itemizedlist> + <listitem> + <para> +<function>XSetModifierMapping</function> +to indicate which KeyCodes are to be used as modifiers + </para> + </listitem> + <listitem> + <para> +<function>XChangeKeyboardMapping</function> +to change the keyboard mapping + </para> + </listitem> + <listitem> + <para> +<function>XSetPointerMapping</function> +to set the pointer mapping + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XMappingEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* MappingNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* unused */ + int request; /* one of MappingModifier, MappingKeyboard, + MappingPointer */ + int first_keycode; /* first keycode */ + int count; /* defines range of change w. first_keycode*/ +} XMappingEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The request member is set to indicate the kind of mapping change that occurred +and can be +<function>MappingModifier ,</function> +<function>MappingKeyboard ,</function> +or +<function>MappingPointer .</function> +If it is +<function>MappingModifier ,</function> +the modifier mapping was changed. +If it is +<function>MappingKeyboard ,</function> +the keyboard mapping was changed. +If it is +<function>MappingPointer ,</function> +the pointer button mapping was changed. +The first_keycode and count members are set only +if the request member was set to +<function>MappingKeyboard .</function> +The number in first_keycode represents the first number in the range +of the altered mapping, +and count represents the number of keycodes altered. +</para> +<para> +<!-- .LP --> +To update the client application's knowledge of the keyboard, +you should call +<function>XRefreshKeyboardMapping . </function> +</para> +</sect2> +<sect2 id="ReparentNotify_Events"> +<title>ReparentNotify Events</title> +<!-- .XS --> +<!-- (SN ReparentNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "ReparentNotify" --> +<!-- .IN "ReparentNotify" "" "@DEF@" --> +The X server can report +<function>ReparentNotify</function> +events to clients wanting information about changing a window's parent. +The X server generates this event whenever a client +application calls +<function>XReparentWindow </function> +and the window is actually reparented. +</para> +<para> +<!-- .LP --> +To receive +<function>ReparentNotify</function> +events, set the +<function>StructureNotifyMask</function> +bit in the event-mask attribute of the window or the +<function>SubstructureNotifyMask</function> +bit in the event-mask attribute of either the old or the new parent window +(in which case, reparenting any child generates an event). +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XReparentEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* ReparentNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + Window parent; + int x, y; + Bool override_redirect; +} XReparentEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The event member is set either to the reparented window +or to the old or the new parent, depending on whether +<function>StructureNotify</function> +or +<function>SubstructureNotify</function> +was selected. +The window member is set to the window that was reparented. +The parent member is set to the new parent window. +The x and y members are set to the reparented window's coordinates relative +to the new parent window's +origin and define the upper-left outer corner of the reparented window. +The override_redirect member is set to the override-redirect attribute of the +window specified by the window member. +Window manager clients normally should ignore this window +if the override_redirect member is +<function>True .</function> +</para> +</sect2> +<sect2 id="UnmapNotify_Events"> +<title>UnmapNotify Events</title> +<!-- .XS --> +<!-- (SN UnmapNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "UnmapNotify" --> +<!-- .IN "UnmapNotify" "" "@DEF@" --> +The X server can report +<function>UnmapNotify</function> +events to clients wanting information about which windows are unmapped. +The X server generates this event type whenever a client application changes the +window's state from mapped to unmapped. +</para> +<para> +<!-- .LP --> +To receive +<function>UnmapNotify</function> +events, set the +<function>StructureNotifyMask</function> +bit in the event-mask attribute of the window or the +<function>SubstructureNotifyMask</function> +bit in the event-mask attribute of the parent window +(in which case, unmapping any child window generates an event). +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XUnmapEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* UnmapNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window event; + Window window; + Bool from_configure; +} XUnmapEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The event member is set either to the unmapped window or to its parent, +depending on whether +<function>StructureNotify</function> +or +<function>SubstructureNotify</function> +was selected. +This is the window used by the X server to report the event. +The window member is set to the window that was unmapped. +The from_configure member is set to +<function>True </function> +if the event was generated as a result of a resizing of the window's parent when +the window itself had a win_gravity of +<function>UnmapGravity .</function> +</para> +</sect2> +<sect2 id="VisibilityNotify_Events"> +<title>VisibilityNotify Events</title> +<!-- .XS --> +<!-- (SN VisibilityNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "VisibilityNotify" --> +<!-- .IN "VisibilityNotify" "" "@DEF@" --> +The X server can report +<function>VisibilityNotify</function> +events to clients wanting any change in the visibility of the specified window. +A region of a window is visible if someone looking at the screen can +actually see it. +The X server generates this event whenever the visibility changes state. +However, this event is never generated for windows whose class is +<function>InputOnly .</function> +</para> +<para> +<!-- .LP --> +All +<function>VisibilityNotify</function> +events caused by a hierarchy change are generated +after any hierarchy event +<function>( UnmapNotify , </function> +<function>MapNotify , </function> +<function>ConfigureNotify ,</function> +<function>GravityNotify ,</function> +<function>CirculateNotify )</function> +caused by that change. Any +<function>VisibilityNotify</function> +event on a given window is generated before any +<function>Expose </function> +events on that window, but it is not required that all +<function>VisibilityNotify</function> +events on all windows be generated before all +<function>Expose</function> +events on all windows. +The X protocol does not constrain the ordering of +<function>VisibilityNotify</function> +events with +respect to +<function>FocusOut , </function> +<function>EnterNotify ,</function> +and +<function>LeaveNotify</function> +events. +</para> +<para> +<!-- .LP --> +To receive +<function>VisibilityNotify</function> +events, set the +<function>VisibilityChangeMask</function> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XVisibilityEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* VisibilityNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + int state; +} XVisibilityEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The window member is set to the window whose visibility state changes. +The state member is set to the state of the window's visibility and can be +<function>VisibilityUnobscured ,</function> +<function>VisibilityPartiallyObscured ,</function> +or +<function>VisibilityFullyObscured .</function> +The X server ignores all of a window's subwindows +when determining the visibility state of the window and processes +<function>VisibilityNotify</function> +events according to the following: +</para> +<itemizedlist> + <listitem> + <para> +When the window changes state from partially obscured, fully obscured, +or not viewable to viewable and completely unobscured, +the X server generates the event with the state member of the +<function>XVisibilityEvent</function> +structure set to +<function>VisibilityUnobscured .</function> + </para> + </listitem> + <listitem> + <para> +When the window changes state from viewable and completely unobscured or +not viewable to viewable and partially obscured, +the X server generates the event with the state member of the +<function>XVisibilityEvent</function> +structure set to +<function>VisibilityPartiallyObscured .</function> + </para> + </listitem> + <listitem> + <para> +When the window changes state from viewable and completely unobscured, +viewable and partially obscured, or not viewable to viewable and +fully obscured, +the X server generates the event with the state member of the +<function>XVisibilityEvent</function> +structure set to +<function>VisibilityFullyObscured .</function> + </para> + </listitem> +</itemizedlist> +</sect2> +</sect1> +<sect1 id="Structure_Control_Events"> +<title>Structure Control Events</title> +<!-- .XS --> +<!-- (SN Structure Control Events --> +<!-- .XE --> +<para> +<!-- .LP --> +This section discusses: +</para> +<itemizedlist> + <listitem> + <para> +<function>CirculateRequest</function> +events + </para> + </listitem> + <listitem> + <para> +<function>ConfigureRequest</function> +events + </para> + </listitem> + <listitem> + <para> +<function>MapRequest </function> +events + </para> + </listitem> + <listitem> + <para> +<function>ResizeRequest </function> +events + </para> + </listitem> +</itemizedlist> +<sect2 id="CirculateRequest_Events"> +<title>CirculateRequest Events</title> +<!-- .XS --> +<!-- (SN CirculateRequest Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "CirculateRequest" --> +<!-- .IN "CirculateRequest" "" "@DEF@" --> +The X server can report +<function>CirculateRequest</function> +events to clients wanting information about +when another client initiates a circulate window request +on a specified window. +The X server generates this event type whenever a client initiates a circulate +window request on a window and a subwindow actually needs to be restacked. +The client initiates a circulate window request on the window by calling +<function>XCirculateSubwindows ,</function> +<function>XCirculateSubwindowsUp ,</function> +or +<function>XCirculateSubwindowsDown .</function> +</para> +<para> +<!-- .LP --> +To receive +<function>CirculateRequest</function> +events, set the +<function>SubstructureRedirectMask</function> +in the event-mask attribute of the window. +Then, in the future, +the circulate window request for the specified window is not executed, +and thus, any subwindow's position in the stack is not changed. +For example, suppose a client application calls +<function>XCirculateSubwindowsUp</function> +to raise a subwindow to the top of the stack. +If you had selected +<function>SubstructureRedirectMask</function> +on the window, the X server reports to you a +<function>CirculateRequest</function> +event and does not raise the subwindow to the top of the stack. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XCirculateRequestEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* CirculateRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; + int place; /* PlaceOnTop, PlaceOnBottom */ +} XCirculateRequestEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The parent member is set to the parent window. +The window member is set to the subwindow to be restacked. +The place member is set to what the new position in the stacking order should be +and is either +<function>PlaceOnTop</function> +or +<function>PlaceOnBottom .</function> +If it is +<function>PlaceOnTop ,</function> +the subwindow should be on top of all siblings. +If it is +<function>PlaceOnBottom ,</function> +the subwindow should be below all siblings. +</para> +</sect2> +<sect2 id="ConfigureRequest_Events"> +<title>ConfigureRequest Events</title> +<!-- .XS --> +<!-- (SN ConfigureRequest Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "ConfigureRequest" --> +<!-- .IN "ConfigureRequest" "" "@DEF@" --> +The X server can report +<function>ConfigureRequest</function> +events to clients wanting information about when a different client initiates +a configure window request on any child of a specified window. +The configure window request attempts to +reconfigure a window's size, position, border, and stacking order. +The X server generates this event whenever a different client initiates +a configure window request on a window by calling +<function>XConfigureWindow ,</function> +<function>XLowerWindow ,</function> +<function>XRaiseWindow ,</function> +<function>XMapRaised ,</function> +<function>XMoveResizeWindow ,</function> +<function>XMoveWindow ,</function> +<function>XResizeWindow ,</function> +<function>XRestackWindows ,</function> +or +<function>XSetWindowBorderWidth .</function> +</para> +<para> +<!-- .LP --> +To receive +<function>ConfigureRequest</function> +events, set the +<function>SubstructureRedirectMask</function> +bit in the event-mask attribute of the window. +<function>ConfigureRequest</function> +events are generated when a +<function>ConfigureWindow</function> +protocol request is issued on a child window by another client. +For example, suppose a client application calls +<function>XLowerWindow</function> +to lower a window. +If you had selected +<function>SubstructureRedirectMask </function> +on the parent window and if the override-redirect attribute +of the window is set to +<function>False ,</function> +the X server reports a +<function>ConfigureRequest</function> +event to you and does not lower the specified window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XConfigureRequestEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* ConfigureRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; + int x, y; + int width, height; + int border_width; + Window above; + int detail; /* Above, Below, TopIf, BottomIf, Opposite */ + unsigned long value_mask; +} XConfigureRequestEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The parent member is set to the parent window. +The window member is set to the window whose size, position, border width, +and/or stacking order is to be reconfigured. +The value_mask member indicates which components were specified in the +<function>ConfigureWindow </function> +protocol request. +The corresponding values are reported as given in the request. +The remaining values are filled in from the current geometry of the window, +except in the case of above (sibling) and detail (stack-mode), +which are reported as +<function>None</function> +and +<function>Above ,</function> +respectively, if they are not given in the request. +</para> +</sect2> +<sect2 id="MapRequest_Events"> +<title>MapRequest Events</title> +<!-- .XS --> +<!-- (SN MapRequest Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "MapRequest" --> +<!-- .IN "MapRequest" "" "@DEF@" --> +The X server can report +<function>MapRequest</function> +events to clients wanting information about a different client's desire +to map windows. +A window is considered mapped when a map window request completes. +The X server generates this event whenever a different client initiates +a map window request on an unmapped window whose override_redirect member +is set to +<function>False .</function> +Clients initiate map window requests by calling +<function>XMapWindow ,</function> +<function>XMapRaised ,</function> +or +<function>XMapSubwindows .</function> +</para> +<para> +<!-- .LP --> +To receive +<function>MapRequest</function> +events, set the +<function>SubstructureRedirectMask</function> +bit in the event-mask attribute of the window. +This means another client's attempts to map a child window by calling one of +the map window request functions is intercepted, and you are sent a +<function>MapRequest</function> +instead. +For example, suppose a client application calls +<function>XMapWindow</function> +to map a window. +If you (usually a window manager) had selected +<function>SubstructureRedirectMask </function> +on the parent window and if the override-redirect attribute +of the window is set to +<function>False ,</function> +the X server reports a +<function>MapRequest</function> +event to you +and does not map the specified window. +Thus, this event gives your window manager client the ability +to control the placement of subwindows. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XMapRequestEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* MapRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window parent; + Window window; +} XMapRequestEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The parent member is set to the parent window. +The window member is set to the window to be mapped. +</para> +</sect2> +<sect2 id="ResizeRequest_Events"> +<title>ResizeRequest Events</title> +<!-- .XS --> +<!-- (SN ResizeRequest Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "ResizeRequest" --> +<!-- .IN "ResizeRequest" "" "@DEF@" --> +The X server can report +<function>ResizeRequest</function> +events to clients wanting information about another client's attempts to change the +size of a window. +The X server generates this event whenever some other client attempts to change +the size of the specified window by calling +<function>XConfigureWindow ,</function> +<function>XResizeWindow ,</function> +or +<function>XMoveResizeWindow .</function> +</para> +<para> +<!-- .LP --> +To receive +<function>ResizeRequest</function> +events, set the +<function>ResizeRedirect</function> +bit in the event-mask attribute of the window. +Any attempts to change the size by other clients are then redirected. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XResizeRequestEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* ResizeRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + int width, height; +} XResizeRequestEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The window member is set to the window whose size another +client attempted to change. +The width and height members are set to the inside size of the window, +excluding the border. +</para> +</sect2> +</sect1> +<sect1 id="Colormap_State_Change_Events"> +<title>Colormap State Change Events</title> +<!-- .XS --> +<!-- (SN Colormap State Change Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "ColormapNotify" --> +<!-- .IN "ColormapNotify" "" "@DEF@" --> +The X server can report +<function>ColormapNotify</function> +events to clients wanting information about when the colormap changes +and when a colormap is installed or uninstalled. +The X server generates this event type whenever a client application: +</para> +<itemizedlist> + <listitem> + <para> +Changes the colormap member of the +<function>XSetWindowAttributes</function> +structure by +calling +<function>XChangeWindowAttributes ,</function> +<function>XFreeColormap ,</function> +or +<function>XSetWindowColormap </function> + </para> + </listitem> + <listitem> + <para> +Installs or uninstalls the colormap by calling +<function>XInstallColormap</function> +or +<function>XUninstallColormap </function> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +To receive +<function>ColormapNotify </function> +events, set the +<function>ColormapChangeMask</function> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XColormapEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* ColormapNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + Colormap colormap; /* colormap or None */ + Bool new; + int state; /* ColormapInstalled, ColormapUninstalled */ +} XColormapEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The window member is set to the window whose associated +colormap is changed, installed, or uninstalled. +For a colormap that is changed, installed, or uninstalled, +the colormap member is set to the colormap associated with the window. +For a colormap that is changed by a call to +<function>XFreeColormap ,</function> +the colormap member is set to +<function>None .</function> +The new member is set to indicate whether the colormap +for the specified window was changed or installed or uninstalled +and can be +<function>True</function> +or +<function>False .</function> +If it is +<function>True ,</function> +the colormap was changed. +If it is +<function>False ,</function> +the colormap was installed or uninstalled. +The state member is always set to indicate whether the colormap is installed or +uninstalled and can be +<function>ColormapInstalled</function> +or +<function>ColormapUninstalled .</function> +</para> +</sect1> +<sect1 id="Client_Communication_Events"> +<title>Client Communication Events</title> +<!-- .XS --> +<!-- (SN Client Communication Events --> +<!-- .XE --> +<para> +<!-- .LP --> +This section discusses: +</para> +<itemizedlist> + <listitem> + <para> +<function>ClientMessage </function> +events + </para> + </listitem> + <listitem> + <para> +<function>PropertyNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>SelectionClear</function> +events + </para> + </listitem> + <listitem> + <para> +<function>SelectionNotify</function> +events + </para> + </listitem> + <listitem> + <para> +<function>SelectionRequest</function> +events + </para> + </listitem> +</itemizedlist> +<sect2 id="ClientMessage_Events"> +<title>ClientMessage Events</title> +<!-- .XS --> +<!-- (SN ClientMessage Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "ClientMessage" --> +<!-- .IN "ClientMessage" "" "@DEF@" --> +The X server generates +<function>ClientMessage</function> +events only when a client calls the function +<function>XSendEvent .</function> +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XClientMessageEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 1i 3i --> +<!-- .ta .5i 1i 3i --> +typedef struct { + int type; /* ClientMessage */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + Atom message_type; + int format; + union { + char b[20]; + short s[10]; + long l[5]; + } data; +} XClientMessageEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The message_type member is set to an atom that indicates how the data +should be interpreted by the receiving client. +The format member is set to 8, 16, or 32 and specifies whether the data +should be viewed as a list of bytes, shorts, or longs. +The data member is a union that contains the members b, s, and l. +The b, s, and l members represent data of twenty 8-bit values, +ten 16-bit values, and five 32-bit values. +Particular message types might not make use of all these values. +The X server places no interpretation on the values in the window, +message_type, or data members. +</para> +</sect2> +<sect2 id="PropertyNotify_Events"> +<title>PropertyNotify Events</title> +<!-- .XS --> +<!-- (SN PropertyNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "PropertyNotify" --> +<!-- .IN "PropertyNotify" "" "@DEF@" --> +The X server can report +<function>PropertyNotify</function> +events to clients wanting information about property changes +for a specified window. +</para> +<para> +<!-- .LP --> +To receive +<function>PropertyNotify</function> +events, set the +<function>PropertyChangeMask</function> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XPropertyEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* PropertyNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + Atom atom; + Time time; + int state; /* PropertyNewValue or PropertyDelete */ +} XPropertyEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The window member is set to the window whose associated +property was changed. +The atom member is set to the property's atom and indicates which +property was changed or desired. +The time member is set to the server time when the property was changed. +The state member is set to indicate whether the property was changed +to a new value or deleted and can be +<function>PropertyNewValue</function> +or +<function>PropertyDelete .</function> +The state member is set to +<function>PropertyNewValue</function> +when a property of the window is changed using +<function>XChangeProperty</function> +or +<function>XRotateWindowProperties</function> +(even when adding zero-length data using +<function>XChangeProperty )</function> +and when replacing all or part of a property with identical data using +<function>XChangeProperty</function> +or +<function>XRotateWindowProperties .</function> +The state member is set to +<function>PropertyDelete</function> +when a property of the window is deleted using +<function>XDeleteProperty</function> +or, if the delete argument is +<function>True ,</function> +<function>XGetWindowProperty .</function> +</para> +</sect2> +<sect2 id="SelectionClear_Events"> +<title>SelectionClear Events</title> +<!-- .XS --> +<!-- (SN SelectionClear Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "SelectionClear" --> +<!-- .IN "SelectionClear" "" "@DEF@" --> +The X server reports +<function>SelectionClear</function> +events to the client losing ownership of a selection. +The X server generates this event type when another client +asserts ownership of the selection by calling +<function>XSetSelectionOwner .</function> +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XSelectionClearEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* SelectionClear */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + Atom selection; + Time time; +} XSelectionClearEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The selection member is set to the selection atom. +The time member is set to the last change time recorded for the +selection. +The window member is the window that was specified by the current owner +(the owner losing the selection) in its +<function>XSetSelectionOwner</function> +call. +</para> +</sect2> +<sect2 id="SelectionRequest_Events"> +<title>SelectionRequest Events</title> +<!-- .XS --> +<!-- (SN SelectionRequest Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "SelectionRequest" --> +<!-- .IN "SelectionRequest" "" "@DEF@" --> +The X server reports +<function>SelectionRequest</function> +events to the owner of a selection. +The X server generates this event whenever a client +requests a selection conversion by calling +<function>XConvertSelection </function> +for the owned selection. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XSelectionRequestEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* SelectionRequest */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window owner; + Window requestor; + Atom selection; + Atom target; + Atom property; + Time time; +} XSelectionRequestEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The owner member is set to the window +that was specified by the current owner in its +<function>XSetSelectionOwner</function> +call. +The requestor member is set to the window requesting the selection. +The selection member is set to the atom that names the selection. +For example, PRIMARY is used to indicate the primary selection. +The target member is set to the atom that indicates the type +the selection is desired in. +The property member can be a property name or +<function>None .</function> +The time member is set to the timestamp or +<function>CurrentTime </function> +value from the +<function>ConvertSelection</function> +request. +</para> +<para> +<!-- .LP --> +The owner should convert the selection based on the specified target type +and send a +<function>SelectionNotify</function> +event back to the requestor. +A complete specification for using selections is given in the X Consortium +standard <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>. +</para> +</sect2> +<sect2 id="SelectionNotify_Events"> +<title>SelectionNotify Events</title> +<!-- .XS --> +<!-- (SN SelectionNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .IN "Events" "SelectionNotify" --> +<!-- .IN "SelectionNotify" "" "@DEF@" --> +This event is generated by the X server in response to a +<function>ConvertSelection </function> +protocol request when there is no owner for the selection. +When there is an owner, it should be generated by the owner +of the selection by using +<function>XSendEvent .</function> +The owner of a selection should send this event to a requestor when a selection +has been converted and stored as a property +or when a selection conversion could +not be performed (which is indicated by setting the property member to +<function>None ).</function> +</para> +<para> +<!-- .LP --> +If +<function>None</function> +is specified as the property in the +<function>ConvertSelection</function> +protocol request, the owner should choose a property name, +store the result as that property on the requestor window, +and then send a +<function>SelectionNotify</function> +giving that actual property name. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<!-- .IN "XSelectionEvent" "" "@DEF@" --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* SelectionNotify */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window requestor; + Atom selection; + Atom target; + Atom property; /* atom or None */ + Time time; +} XSelectionEvent; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The requestor member is set to the window associated with +the requestor of the selection. +The selection member is set to the atom that indicates the selection. +For example, PRIMARY is used for the primary selection. +The target member is set to the atom that indicates the converted type. +For example, PIXMAP is used for a pixmap. +The property member is set to the atom that indicates which +property the result was stored on. +If the conversion failed, +the property member is set to +<function>None .</function> +The time member is set to the time the conversion took place and +can be a timestamp or +<function>CurrentTime .</function> +<!-- .bp --> + + +</para> +</sect2> +</sect1> +</chapter> |