diff options
Diffstat (limited to 'libX11')
| -rw-r--r-- | libX11/specs/libX11/AppC.xml | 39 | ||||
| -rw-r--r-- | libX11/specs/libX11/AppD.xml | 7 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH01.xml | 1689 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH02.xml | 35 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH03.xml | 33 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH04.xml | 18 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH05.xml | 2 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH06.xml | 6 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH07.xml | 2 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH08.xml | 2 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH09.xml | 4 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH10.xml | 9481 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH11.xml | 7 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH13.xml | 25 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH14.xml | 45 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH15.xml | 17 | ||||
| -rw-r--r-- | libX11/specs/libX11/CH16.xml | 8 |
17 files changed, 5739 insertions, 5681 deletions
diff --git a/libX11/specs/libX11/AppC.xml b/libX11/specs/libX11/AppC.xml index fb08f8592..da687ecbb 100644 --- a/libX11/specs/libX11/AppC.xml +++ b/libX11/specs/libX11/AppC.xml @@ -36,7 +36,7 @@ and should use minor opcodes to distinguish the requests. <para> <!-- .LP --> The symbols and macros used for writing stubs to Xlib are listed in -<X11/Xlibint.h> . +<filename class="headerfile"><X11/Xlibint.h></filename>. <!-- .SH --> Basic Protocol Support Routines </para> @@ -236,7 +236,7 @@ The structure returns the information from <function>XInitExtension</function> and is defined in -<X11/Xlib.h> : +<filename class="headerfile"><X11/Xlib.h></filename>: </para> <para> <!-- .LP --> @@ -1262,7 +1262,8 @@ returned to. If your procedure returns a zero value, the error is not suppressed, and the client's error handler is called. -(For further information, see section 11.8.2.) +(For further information, +see <link linkend="Using_the_Default_Error_Handlers">section 11.8.2</link>.) If your procedure returns nonzero, the error is suppressed, and <function>_XReply</function> @@ -1572,7 +1573,7 @@ on these lists. <!-- .LP --> The following structure is used in the functions in this section and is defined in -<X11/Xlib.h> +<filename class="headerfile"><X11/Xlib.h></filename> </para> <para> <!-- .LP --> @@ -1743,7 +1744,7 @@ There is no way to find additional structures. The <function>XAllocID</function> macro, which allocates and returns a resource ID, is defined in -<X11/Xlib.h>. +<filename class="headerfile"><X11/Xlib.h></filename>. <indexterm significance="preferred"><primary>XAllocID</primary></indexterm> <!-- .sM --> <funcsynopsis id='xallocid'> @@ -2020,7 +2021,7 @@ XDrawPoint(dpy, d, gc, x, y) To keep clients from generating very long requests that may monopolize the server, there is a symbol defined in -<X11/Xlibint.h> +<filename class="headerfile"><X11/Xlibint.h></filename> of EPERBATCH on the number of requests batched. Most of the performance benefit occurs in the first few merged requests. Note that @@ -2047,7 +2048,7 @@ Requests, Replies, and Xproto.h <para> <!-- .LP --> The -<X11/Xproto.h> +<filename class="headerfile"><X11/Xproto.h></filename> file contains three sets of definitions that are of interest to the stub implementor: request names, request structures, and reply structures. @@ -2055,10 +2056,10 @@ request names, request structures, and reply structures. <para> <!-- .LP --> You need to generate a file equivalent to -<X11/Xproto.h> +<filename class="headerfile"><X11/Xproto.h></filename> for your extension and need to include it in your stub procedure. Each stub procedure also must include -<X11/Xlibint.h> . +<filename class="headerfile"><X11/Xlibint.h></filename>. </para> <para> <!-- .LP --> @@ -2066,14 +2067,14 @@ The identifiers are deliberately chosen in such a way that, if the request is called X_DoSomething, then its request structure is xDoSomethingReq, and its reply is xDoSomethingReply. The GetReq family of macros, defined in -<X11/Xlibint.h> , +<filename class="headerfile"><X11/Xlibint.h></filename>, takes advantage of this naming scheme. </para> <para> <!-- .LP --> For each X request, there is a definition in -<X11/Xproto.h> +<filename class="headerfile"><X11/Xproto.h></filename> that looks similar to this: </para> <para> @@ -2134,7 +2135,7 @@ these should be used for all 16-bit and 32-bit quantities, as discussed below. <para> <!-- .LP --> Most protocol requests have a corresponding structure typedef in -<X11/Xproto.h>, +<filename class="headerfile"><X11/Xproto.h></filename>, which looks like: </para> <para> @@ -2162,7 +2163,7 @@ you need not declare a request structure in your extension header file. Instead, such requests use the <structname>xResourceReq</structname> structure in -<X11/Xproto.h>. +<filename class="headerfile"><X11/Xproto.h></filename>. This structure is used for any request whose single argument is a <type>Window</type>, <type>Pixmap</type>, @@ -2215,14 +2216,14 @@ A few protocol requests take no arguments at all. Instead, they use the <structname>xReq</structname> structure in -<X11/Xproto.h>, +<filename class="headerfile"><X11/Xproto.h></filename>, which contains only a reqType and a length (and a pad byte). </para> <para> <!-- .LP --> If the protocol request requires a reply, then -<X11/Xproto.h> +<filename class="headerfile"><X11/Xproto.h></filename> also contains a reply structure typedef: </para> <para> @@ -2280,7 +2281,7 @@ have reply structures longer than 32 bytes in the core protocol. <para> <!-- .LP --> A few protocol requests return replies that contain no data. -<X11/Xproto.h> +<filename class="headerfile"><X11/Xproto.h></filename> does not define reply structures for these. Instead, they use the <structname>xGenericReply</structname> @@ -2372,7 +2373,7 @@ Sending the Protocol Request and Arguments <!-- .LP --> After the variable declarations, a stub procedure should call one of four macros defined in -<X11/Xlibint.h>: +<filename class="headerfile"><X11/Xlibint.h></filename>: <function>GetReq</function>, <function>GetReqExtra</function>, <function>GetResReq</function>, @@ -2380,7 +2381,7 @@ or <function>GetEmptyReq</function>. All of these macros take, as their first argument, the name of the protocol request as declared in -<X11/Xproto.h> +<filename class="headerfile"><X11/Xproto.h></filename> except with X_ removed. Each one declares a <type>Display</type> @@ -3297,7 +3298,7 @@ the simplest and fastest is outlined below. <para> Declare an array of pointers, _NFILE long (this is normally found in -<stdio.h> +<filename class="headerfile"><stdio.h></filename> and is the number of file descriptors supported on the system) of type <structname>XExtCodes</structname>. diff --git a/libX11/specs/libX11/AppD.xml b/libX11/specs/libX11/AppD.xml index afe65907d..3c8af3f6b 100644 --- a/libX11/specs/libX11/AppD.xml +++ b/libX11/specs/libX11/AppD.xml @@ -753,7 +753,8 @@ with the following syntax: <programlisting> XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP); </programlisting> -See section 14.3 for the semantics of standard colormaps. +See <link linkend="Standard_Colormaps">section 14.3</link> for the +semantics of standard colormaps. </para> <para> <!-- .LP --> @@ -1050,7 +1051,7 @@ geometry specifications. The <function>XGetDefault</function> function provides a primitive interface to the resource manager facilities -discussed in chapter 15. <!-- xref --> +discussed in <link linkend="resource_manager_functions">chapter 15</link>. It is only useful in very simple applications. </para> <para> @@ -1548,7 +1549,7 @@ dash-offset, dash-list, fill-style, and fill-rule. <para> <!-- .LP --> These functions have been superseded by the context management functions -(see section 16.10). +(see <link linkend="Using_the_Context_Manager">section 16.10</link>). It is often necessary to associate arbitrary information with resource IDs. Xlib provides the <function>XAssocTable</function> diff --git a/libX11/specs/libX11/CH01.xml b/libX11/specs/libX11/CH01.xml index a401b9a5b..21750aba1 100644 --- a/libX11/specs/libX11/CH01.xml +++ b/libX11/specs/libX11/CH01.xml @@ -1,843 +1,846 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<chapter id="Introduction_to_Xlib"><title>Introduction to Xlib</title>
-
- <para>
-The X Window System is a network-transparent window system that was
-designed at MIT. X display servers run on computers with either
-monochrome or color bitmap display hardware. The server distributes
-user input to and accepts output requests from various client programs
-located either on the same machine or elsewhere in the network. Xlib
-is a C subroutine library that application programs (clients) use to
-interface with the window system by means of a stream connection.
-Although a client usually runs on the same machine as the X server
-it is talking to, this need not be the case.
- </para>
- <para>
-<citetitle>Xlib − C Language X Interface</citetitle> is a reference
-guide to the low-level C language interface to the X Window System
-protocol. It is neither a tutorial nor a user’s guide to programming
-the X Window System. Rather, it provides a detailed description of
-each function in the library as well as a discussion of the related
-background information. <citetitle>Xlib − C Language X Interface</citetitle>
-assumes a basic understanding of a graphics window system and of the C
-programming language. Other higher-level abstractions (for example,
-those provided by the toolkits for X) are built on top of the Xlib
-library. For further information about these higher-level libraries,
-see the appropriate toolkit documentation.
-The <citetitle>X Window System Protocol</citetitle> provides the
-definitive word on the behavior of X.
-Although additional information appears here, the protocol document is
-the ruling document.
- </para>
- <para>
-To provide an introduction to X programming, this chapter discusses:
-
- <itemizedlist>
- <listitem><para><link linkend="Overview_of_the_X_Window_System">Overview of the X Window System</link></para></listitem>
- <listitem><para><link linkend="Errors">Errors</link></para></listitem>
- <listitem><para><link linkend="Standard_Header_Files">Standard header files</link></para></listitem>
- <listitem><para><link linkend="Generic_Values_and_Types">Generic values and types</link></para></listitem>
- <listitem><para><link linkend="Naming_and_Argument_Conventions_within_Xlib">Naming and argument conventions within Xlib</link></para></listitem>
- <listitem><para><link linkend="Programming_Considerations">Programming considerations</link></para></listitem>
- <listitem><para><link linkend="Character_Sets_and_Encodings">Character sets and encodings</link></para></listitem>
- <listitem><para><link linkend="Formatting_Conventions">Formatting conventions</link></para></listitem>
- </itemizedlist>
- </para>
-
- <sect1 id="Overview_of_the_X_Window_System">
- <title>Overview of the X Window System</title>
- <para>
-Some of the terms used in this book are unique to X,
-and other terms that are common to other window systems
-have different meanings in X. You may find it helpful to refer to
-<link linkend="glossary">the glossary</link>,
-which is located at the end of the book.
- </para>
- <para>
-The X Window System supports one or more screens containing
-overlapping windows or subwindows.
-<indexterm><primary>Screen</primary></indexterm>
-A <firstterm>screen</firstterm> is a physical monitor and hardware
-that can be color, grayscale, or monochrome.
-There can be multiple screens for each display or workstation.
-A single X server can provide display services for any number of screens.
-A set of screens for a single user with one keyboard and one pointer
-(usually a mouse) is called a <firstterm>display</firstterm>.
- </para>
- <para>
-All the windows in an X server are arranged in strict hierarchies.
-At the top of each hierarchy is a <firstterm>root window</firstterm>,
-which covers each of the display screens.
-Each root window is partially or completely covered by child windows.
-All windows, except for root windows, have parents.
-There is usually at least one window for each application program.
-<indexterm><primary>Child window</primary></indexterm>
-<indexterm><primary>Parent Window</primary></indexterm>
-Child windows may in turn have their own children.
-In this way,
-an application program can create an arbitrarily deep tree
-on each screen.
-X provides graphics, text, and raster operations for windows.
- </para>
- <para>
-A child window can be larger than its parent.
-That is, part or all of
-the child window can extend beyond the boundaries of the parent,
-but all output to a window is clipped by its parent.
-<indexterm><primary>Stacking order</primary></indexterm>
-If several children of a window have overlapping locations,
-one of the children is considered to be on top of or raised over the
-others, thus obscuring them.
-Output to areas covered by other windows is suppressed by the window
-system unless the window has backing store.
-If a window is obscured by a second window,
-the second window obscures only those ancestors of the second window
-that are also ancestors of the first window.
- </para>
- <para>
-<indexterm significance="preferred"><primary>Window</primary></indexterm>
-A window has a border zero or more pixels in width, which can
-be any pattern (pixmap) or solid color you like.
-A window usually but not always has a background pattern,
-which will be repainted by the window system when uncovered.
-Child windows obscure their parents,
-and graphic operations in the parent window usually
-are clipped by the children.
- </para>
- <para>
-Each window and pixmap has its own coordinate system.
-The coordinate system has the X axis horizontal and the Y axis vertical
-with the origin [0, 0] at the upper-left corner.
-Coordinates are integral,
-in terms of pixels,
-and coincide with pixel centers.
-For a window,
-the origin is inside the border at the inside, upper-left corner.
- </para>
- <para>
-X does not guarantee to preserve the contents of windows.
-When part or all of a window is hidden and then brought back onto the screen,
-its contents may be lost.
-The server then sends the client program an
-<systemitem class="event">Expose</systemitem>
-event to notify it that part or all of the window needs to be repainted.
-Programs must be prepared to regenerate the contents of windows on demand.
- </para>
- <para>
-<indexterm><primary>Pixmap</primary></indexterm>
-<indexterm><primary>Drawable</primary></indexterm>
-<indexterm><primary>Tile</primary></indexterm>
-<indexterm><primary>Bitmap</primary></indexterm>
-X also provides off-screen storage of graphics objects,
-called <firstterm linkend="glossary:Pixmap">pixmaps</firstterm>.
-Single plane (depth 1) pixmaps are sometimes referred to as
-<firstterm>bitmaps</firstterm>.
-Pixmaps can be used in most graphics functions interchangeably with
-windows and are used in various graphics operations to define patterns or tiles.
-Windows and pixmaps together are referred to as drawables.
- </para>
- <para>
-Most of the functions in Xlib just add requests to an output buffer.
-These requests later execute asynchronously on the X server.
-Functions that return values of information stored in
-the server do not return (that is, they block)
-until an explicit reply is received or an error occurs.
-You can provide an error handler,
-which will be called when the error is reported.
- </para>
- <para>
-<indexterm><primary>XSync</primary></indexterm>
-If a client does not want a request to execute asynchronously,
-it can follow the request with a call to
-<function>XSync</function>,
-which blocks until all previously buffered
-asynchronous events have been sent and acted on.
-As an important side effect,
-the output buffer in Xlib is always flushed by a call to any function
-that returns a value from the server or waits for input.
- </para>
- <para>
-<indexterm><primary>Resource IDs</primary></indexterm>
-<indexterm><primary>Resource IDs</primary><secondary>Window</secondary></indexterm>
-<indexterm><primary>Resource IDs</primary><secondary>Font</secondary></indexterm>
-<indexterm><primary>Resource IDs</primary><secondary>Pixmap</secondary></indexterm>
-<indexterm><primary>Resource IDs</primary><secondary>Colormap</secondary></indexterm>
-<indexterm><primary>Resource IDs</primary><secondary>Cursor</secondary></indexterm>
-<indexterm><primary>Resource IDs</primary><secondary>GContext</secondary></indexterm>
-Many Xlib functions will return an integer resource ID,
-which allows you to refer to objects stored on the X server.
-These can be of type
-<type>Window</type>,
-<type>Font</type>,
-<type>Pixmap</type>,
-<type>Colormap</type>,
-<type>Cursor</type>,
-and
-<type>GContext</type>,
-as defined in the file
-<filename class="headerfile"><X11/X.h></filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
-These resources are created by requests and are destroyed
-(or freed) by requests or when connections are closed.
-Most of these resources are potentially sharable between
-applications, and in fact, windows are manipulated explicitly by
-window manager programs.
-Fonts and cursors are shared automatically across multiple screens.
-Fonts are loaded and unloaded as needed and are shared by multiple clients.
-Fonts are often cached in the server.
-Xlib provides no support for sharing graphics contexts between applications.
- </para>
- <para>
-<indexterm><primary>Event</primary></indexterm>
-Client programs are informed of events.
-Events may either be side effects of a request (for example, restacking windows
-generates
-<systemitem class="event">Expose</systemitem>
-events) or completely asynchronous (for example, from the keyboard).
-A client program asks to be informed of events.
-Because other applications can send events to your application,
-programs must be prepared to handle (or ignore) events of all types.
- </para>
- <para>
-Input events (for example, a key pressed or the pointer moved)
-arrive asynchronously from the server and are queued until they are
-requested by an explicit call (for example,
-<function>XNextEvent</function>
-or
-<function>XWindowEvent</function>).
-In addition, some library
-functions (for example,
-<function>XRaiseWindow</function>)
-generate
-<symbol>Expose</symbol>
-and
-<symbol>ConfigureRequest</symbol>
-events.
-These events also arrive asynchronously, but the client may
-<indexterm><primary>XSync</primary></indexterm>
-wish to explicitly wait for them by calling
-<function>XSync</function>
-after calling a function that can cause the server to generate events.
- </para>
- </sect1>
-
- <sect1 id="Errors">
- <title>Errors</title>
-
- <para>
-Some functions return
-<type>Status</type>,
-an integer error indication.
-If the function fails, it returns a zero.
-If the function returns a status of zero,
-it has not updated the return arguments.
-<indexterm><primary>Status</primary></indexterm>
-Because C does not provide multiple return values,
-many functions must return their results by writing into client-passed storage.
-<indexterm><primary>Error</primary><secondary>handling</secondary></indexterm>
-By default, errors are handled either by a standard library function
-or by one that you provide.
-Functions that return pointers to strings return NULL pointers if
-the string does not exist.
- </para>
- <para>
-The X server reports protocol errors at the time that it detects them.
-If more than one error could be generated for a given request,
-the server can report any of them.
- </para>
- <para>
-Because Xlib usually does not transmit requests to the server immediately
-(that is, it buffers them), errors can be reported much later than they
-actually occur.
-For debugging purposes, however,
-Xlib provides a mechanism for forcing synchronous behavior
-(see section 11.8.1). <!-- xref -->
-When synchronization is enabled,
-errors are reported as they are generated.
- </para>
- <para>
-When Xlib detects an error,
-it calls an error handler,
-which your program can provide.
-If you do not provide an error handler,
-the error is printed, and your program terminates.
- </para>
- </sect1>
-
- <sect1 id="Standard_Header_Files">
- <title>Standard Header Files</title>
-
- <para>
-The following include files are part of the Xlib standard:
-<indexterm><primary>Headers</primary></indexterm>
-
-<variablelist>
- <varlistentry id="Standard_Header_Files:Xlib.h">
- <term><filename class="headerfile"><X11/Xlib.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/Xlib.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/Xlib.h></secondary></indexterm>
- <para>
-This is the main header file for Xlib.
-The majority of all Xlib symbols are declared by including this file.
-This file also contains the preprocessor symbol
-<symbol>XlibSpecificationRelease</symbol>.
-<indexterm significance="preferred"><primary>XlibSpecificationRelease</primary></indexterm>
-This symbol is defined to have the 6 in this release of the standard.
-(Release 5 of Xlib was the first release to have this symbol.)
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:X.h">
- <term><filename class="headerfile"><X11/X.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/X.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/X.h></secondary></indexterm>
- <para>
-This file declares types and constants for the X protocol that are
-to be used by applications. It is included automatically from
-<filename class="headerfile"><X11/Xlib.h></filename>
-so application code should never need to
-reference this file directly.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:Xcms.h">
- <term><filename class="headerfile"><X11/Xcms.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/Xcms.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/Xcms.h></secondary></indexterm>
- <para>
-This file contains symbols for much of the color management facilities
-described in chapter 6. All functions, types, and symbols with the
-prefix "Xcms", <!-- xref -->
-plus the Color Conversion Contexts macros, are declared in this file.
-<filename class="headerfile"><X11/Xlib.h></filename>
-must be included before including this file.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:Xutil.h">
- <term><filename class="headerfile"><X11/Xutil.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/Xutil.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/Xutil.h></secondary></indexterm>
- <para>
-This file declares various functions, types, and symbols used for
-inter-client communication and application utility functions,
-which are described in chapters 14 and 16. <!-- xref -->
-<filename class="headerfile"><X11/Xlib.h></filename> must be included before including this file.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:Xresource.h">
- <term><filename class="headerfile"><X11/Xresource.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/Xresource.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/Xresource.h></secondary></indexterm>
- <para>
-This file declares all functions, types, and symbols for the
-resource manager facilities, which are described in chapter 15.
-<filename class="headerfile"><X11/Xlib.h></filename> <!-- xref -->
-must be included before including this file.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:Xatom.h">
- <term><filename class="headerfile"><X11/Xatom.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/Xatom.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/Xatom.h></secondary></indexterm>
- <para>
-This file declares all predefined atoms,
-which are symbols with the prefix "XA_".
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:cursorfont.h">
- <term><filename class="headerfile"><X11/cursorfont.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/cursorfont.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/cursorfont.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/cursorfont.h></secondary></indexterm>
- <para>
-This file declares the cursor symbols for the standard cursor font,
-which are listed in <link linkend="x_font_cursors">Appendix B</link>.
-All cursor symbols have the prefix "XC_".
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:keysymdef.h">
- <term><filename class="headerfile"><X11/keysymdef.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/keysymdef.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/keysymdef.h></secondary></indexterm>
- <para>
-This file declares all standard KeySym values,
-which are symbols with the prefix "XK_".
-The KeySyms are arranged in groups, and a preprocessor symbol controls
-inclusion of each group. The preprocessor symbol must be defined
-prior to inclusion of the file to obtain the associated values.
-The preprocessor symbols are
-<symbol>XK_MISCELLANY</symbol>,
-<symbol>XK_XKB_KEYS</symbol>,
-<symbol>XK_3270</symbol>,
-<symbol>XK_LATIN1</symbol>,
-<symbol>XK_LATIN2</symbol>,
-<symbol>XK_LATIN3</symbol>,
-<symbol>XK_LATIN4</symbol>,
-<symbol>XK_KATAKANA</symbol>,
-<symbol>XK_ARABIC</symbol>,
-<symbol>XK_CYRILLIC</symbol>,
-<symbol>XK_GREEK</symbol>,
-<symbol>XK_TECHNICAL</symbol>,
-<symbol>XK_SPECIAL</symbol>,
-<symbol>XK_PUBLISHING</symbol>,
-<symbol>XK_APL</symbol>,
-<symbol>XK_HEBREW</symbol>,
-<symbol>XK_THAI</symbol>, and
-<symbol>XK_KOREAN</symbol>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:keysym.h">
- <term><filename class="headerfile"><X11/keysym.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/keysym.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/keysym.h></secondary></indexterm>
- <para>
-This file defines the preprocessor symbols
-<symbol>XK_MISCELLANY</symbol>,
-<symbol>XK_XKB_KEYS</symbol>,
-<symbol>XK_LATIN1</symbol>,
-<symbol>XK_LATIN2</symbol>,
-<symbol>XK_LATIN3</symbol>,
-<symbol>XK_LATIN4</symbol>, and
-<symbol>XK_GREEK</symbol>
-and then includes <filename class="headerfile"><X11/keysymdef.h></filename>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:Xlibint.h">
- <term><filename class="headerfile"><X11/Xlibint.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/Xlibint.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/Xlibint.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/Xlibint.h></secondary></indexterm>
- <para>
-This file declares all the functions, types, and symbols used for
-extensions, which are described in <link linkend="extensions">Appendix C</link>.
-This file automatically includes
-<filename class="headerfile"><X11/Xlib.h></filename>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:Xproto.h">
- <term><filename class="headerfile"><X11/Xproto.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/Xproto.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/Xproto.h></secondary></indexterm>
- <para>
-This file declares types and symbols for the basic X protocol,
-for use in implementing extensions.
-It is included automatically from
-<filename class="headerfile"><X11/Xlibint.h></filename>,
-so application and extension code should never need to
-reference this file directly.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:Xprotostr.h">
- <term><filename class="headerfile"><X11/Xprotostr.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/Xprotostr.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/Xprotostr.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/Xprotostr.h></secondary></indexterm>
- <para>
-This file declares types and symbols for the basic X protocol,
-for use in implementing extensions.
-It is included automatically from
-<filename class="headerfile"><X11/Xproto.h></filename>,
-so application and extension code should never need to
-reference this file directly.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="Standard_Header_Files:X10.h">
- <term><filename class="headerfile"><X11/X10.h></filename></term>
- <listitem>
- <indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm>
- <indexterm><primary>Files</primary><secondary><X11/X10.h></secondary></indexterm>
- <indexterm><primary>Headers</primary><secondary><X11/X10.h></secondary></indexterm>
- <para>
-This file declares all the functions, types, and symbols used for the
-X10 compatibility functions, which are described in
-<link linkend="X_Version_10_Compatibility_Functions">Appendix D</link>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
- </para>
- </sect1>
-
- <sect1 id="Generic_Values_and_Types">
- <title>Generic Values and Types</title>
-
- <para>
-The following symbols are defined by Xlib and used throughout the manual:
-<itemizedlist>
- <listitem>
- <para>
-<indexterm significance="preferred"><primary>Bool</primary></indexterm>
-<indexterm significance="preferred"><primary>True</primary></indexterm>
-<indexterm significance="preferred"><primary>False</primary></indexterm>
-Xlib defines the type
-<type>Bool</type>
-and the Boolean values
-<symbol>True</symbol>
-and
-<symbol>False</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-<indexterm significance="preferred"><primary>None</primary></indexterm>
-<symbol>None</symbol>
-is the universal null resource ID or atom.
- </para>
- </listitem>
- <listitem>
- <para>
-<indexterm significance="preferred"><primary>XID</primary></indexterm>
-The type
-<type>XID</type>
-is used for generic resource IDs.
- </para>
- </listitem>
- <listitem>
- <para>
-<indexterm significance="preferred"><primary>XPointer</primary></indexterm>
-The type <type>XPointer</type> is defined to be <type>char *</type>
-and is used as a generic opaque pointer to data.
- </para>
- </listitem>
-</itemizedlist>
- </para>
- </sect1>
-
- <sect1 id="Naming_and_Argument_Conventions_within_Xlib">
- <title>Naming and Argument Conventions within Xlib</title>
-
- <para>
-Xlib follows a number of conventions for the naming and syntax of the functions.
-Given that you remember what information the function requires,
-these conventions are intended to make the syntax of the functions more
-predictable.
- </para>
- <para>
-The major naming conventions are:
-<itemizedlist>
- <listitem>
- <para>
-To differentiate the X symbols from the other symbols,
-the library uses mixed case for external symbols.
-It leaves lowercase for variables and all uppercase for user macros,
-as per existing convention.
- </para>
- </listitem>
- <listitem>
- <para>
-All Xlib functions begin with a capital X.
- </para>
- </listitem>
- <listitem>
- <para>
-The beginnings of all function names and symbols are capitalized.
- </para>
- </listitem>
- <listitem>
- <para>
-All user-visible data structures begin with a capital X.
-More generally,
-anything that a user might dereference begins with a capital X.
- </para>
- </listitem>
- <listitem>
- <para>
-Macros and other symbols do not begin with a capital X.
-To distinguish them from all user symbols,
-each word in the macro is capitalized.
- </para>
- </listitem>
- <listitem>
- <para>
-All elements of or variables in a data structure are in lowercase.
-Compound words, where needed, are constructed with underscores (_).
- </para>
- </listitem>
- <listitem>
- <para>
-The display argument, where used, is always first in the argument list.
- </para>
- </listitem>
- <listitem>
- <para>
-All resource objects, where used, occur at the beginning of the argument list
-immediately after the display argument.
- </para>
- </listitem>
- <listitem>
- <para>
-When a graphics context is present together with
-another type of resource (most commonly, a drawable), the
-graphics context occurs in the argument list after the other
-resource.
-Drawables outrank all other resources.
- </para>
- </listitem>
- <listitem>
- <para>
-Source arguments always precede the destination arguments in the argument list.
- </para>
- </listitem>
- <listitem>
- <para>
-The x argument always precedes the y argument in the argument list.
- </para>
- </listitem>
- <listitem>
- <para>
-The width argument always precedes the height argument in the argument list.
- </para>
- </listitem>
- <listitem>
- <para>
-Where the x, y, width, and height arguments are used together,
-the x and y arguments always precede the width and height arguments.
- </para>
- </listitem>
- <listitem>
- <para>
-Where a mask is accompanied with a structure,
-the mask always precedes the pointer to the structure in the argument list.
- </para>
- </listitem>
-</itemizedlist>
- </para>
- </sect1>
-
- <sect1 id="Programming_Considerations">
- <title>Programming Considerations</title>
-
- <para>
-The major programming considerations are:
-<itemizedlist>
- <listitem>
- <para>
-Coordinates and sizes in X are actually 16-bit quantities.
-This decision was made to minimize the bandwidth required for a
-given level of performance.
-Coordinates usually are declared as an
-<type>int</type>
-in the interface.
-Values larger than 16 bits are truncated silently.
-Sizes (width and height) are declared as unsigned quantities.
- </para>
- </listitem>
- <listitem>
- <para>
-Keyboards are the greatest variable between different
-manufacturers' workstations.
-If you want your program to be portable,
-you should be particularly conservative here.
- </para>
- </listitem>
- <listitem>
- <para>
-Many display systems have limited amounts of off-screen memory.
-If you can, you should minimize use of pixmaps and backing
-store.
- </para>
- </listitem>
- <listitem>
- <para>
-The user should have control of his screen real estate.
-Therefore, you should write your applications to react to window management
-rather than presume control of the entire screen.
-What you do inside of your top-level window, however,
-is up to your application.
-For further information,
-see chapter 14 <!-- xref -->
-and the <citetitle>Inter-Client Communication Conventions Manual</citetitle>.
- </para>
- </listitem>
-</itemizedlist>
- </para>
- </sect1>
-
- <sect1 id="Character_Sets_and_Encodings">
- <title>Character Sets and Encodings</title>
-
- <para>
-Some of the Xlib functions make reference to specific character sets
-and character encodings.
-The following are the most common:
-
-<variablelist>
- <varlistentry>
- <term><firstterm>X Portable Character Set</firstterm></term>
- <listitem><para>
-A basic set of 97 characters,
-which are assumed to exist in all locales supported by Xlib.
-This set contains the following characters:
-<literallayout>
-a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>, and <newline>
-</literallayout>
- </para>
- <para>
-This set is the left/lower half
-of the graphic character set of ISO8859-1 plus space, tab, and newline.
-It is also the set of graphic characters in 7-bit ASCII plus the same
-three control characters.
-The actual encoding of these characters on the host is system dependent.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><firstterm>Host Portable Character Encoding</firstterm></term>
- <listitem>
- <para>
-The encoding of the X Portable Character Set on the host.
-The encoding itself is not defined by this standard,
-but the encoding must be the same in all locales supported by Xlib on the host.
-If a string is said to be in the Host Portable Character Encoding,
-then it only contains characters from the X Portable Character Set,
-in the host encoding.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><firstterm>Latin-1</firstterm></term>
- <listitem>
- <para>
-The coded character set defined by the ISO8859-1 standard.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><firstterm>Latin Portable Character Encoding</firstterm></term>
- <listitem>
- <para>
-The encoding of the X Portable Character Set using the Latin-1 codepoints
-plus ASCII control characters.
-If a string is said to be in the Latin Portable Character Encoding,
-then it only contains characters from the X Portable Character Set,
-not all of Latin-1.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><firstterm>STRING Encoding</firstterm></term>
- <listitem>
- <para>
-Latin-1, plus tab and newline.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><firstterm><acronym>POSIX</acronym> Portable Filename Character Set</firstterm></term>
- <listitem>
- <para>
-The set of 65 characters,
-which can be used in naming files on a <acronym>POSIX</acronym>-compliant host,
-that are correctly processed in all locales.
-The set is:
-<literallayout>
-a..z A..Z 0..9 ._-
-</literallayout>
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
- </para>
- </sect1>
-
- <sect1 id="Formatting_Conventions">
- <title>Formatting Conventions</title>
-
- <para>
- <citetitle>Xlib − C Language X Interface</citetitle> uses the
- following conventions:
-
- <itemizedlist>
- <listitem>
- <para>
-Global symbols are printed in
-<function>this</function>
-<function>special</function>
-<function>font</function>.
-These can be either function names,
-symbols defined in include files, or structure names.
-When declared and defined,
-function arguments are printed in <emphasis remap='I'>italics</emphasis>.
-In the explanatory text that follows,
-they usually are printed in regular type.
- </para>
- </listitem>
- <listitem>
- <para>
-Each function is introduced by a general discussion that
-distinguishes it from other functions.
-The function declaration itself follows,
-and each argument is specifically explained.
-Although ANSI C function prototype syntax is not used,
-Xlib header files normally declare functions using function prototypes
-in ANSI C environments.
-General discussion of the function, if any is required,
-follows the arguments.
-Where applicable,
-the last paragraph of the explanation lists the possible
-Xlib error codes that the function can generate.
-For a complete discussion of the Xlib error codes,
-see section 11.8.2. <!-- xref -->
- </para>
- </listitem>
- <listitem>
- <para>
-To eliminate any ambiguity between those arguments that you pass and those that
-a function returns to you,
-the explanations for all arguments that you pass start with the word
-<emphasis remap='I'>specifies</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>specify</emphasis>.
-The explanations for all arguments that are returned to you start with the
-word <emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>return</emphasis>.
-The explanations for all arguments that you can pass and are returned start
-with the words <emphasis remap='I'>specifies and returns</emphasis>.
- </para>
- </listitem>
- <listitem>
- <para>
-Any pointer to a structure that is used to return a value is designated as
-such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name.
-All other pointers passed to these functions are
-used for reading only.
-A few arguments use pointers to structures that are used for
-both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis> suffix.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </sect1>
-</chapter>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<chapter id="Introduction_to_Xlib"><title>Introduction to Xlib</title> + + <para> +The X Window System is a network-transparent window system that was +designed at MIT. X display servers run on computers with either +monochrome or color bitmap display hardware. The server distributes +user input to and accepts output requests from various client programs +located either on the same machine or elsewhere in the network. Xlib +is a C subroutine library that application programs (clients) use to +interface with the window system by means of a stream connection. +Although a client usually runs on the same machine as the X server +it is talking to, this need not be the case. + </para> + <para> +<citetitle>Xlib − C Language X Interface</citetitle> is a reference +guide to the low-level C language interface to the X Window System +protocol. It is neither a tutorial nor a user’s guide to programming +the X Window System. Rather, it provides a detailed description of +each function in the library as well as a discussion of the related +background information. <citetitle>Xlib − C Language X Interface</citetitle> +assumes a basic understanding of a graphics window system and of the C +programming language. Other higher-level abstractions (for example, +those provided by the toolkits for X) are built on top of the Xlib +library. For further information about these higher-level libraries, +see the appropriate toolkit documentation. +The <citetitle>X Window System Protocol</citetitle> provides the +definitive word on the behavior of X. +Although additional information appears here, the protocol document is +the ruling document. + </para> + <para> +To provide an introduction to X programming, this chapter discusses: + + <itemizedlist> + <listitem><para><link linkend="Overview_of_the_X_Window_System">Overview of the X Window System</link></para></listitem> + <listitem><para><link linkend="Errors">Errors</link></para></listitem> + <listitem><para><link linkend="Standard_Header_Files">Standard header files</link></para></listitem> + <listitem><para><link linkend="Generic_Values_and_Types">Generic values and types</link></para></listitem> + <listitem><para><link linkend="Naming_and_Argument_Conventions_within_Xlib">Naming and argument conventions within Xlib</link></para></listitem> + <listitem><para><link linkend="Programming_Considerations">Programming considerations</link></para></listitem> + <listitem><para><link linkend="Character_Sets_and_Encodings">Character sets and encodings</link></para></listitem> + <listitem><para><link linkend="Formatting_Conventions">Formatting conventions</link></para></listitem> + </itemizedlist> + </para> + + <sect1 id="Overview_of_the_X_Window_System"> + <title>Overview of the X Window System</title> + <para> +Some of the terms used in this book are unique to X, +and other terms that are common to other window systems +have different meanings in X. You may find it helpful to refer to +<link linkend="glossary">the glossary</link>, +which is located at the end of the book. + </para> + <para> +The X Window System supports one or more screens containing +overlapping windows or subwindows. +<indexterm><primary>Screen</primary></indexterm> +A <firstterm>screen</firstterm> is a physical monitor and hardware +that can be color, grayscale, or monochrome. +There can be multiple screens for each display or workstation. +A single X server can provide display services for any number of screens. +A set of screens for a single user with one keyboard and one pointer +(usually a mouse) is called a <firstterm>display</firstterm>. + </para> + <para> +All the windows in an X server are arranged in strict hierarchies. +At the top of each hierarchy is a <firstterm>root window</firstterm>, +which covers each of the display screens. +Each root window is partially or completely covered by child windows. +All windows, except for root windows, have parents. +There is usually at least one window for each application program. +<indexterm><primary>Child window</primary></indexterm> +<indexterm><primary>Parent Window</primary></indexterm> +Child windows may in turn have their own children. +In this way, +an application program can create an arbitrarily deep tree +on each screen. +X provides graphics, text, and raster operations for windows. + </para> + <para> +A child window can be larger than its parent. +That is, part or all of +the child window can extend beyond the boundaries of the parent, +but all output to a window is clipped by its parent. +<indexterm><primary>Stacking order</primary></indexterm> +If several children of a window have overlapping locations, +one of the children is considered to be on top of or raised over the +others, thus obscuring them. +Output to areas covered by other windows is suppressed by the window +system unless the window has backing store. +If a window is obscured by a second window, +the second window obscures only those ancestors of the second window +that are also ancestors of the first window. + </para> + <para> +<indexterm significance="preferred"><primary>Window</primary></indexterm> +A window has a border zero or more pixels in width, which can +be any pattern (pixmap) or solid color you like. +A window usually but not always has a background pattern, +which will be repainted by the window system when uncovered. +Child windows obscure their parents, +and graphic operations in the parent window usually +are clipped by the children. + </para> + <para> +Each window and pixmap has its own coordinate system. +The coordinate system has the X axis horizontal and the Y axis vertical +with the origin [0, 0] at the upper-left corner. +Coordinates are integral, +in terms of pixels, +and coincide with pixel centers. +For a window, +the origin is inside the border at the inside, upper-left corner. + </para> + <para> +X does not guarantee to preserve the contents of windows. +When part or all of a window is hidden and then brought back onto the screen, +its contents may be lost. +The server then sends the client program an +<systemitem class="event">Expose</systemitem> +event to notify it that part or all of the window needs to be repainted. +Programs must be prepared to regenerate the contents of windows on demand. + </para> + <para> +<indexterm><primary>Pixmap</primary></indexterm> +<indexterm><primary>Drawable</primary></indexterm> +<indexterm><primary>Tile</primary></indexterm> +<indexterm><primary>Bitmap</primary></indexterm> +X also provides off-screen storage of graphics objects, +called <firstterm linkend="glossary:Pixmap">pixmaps</firstterm>. +Single plane (depth 1) pixmaps are sometimes referred to as +<firstterm>bitmaps</firstterm>. +Pixmaps can be used in most graphics functions interchangeably with +windows and are used in various graphics operations to define patterns or tiles. +Windows and pixmaps together are referred to as drawables. + </para> + <para> +Most of the functions in Xlib just add requests to an output buffer. +These requests later execute asynchronously on the X server. +Functions that return values of information stored in +the server do not return (that is, they block) +until an explicit reply is received or an error occurs. +You can provide an error handler, +which will be called when the error is reported. + </para> + <para> +<indexterm><primary>XSync</primary></indexterm> +If a client does not want a request to execute asynchronously, +it can follow the request with a call to +<function>XSync</function>, +which blocks until all previously buffered +asynchronous events have been sent and acted on. +As an important side effect, +the output buffer in Xlib is always flushed by a call to any function +that returns a value from the server or waits for input. + </para> + <para> +<indexterm><primary>Resource IDs</primary></indexterm> +<indexterm><primary>Resource IDs</primary><secondary>Window</secondary></indexterm> +<indexterm><primary>Resource IDs</primary><secondary>Font</secondary></indexterm> +<indexterm><primary>Resource IDs</primary><secondary>Pixmap</secondary></indexterm> +<indexterm><primary>Resource IDs</primary><secondary>Colormap</secondary></indexterm> +<indexterm><primary>Resource IDs</primary><secondary>Cursor</secondary></indexterm> +<indexterm><primary>Resource IDs</primary><secondary>GContext</secondary></indexterm> +Many Xlib functions will return an integer resource ID, +which allows you to refer to objects stored on the X server. +These can be of type +<type>Window</type>, +<type>Font</type>, +<type>Pixmap</type>, +<type>Colormap</type>, +<type>Cursor</type>, +and +<type>GContext</type>, +as defined in the file +<filename class="headerfile"><X11/X.h></filename>. +<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm> +These resources are created by requests and are destroyed +(or freed) by requests or when connections are closed. +Most of these resources are potentially sharable between +applications, and in fact, windows are manipulated explicitly by +window manager programs. +Fonts and cursors are shared automatically across multiple screens. +Fonts are loaded and unloaded as needed and are shared by multiple clients. +Fonts are often cached in the server. +Xlib provides no support for sharing graphics contexts between applications. + </para> + <para> +<indexterm><primary>Event</primary></indexterm> +Client programs are informed of events. +Events may either be side effects of a request (for example, restacking windows +generates +<systemitem class="event">Expose</systemitem> +events) or completely asynchronous (for example, from the keyboard). +A client program asks to be informed of events. +Because other applications can send events to your application, +programs must be prepared to handle (or ignore) events of all types. + </para> + <para> +Input events (for example, a key pressed or the pointer moved) +arrive asynchronously from the server and are queued until they are +requested by an explicit call (for example, +<function>XNextEvent</function> +or +<function>XWindowEvent</function>). +In addition, some library +functions (for example, +<function>XRaiseWindow</function>) +generate +<symbol>Expose</symbol> +and +<symbol>ConfigureRequest</symbol> +events. +These events also arrive asynchronously, but the client may +<indexterm><primary>XSync</primary></indexterm> +wish to explicitly wait for them by calling +<function>XSync</function> +after calling a function that can cause the server to generate events. + </para> + </sect1> + + <sect1 id="Errors"> + <title>Errors</title> + + <para> +Some functions return +<type>Status</type>, +an integer error indication. +If the function fails, it returns a zero. +If the function returns a status of zero, +it has not updated the return arguments. +<indexterm><primary>Status</primary></indexterm> +Because C does not provide multiple return values, +many functions must return their results by writing into client-passed storage. +<indexterm><primary>Error</primary><secondary>handling</secondary></indexterm> +By default, errors are handled either by a standard library function +or by one that you provide. +Functions that return pointers to strings return NULL pointers if +the string does not exist. + </para> + <para> +The X server reports protocol errors at the time that it detects them. +If more than one error could be generated for a given request, +the server can report any of them. + </para> + <para> +Because Xlib usually does not transmit requests to the server immediately +(that is, it buffers them), errors can be reported much later than they +actually occur. +For debugging purposes, however, +Xlib provides a mechanism for forcing synchronous behavior +(see <link linkend="Enabling_or_Disabling_Synchronization">section 11.8.1</link>). +When synchronization is enabled, +errors are reported as they are generated. + </para> + <para> +When Xlib detects an error, +it calls an error handler, +which your program can provide. +If you do not provide an error handler, +the error is printed, and your program terminates. + </para> + </sect1> + + <sect1 id="Standard_Header_Files"> + <title>Standard Header Files</title> + + <para> +The following include files are part of the Xlib standard: +<indexterm><primary>Headers</primary></indexterm> + +<variablelist> + <varlistentry id="Standard_Header_Files:Xlib.h"> + <term><filename class="headerfile"><X11/Xlib.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/Xlib.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/Xlib.h></secondary></indexterm> + <para> +This is the main header file for Xlib. +The majority of all Xlib symbols are declared by including this file. +This file also contains the preprocessor symbol +<symbol>XlibSpecificationRelease</symbol>. +<indexterm significance="preferred"><primary>XlibSpecificationRelease</primary></indexterm> +This symbol is defined to have the 6 in this release of the standard. +(Release 5 of Xlib was the first release to have this symbol.) + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:X.h"> + <term><filename class="headerfile"><X11/X.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/X.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/X.h></secondary></indexterm> + <para> +This file declares types and constants for the X protocol that are +to be used by applications. It is included automatically from +<filename class="headerfile"><X11/Xlib.h></filename> +so application code should never need to +reference this file directly. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:Xcms.h"> + <term><filename class="headerfile"><X11/Xcms.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/Xcms.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/Xcms.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/Xcms.h></secondary></indexterm> + <para> +This file contains symbols for much of the color management facilities +described in <link linkend="color_management_functions">chapter 6</link>. +All functions, types, and symbols with the prefix "Xcms", +plus the Color Conversion Contexts macros, are declared in this file. +<filename class="headerfile"><X11/Xlib.h></filename> +must be included before including this file. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:Xutil.h"> + <term><filename class="headerfile"><X11/Xutil.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/Xutil.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/Xutil.h></secondary></indexterm> + <para> +This file declares various functions, types, and symbols used for +inter-client communication and application utility functions, +which are described in chapters +<link linkend="inter_client_communication_functions">14</link> and +<link linkend="application_utility_functions">16</link>. +<filename class="headerfile"><X11/Xlib.h></filename> must be included before including this file. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:Xresource.h"> + <term><filename class="headerfile"><X11/Xresource.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/Xresource.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/Xresource.h></secondary></indexterm> + <para> +This file declares all functions, types, and symbols for the +resource manager facilities, which are described in +<link linkend="resource_manager_functions">chapter 15</link>. +<filename class="headerfile"><X11/Xlib.h></filename> <!-- xref --> +must be included before including this file. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:Xatom.h"> + <term><filename class="headerfile"><X11/Xatom.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/Xatom.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/Xatom.h></secondary></indexterm> + <para> +This file declares all predefined atoms, +which are symbols with the prefix "XA_". + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:cursorfont.h"> + <term><filename class="headerfile"><X11/cursorfont.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/cursorfont.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/cursorfont.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/cursorfont.h></secondary></indexterm> + <para> +This file declares the cursor symbols for the standard cursor font, +which are listed in <link linkend="x_font_cursors">Appendix B</link>. +All cursor symbols have the prefix "XC_". + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:keysymdef.h"> + <term><filename class="headerfile"><X11/keysymdef.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/keysymdef.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/keysymdef.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/keysymdef.h></secondary></indexterm> + <para> +This file declares all standard KeySym values, +which are symbols with the prefix "XK_". +The KeySyms are arranged in groups, and a preprocessor symbol controls +inclusion of each group. The preprocessor symbol must be defined +prior to inclusion of the file to obtain the associated values. +The preprocessor symbols are +<symbol>XK_MISCELLANY</symbol>, +<symbol>XK_XKB_KEYS</symbol>, +<symbol>XK_3270</symbol>, +<symbol>XK_LATIN1</symbol>, +<symbol>XK_LATIN2</symbol>, +<symbol>XK_LATIN3</symbol>, +<symbol>XK_LATIN4</symbol>, +<symbol>XK_KATAKANA</symbol>, +<symbol>XK_ARABIC</symbol>, +<symbol>XK_CYRILLIC</symbol>, +<symbol>XK_GREEK</symbol>, +<symbol>XK_TECHNICAL</symbol>, +<symbol>XK_SPECIAL</symbol>, +<symbol>XK_PUBLISHING</symbol>, +<symbol>XK_APL</symbol>, +<symbol>XK_HEBREW</symbol>, +<symbol>XK_THAI</symbol>, and +<symbol>XK_KOREAN</symbol>. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:keysym.h"> + <term><filename class="headerfile"><X11/keysym.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/keysym.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/keysym.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/keysym.h></secondary></indexterm> + <para> +This file defines the preprocessor symbols +<symbol>XK_MISCELLANY</symbol>, +<symbol>XK_XKB_KEYS</symbol>, +<symbol>XK_LATIN1</symbol>, +<symbol>XK_LATIN2</symbol>, +<symbol>XK_LATIN3</symbol>, +<symbol>XK_LATIN4</symbol>, and +<symbol>XK_GREEK</symbol> +and then includes <filename class="headerfile"><X11/keysymdef.h></filename>. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:Xlibint.h"> + <term><filename class="headerfile"><X11/Xlibint.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/Xlibint.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/Xlibint.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/Xlibint.h></secondary></indexterm> + <para> +This file declares all the functions, types, and symbols used for +extensions, which are described in <link linkend="extensions">Appendix C</link>. +This file automatically includes +<filename class="headerfile"><X11/Xlib.h></filename>. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:Xproto.h"> + <term><filename class="headerfile"><X11/Xproto.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/Xproto.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/Xproto.h></secondary></indexterm> + <para> +This file declares types and symbols for the basic X protocol, +for use in implementing extensions. +It is included automatically from +<filename class="headerfile"><X11/Xlibint.h></filename>, +so application and extension code should never need to +reference this file directly. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:Xprotostr.h"> + <term><filename class="headerfile"><X11/Xprotostr.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/Xprotostr.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/Xprotostr.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/Xprotostr.h></secondary></indexterm> + <para> +This file declares types and symbols for the basic X protocol, +for use in implementing extensions. +It is included automatically from +<filename class="headerfile"><X11/Xproto.h></filename>, +so application and extension code should never need to +reference this file directly. + </para> + </listitem> + </varlistentry> + <varlistentry id="Standard_Header_Files:X10.h"> + <term><filename class="headerfile"><X11/X10.h></filename></term> + <listitem> + <indexterm type="file"><primary><filename class="headerfile">X11/X10.h</filename></primary></indexterm> + <indexterm><primary>Files</primary><secondary><X11/X10.h></secondary></indexterm> + <indexterm><primary>Headers</primary><secondary><X11/X10.h></secondary></indexterm> + <para> +This file declares all the functions, types, and symbols used for the +X10 compatibility functions, which are described in +<link linkend="X_Version_10_Compatibility_Functions">Appendix D</link>. + </para> + </listitem> + </varlistentry> +</variablelist> + </para> + </sect1> + + <sect1 id="Generic_Values_and_Types"> + <title>Generic Values and Types</title> + + <para> +The following symbols are defined by Xlib and used throughout the manual: +<itemizedlist> + <listitem> + <para> +<indexterm significance="preferred"><primary>Bool</primary></indexterm> +<indexterm significance="preferred"><primary>True</primary></indexterm> +<indexterm significance="preferred"><primary>False</primary></indexterm> +Xlib defines the type +<type>Bool</type> +and the Boolean values +<symbol>True</symbol> +and +<symbol>False</symbol>. + </para> + </listitem> + <listitem> + <para> +<indexterm significance="preferred"><primary>None</primary></indexterm> +<symbol>None</symbol> +is the universal null resource ID or atom. + </para> + </listitem> + <listitem> + <para> +<indexterm significance="preferred"><primary>XID</primary></indexterm> +The type +<type>XID</type> +is used for generic resource IDs. + </para> + </listitem> + <listitem> + <para> +<indexterm significance="preferred"><primary>XPointer</primary></indexterm> +The type <type>XPointer</type> is defined to be <type>char *</type> +and is used as a generic opaque pointer to data. + </para> + </listitem> +</itemizedlist> + </para> + </sect1> + + <sect1 id="Naming_and_Argument_Conventions_within_Xlib"> + <title>Naming and Argument Conventions within Xlib</title> + + <para> +Xlib follows a number of conventions for the naming and syntax of the functions. +Given that you remember what information the function requires, +these conventions are intended to make the syntax of the functions more +predictable. + </para> + <para> +The major naming conventions are: +<itemizedlist> + <listitem> + <para> +To differentiate the X symbols from the other symbols, +the library uses mixed case for external symbols. +It leaves lowercase for variables and all uppercase for user macros, +as per existing convention. + </para> + </listitem> + <listitem> + <para> +All Xlib functions begin with a capital X. + </para> + </listitem> + <listitem> + <para> +The beginnings of all function names and symbols are capitalized. + </para> + </listitem> + <listitem> + <para> +All user-visible data structures begin with a capital X. +More generally, +anything that a user might dereference begins with a capital X. + </para> + </listitem> + <listitem> + <para> +Macros and other symbols do not begin with a capital X. +To distinguish them from all user symbols, +each word in the macro is capitalized. + </para> + </listitem> + <listitem> + <para> +All elements of or variables in a data structure are in lowercase. +Compound words, where needed, are constructed with underscores (_). + </para> + </listitem> + <listitem> + <para> +The display argument, where used, is always first in the argument list. + </para> + </listitem> + <listitem> + <para> +All resource objects, where used, occur at the beginning of the argument list +immediately after the display argument. + </para> + </listitem> + <listitem> + <para> +When a graphics context is present together with +another type of resource (most commonly, a drawable), the +graphics context occurs in the argument list after the other +resource. +Drawables outrank all other resources. + </para> + </listitem> + <listitem> + <para> +Source arguments always precede the destination arguments in the argument list. + </para> + </listitem> + <listitem> + <para> +The x argument always precedes the y argument in the argument list. + </para> + </listitem> + <listitem> + <para> +The width argument always precedes the height argument in the argument list. + </para> + </listitem> + <listitem> + <para> +Where the x, y, width, and height arguments are used together, +the x and y arguments always precede the width and height arguments. + </para> + </listitem> + <listitem> + <para> +Where a mask is accompanied with a structure, +the mask always precedes the pointer to the structure in the argument list. + </para> + </listitem> +</itemizedlist> + </para> + </sect1> + + <sect1 id="Programming_Considerations"> + <title>Programming Considerations</title> + + <para> +The major programming considerations are: +<itemizedlist> + <listitem> + <para> +Coordinates and sizes in X are actually 16-bit quantities. +This decision was made to minimize the bandwidth required for a +given level of performance. +Coordinates usually are declared as an +<type>int</type> +in the interface. +Values larger than 16 bits are truncated silently. +Sizes (width and height) are declared as unsigned quantities. + </para> + </listitem> + <listitem> + <para> +Keyboards are the greatest variable between different +manufacturers' workstations. +If you want your program to be portable, +you should be particularly conservative here. + </para> + </listitem> + <listitem> + <para> +Many display systems have limited amounts of off-screen memory. +If you can, you should minimize use of pixmaps and backing +store. + </para> + </listitem> + <listitem> + <para> +The user should have control of his screen real estate. +Therefore, you should write your applications to react to window management +rather than presume control of the entire screen. +What you do inside of your top-level window, however, +is up to your application. +For further information, +see <link linkend="inter_client_communication_functions">chapter 14</link> +and the <citetitle>Inter-Client Communication Conventions Manual</citetitle>. + </para> + </listitem> +</itemizedlist> + </para> + </sect1> + + <sect1 id="Character_Sets_and_Encodings"> + <title>Character Sets and Encodings</title> + + <para> +Some of the Xlib functions make reference to specific character sets +and character encodings. +The following are the most common: + +<variablelist> + <varlistentry> + <term><firstterm>X Portable Character Set</firstterm></term> + <listitem><para> +A basic set of 97 characters, +which are assumed to exist in all locales supported by Xlib. +This set contains the following characters: +<literallayout> +a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>, and <newline> +</literallayout> + </para> + <para> +This set is the left/lower half +of the graphic character set of ISO8859-1 plus space, tab, and newline. +It is also the set of graphic characters in 7-bit ASCII plus the same +three control characters. +The actual encoding of these characters on the host is system dependent. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><firstterm>Host Portable Character Encoding</firstterm></term> + <listitem> + <para> +The encoding of the X Portable Character Set on the host. +The encoding itself is not defined by this standard, +but the encoding must be the same in all locales supported by Xlib on the host. +If a string is said to be in the Host Portable Character Encoding, +then it only contains characters from the X Portable Character Set, +in the host encoding. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><firstterm>Latin-1</firstterm></term> + <listitem> + <para> +The coded character set defined by the ISO8859-1 standard. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><firstterm>Latin Portable Character Encoding</firstterm></term> + <listitem> + <para> +The encoding of the X Portable Character Set using the Latin-1 codepoints +plus ASCII control characters. +If a string is said to be in the Latin Portable Character Encoding, +then it only contains characters from the X Portable Character Set, +not all of Latin-1. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><firstterm>STRING Encoding</firstterm></term> + <listitem> + <para> +Latin-1, plus tab and newline. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><firstterm><acronym>POSIX</acronym> Portable Filename Character Set</firstterm></term> + <listitem> + <para> +The set of 65 characters, +which can be used in naming files on a <acronym>POSIX</acronym>-compliant host, +that are correctly processed in all locales. +The set is: +<literallayout> +a..z A..Z 0..9 ._- +</literallayout> + </para> + </listitem> + </varlistentry> +</variablelist> + </para> + </sect1> + + <sect1 id="Formatting_Conventions"> + <title>Formatting Conventions</title> + + <para> + <citetitle>Xlib − C Language X Interface</citetitle> uses the + following conventions: + + <itemizedlist> + <listitem> + <para> +Global symbols are printed in +<function>this</function> +<function>special</function> +<function>font</function>. +These can be either function names, +symbols defined in include files, or structure names. +When declared and defined, +function arguments are printed in <emphasis remap='I'>italics</emphasis>. +In the explanatory text that follows, +they usually are printed in regular type. + </para> + </listitem> + <listitem> + <para> +Each function is introduced by a general discussion that +distinguishes it from other functions. +The function declaration itself follows, +and each argument is specifically explained. +Although ANSI C function prototype syntax is not used, +Xlib header files normally declare functions using function prototypes +in ANSI C environments. +General discussion of the function, if any is required, +follows the arguments. +Where applicable, +the last paragraph of the explanation lists the possible +Xlib error codes that the function can generate. +For a complete discussion of the Xlib error codes, +see <link linkend="Using_the_Default_Error_Handlers">section 11.8.2</link>. + </para> + </listitem> + <listitem> + <para> +To eliminate any ambiguity between those arguments that you pass and those that +a function returns to you, +the explanations for all arguments that you pass start with the word +<emphasis remap='I'>specifies</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>specify</emphasis>. +The explanations for all arguments that are returned to you start with the +word <emphasis remap='I'>returns</emphasis> or, in the case of multiple arguments, the word <emphasis remap='I'>return</emphasis>. +The explanations for all arguments that you can pass and are returned start +with the words <emphasis remap='I'>specifies and returns</emphasis>. + </para> + </listitem> + <listitem> + <para> +Any pointer to a structure that is used to return a value is designated as +such by the <emphasis remap='I'>_return</emphasis> suffix as part of its name. +All other pointers passed to these functions are +used for reading only. +A few arguments use pointers to structures that are used for +both input and output and are indicated by using the <emphasis remap='I'>_in_out</emphasis> suffix. + </para> + </listitem> + </itemizedlist> + </para> + </sect1> +</chapter> diff --git a/libX11/specs/libX11/CH02.xml b/libX11/specs/libX11/CH02.xml index 901a38503..4a57266bd 100644 --- a/libX11/specs/libX11/CH02.xml +++ b/libX11/specs/libX11/CH02.xml @@ -158,7 +158,8 @@ using the <function>DefaultScreen</function> macro or the <function>XDefaultScreen</function> -function if you are using languages other than C (see section 2.2.1). +function if you are using languages other than C +(see <link linkend="Display_Macros_">section 2.2.1</link>). </para> </listitem> </varlistentry> @@ -242,12 +243,12 @@ For information about using macros and functions to obtain information from the <type>Display</type> structure, -see section 2.2.1. +see <link linkend="Display_Macros_">section 2.2.1</link>. </para> <para> <!-- .LP --> X servers may implement various types of access control mechanisms -(see section 9.8). +(see <link linkend="Controlling_Host_Access">section 9.8</link>). </para> </sect1> <sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens"> @@ -886,7 +887,7 @@ Specifies the appropriate screen number on the host server. <indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm> Both return the default visual type for the specified screen. For further information about visual types, -see section 3.1. +see <link linkend="Visual_Types">section 3.1</link>. </para> <para> <!-- .LP --> @@ -1476,7 +1477,9 @@ Applications are required to present data to the X server in a format that the server demands. To help simplify applications, most of the work required to convert the data is provided by Xlib -(see sections 8.7 and 16.8). +(see sections +<link linkend="Transferring_Images_between_Client_and_Server">8.7</link> and +<link linkend="Manipulating_Images">16.8</link>). </para> <para> <!-- .LP --> @@ -2166,7 +2169,7 @@ structure. <indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm> Both return the default visual of the specified screen. For information on visual types, -see section 3.1. +see <link linkend="Visual_Types">section 3.1</link>. </para> <para> <!-- .LP --> @@ -2209,7 +2212,7 @@ The value returned can be one of <symbol>NotUseful</symbol>, or <symbol>Always</symbol> -(see section 3.2.4). +(see <link linkend="Backing_Store_Attribute">section 3.2.4</link>). </para> <para> <!-- .LP --> @@ -2252,7 +2255,8 @@ If the screen supports save unders. If <symbol>False</symbol>, -the screen does not support save unders (see section 3.2.5). +the screen does not support save unders +(see <link linkend="Save_Under_Flag">section 3.2.5</link>). </para> <para> <!-- .LP --> @@ -2543,7 +2547,8 @@ structure. <indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm> <indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm> Both return the maximum number of installed colormaps supported -by the specified screen (see section 9.3). +by the specified screen +(see <link linkend="Managing_Installed_Colormaps">section 9.3</link>). </para> <para> <!-- .LP --> @@ -2580,7 +2585,8 @@ structure. <indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm> <indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm> Both return the minimum number of installed colormaps supported -by the specified screen (see section 9.3). +by the specified screen +(see <link linkend="Managing_Installed_Colormaps">section 9.3</link>). </para> <para> <!-- .LP --> @@ -2871,7 +2877,7 @@ close_mode argument is <symbol>RetainPermanent</symbol> or <symbol>RetainTemporary</symbol>, -see section 2.6. +see <link linkend="Using_X_Server_Connection_Close_Operations_">section 2.6</link>. </para> <para> <!-- .LP --> @@ -3020,7 +3026,8 @@ It deletes all but the predefined atom identifiers. </listitem> <listitem> <para> -It deletes all properties on all root windows (see section 4.3). +It deletes all properties on all root windows +(see <link linkend="Properties_and_Atoms">section 4.3</link>). </para> </listitem> <listitem> @@ -3198,7 +3205,9 @@ for threads using <!-- .LP --> In addition to the connection to the X server, an Xlib implementation may require connections to other kinds of servers (for example, to -input method servers as described in chapter 13). Toolkits and clients +input method servers as described in +<link linkend="locales_and_internationalized_text_functions">chapter 13</link>). +Toolkits and clients that use multiple displays, or that use displays in combination with other inputs, need to obtain these additional connections to correctly block until input is available and need to process that input diff --git a/libX11/specs/libX11/CH03.xml b/libX11/specs/libX11/CH03.xml index 9cbacd83b..d26a814c3 100644 --- a/libX11/specs/libX11/CH03.xml +++ b/libX11/specs/libX11/CH03.xml @@ -23,7 +23,8 @@ Because default windows and visual types are defined for each screen, most simple applications need not deal with this complexity. Xlib provides macros and functions that return the default root window, the default depth of the default root window, and the default visual type -(see sections 2.2.1 and 16.7). +(see sections <link linkend="Display_Macros_">2.2.1</link> +and <link linkend="Determining_the_Appropriate_Visual_Type">16.7</link>). </para> <para> <!-- .LP --> @@ -31,7 +32,9 @@ Xlib uses an opaque <structname>Visual</structname> <indexterm significance="preferred"><primary>Visual</primary></indexterm> structure that contains information about the possible color mapping. -The visual utility functions (see section 16.7) use an +The visual utility functions +(see <link linkend="Determining_the_Appropriate_Visual_Type">section 16.7</link>) +use an <structname>XVisualInfo</structname> structure to return this information to an application. The members of this structure pertinent to this discussion are class, red_mask, @@ -217,7 +220,8 @@ All <symbol>InputOutput</symbol> windows have a border width of zero or more pixels, an optional background, an event suppression mask (which suppresses propagation of events from -children), and a property list (see section 4.3). +children), and a property list +(see <link linkend="Properties_and_Atoms">section 4.3</link>). The window border and background can be a solid color or a pattern, called a tile. All windows except the root have a parent and are clipped by their parent. @@ -231,7 +235,8 @@ obscured area. </para> <para> <!-- .LP --> -Windows also have associated property lists (see section 4.3). +Windows also have associated property lists +(see <link linkend="Properties_and_Atoms">section 4.3</link>). </para> <para> <!-- .LP --> @@ -644,7 +649,7 @@ Otherwise, the initial contents of the exposed regions are undefined. events are then generated for the regions, even if the background-pixmap is <symbol>None</symbol> -(see section 10.9). +(see <link linkend="Exposure_Events">section 10.9</link>). </para> </sect2> <sect2 id="Border_Attribute"> @@ -813,7 +818,8 @@ the corresponding pair defines the change in position of the window within the parent. When a window is so repositioned, a <symbol>GravityNotify</symbol> -event is generated (see section 10.10.5). +event is generated +(see <link linkend="GravityNotify_Events">section 10.10.5</link>). </para> <para> <!-- .LP --> @@ -1066,7 +1072,7 @@ or <symbol>False</symbol> (default). Window managers use this information to avoid tampering with pop-up windows -(see also chapter 14). +(see also <link linkend="inter_client_communication_functions">chapter 14</link>). </para> </sect2> <sect2 id="Colormap_Attribute"> @@ -1161,7 +1167,7 @@ which are discussed in the appropriate toolkit documentation. If you do not use a toolkit, however, you must provide some standard information or hints for the window manager by using the Xlib inter-client communication functions -(see chapter 14). +(see <link linkend="inter_client_communication_functions">chapter 14</link>). </para> <para> <!-- .LP --> @@ -1205,7 +1211,8 @@ you should set these properties for top-level windows before mapping them. <para> <!-- .LP --> For further information, -see chapter 14 and the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>. +see <link linkend="inter_client_communication_functions">chapter 14</link> and +the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>. </para> <para> <!-- .LP --> @@ -1868,7 +1875,8 @@ windows and then decide to map the window to its final location. A window manager that wants to provide decoration might reparent the child into a frame first. For further information, -see sections 3.2.8 and 10.10. +see <link linkend="Override_Redirect_Flag">sections 3.2.8</link> +and <link linkend="Window_State_Change_Events_">10.10</link>. Only a single client at a time can select for <symbol>SubstructureRedirectMask</symbol>. </para> @@ -2398,7 +2406,8 @@ children of the window are affected as specified. If a window's size actually changes, the window's subwindows move according to their window gravity. Depending on the window's bit gravity, -the contents of the window also may be moved (see section 3.2.3). +the contents of the window also may be moved +(see <link linkend="Gravity_Attributes">section 3.2.3</link>). </para> <para> <!-- .LP --> @@ -3558,7 +3567,7 @@ Specifies the structure from which the values (as specified by the value mask) are to be taken. The value mask should have the appropriate bits set to indicate which attributes have been set in the structure -(see section 3.2). +(see <link linkend="Window_Attributes">section 3.2</link>). </para> </listitem> </varlistentry> diff --git a/libX11/specs/libX11/CH04.xml b/libX11/specs/libX11/CH04.xml index d224216d3..79f8fa949 100644 --- a/libX11/specs/libX11/CH04.xml +++ b/libX11/specs/libX11/CH04.xml @@ -291,7 +291,7 @@ and can be one of the following: <para> <!-- .LP --> For additional information on gravity, -see section 3.2.3. <!-- xref --> +see <link linkend="Gravity_Attributes">section 3.2.3</link>. </para> <para> <!-- .LP --> @@ -817,7 +817,7 @@ the current state of the mouse buttons and the modifier keys. <!-- .LP --> Note that the logical state of a device (as seen through Xlib) may lag the physical state if device event processing is frozen -(see section 12.1). <!-- xref --> +(see <link linkend="Pointer_Grabbing_">section 12.1</link>). </para> <para> <!-- .LP --> @@ -867,7 +867,7 @@ If you define further properties of complex type, you must encode and decode them yourself. These functions must be carefully written if they are to be portable. For further information about how to write a library extension, -see appendix C. <!-- xref --> +see <link linkend="extensions">appendix C</link>. <!-- .NE --> The type of a property is defined by an atom, which allows for arbitrary extension in this type scheme. @@ -887,7 +887,7 @@ To avoid name clashes with user symbols, the name for each atom has the XA_ prefix. For an explanation of the functions that let you get and set much of the information stored in these predefined properties, -see chapter 14. <!-- xref --> +see <link linkend="inter_client_communication_functions">chapter 14</link>. </para> <para> <!-- .LP --> @@ -1040,7 +1040,7 @@ The built-in font property names are: <para> <!-- .LP --> For further information about font properties, -see section 8.5. <!-- xref --> +see <link linkend="Font_Metrics">section 8.5</link>. </para> <para> <!-- .LP --> @@ -1381,7 +1381,8 @@ error. <para> <!-- .LP --> You can attach a property list to every window. -Each property has a name, a type, and a value (see section 4.3). <!-- xref --> +Each property has a name, a type, and a value +(see <link linkend="Properties_and_Atoms">section 4.3</link>). The value is an array of 8-bit, 16-bit, or 32-bit quantities, whose interpretation is left to the clients. The type <type>char</type> @@ -1396,7 +1397,8 @@ is used to represent 32-bit quantities. Xlib provides functions that you can use to obtain, change, update, or interchange window properties. In addition, Xlib provides other utility functions for inter-client -communication (see chapter 14). <!-- xref --> +communication +(see <link linkend="inter_client_communication_functions">chapter 14</link>). </para> <para> <!-- .LP --> @@ -1934,7 +1936,7 @@ The lifetime of a property is not tied to the storing client. Properties remain until explicitly deleted, until the window is destroyed, or until the server resets. For a discussion of what happens when the connection to the X server is closed, -see section 2.6. <!-- xref --> +see <link linkend="Using_X_Server_Connection_Close_Operations_">section 2.6</link>. The maximum size of a property is server dependent and can vary dynamically depending on the amount of memory the server has available. (If there is insufficient space, a diff --git a/libX11/specs/libX11/CH05.xml b/libX11/specs/libX11/CH05.xml index 3ad7076ea..6df3509a6 100644 --- a/libX11/specs/libX11/CH05.xml +++ b/libX11/specs/libX11/CH05.xml @@ -277,7 +277,7 @@ The initial colors of a cursor are a black foreground and a white background (see <function>XRecolorCursor</function>). For further information about cursor shapes, -see appendix B. +see <link linkend="x_font_cursors">appendix B</link>. </para> <para> <!-- .LP --> diff --git a/libX11/specs/libX11/CH06.xml b/libX11/specs/libX11/CH06.xml index ab5cec031..bd3c1adc3 100644 --- a/libX11/specs/libX11/CH06.xml +++ b/libX11/specs/libX11/CH06.xml @@ -172,7 +172,7 @@ Possible visual types are <symbol>TrueColor</symbol>, or <symbol>DirectColor</symbol> -(see section 3.1). +(see <link linkend="Visual_Types">section 3.1</link>). </para> <sect1 id="Color_Structures"> <title>Color Structures</title> @@ -294,7 +294,7 @@ it indicates that the color specification is in a device-dependent form; otherwise, it is in a device-independent form. If the 31st bit is set, this indicates that the color space has been added to Xlib at run time -(see section 6.12.4). +(see <link linkend="Creating_Additional_Color_Spaces">section 6.12.4</link>). The format value for a color space added at run time may be different each time the program is executed. If references to such a color space must be made outside the client @@ -917,7 +917,7 @@ if alloc is the colormap initially has no allocated entries, and clients can allocate them. For information about the visual types, -see section 3.1. +see <link linkend="Visual_Types">section 3.1</link>. </para> <para> <!-- .LP --> diff --git a/libX11/specs/libX11/CH07.xml b/libX11/specs/libX11/CH07.xml index ff1a9d836..32c94f15a 100644 --- a/libX11/specs/libX11/CH07.xml +++ b/libX11/specs/libX11/CH07.xml @@ -3197,7 +3197,7 @@ errors. Xlib provides a set of basic functions for performing region arithmetic. For information about these functions, -see section 16.5. +see <link linkend="Manipulating_Regions">section 16.5</link>. </para> </sect2> <sect2 id="Setting_the_Arc_Mode_Subwindow_Mode_and_Graphics_Exposure_"> diff --git a/libX11/specs/libX11/CH08.xml b/libX11/specs/libX11/CH08.xml index 5f450fe9d..e6eae13be 100644 --- a/libX11/specs/libX11/CH08.xml +++ b/libX11/specs/libX11/CH08.xml @@ -5268,7 +5268,7 @@ frequently used data formats by replacing functions in the procedure vector with special case functions. Supported operations include destroying the image, getting a pixel, storing a pixel, extracting a subimage of an image, and adding a constant -to an image (see section 16.8). +to an image (see <link linkend="Manipulating_Images">section 16.8</link>). </para> <para> <!-- .LP --> diff --git a/libX11/specs/libX11/CH09.xml b/libX11/specs/libX11/CH09.xml index eff97c39c..2389e824d 100644 --- a/libX11/specs/libX11/CH09.xml +++ b/libX11/specs/libX11/CH09.xml @@ -194,7 +194,7 @@ The save-set of a client is a list of other clients' windows that, if they are inferiors of one of the client's windows at connection close, should not be destroyed and should be remapped if they are unmapped. For further information about close-connection processing, -see section 2.6. +see <link linkend="Using_X_Server_Connection_Close_Operations_">section 2.6</link>. To allow an application's window to survive when a window manager that has reparented a window fails, Xlib provides the save-set functions that you can @@ -992,7 +992,7 @@ If <symbol>AllTemporary</symbol> is specified, the resources of all clients that have terminated in <symbol>RetainTemporary</symbol> -are destroyed (see section 2.5). +are destroyed (see <link linkend="Closing_the_Display">section 2.5</link>). This permits implementation of window manager facilities that aid debugging. A client can set its close-down mode to <symbol>RetainTemporary</symbol>. diff --git a/libX11/specs/libX11/CH10.xml b/libX11/specs/libX11/CH10.xml index e7b945323..8a06a706f 100644 --- a/libX11/specs/libX11/CH10.xml +++ b/libX11/specs/libX11/CH10.xml @@ -1,4739 +1,4742 @@ -<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<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
-connection. 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 -->
-<indexterm><primary>Event</primary><secondary>types</secondary></indexterm>
-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.
-<indexterm><primary>Event</primary></indexterm>
-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,
-<symbol>MappingNotify</symbol>
-events are always sent to all clients.
-<indexterm><primary>Input Control</primary></indexterm>
-<indexterm><primary>Output Control</primary></indexterm>
-</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
-<filename class="headerfile"><X11/X.h></filename>,
-<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
-which is used when referring to an event type.
-<indexterm><primary>Event</primary><secondary>categories</secondary></indexterm>
-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><symbol>KeyPress</symbol>,
- <symbol>KeyRelease</symbol></entry>
- </row>
- <row>
- <entry>Pointer events</entry>
- <entry><symbol>ButtonPress</symbol>,
- <symbol>ButtonRelease</symbol>,
- <symbol>MotionNotify</symbol></entry>
- </row>
- <row>
- <entry>Window crossing events</entry>
- <entry><symbol>EnterNotify</symbol>,
- <symbol>LeaveNotify</symbol></entry>
- </row>
- <row>
- <entry>Input focus events</entry>
- <entry><symbol>FocusIn</symbol>,
- <symbol>FocusOut</symbol></entry>
- </row>
- <row>
- <entry>Keymap state notification event</entry>
- <entry><symbol>KeymapNotify</symbol></entry>
- </row>
- <row>
- <entry>Exposure events</entry>
- <entry><symbol>Expose</symbol>,
- <symbol>GraphicsExpose</symbol>,
- <symbol>NoExpose</symbol></entry>
- </row>
- <row>
- <entry>Structure control events</entry>
- <entry><symbol>CirculateRequest</symbol>,
- <symbol>ConfigureRequest</symbol>,
- <symbol>MapRequest</symbol>,
- <symbol>ResizeRequest</symbol></entry>
- </row>
- <row>
- <entry>Window state notification events</entry>
- <entry>
- <symbol>CirculateNotify</symbol>,
- <symbol>ConfigureNotify</symbol>,
- <symbol>CreateNotify</symbol>,
- <symbol>DestroyNotify</symbol>,
- <symbol>GravityNotify</symbol>,
- <symbol>MapNotify</symbol>,
- <symbol>MappingNotify</symbol>,
- <symbol>ReparentNotify</symbol>,
- <symbol>UnmapNotify</symbol>,
- <symbol>VisibilityNotify</symbol></entry>
- </row>
- <row>
- <entry>Colormap state notification event</entry>
- <entry><symbol>ColormapNotify</symbol></entry>
- </row>
- <row>
- <entry>Client communication events</entry>
- <entry><symbol>ClientMessage</symbol>,
- <symbol>PropertyNotify</symbol>,
- <symbol>SelectionClear</symbol>,
- <symbol>SelectionNotify</symbol>,
- <symbol>SelectionRequest</symbol></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
-<filename class="headerfile"><X11/Xlib.h></filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm>
-All the event structures have the following common members:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XAnyEvent</primary></indexterm>
-<!-- .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
-<symbol>GraphicsExpose</symbol>
-event to a client application, it sends an
-<structname>XGraphicsExposeEvent</structname>
-structure with the type member set to
-<symbol>GraphicsExpose</symbol>.
-The display member is set to a pointer to the display the event was read on.
-The send_event member is set to
-<symbol>True</symbol>
-if the event came from a
-<systemitem>SendEvent</systemitem>
-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
-<structname>XEvent</structname>
-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
-<structname>XEvent</structname>
-union.
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XEvent</primary></indexterm>
-<!-- .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
-<structname>XEvent</structname>
-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
-<type>Bool</type>
-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 -->
-<indexterm significance="preferred"><primary>Event mask</primary></indexterm>
-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
-<filename class="headerfile"><X11/X.h></filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm>
-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
-<symbol>False</symbol>,
-<symbol>GraphicsExpose</symbol>
-and
-<symbol>NoExpose</symbol>
-are reported by default as a result of
-<function>XCopyPlane</function>
-and
-<function>XCopyArea</function>.
-<symbol>SelectionClear</symbol>,
-<symbol>SelectionRequest</symbol>,
-<symbol>SelectionNotify</symbol>,
-or
-<symbol>ClientMessage</symbol>
-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,
-<symbol>MappingNotify</symbol>
-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><symbol>NoEventMask</symbol></entry>
- <entry>No events wanted</entry>
- </row>
- <row>
- <entry><symbol>KeyPressMask</symbol></entry>
- <entry>Keyboard down events wanted</entry>
- </row>
- <row>
- <entry><symbol>KeyReleaseMask</symbol></entry>
- <entry>Keyboard up events wanted</entry>
- </row>
- <row>
- <entry><symbol>ButtonPressMask</symbol></entry>
- <entry>Pointer button down events wanted</entry>
- </row>
- <row>
- <entry><symbol>ButtonReleaseMask</symbol></entry>
- <entry>Pointer button up events wanted</entry>
- </row>
- <row>
- <entry><symbol>EnterWindowMask</symbol></entry>
- <entry>Pointer window entry events wanted</entry>
- </row>
- <row>
- <entry><symbol>LeaveWindowMask</symbol></entry>
- <entry>Pointer window leave events wanted</entry>
- </row>
- <row>
- <entry><symbol>PointerMotionMask</symbol></entry>
- <entry>Pointer motion events wanted</entry>
- </row>
- <row>
- <entry><symbol>PointerMotionHintMask</symbol></entry>
- <entry>Pointer motion hints wanted</entry>
- </row>
- <row>
- <entry><symbol>Button1MotionMask</symbol></entry>
- <entry>Pointer motion while button 1 down</entry>
- </row>
- <row>
- <entry><symbol>Button2MotionMask</symbol></entry>
- <entry>Pointer motion while button 2 down</entry>
- </row>
- <row>
- <entry><symbol>Button3MotionMask</symbol></entry>
- <entry>Pointer motion while button 3 down</entry>
- </row>
- <row>
- <entry><symbol>Button4MotionMask</symbol></entry>
- <entry>Pointer motion while button 4 down</entry>
- </row>
- <row>
- <entry><symbol>Button5MotionMask</symbol></entry>
- <entry>Pointer motion while button 5 down</entry>
- </row>
- <row>
- <entry><symbol>ButtonMotionMask</symbol></entry>
- <entry>Pointer motion while any button down</entry>
- </row>
- <row>
- <entry><symbol>KeymapStateMask</symbol></entry>
- <entry>Keyboard state wanted at window entry and focus in</entry>
- </row>
- <row>
- <entry><symbol>ExposureMask</symbol></entry>
- <entry>Any exposure wanted</entry>
- </row>
- <row>
- <entry><symbol>VisibilityChangeMask</symbol></entry>
- <entry>Any change in visibility wanted</entry>
- </row>
- <row>
- <entry><symbol>StructureNotifyMask</symbol></entry>
- <entry>Any change in window structure wanted</entry>
- </row>
- <row>
- <entry><symbol>ResizeRedirectMask</symbol></entry>
- <entry>Redirect resize of this window</entry>
- </row>
- <row>
- <entry><symbol>SubstructureNotifyMask</symbol></entry>
- <entry>Substructure notification wanted</entry>
- </row>
- <row>
- <entry><symbol>SubstructureRedirectMask</symbol></entry>
- <entry>Redirect structure requests on children</entry>
- </row>
- <row>
- <entry><symbol>FocusChangeMask</symbol></entry>
- <entry>Any change in input focus wanted</entry>
- </row>
- <row>
- <entry><symbol>PropertyChangeMask</symbol></entry>
- <entry>Any change in property wanted</entry>
- </row>
- <row>
- <entry><symbol>ColormapChangeMask</symbol></entry>
- <entry>Any change in colormap wanted</entry>
- </row>
- <row>
- <entry><symbol>OwnerGrabButtonMask</symbol></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
-<symbol>ButtonPressMask</symbol>,
-the X server sends back only
-<symbol>ButtonPress</symbol>
-events.
-<indexterm><primary>CurrentTime</primary></indexterm>
-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
-<symbol>SubstructureNotifyMask</symbol>,
-the X server can send back
-<symbol>CirculateNotify</symbol>,
-<symbol>ConfigureNotify</symbol>,
-<symbol>CreateNotify</symbol>,
-<symbol>DestroyNotify</symbol>,
-<symbol>GravityNotify</symbol>,
-<symbol>MapNotify</symbol>,
-<symbol>ReparentNotify</symbol>,
-or
-<symbol>UnmapNotify</symbol>
-events.
-</para>
-<para>
-<!-- .LP -->
-In another case,
-two event masks can map to one event type.
-For example,
-if you pass either
-<symbol>PointerMotionMask</symbol>
-or
-<symbol>ButtonMotionMask</symbol>,
-the X server sends back
-a
-<symbol>MotionNotify</symbol>
-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><symbol>GrabModeAsync</symbol></entry>
- </row>
- <row>
- <entry><emphasis remap='I'>keyboard_mode</emphasis></entry>
- <entry><symbol>GrabModeAsync</symbol></entry>
- </row>
- <row>
- <entry><emphasis remap='I'>owner_events</emphasis></entry>
- <entry><symbol>True</symbol>,
- if the client has selected
- <symbol>OwnerGrabButtonMask</symbol>
- on the event window,
- otherwise
- <symbol>False</symbol></entry>
- </row>
- <row>
- <entry><emphasis remap='I'>confine_to</emphasis></entry>
- <entry><symbol>None</symbol></entry>
- </row>
- <row>
- <entry><emphasis remap='I'>cursor</emphasis></entry>
- <entry><symbol>None</symbol></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 -->
-<indexterm><primary>Events</primary><secondary>ButtonPress</secondary></indexterm>
-<indexterm><primary>Events</primary><secondary>ButtonRelease</secondary></indexterm>
-<indexterm><primary>Events</primary><secondary>KeyPress</secondary></indexterm>
-<indexterm><primary>Events</primary><secondary>KeyRelease</secondary></indexterm>
-<indexterm><primary>Events</primary><secondary>MotionNotify</secondary></indexterm>
-This section discusses the processing that occurs for the
-keyboard events
-<symbol>KeyPress</symbol>
-and
-<symbol>KeyRelease</symbol>
-and the pointer events
-<symbol>ButtonPress</symbol>,
-<symbol>ButtonRelease</symbol>,
-and
-<symbol>MotionNotify</symbol>.
-For information about the keyboard event-handling utilities,
-see chapter 11.
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>KeyPress</primary></indexterm>
-<indexterm significance="preferred"><primary>KeyRelease</primary></indexterm>
-The X server reports
-<symbol>KeyPress</symbol>
-or
-<symbol>KeyRelease</symbol>
-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.
-<indexterm significance="preferred"><primary>ButtonPress</primary></indexterm>
-<indexterm significance="preferred"><primary>ButtonRelease</primary></indexterm>
-The X server reports
-<symbol>ButtonPress</symbol>
-or
-<symbol>ButtonRelease</symbol>
-events to clients wanting information about buttons that logically change state.
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>MotionNotify</primary></indexterm>
-The X server reports
-<symbol>MotionNotify</symbol>
-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
-<symbol>MotionNotify</symbol>
-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
-<symbol>KeyPress</symbol>,
-<symbol>KeyRelease</symbol>,
-<symbol>ButtonPress</symbol>,
-and
-<symbol>ButtonRelease</symbol>
-events, set
-<symbol>KeyPressMask</symbol>,
-<symbol>KeyReleaseMask</symbol>,
-<symbol>ButtonPressMask</symbol>,
-and
-<symbol>ButtonReleaseMask</symbol>
-bits in the event-mask attribute of the window.
-</para>
-<para>
-<!-- .LP -->
-To receive
-<symbol>MotionNotify</symbol>
-events, set one or more of the following event
-masks bits in the event-mask attribute of the window.
-</para>
-<itemizedlist>
- <listitem>
- <para>
-<symbol>Button1MotionMask</symbol> - <symbol>Button5MotionMask</symbol>
- </para>
- </listitem>
- <listitem>
- <para>
-The client application receives
-<symbol>MotionNotify</symbol>
-events only when one or more of the specified buttons is pressed.
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>ButtonMotionMask</symbol>
- </para>
- </listitem>
- <listitem>
- <para>
-The client application receives
-<symbol>MotionNotify</symbol>
-events only when at least one button is pressed.
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>PointerMotionMask</symbol>
- </para>
- </listitem>
- <listitem>
- <para>
-The client application receives
-<symbol>MotionNotify</symbol>
-events independent of the state of
-the pointer buttons.
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>PointerMotionHintMask</symbol>
- </para>
- </listitem>
- <listitem>
- <para>
-If
-<symbol>PointerMotionHintMask</symbol>
-is selected in combination with one or more of the above masks,
-the X server is free to send only one
-<symbol>MotionNotify</symbol>
-event (with the is_hint member of the
-<type>XPointerMovedEvent</type>
-structure set to
-<symbol>NotifyHint</symbol>)
-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
-<symbol>MotionNotify</symbol>
-events without is_hint set to
-<symbol>NotifyHint</symbol>.
- </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
-<symbol>True</symbol>
-or
-<symbol>False</symbol>.
-If
-<symbol>True</symbol>,
-the event and root windows are on the same screen.
-If
-<symbol>False</symbol>,
-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
-<symbol>None</symbol>.
-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:
-<symbol>Button1Mask</symbol>,
-<symbol>Button2Mask</symbol>,
-<symbol>Button3Mask</symbol>,
-<symbol>Button4Mask</symbol>,
-<symbol>Button5Mask</symbol>,
-<symbol>ShiftMask</symbol>,
-<symbol>LockMask</symbol>,
-<symbol>ControlMask</symbol>,
-<symbol>Mod1Mask</symbol>,
-<symbol>Mod2Mask</symbol>,
-<symbol>Mod3Mask</symbol>,
-<symbol>Mod4Mask</symbol>,
-and
-<symbol>Mod5Mask</symbol>.
-</para>
-<para>
-<!-- .LP -->
-Each of these structures also has a member that indicates the detail.
-For the
-<type>XKeyPressedEvent</type>
-and
-<type>XKeyReleasedEvent</type>
-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
-<type>XButtonPressedEvent</type>
-and
-<type>XButtonReleasedEvent</type>
-structures, this member is called button.
-It represents the pointer button that changed state and can be the
-<symbol>Button1</symbol>,
-<symbol>Button2</symbol>,
-<symbol>Button3</symbol>,
-<symbol>Button4</symbol>,
-or
-<symbol>Button5</symbol>
-value.
-For the
-<type>XPointerMovedEvent</type>
-structure, this member is called is_hint.
-It can be set to
-<symbol>NotifyNormal</symbol>
-or
-<symbol>NotifyHint</symbol>.
-</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><symbol>Button1MotionMask</symbol></entry>
- <entry>(1L<<8)</entry>
- </row>
- <row>
- <entry><symbol>Button2MotionMask</symbol></entry>
- <entry>(1L<<9)</entry>
- </row>
- <row>
- <entry><symbol>Button3MotionMask</symbol></entry>
- <entry>(1L<<10)</entry>
- </row>
- <row>
- <entry><symbol>Button4MotionMask</symbol></entry>
- <entry>(1L<<11)</entry>
- </row>
- <row>
- <entry><symbol>Button5MotionMask</symbol></entry>
- <entry>(1L<<12)</entry>
- </row>
- <row>
- <entry><symbol>Button1Mask</symbol></entry>
- <entry>(1<<8)</entry>
- </row>
- <row>
- <entry><symbol>Button2Mask</symbol></entry>
- <entry>(1<<9)</entry>
- </row>
- <row>
- <entry><symbol>Button3Mask</symbol></entry>
- <entry>(1<<10)</entry>
- </row>
- <row>
- <entry><symbol>Button4Mask</symbol></entry>
- <entry>(1<<11)</entry>
- </row>
- <row>
- <entry><symbol>Button5Mask</symbol></entry>
- <entry>(1<<12)</entry>
- </row>
- <row>
- <entry><symbol>ShiftMask</symbol></entry>
- <entry>(1<<0)</entry>
- </row>
- <row>
- <entry><symbol>LockMask</symbol></entry>
- <entry>(1<<1)</entry>
- </row>
- <row>
- <entry><symbol>ControlMask</symbol></entry>
- <entry>(1<<2)</entry>
- </row>
- <row>
- <entry><symbol>Mod1Mask</symbol></entry>
- <entry>(1<<3)</entry>
- </row>
- <row>
- <entry><symbol>Mod2Mask</symbol></entry>
- <entry>(1<<4)</entry>
- </row>
- <row>
- <entry><symbol>Mod3Mask</symbol></entry>
- <entry>(1<<5)</entry>
- </row>
- <row>
- <entry><symbol>Mod4Mask</symbol></entry>
- <entry>(1<<6)</entry>
- </row>
- <row>
- <entry><symbol>Mod5Mask</symbol></entry>
- <entry>(1<<7)</entry>
- </row>
- <row>
- <entry><symbol>Button1</symbol></entry>
- <entry>1</entry>
- </row>
- <row>
- <entry><symbol>Button2</symbol></entry>
- <entry>2</entry>
- </row>
- <row>
- <entry><symbol>Button3</symbol></entry>
- <entry>3</entry>
- </row>
- <row>
- <entry><symbol>Button4</symbol></entry>
- <entry>4</entry>
- </row>
- <row>
- <entry><symbol>Button5</symbol></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 -->
-<indexterm><primary>Events</primary><secondary>EnterNotify</secondary></indexterm>
-<indexterm><primary>Events</primary><secondary>LeaveNotify</secondary></indexterm>
-This section describes the processing that
-occurs for the window crossing events
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>.
-<indexterm significance="preferred"><primary>EnterNotify</primary></indexterm>
-<indexterm significance="preferred"><primary>LeaveNotify</primary></indexterm>
-If a pointer motion or a window hierarchy change causes the
-pointer to be in a different window than before, the X server reports
-<symbol>EnterNotify</symbol>
-or
-<symbol>LeaveNotify</symbol>
-events to clients who have selected for these events.
-All
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>
-events caused by a hierarchy change are
-generated after any hierarchy event
-(<symbol>UnmapNotify</symbol>,
-<symbol>MapNotify</symbol>,
-<symbol>ConfigureNotify</symbol>,
-<symbol>GravityNotify</symbol>,
-<symbol>CirculateNotify</symbol>)
-caused by that change;
-however, the X protocol does not constrain the ordering of
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>
-events with respect to
-<symbol>FocusOut</symbol>,
-<symbol>VisibilityNotify</symbol>,
-and
-<symbol>Expose</symbol>
-events.
-</para>
-<para>
-<!-- .LP -->
-This contrasts with
-<symbol>MotionNotify</symbol>
-events, which are also generated when the pointer moves
-but only when the pointer motion begins and ends in a single window.
-An
-<symbol>EnterNotify</symbol>
-or
-<symbol>LeaveNotify</symbol>
-event also can be generated when some client application calls
-<function>XGrabPointer</function>
-and
-<function>XUngrabPointer</function>.
-</para>
-<para>
-<!-- .LP -->
-To receive
-<symbol>EnterNotify</symbol>
-or
-<symbol>LeaveNotify</symbol>
-events, set the
-<symbol>EnterWindowMask</symbol>
-or
-<symbol>LeaveWindowMask</symbol>
-bits of the event-mask attribute of the window.
-</para>
-<para>
-<!-- .LP -->
-The structure for these event types contains:
-</para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XCrossingEvent</primary></indexterm>
-<indexterm significance="preferred"><primary>XEnterWindowEvent</primary></indexterm>
-<indexterm significance="preferred"><primary>XLeaveWindowEvent</primary></indexterm>
-<!-- .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
-<symbol>EnterNotify</symbol>
-or
-<symbol>LeaveNotify</symbol>
-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
-<symbol>LeaveNotify</symbol>
-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
-<symbol>None</symbol>.
-For an
-<symbol>EnterNotify</symbol>
-event, if a child of the event window contains the final pointer position,
-the subwindow component is set to that child or
-<symbol>None</symbol>.
-</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
-<symbol>True</symbol>
-or
-<symbol>False</symbol>.
-If
-<symbol>True</symbol>,
-the event and root windows are on the same screen.
-If
-<symbol>False</symbol>,
-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
-<symbol>True</symbol>
-or
-<symbol>False</symbol>.
-If
-<symbol>True</symbol>,
-the event window is the focus window or an inferior of the focus window.
-If
-<symbol>False</symbol>,
-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:
-<symbol>Button1Mask</symbol>,
-<symbol>Button2Mask</symbol>,
-<symbol>Button3Mask</symbol>,
-<symbol>Button4Mask</symbol>,
-<symbol>Button5Mask</symbol>,
-<symbol>ShiftMask</symbol>,
-<symbol>LockMask</symbol>,
-<symbol>ControlMask</symbol>,
-<symbol>Mod1Mask</symbol>,
-<symbol>Mod2Mask</symbol>,
-<symbol>Mod3Mask</symbol>,
-<symbol>Mod4Mask</symbol>,
-<symbol>Mod5Mask</symbol>.
-</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
-<symbol>NotifyNormal</symbol>,
-<symbol>NotifyGrab</symbol>,
-or
-<symbol>NotifyUngrab</symbol>.
-</para>
-<para>
-<!-- .LP -->
-The detail member is set to indicate the notify detail and can be
-<symbol>NotifyAncestor</symbol>,
-<symbol>NotifyVirtual</symbol>,
-<symbol>NotifyInferior</symbol>,
-<symbol>NotifyNonlinear</symbol>,
-or
-<symbol>NotifyNonlinearVirtual</symbol>.
-</para>
-<sect2 id="Normal_Entry_Exit_Events">
-<title>Normal Entry/Exit Events</title>
-<!-- .XS -->
-<!-- (SN Normal Entry/Exit Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>
-events are generated when the pointer moves from
-one window to another window.
-Normal events are identified by
-<type>XEnterWindowEvent</type>
-or
-<type>XLeaveWindowEvent</type>
-structures whose mode member is set to
-<symbol>NotifyNormal</symbol>.
-</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
-<symbol>LeaveNotify</symbol>
-event on window A, with the detail member of the
-<type>XLeaveWindowEvent</type>
-structure set to
-<symbol>NotifyAncestor</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>LeaveNotify</symbol>
-event on each window between window A and window B, exclusive,
-with the detail member of each
-<type>XLeaveWindowEvent</type>
-structure set to
-<symbol>NotifyVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates an
-<symbol>EnterNotify</symbol>
-event on window B, with the detail member of the
-<type>XEnterWindowEvent</type>
-structure set to
-<symbol>NotifyInferior</symbol>.
-<!-- .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
-<symbol>LeaveNotify</symbol>
-event on window A,
-with the detail member of the
-<type>XLeaveWindowEvent</type>
-structure set to
-<symbol>NotifyInferior</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates an
-<symbol>EnterNotify</symbol>
-event on each window between window A and window B, exclusive, with the
-detail member of each
-<type>XEnterWindowEvent</type>
-structure set to
-<symbol>NotifyVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates an
-<symbol>EnterNotify</symbol>
-event on window B, with the detail member of the
-<type>XEnterWindowEvent</type>
-structure set to
-<symbol>NotifyAncestor</symbol>.
-<!-- .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
-<symbol>LeaveNotify</symbol>
-event on window A,
-with the detail member of the
-<type>XLeaveWindowEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>LeaveNotify</symbol>
-event on each window between window A and window C, exclusive,
-with the detail member of each
-<type>XLeaveWindowEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates an
-<symbol>EnterNotify</symbol>
-event on each window between window C and window B, exclusive,
-with the detail member of each
-<type>XEnterWindowEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates an
-<symbol>EnterNotify</symbol>
-event on window B, with the detail member of the
-<type>XEnterWindowEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
-<!-- .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
-<symbol>LeaveNotify</symbol>
-event on window A,
-with the detail member of the
-<type>XLeaveWindowEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If window A is not a root window,
-it generates a
-<symbol>LeaveNotify</symbol>
-event on each window above window A up to and including its root,
-with the detail member of each
-<type>XLeaveWindowEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If window B is not a root window,
-it generates an
-<symbol>EnterNotify</symbol>
-event on each window from window B's root down to but not including
-window B, with the detail member of each
-<type>XEnterWindowEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates an
-<symbol>EnterNotify</symbol>
-event on window B, with the detail member of the
-<type>XEnterWindowEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
-<!-- .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
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>
-events are generated when a pointer grab activates or deactivates.
-Events in which the pointer grab activates
-are identified by
-<type>XEnterWindowEvent</type>
-or
-<type>XLeaveWindowEvent</type>
-structures whose mode member is set to
-<symbol>NotifyGrab</symbol>.
-Events in which the pointer grab deactivates
-are identified by
-<type>XEnterWindowEvent</type>
-or
-<type>XLeaveWindowEvent</type>
-structures whose mode member is set to
-<symbol>NotifyUngrab</symbol>
-(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
-<symbol>ButtonPress</symbol>
-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
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>
-events (see section 10.6.1)
-with the mode members of the
-<type>XEnterWindowEvent</type>
-and
-<type>XLeaveWindowEvent</type>
-structures set to
-<symbol>NotifyGrab</symbol>.
-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
-<symbol>ButtonRelease</symbol>
-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
-<symbol>EnterNotify</symbol>
-and
-<symbol>LeaveNotify</symbol>
-events (see section 10.6.1)
-with the mode members of the
-<type>XEnterWindowEvent</type>
-and
-<type>XLeaveWindowEvent</type>
-structures set to
-<symbol>NotifyUngrab</symbol>.
-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 -->
-<indexterm><primary>Events</primary><secondary>FocusIn</secondary></indexterm>
-<indexterm><primary>Events</primary><secondary>FocusOut</secondary></indexterm>
-This section describes the processing that occurs for the input focus events
-<symbol>FocusIn</symbol>
-and
-<symbol>FocusOut</symbol>.
-<indexterm significance="preferred"><primary>FocusIn</primary></indexterm>
-<indexterm significance="preferred"><primary>FocusOut</primary></indexterm>
-The X server can report
-<symbol>FocusIn</symbol>
-or
-<symbol>FocusOut</symbol>
-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
-<symbol>FocusIn</symbol>
-or
-<symbol>FocusOut</symbol>
-events, set the
-<symbol>FocusChangeMask</symbol>
-bit in the event-mask attribute of the window.
-</para>
-<para>
-<!-- .LP -->
-The structure for these event types contains:
-</para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XFocusChangeEvent</primary></indexterm>
-<indexterm significance="preferred"><primary>XFocusInEvent</primary></indexterm>
-<indexterm significance="preferred"><primary>XFocusOutEvent</primary></indexterm>
-<!-- .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
-<symbol>FocusIn</symbol>
-or
-<symbol>FocusOut</symbol>
-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
-<symbol>NotifyNormal</symbol>,
-<symbol>NotifyWhileGrabbed</symbol>,
-<symbol>NotifyGrab</symbol>,
-or
-<symbol>NotifyUngrab</symbol>.
-</para>
-<para>
-<!-- .LP -->
-All
-<symbol>FocusOut</symbol>
-events caused by a window unmap are generated after any
-<symbol>UnmapNotify</symbol>
-event; however, the X protocol does not constrain the ordering of
-<symbol>FocusOut</symbol>
-events with respect to
-generated
-<symbol>EnterNotify</symbol>,
-<symbol>LeaveNotify</symbol>,
-<symbol>VisibilityNotify</symbol>,
-and
-<symbol>Expose</symbol>
-events.
-</para>
-<para>
-<!-- .LP -->
-Depending on the event mode,
-the detail member is set to indicate the notify detail and can be
-<symbol>NotifyAncestor</symbol>,
-<symbol>NotifyVirtual</symbol>,
-<symbol>NotifyInferior</symbol>,
-<symbol>NotifyNonlinear</symbol>,
-<symbol>NotifyNonlinearVirtual</symbol>,
-<symbol>NotifyPointer</symbol>,
-<symbol>NotifyPointerRoot</symbol>,
-or
-<symbol>NotifyDetailNone</symbol>.
-</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
-<type>XFocusInEvent</type>
-or
-<type>XFocusOutEvent</type>
-structures whose mode member is set to
-<symbol>NotifyNormal</symbol>.
-Focus events while grabbed are identified by
-<type>XFocusInEvent</type>
-or
-<type>XFocusOutEvent</type>
-structures whose mode member is set to
-<symbol>NotifyWhileGrabbed</symbol>.
-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
-<symbol>FocusOut</symbol>
-event on window A, with the detail member of the
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyAncestor</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusOut</symbol>
-event on each window between window A and window B, exclusive,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on window B, with the detail member of the
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyInferior</symbol>.
- </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
-<symbol>FocusIn</symbol>
-event on each window below window B, down to and including window P,
-with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
-<!-- .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
-<symbol>FocusOut</symbol>
-event on each window from window P up to but not including window A,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusOut</symbol>
-event on window A,
-with the detail member of the
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyInferior</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on each window between window A and window B, exclusive, with the
-detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on window B, with the detail member of the
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyAncestor</symbol>.
-<!-- .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
-<symbol>FocusOut</symbol>
-event on each window from window P up to but not including window A,
-with the detail member of the
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusOut</symbol>
-event on window A,
-with the detail member of the
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusOut</symbol>
-event on each window between window A and window C, exclusive,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on each window between C and B, exclusive,
-with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on window B, with the detail member of the
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If window P is an inferior of window B, it generates a
-<symbol>FocusIn</symbol>
-event on each window below window B down to and including window P,
-with the detail member of the
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
-<!-- .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
-<symbol>FocusOut</symbol>
-event on each window from window P up to but not including window A,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusOut</symbol>
-event on window A,
-with the detail member of the
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If window A is not a root window,
-it generates a
-<symbol>FocusOut</symbol>
-event on each window above window A up to and including its root,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If window B is not a root window,
-it generates a
-<symbol>FocusIn</symbol>
-event on each window from window B's root down to but not including
-window B, with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on window B, with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If window P is an inferior of window B, it generates a
-<symbol>FocusIn</symbol>
-event on each window below window B down to and including window P,
-with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
-<!-- .RE -->
- </para>
- </listitem>
- <listitem>
- <para>
-When the focus moves from window A to
-<symbol>PointerRoot</symbol>
-(events sent to the window under the pointer)
-or
-<symbol>None</symbol>
-(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
-<symbol>FocusOut</symbol>
-event on each window from window P up to but not including window A,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusOut</symbol>
-event on window A, with the detail member of the
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If window A is not a root window,
-it generates a
-<symbol>FocusOut</symbol>
-event on each window above window A up to and including its root,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on the root window of all screens, with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyPointerRoot</symbol>
-(or
-<symbol>NotifyDetailNone</symbol>).
- </para>
- </listitem>
- <listitem>
- <para>
-If the new focus is
-<symbol>PointerRoot</symbol>,
-it generates a
-<symbol>FocusIn</symbol>
-event on each window from window P's root down to and including window P,
-with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
-<!-- .RE -->
- </para>
- </listitem>
- <listitem>
- <para>
-When the focus moves from
-<symbol>PointerRoot</symbol>
-(events sent to the window under the pointer)
-or
-<symbol>None</symbol>
-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
-<symbol>PointerRoot</symbol>,
-it generates a
-<symbol>FocusOut</symbol>
-event on each window from window P up to and including window P's root,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusOut</symbol>
-event on all root windows,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyPointerRoot</symbol>
-(or
-<symbol>NotifyDetailNone</symbol>).
- </para>
- </listitem>
- <listitem>
- <para>
-If window A is not a root window,
-it generates a
-<symbol>FocusIn</symbol>
-event on each window from window A's root down to but not including window A,
-with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyNonlinearVirtual</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on window A,
-with the detail member of the
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyNonlinear</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If window P is an inferior of window A, it generates a
-<symbol>FocusIn</symbol>
-event on each window below window A down to and including window P,
-with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
-<!-- .RE -->
- </para>
- </listitem>
- <listitem>
- <para>
-When the focus moves from
-<symbol>PointerRoot</symbol>
-(events sent to the window under the pointer)
-to
-<symbol>None</symbol>
-(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
-<symbol>PointerRoot</symbol>,
-it generates a
-<symbol>FocusOut</symbol>
-event on each window from window P up to and including window P's root,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusOut</symbol>
-event on all root windows,
-with the detail member of each
-<type>XFocusOutEvent</type>
-structure set to either
-<symbol>NotifyPointerRoot</symbol>
-or
-<symbol>NotifyDetailNone</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-It generates a
-<symbol>FocusIn</symbol>
-event on all root windows,
-with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyDetailNone</symbol>
-or
-<symbol>NotifyPointerRoot</symbol>.
- </para>
- </listitem>
- <listitem>
- <para>
-If the new focus is
-<symbol>PointerRoot</symbol>,
-it generates a
-<symbol>FocusIn</symbol>
-event on each window from window P's root down to and including window P,
-with the detail member of each
-<type>XFocusInEvent</type>
-structure set to
-<symbol>NotifyPointer</symbol>.
-<!-- .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
-<type>XFocusInEvent</type>
-or
-<type>XFocusOutEvent</type>
-structures whose mode member is set to
-<symbol>NotifyGrab</symbol>.
-Focus events in which the keyboard grab deactivates
-are identified by
-<type>XFocusInEvent</type>
-or
-<type>XFocusOutEvent</type>
-structures whose mode member is set to
-<symbol>NotifyUngrab</symbol>
-(see
-<function>XGrabKeyboard</function>).
-</para>
-<itemizedlist>
- <listitem>
- <para>
-When a keyboard grab activates before generating any actual
-<symbol>KeyPress</symbol>
-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
-<symbol>FocusIn</symbol>
-and
-<symbol>FocusOut</symbol>
-events, with the mode members of the
-<type>XFocusInEvent</type>
-and
-<type>XFocusOutEvent</type>
-structures set to
-<symbol>NotifyGrab</symbol>.
-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
-<symbol>KeyRelease</symbol>
-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
-<symbol>FocusIn</symbol>
-and
-<symbol>FocusOut</symbol>
-events, with the mode members of the
-<type>XFocusInEvent</type>
-and
-<type>XFocusOutEvent</type>
-structures set to
-<symbol>NotifyUngrab</symbol>.
-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 -->
-<indexterm><primary>Events</primary><secondary>KeymapNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>KeymapNotify</primary></indexterm>
-The X server can report
-<symbol>KeymapNotify</symbol>
-events to clients that want information about changes in their keyboard state.
-</para>
-<para>
-<!-- .LP -->
-To receive
-<symbol>KeymapNotify</symbol>
-events, set the
-<symbol>KeymapStateMask</symbol>
-bit in the event-mask attribute of the window.
-The X server generates this event immediately after every
-<symbol>EnterNotify</symbol>
-and
-<symbol>FocusIn</symbol>
-event.
-</para>
-<para>
-<!-- .LP -->
-The structure for this event type contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XKeymapEvent</primary></indexterm>
-<!-- .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
-<symbol>Expose</symbol>
-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 -->
-<indexterm><primary>Events</primary><secondary>Expose</secondary></indexterm>
-<indexterm significance="preferred"><primary>Expose</primary></indexterm>
-The X server can report
-<symbol>Expose</symbol>
-events to clients wanting information about when the contents of window regions
-have been lost.
-The circumstances in which the X server generates
-<symbol>Expose</symbol>
-events are not as definite as those for other events.
-However, the X server never generates
-<symbol>Expose</symbol>
-events on windows whose class you specified as
-<symbol>InputOnly</symbol>.
-The X server can generate
-<symbol>Expose</symbol>
-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
-<symbol>Always</symbol>
-or
-<symbol>WhenMapped</symbol>.
-The regions decompose into an (arbitrary) set of rectangles,
-and an
-<symbol>Expose</symbol>
-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
-<symbol>Expose</symbol>
-events, such as raising a window.
-</para>
-<para>
-<!-- .LP -->
-To receive
-<symbol>Expose</symbol>
-events, set the
-<symbol>ExposureMask</symbol>
-bit in the event-mask attribute of the window.
-</para>
-<para>
-<!-- .LP -->
-The structure for this event type contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XExposeEvent</primary></indexterm>
-<!-- .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
-<symbol>Expose</symbol>
-events that are to follow.
-If count is zero, no more
-<symbol>Expose</symbol>
-events follow for this window.
-However, if count is nonzero, at least that number of
-<symbol>Expose</symbol>
-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
-<symbol>Expose</symbol>
-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 -->
-<indexterm><primary>Events</primary><secondary>GraphicsExpose</secondary></indexterm>
-<indexterm><primary>Events</primary><secondary>NoExpose</secondary></indexterm>
-<indexterm significance="preferred"><primary>GraphicsExpose</primary></indexterm>
-The X server can report
-<symbol>GraphicsExpose</symbol>
-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 -->
-<indexterm significance="preferred"><primary>NoExpose</primary></indexterm>
-The X server generates a
-<symbol>NoExpose</symbol>
-event whenever a graphics request that might
-produce a
-<symbol>GraphicsExpose</symbol>
-event does not produce any.
-In other words, the client is really asking for a
-<symbol>GraphicsExpose</symbol>
-event but instead receives a
-<symbol>NoExpose</symbol>
-event.
-</para>
-<para>
-<!-- .LP -->
-To receive
-<symbol>GraphicsExpose</symbol>
-or
-<symbol>NoExpose</symbol>
-events, you must first set the graphics-exposure
-attribute of the graphics context to
-<symbol>True</symbol>.
-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 -->
-<indexterm significance="preferred"><primary>XGraphicsExposeEvent</primary></indexterm>
-<!-- .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 -->
-<indexterm significance="preferred"><primary>XNoExposeEvent</primary></indexterm>
-<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
-<symbol>X_CopyArea</symbol>
-or
-<symbol>X_CopyPlane</symbol>.
-If it is
-<symbol>X_CopyArea</symbol>,
-a call to
-<function>XCopyArea</function>
-initiated the request.
-If it is
-<symbol>X_CopyPlane</symbol>,
-a call to
-<function>XCopyPlane</function>
-initiated the request.
-These constants are defined in
-<filename class="headerfile"><X11/Xproto.h></filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xproto.h></filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xproto.h></filename></secondary></indexterm>
-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
-<structname>XGraphicsExposeEvent</structname>
-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
-<symbol>GraphicsExpose</symbol>
-events to follow.
-If count is zero, no more
-<symbol>GraphicsExpose</symbol>
-events follow for this window.
-However, if count is nonzero, at least that number of
-<symbol>GraphicsExpose</symbol>
-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>
-<symbol>CirculateNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>ConfigureNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>CreateNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>DestroyNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>GravityNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>MapNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>MappingNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>ReparentNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>UnmapNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>VisibilityNotify</symbol>
-events
-<!-- .\" .SH 3 -->
- </para>
- </listitem>
-</itemizedlist>
-<sect2 id="CirculateNotify_Events">
-<title>CirculateNotify Events</title>
-<!-- .XS -->
-<!-- (SN CirculateNotify Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>CirculateNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>CirculateNotify</primary></indexterm>
-The X server can report
-<symbol>CirculateNotify</symbol>
-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
-<symbol>CirculateNotify</symbol>
-events, set the
-<symbol>StructureNotifyMask</symbol>
-bit in the event-mask attribute of the window
-or the
-<symbol>SubstructureNotifyMask</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XCirculateEvent</primary></indexterm>
-<!-- .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
-<systemitem class="event">StructureNotify</systemitem>
-or
-<systemitem class="event">SubstructureNotify</systemitem>
-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
-<symbol>PlaceOnTop</symbol>
-or
-<symbol>PlaceOnBottom</symbol>.
-If it is
-<symbol>PlaceOnTop</symbol>,
-the window is now on top of all siblings.
-If it is
-<symbol>PlaceOnBottom</symbol>,
-the window is now below all siblings.
-</para>
-</sect2>
-<sect2 id="ConfigureNotify_Events">
-<title>ConfigureNotify Events</title>
-<!-- .XS -->
-<!-- (SN ConfigureNotify Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>ConfigureNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>ConfigureNotify</primary></indexterm>
-The X server can report
-<symbol>ConfigureNotify</symbol>
-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
-<symbol>ConfigureNotify</symbol>
-events, set the
-<symbol>StructureNotifyMask</symbol>
-bit in the event-mask attribute of the window or the
-<symbol>SubstructureNotifyMask</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XConfigureEvent</primary></indexterm>
-<!-- .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
-<systemitem class="event">StructureNotify</systemitem>
-or
-<systemitem class="event">SubstructureNotify</systemitem>
-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
-<symbol>None</symbol>,
-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
-<symbol>True</symbol>.
-</para>
-</sect2>
-<sect2 id="CreateNotify_Events">
-<title>CreateNotify Events</title>
-<!-- .XS -->
-<!-- (SN CreateNotify Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>CreateNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>CreateNotify</primary></indexterm>
-The X server can report
-<symbol>CreateNotify</symbol>
-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
-<symbol>CreateNotify</symbol>
-events, set the
-<symbol>SubstructureNotifyMask</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XCreateWindowEvent</primary></indexterm>
-<!-- .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
-<symbol>True</symbol>.
-</para>
-</sect2>
-<sect2 id="DestroyNotify_Events">
-<title>DestroyNotify Events</title>
-<!-- .XS -->
-<!-- (SN DestroyNotify Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>DestroyNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>DestroyNotify</primary></indexterm>
-The X server can report
-<symbol>DestroyNotify</symbol>
-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
-<symbol>DestroyNotify</symbol>
-events is such that for any given window,
-<symbol>DestroyNotify</symbol>
-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
-<symbol>DestroyNotify</symbol>
-events, set the
-<symbol>StructureNotifyMask</symbol>
-bit in the event-mask attribute of the window or the
-<symbol>SubstructureNotifyMask</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XDestroyWindowEvent</primary></indexterm>
-<!-- .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
-<systemitem class="event">StructureNotify</systemitem>
-or
-<systemitem class="event">SubstructureNotify</systemitem>
-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 -->
-<indexterm><primary>Events</primary><secondary>GravityNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>GravityNotify</primary></indexterm>
-The X server can report
-<symbol>GravityNotify</symbol>
-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
-<symbol>GravityNotify</symbol>
-events, set the
-<symbol>StructureNotifyMask</symbol>
-bit in the event-mask attribute of the window or the
-<symbol>SubstructureNotifyMask</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XGravityEvent</primary></indexterm>
-<!-- .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
-<systemitem class="event">StructureNotify</systemitem>
-or
-<systemitem class="event">SubstructureNotify</systemitem>
-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 -->
-<indexterm><primary>Events</primary><secondary>MapNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>MapNotify</primary></indexterm>
-The X server can report
-<symbol>MapNotify</symbol>
-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
-<symbol>MapNotify</symbol>
-events, set the
-<symbol>StructureNotifyMask</symbol>
-bit in the event-mask attribute of the window or the
-<symbol>SubstructureNotifyMask</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XMapEvent</primary></indexterm>
-<!-- .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
-<systemitem class="event">StructureNotify</systemitem>
-or
-<systemitem class="event">SubstructureNotify</systemitem>
-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
-<symbol>True</symbol>,
-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 -->
-<indexterm><primary>Events</primary><secondary>MappingNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>MappingNotify</primary></indexterm>
-The X server reports
-<symbol>MappingNotify</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XMappingEvent</primary></indexterm>
-<!-- .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
-<symbol>MappingModifier</symbol>,
-<symbol>MappingKeyboard</symbol>,
-or
-<symbol>MappingPointer</symbol>.
-If it is
-<symbol>MappingModifier</symbol>,
-the modifier mapping was changed.
-If it is
-<symbol>MappingKeyboard</symbol>,
-the keyboard mapping was changed.
-If it is
-<symbol>MappingPointer</symbol>,
-the pointer button mapping was changed.
-The first_keycode and count members are set only
-if the request member was set to
-<symbol>MappingKeyboard</symbol>.
-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 -->
-<indexterm><primary>Events</primary><secondary>ReparentNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>ReparentNotify</primary></indexterm>
-The X server can report
-<symbol>ReparentNotify</symbol>
-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
-<symbol>ReparentNotify</symbol>
-events, set the
-<symbol>StructureNotifyMask</symbol>
-bit in the event-mask attribute of the window or the
-<symbol>SubstructureNotifyMask</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XReparentEvent</primary></indexterm>
-<!-- .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
-<systemitem class="event">StructureNotify</systemitem>
-or
-<systemitem class="event">SubstructureNotify</systemitem>
-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
-<symbol>True</symbol>.
-</para>
-</sect2>
-<sect2 id="UnmapNotify_Events">
-<title>UnmapNotify Events</title>
-<!-- .XS -->
-<!-- (SN UnmapNotify Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>UnmapNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>UnmapNotify</primary></indexterm>
-The X server can report
-<symbol>UnmapNotify</symbol>
-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
-<symbol>UnmapNotify</symbol>
-events, set the
-<symbol>StructureNotifyMask</symbol>
-bit in the event-mask attribute of the window or the
-<symbol>SubstructureNotifyMask</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XUnmapEvent</primary></indexterm>
-<!-- .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
-<systemitem class="event">StructureNotify</systemitem>
-or
-<systemitem class="event">SubstructureNotify</systemitem>
-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
-<symbol>True</symbol>
-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
-<symbol>UnmapGravity</symbol>.
-</para>
-</sect2>
-<sect2 id="VisibilityNotify_Events">
-<title>VisibilityNotify Events</title>
-<!-- .XS -->
-<!-- (SN VisibilityNotify Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>VisibilityNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>VisibilityNotify</primary></indexterm>
-The X server can report
-<symbol>VisibilityNotify</symbol>
-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
-<symbol>InputOnly</symbol>.
-</para>
-<para>
-<!-- .LP -->
-All
-<symbol>VisibilityNotify</symbol>
-events caused by a hierarchy change are generated
-after any hierarchy event
-(<symbol>UnmapNotify</symbol>,
-<symbol>MapNotify</symbol>,
-<symbol>ConfigureNotify</symbol>,
-<symbol>GravityNotify</symbol>,
-<symbol>CirculateNotify</symbol>)
-caused by that change. Any
-<symbol>VisibilityNotify</symbol>
-event on a given window is generated before any
-<symbol>Expose</symbol>
-events on that window, but it is not required that all
-<symbol>VisibilityNotify</symbol>
-events on all windows be generated before all
-<symbol>Expose</symbol>
-events on all windows.
-The X protocol does not constrain the ordering of
-<symbol>VisibilityNotify</symbol>
-events with
-respect to
-<symbol>FocusOut</symbol>,
-<symbol>EnterNotify</symbol>,
-and
-<symbol>LeaveNotify</symbol>
-events.
-</para>
-<para>
-<!-- .LP -->
-To receive
-<symbol>VisibilityNotify</symbol>
-events, set the
-<symbol>VisibilityChangeMask</symbol>
-bit in the event-mask attribute of the window.
-</para>
-<para>
-<!-- .LP -->
-The structure for this event type contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XVisibilityEvent</primary></indexterm>
-<!-- .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
-<symbol>VisibilityUnobscured</symbol>,
-<symbol>VisibilityPartiallyObscured</symbol>,
-or
-<symbol>VisibilityFullyObscured</symbol>.
-The X server ignores all of a window's subwindows
-when determining the visibility state of the window and processes
-<symbol>VisibilityNotify</symbol>
-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
-<structname>XVisibilityEvent</structname>
-structure set to
-<symbol>VisibilityUnobscured</symbol>.
- </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
-<structname>XVisibilityEvent</structname>
-structure set to
-<symbol>VisibilityPartiallyObscured</symbol>.
- </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
-<structname>XVisibilityEvent</structname>
-structure set to
-<symbol>VisibilityFullyObscured</symbol>.
- </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>
-<symbol>CirculateRequest</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>ConfigureRequest</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>MapRequest</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>ResizeRequest</symbol>
-events
- </para>
- </listitem>
-</itemizedlist>
-<sect2 id="CirculateRequest_Events">
-<title>CirculateRequest Events</title>
-<!-- .XS -->
-<!-- (SN CirculateRequest Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>CirculateRequest</secondary></indexterm>
-<indexterm significance="preferred"><primary>CirculateRequest</primary></indexterm>
-The X server can report
-<symbol>CirculateRequest</symbol>
-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
-<symbol>CirculateRequest</symbol>
-events, set the
-<symbol>SubstructureRedirectMask</symbol>
-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
-<symbol>SubstructureRedirectMask</symbol>
-on the window, the X server reports to you a
-<symbol>CirculateRequest</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XCirculateRequestEvent</primary></indexterm>
-<!-- .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
-<symbol>PlaceOnTop</symbol>
-or
-<symbol>PlaceOnBottom</symbol>.
-If it is
-<symbol>PlaceOnTop</symbol>,
-the subwindow should be on top of all siblings.
-If it is
-<symbol>PlaceOnBottom</symbol>,
-the subwindow should be below all siblings.
-</para>
-</sect2>
-<sect2 id="ConfigureRequest_Events">
-<title>ConfigureRequest Events</title>
-<!-- .XS -->
-<!-- (SN ConfigureRequest Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>ConfigureRequest</secondary></indexterm>
-<indexterm significance="preferred"><primary>ConfigureRequest</primary></indexterm>
-The X server can report
-<symbol>ConfigureRequest</symbol>
-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
-<symbol>ConfigureRequest</symbol>
-events, set the
-<symbol>SubstructureRedirectMask</symbol>
-bit in the event-mask attribute of the window.
-<symbol>ConfigureRequest</symbol>
-events are generated when a
-<systemitem>ConfigureWindow</systemitem>
-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
-<symbol>SubstructureRedirectMask</symbol>
-on the parent window and if the override-redirect attribute
-of the window is set to
-<symbol>False</symbol>,
-the X server reports a
-<symbol>ConfigureRequest</symbol>
-event to you and does not lower the specified window.
-</para>
-<para>
-<!-- .LP -->
-The structure for this event type contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XConfigureRequestEvent</primary></indexterm>
-<!-- .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
-<systemitem>ConfigureWindow</systemitem>
-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
-<symbol>None</symbol>
-and
-<symbol>Above</symbol>,
-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 -->
-<indexterm><primary>Events</primary><secondary>MapRequest</secondary></indexterm>
-<indexterm significance="preferred"><primary>MapRequest</primary></indexterm>
-The X server can report
-<symbol>MapRequest</symbol>
-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
-<symbol>False</symbol>.
-Clients initiate map window requests by calling
-<function>XMapWindow</function>,
-<function>XMapRaised</function>,
-or
-<function>XMapSubwindows</function>.
-</para>
-<para>
-<!-- .LP -->
-To receive
-<symbol>MapRequest</symbol>
-events, set the
-<symbol>SubstructureRedirectMask</symbol>
-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
-<symbol>MapRequest</symbol>
-instead.
-For example, suppose a client application calls
-<function>XMapWindow</function>
-to map a window.
-If you (usually a window manager) had selected
-<symbol>SubstructureRedirectMask</symbol>
-on the parent window and if the override-redirect attribute
-of the window is set to
-<symbol>False</symbol>,
-the X server reports a
-<symbol>MapRequest</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XMapRequestEvent</primary></indexterm>
-<!-- .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 -->
-<indexterm><primary>Events</primary><secondary>ResizeRequest</secondary></indexterm>
-<indexterm significance="preferred"><primary>ResizeRequest</primary></indexterm>
-The X server can report
-<symbol>ResizeRequest</symbol>
-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
-<symbol>ResizeRequest</symbol>
-events, set the
-<symbol>ResizeRedirect</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XResizeRequestEvent</primary></indexterm>
-<!-- .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 -->
-<indexterm><primary>Events</primary><secondary>ColormapNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>ColormapNotify</primary></indexterm>
-The X server can report
-<symbol>ColormapNotify</symbol>
-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
-<structname>XSetWindowAttributes</structname>
-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
-<symbol>ColormapNotify</symbol>
-events, set the
-<symbol>ColormapChangeMask</symbol>
-bit in the event-mask attribute of the window.
-</para>
-<para>
-<!-- .LP -->
-The structure for this event type contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XColormapEvent</primary></indexterm>
-<!-- .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
-<symbol>None</symbol>.
-The new member is set to indicate whether the colormap
-for the specified window was changed or installed or uninstalled
-and can be
-<symbol>True</symbol>
-or
-<symbol>False</symbol>.
-If it is
-<symbol>True</symbol>,
-the colormap was changed.
-If it is
-<symbol>False</symbol>,
-the colormap was installed or uninstalled.
-The state member is always set to indicate whether the colormap is installed or
-uninstalled and can be
-<symbol>ColormapInstalled</symbol>
-or
-<symbol>ColormapUninstalled</symbol>.
-</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>
-<symbol>ClientMessage</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>PropertyNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>SelectionClear</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>SelectionNotify</symbol>
-events
- </para>
- </listitem>
- <listitem>
- <para>
-<symbol>SelectionRequest</symbol>
-events
- </para>
- </listitem>
-</itemizedlist>
-<sect2 id="ClientMessage_Events">
-<title>ClientMessage Events</title>
-<!-- .XS -->
-<!-- (SN ClientMessage Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm><primary>Events</primary><secondary>ClientMessage</secondary></indexterm>
-<indexterm significance="preferred"><primary>ClientMessage</primary></indexterm>
-The X server generates
-<symbol>ClientMessage</symbol>
-events only when a client calls the function
-<function>XSendEvent</function>.
-</para>
-<para>
-<!-- .LP -->
-The structure for this event type contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XClientMessageEvent</primary></indexterm>
-<!-- .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 -->
-<indexterm><primary>Events</primary><secondary>PropertyNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>PropertyNotify</primary></indexterm>
-The X server can report
-<symbol>PropertyNotify</symbol>
-events to clients wanting information about property changes
-for a specified window.
-</para>
-<para>
-<!-- .LP -->
-To receive
-<symbol>PropertyNotify</symbol>
-events, set the
-<symbol>PropertyChangeMask</symbol>
-bit in the event-mask attribute of the window.
-</para>
-<para>
-<!-- .LP -->
-The structure for this event type contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XPropertyEvent</primary></indexterm>
-<!-- .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
-<symbol>PropertyNewValue</symbol>
-or
-<symbol>PropertyDelete</symbol>.
-The state member is set to
-<symbol>PropertyNewValue</symbol>
-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
-<symbol>PropertyDelete</symbol>
-when a property of the window is deleted using
-<function>XDeleteProperty</function>
-or, if the delete argument is
-<symbol>True</symbol>,
-<function>XGetWindowProperty</function>.
-</para>
-</sect2>
-<sect2 id="SelectionClear_Events">
-<title>SelectionClear Events</title>
-<!-- .XS -->
-<!-- (SN SelectionClear Events -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm ><primary>Events</primary><secondary>SelectionClear</secondary></indexterm>
-<indexterm significance="preferred"><primary>SelectionClear</primary></indexterm>
-The X server reports
-<symbol>SelectionClear</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XSelectionClearEvent</primary></indexterm>
-<!-- .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 -->
-<indexterm><primary>Events</primary><secondary>SelectionRequest</secondary></indexterm>
-<indexterm significance="preferred"><primary>SelectionRequest</primary></indexterm>
-The X server reports
-<symbol>SelectionRequest</symbol>
-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 -->
-<indexterm significance="preferred"><primary>XSelectionRequestEvent</primary></indexterm>
-<!-- .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
-<symbol>None</symbol>.
-The time member is set to the timestamp or
-<symbol>CurrentTime</symbol>
-value from the
-<systemitem>ConvertSelection</systemitem>
-request.
-</para>
-<para>
-<!-- .LP -->
-The owner should convert the selection based on the specified target type
-and send a
-<symbol>SelectionNotify</symbol>
-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 -->
-<indexterm><primary>Events</primary><secondary>SelectionNotify</secondary></indexterm>
-<indexterm significance="preferred"><primary>SelectionNotify</primary></indexterm>
-This event is generated by the X server in response to a
-<systemitem>ConvertSelection</systemitem>
-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
-<symbol>None</symbol>).
-</para>
-<para>
-<!-- .LP -->
-If
-<symbol>None</symbol>
-is specified as the property in the
-<systemitem>ConvertSelection</systemitem>
-protocol request, the owner should choose a property name,
-store the result as that property on the requestor window,
-and then send a
-<symbol>SelectionNotify</symbol>
-giving that actual property name.
-</para>
-<para>
-<!-- .LP -->
-The structure for this event type contains:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XSelectionEvent</primary></indexterm>
-<!-- .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
-<symbol>None</symbol>.
-The time member is set to the time the conversion took place and
-can be a timestamp or
-<symbol>CurrentTime</symbol>.
-<!-- .bp -->
-
-
-</para>
-</sect2>
-</sect1>
-</chapter>
+<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<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 +connection. 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 +<link linkend="event_handling_functions">the next chapter</link>. +</para> + +<sect1 id="Event_Types"> +<title>Event Types</title> +<!-- .XS --> +<!-- (SN Event Types --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Event</primary><secondary>types</secondary></indexterm> +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. +<indexterm><primary>Event</primary></indexterm> +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, +<symbol>MappingNotify</symbol> +events are always sent to all clients. +<indexterm><primary>Input Control</primary></indexterm> +<indexterm><primary>Output Control</primary></indexterm> +</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 +<filename class="headerfile"><X11/X.h></filename>, +<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm> +which is used when referring to an event type. +<indexterm><primary>Event</primary><secondary>categories</secondary></indexterm> +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><symbol>KeyPress</symbol>, + <symbol>KeyRelease</symbol></entry> + </row> + <row> + <entry>Pointer events</entry> + <entry><symbol>ButtonPress</symbol>, + <symbol>ButtonRelease</symbol>, + <symbol>MotionNotify</symbol></entry> + </row> + <row> + <entry>Window crossing events</entry> + <entry><symbol>EnterNotify</symbol>, + <symbol>LeaveNotify</symbol></entry> + </row> + <row> + <entry>Input focus events</entry> + <entry><symbol>FocusIn</symbol>, + <symbol>FocusOut</symbol></entry> + </row> + <row> + <entry>Keymap state notification event</entry> + <entry><symbol>KeymapNotify</symbol></entry> + </row> + <row> + <entry>Exposure events</entry> + <entry><symbol>Expose</symbol>, + <symbol>GraphicsExpose</symbol>, + <symbol>NoExpose</symbol></entry> + </row> + <row> + <entry>Structure control events</entry> + <entry><symbol>CirculateRequest</symbol>, + <symbol>ConfigureRequest</symbol>, + <symbol>MapRequest</symbol>, + <symbol>ResizeRequest</symbol></entry> + </row> + <row> + <entry>Window state notification events</entry> + <entry> + <symbol>CirculateNotify</symbol>, + <symbol>ConfigureNotify</symbol>, + <symbol>CreateNotify</symbol>, + <symbol>DestroyNotify</symbol>, + <symbol>GravityNotify</symbol>, + <symbol>MapNotify</symbol>, + <symbol>MappingNotify</symbol>, + <symbol>ReparentNotify</symbol>, + <symbol>UnmapNotify</symbol>, + <symbol>VisibilityNotify</symbol></entry> + </row> + <row> + <entry>Colormap state notification event</entry> + <entry><symbol>ColormapNotify</symbol></entry> + </row> + <row> + <entry>Client communication events</entry> + <entry><symbol>ClientMessage</symbol>, + <symbol>PropertyNotify</symbol>, + <symbol>SelectionClear</symbol>, + <symbol>SelectionNotify</symbol>, + <symbol>SelectionRequest</symbol></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 +<filename class="headerfile"><X11/Xlib.h></filename>. +<indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xlib.h></filename></secondary></indexterm> +All the event structures have the following common members: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XAnyEvent</primary></indexterm> +<!-- .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 +<symbol>GraphicsExpose</symbol> +event to a client application, it sends an +<structname>XGraphicsExposeEvent</structname> +structure with the type member set to +<symbol>GraphicsExpose</symbol>. +The display member is set to a pointer to the display the event was read on. +The send_event member is set to +<symbol>True</symbol> +if the event came from a +<systemitem>SendEvent</systemitem> +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 <link linkend="Event_Queue_Management">section 11.3</link>). +</para> +<para> +<!-- .LP --> +In addition to the individual structures declared for each event type, the +<structname>XEvent</structname> +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 +<structname>XEvent</structname> +union. +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XEvent</primary></indexterm> +<!-- .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 +<structname>XEvent</structname> +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 +<type>Bool</type> +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 --> +<indexterm significance="preferred"><primary>Event mask</primary></indexterm> +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 +<filename class="headerfile"><X11/X.h></filename>. +<indexterm type="file"><primary><filename class="headerfile">X11/X.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/X.h></filename></secondary></indexterm> +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 +<symbol>False</symbol>, +<symbol>GraphicsExpose</symbol> +and +<symbol>NoExpose</symbol> +are reported by default as a result of +<function>XCopyPlane</function> +and +<function>XCopyArea</function>. +<symbol>SelectionClear</symbol>, +<symbol>SelectionRequest</symbol>, +<symbol>SelectionNotify</symbol>, +or +<symbol>ClientMessage</symbol> +cannot be masked. +Selection-related events are only sent to clients cooperating +with selections +(see <link linkend="Obtaining_and_Changing_Window_Properties">section 4.5</link>). +When the keyboard or pointer mapping is changed, +<symbol>MappingNotify</symbol> +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><symbol>NoEventMask</symbol></entry> + <entry>No events wanted</entry> + </row> + <row> + <entry><symbol>KeyPressMask</symbol></entry> + <entry>Keyboard down events wanted</entry> + </row> + <row> + <entry><symbol>KeyReleaseMask</symbol></entry> + <entry>Keyboard up events wanted</entry> + </row> + <row> + <entry><symbol>ButtonPressMask</symbol></entry> + <entry>Pointer button down events wanted</entry> + </row> + <row> + <entry><symbol>ButtonReleaseMask</symbol></entry> + <entry>Pointer button up events wanted</entry> + </row> + <row> + <entry><symbol>EnterWindowMask</symbol></entry> + <entry>Pointer window entry events wanted</entry> + </row> + <row> + <entry><symbol>LeaveWindowMask</symbol></entry> + <entry>Pointer window leave events wanted</entry> + </row> + <row> + <entry><symbol>PointerMotionMask</symbol></entry> + <entry>Pointer motion events wanted</entry> + </row> + <row> + <entry><symbol>PointerMotionHintMask</symbol></entry> + <entry>Pointer motion hints wanted</entry> + </row> + <row> + <entry><symbol>Button1MotionMask</symbol></entry> + <entry>Pointer motion while button 1 down</entry> + </row> + <row> + <entry><symbol>Button2MotionMask</symbol></entry> + <entry>Pointer motion while button 2 down</entry> + </row> + <row> + <entry><symbol>Button3MotionMask</symbol></entry> + <entry>Pointer motion while button 3 down</entry> + </row> + <row> + <entry><symbol>Button4MotionMask</symbol></entry> + <entry>Pointer motion while button 4 down</entry> + </row> + <row> + <entry><symbol>Button5MotionMask</symbol></entry> + <entry>Pointer motion while button 5 down</entry> + </row> + <row> + <entry><symbol>ButtonMotionMask</symbol></entry> + <entry>Pointer motion while any button down</entry> + </row> + <row> + <entry><symbol>KeymapStateMask</symbol></entry> + <entry>Keyboard state wanted at window entry and focus in</entry> + </row> + <row> + <entry><symbol>ExposureMask</symbol></entry> + <entry>Any exposure wanted</entry> + </row> + <row> + <entry><symbol>VisibilityChangeMask</symbol></entry> + <entry>Any change in visibility wanted</entry> + </row> + <row> + <entry><symbol>StructureNotifyMask</symbol></entry> + <entry>Any change in window structure wanted</entry> + </row> + <row> + <entry><symbol>ResizeRedirectMask</symbol></entry> + <entry>Redirect resize of this window</entry> + </row> + <row> + <entry><symbol>SubstructureNotifyMask</symbol></entry> + <entry>Substructure notification wanted</entry> + </row> + <row> + <entry><symbol>SubstructureRedirectMask</symbol></entry> + <entry>Redirect structure requests on children</entry> + </row> + <row> + <entry><symbol>FocusChangeMask</symbol></entry> + <entry>Any change in input focus wanted</entry> + </row> + <row> + <entry><symbol>PropertyChangeMask</symbol></entry> + <entry>Any change in property wanted</entry> + </row> + <row> + <entry><symbol>ColormapChangeMask</symbol></entry> + <entry>Any change in colormap wanted</entry> + </row> + <row> + <entry><symbol>OwnerGrabButtonMask</symbol></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 +<symbol>ButtonPressMask</symbol>, +the X server sends back only +<symbol>ButtonPress</symbol> +events. +<indexterm><primary>CurrentTime</primary></indexterm> +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 +<symbol>SubstructureNotifyMask</symbol>, +the X server can send back +<symbol>CirculateNotify</symbol>, +<symbol>ConfigureNotify</symbol>, +<symbol>CreateNotify</symbol>, +<symbol>DestroyNotify</symbol>, +<symbol>GravityNotify</symbol>, +<symbol>MapNotify</symbol>, +<symbol>ReparentNotify</symbol>, +or +<symbol>UnmapNotify</symbol> +events. +</para> +<para> +<!-- .LP --> +In another case, +two event masks can map to one event type. +For example, +if you pass either +<symbol>PointerMotionMask</symbol> +or +<symbol>ButtonMotionMask</symbol>, +the X server sends back +a +<symbol>MotionNotify</symbol> +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><symbol>GrabModeAsync</symbol></entry> + </row> + <row> + <entry><emphasis remap='I'>keyboard_mode</emphasis></entry> + <entry><symbol>GrabModeAsync</symbol></entry> + </row> + <row> + <entry><emphasis remap='I'>owner_events</emphasis></entry> + <entry><symbol>True</symbol>, + if the client has selected + <symbol>OwnerGrabButtonMask</symbol> + on the event window, + otherwise + <symbol>False</symbol></entry> + </row> + <row> + <entry><emphasis remap='I'>confine_to</emphasis></entry> + <entry><symbol>None</symbol></entry> + </row> + <row> + <entry><emphasis remap='I'>cursor</emphasis></entry> + <entry><symbol>None</symbol></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 --> +<indexterm><primary>Events</primary><secondary>ButtonPress</secondary></indexterm> +<indexterm><primary>Events</primary><secondary>ButtonRelease</secondary></indexterm> +<indexterm><primary>Events</primary><secondary>KeyPress</secondary></indexterm> +<indexterm><primary>Events</primary><secondary>KeyRelease</secondary></indexterm> +<indexterm><primary>Events</primary><secondary>MotionNotify</secondary></indexterm> +This section discusses the processing that occurs for the +keyboard events +<symbol>KeyPress</symbol> +and +<symbol>KeyRelease</symbol> +and the pointer events +<symbol>ButtonPress</symbol>, +<symbol>ButtonRelease</symbol>, +and +<symbol>MotionNotify</symbol>. +For information about the keyboard event-handling utilities, +see <link linkend="event_handling_functions">chapter 11</link>. +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>KeyPress</primary></indexterm> +<indexterm significance="preferred"><primary>KeyRelease</primary></indexterm> +The X server reports +<symbol>KeyPress</symbol> +or +<symbol>KeyRelease</symbol> +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. +<indexterm significance="preferred"><primary>ButtonPress</primary></indexterm> +<indexterm significance="preferred"><primary>ButtonRelease</primary></indexterm> +The X server reports +<symbol>ButtonPress</symbol> +or +<symbol>ButtonRelease</symbol> +events to clients wanting information about buttons that logically change state. +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>MotionNotify</primary></indexterm> +The X server reports +<symbol>MotionNotify</symbol> +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 +<symbol>MotionNotify</symbol> +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 +<symbol>KeyPress</symbol>, +<symbol>KeyRelease</symbol>, +<symbol>ButtonPress</symbol>, +and +<symbol>ButtonRelease</symbol> +events, set +<symbol>KeyPressMask</symbol>, +<symbol>KeyReleaseMask</symbol>, +<symbol>ButtonPressMask</symbol>, +and +<symbol>ButtonReleaseMask</symbol> +bits in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +To receive +<symbol>MotionNotify</symbol> +events, set one or more of the following event +masks bits in the event-mask attribute of the window. +</para> +<itemizedlist> + <listitem> + <para> +<symbol>Button1MotionMask</symbol> - <symbol>Button5MotionMask</symbol> + </para> + </listitem> + <listitem> + <para> +The client application receives +<symbol>MotionNotify</symbol> +events only when one or more of the specified buttons is pressed. + </para> + </listitem> + <listitem> + <para> +<symbol>ButtonMotionMask</symbol> + </para> + </listitem> + <listitem> + <para> +The client application receives +<symbol>MotionNotify</symbol> +events only when at least one button is pressed. + </para> + </listitem> + <listitem> + <para> +<symbol>PointerMotionMask</symbol> + </para> + </listitem> + <listitem> + <para> +The client application receives +<symbol>MotionNotify</symbol> +events independent of the state of +the pointer buttons. + </para> + </listitem> + <listitem> + <para> +<symbol>PointerMotionHintMask</symbol> + </para> + </listitem> + <listitem> + <para> +If +<symbol>PointerMotionHintMask</symbol> +is selected in combination with one or more of the above masks, +the X server is free to send only one +<symbol>MotionNotify</symbol> +event (with the is_hint member of the +<type>XPointerMovedEvent</type> +structure set to +<symbol>NotifyHint</symbol>) +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 +<symbol>MotionNotify</symbol> +events without is_hint set to +<symbol>NotifyHint</symbol>. + </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 +<symbol>True</symbol> +or +<symbol>False</symbol>. +If +<symbol>True</symbol>, +the event and root windows are on the same screen. +If +<symbol>False</symbol>, +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 +<symbol>None</symbol>. +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: +<symbol>Button1Mask</symbol>, +<symbol>Button2Mask</symbol>, +<symbol>Button3Mask</symbol>, +<symbol>Button4Mask</symbol>, +<symbol>Button5Mask</symbol>, +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +and +<symbol>Mod5Mask</symbol>. +</para> +<para> +<!-- .LP --> +Each of these structures also has a member that indicates the detail. +For the +<type>XKeyPressedEvent</type> +and +<type>XKeyReleasedEvent</type> +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 <link linkend="Manipulating_the_Keyboard_Encoding">12.7</link> + and <link linkend="Using_Keyboard_Utility_Functions">16.1</link>). +</para> +<para> +<!-- .LP --> +For the +<type>XButtonPressedEvent</type> +and +<type>XButtonReleasedEvent</type> +structures, this member is called button. +It represents the pointer button that changed state and can be the +<symbol>Button1</symbol>, +<symbol>Button2</symbol>, +<symbol>Button3</symbol>, +<symbol>Button4</symbol>, +or +<symbol>Button5</symbol> +value. +For the +<type>XPointerMovedEvent</type> +structure, this member is called is_hint. +It can be set to +<symbol>NotifyNormal</symbol> +or +<symbol>NotifyHint</symbol>. +</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><symbol>Button1MotionMask</symbol></entry> + <entry>(1L<<8)</entry> + </row> + <row> + <entry><symbol>Button2MotionMask</symbol></entry> + <entry>(1L<<9)</entry> + </row> + <row> + <entry><symbol>Button3MotionMask</symbol></entry> + <entry>(1L<<10)</entry> + </row> + <row> + <entry><symbol>Button4MotionMask</symbol></entry> + <entry>(1L<<11)</entry> + </row> + <row> + <entry><symbol>Button5MotionMask</symbol></entry> + <entry>(1L<<12)</entry> + </row> + <row> + <entry><symbol>Button1Mask</symbol></entry> + <entry>(1<<8)</entry> + </row> + <row> + <entry><symbol>Button2Mask</symbol></entry> + <entry>(1<<9)</entry> + </row> + <row> + <entry><symbol>Button3Mask</symbol></entry> + <entry>(1<<10)</entry> + </row> + <row> + <entry><symbol>Button4Mask</symbol></entry> + <entry>(1<<11)</entry> + </row> + <row> + <entry><symbol>Button5Mask</symbol></entry> + <entry>(1<<12)</entry> + </row> + <row> + <entry><symbol>ShiftMask</symbol></entry> + <entry>(1<<0)</entry> + </row> + <row> + <entry><symbol>LockMask</symbol></entry> + <entry>(1<<1)</entry> + </row> + <row> + <entry><symbol>ControlMask</symbol></entry> + <entry>(1<<2)</entry> + </row> + <row> + <entry><symbol>Mod1Mask</symbol></entry> + <entry>(1<<3)</entry> + </row> + <row> + <entry><symbol>Mod2Mask</symbol></entry> + <entry>(1<<4)</entry> + </row> + <row> + <entry><symbol>Mod3Mask</symbol></entry> + <entry>(1<<5)</entry> + </row> + <row> + <entry><symbol>Mod4Mask</symbol></entry> + <entry>(1<<6)</entry> + </row> + <row> + <entry><symbol>Mod5Mask</symbol></entry> + <entry>(1<<7)</entry> + </row> + <row> + <entry><symbol>Button1</symbol></entry> + <entry>1</entry> + </row> + <row> + <entry><symbol>Button2</symbol></entry> + <entry>2</entry> + </row> + <row> + <entry><symbol>Button3</symbol></entry> + <entry>3</entry> + </row> + <row> + <entry><symbol>Button4</symbol></entry> + <entry>4</entry> + </row> + <row> + <entry><symbol>Button5</symbol></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 --> +<indexterm><primary>Events</primary><secondary>EnterNotify</secondary></indexterm> +<indexterm><primary>Events</primary><secondary>LeaveNotify</secondary></indexterm> +This section describes the processing that +occurs for the window crossing events +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol>. +<indexterm significance="preferred"><primary>EnterNotify</primary></indexterm> +<indexterm significance="preferred"><primary>LeaveNotify</primary></indexterm> +If a pointer motion or a window hierarchy change causes the +pointer to be in a different window than before, the X server reports +<symbol>EnterNotify</symbol> +or +<symbol>LeaveNotify</symbol> +events to clients who have selected for these events. +All +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol> +events caused by a hierarchy change are +generated after any hierarchy event +(<symbol>UnmapNotify</symbol>, +<symbol>MapNotify</symbol>, +<symbol>ConfigureNotify</symbol>, +<symbol>GravityNotify</symbol>, +<symbol>CirculateNotify</symbol>) +caused by that change; +however, the X protocol does not constrain the ordering of +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol> +events with respect to +<symbol>FocusOut</symbol>, +<symbol>VisibilityNotify</symbol>, +and +<symbol>Expose</symbol> +events. +</para> +<para> +<!-- .LP --> +This contrasts with +<symbol>MotionNotify</symbol> +events, which are also generated when the pointer moves +but only when the pointer motion begins and ends in a single window. +An +<symbol>EnterNotify</symbol> +or +<symbol>LeaveNotify</symbol> +event also can be generated when some client application calls +<function>XGrabPointer</function> +and +<function>XUngrabPointer</function>. +</para> +<para> +<!-- .LP --> +To receive +<symbol>EnterNotify</symbol> +or +<symbol>LeaveNotify</symbol> +events, set the +<symbol>EnterWindowMask</symbol> +or +<symbol>LeaveWindowMask</symbol> +bits of the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for these event types contains: +</para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XCrossingEvent</primary></indexterm> +<indexterm significance="preferred"><primary>XEnterWindowEvent</primary></indexterm> +<indexterm significance="preferred"><primary>XLeaveWindowEvent</primary></indexterm> +<!-- .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 +<symbol>EnterNotify</symbol> +or +<symbol>LeaveNotify</symbol> +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 +<symbol>LeaveNotify</symbol> +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 +<symbol>None</symbol>. +For an +<symbol>EnterNotify</symbol> +event, if a child of the event window contains the final pointer position, +the subwindow component is set to that child or +<symbol>None</symbol>. +</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 +<symbol>True</symbol> +or +<symbol>False</symbol>. +If +<symbol>True</symbol>, +the event and root windows are on the same screen. +If +<symbol>False</symbol>, +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 +<symbol>True</symbol> +or +<symbol>False</symbol>. +If +<symbol>True</symbol>, +the event window is the focus window or an inferior of the focus window. +If +<symbol>False</symbol>, +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: +<symbol>Button1Mask</symbol>, +<symbol>Button2Mask</symbol>, +<symbol>Button3Mask</symbol>, +<symbol>Button4Mask</symbol>, +<symbol>Button5Mask</symbol>, +<symbol>ShiftMask</symbol>, +<symbol>LockMask</symbol>, +<symbol>ControlMask</symbol>, +<symbol>Mod1Mask</symbol>, +<symbol>Mod2Mask</symbol>, +<symbol>Mod3Mask</symbol>, +<symbol>Mod4Mask</symbol>, +<symbol>Mod5Mask</symbol>. +</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 +<symbol>NotifyNormal</symbol>, +<symbol>NotifyGrab</symbol>, +or +<symbol>NotifyUngrab</symbol>. +</para> +<para> +<!-- .LP --> +The detail member is set to indicate the notify detail and can be +<symbol>NotifyAncestor</symbol>, +<symbol>NotifyVirtual</symbol>, +<symbol>NotifyInferior</symbol>, +<symbol>NotifyNonlinear</symbol>, +or +<symbol>NotifyNonlinearVirtual</symbol>. +</para> +<sect2 id="Normal_Entry_Exit_Events"> +<title>Normal Entry/Exit Events</title> +<!-- .XS --> +<!-- (SN Normal Entry/Exit Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol> +events are generated when the pointer moves from +one window to another window. +Normal events are identified by +<type>XEnterWindowEvent</type> +or +<type>XLeaveWindowEvent</type> +structures whose mode member is set to +<symbol>NotifyNormal</symbol>. +</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 +<symbol>LeaveNotify</symbol> +event on window A, with the detail member of the +<type>XLeaveWindowEvent</type> +structure set to +<symbol>NotifyAncestor</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>LeaveNotify</symbol> +event on each window between window A and window B, exclusive, +with the detail member of each +<type>XLeaveWindowEvent</type> +structure set to +<symbol>NotifyVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates an +<symbol>EnterNotify</symbol> +event on window B, with the detail member of the +<type>XEnterWindowEvent</type> +structure set to +<symbol>NotifyInferior</symbol>. +<!-- .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 +<symbol>LeaveNotify</symbol> +event on window A, +with the detail member of the +<type>XLeaveWindowEvent</type> +structure set to +<symbol>NotifyInferior</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates an +<symbol>EnterNotify</symbol> +event on each window between window A and window B, exclusive, with the +detail member of each +<type>XEnterWindowEvent</type> +structure set to +<symbol>NotifyVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates an +<symbol>EnterNotify</symbol> +event on window B, with the detail member of the +<type>XEnterWindowEvent</type> +structure set to +<symbol>NotifyAncestor</symbol>. +<!-- .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 +<symbol>LeaveNotify</symbol> +event on window A, +with the detail member of the +<type>XLeaveWindowEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>LeaveNotify</symbol> +event on each window between window A and window C, exclusive, +with the detail member of each +<type>XLeaveWindowEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates an +<symbol>EnterNotify</symbol> +event on each window between window C and window B, exclusive, +with the detail member of each +<type>XEnterWindowEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates an +<symbol>EnterNotify</symbol> +event on window B, with the detail member of the +<type>XEnterWindowEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. +<!-- .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 +<symbol>LeaveNotify</symbol> +event on window A, +with the detail member of the +<type>XLeaveWindowEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. + </para> + </listitem> + <listitem> + <para> +If window A is not a root window, +it generates a +<symbol>LeaveNotify</symbol> +event on each window above window A up to and including its root, +with the detail member of each +<type>XLeaveWindowEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +If window B is not a root window, +it generates an +<symbol>EnterNotify</symbol> +event on each window from window B's root down to but not including +window B, with the detail member of each +<type>XEnterWindowEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates an +<symbol>EnterNotify</symbol> +event on window B, with the detail member of the +<type>XEnterWindowEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. +<!-- .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 +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol> +events are generated when a pointer grab activates or deactivates. +Events in which the pointer grab activates +are identified by +<type>XEnterWindowEvent</type> +or +<type>XLeaveWindowEvent</type> +structures whose mode member is set to +<symbol>NotifyGrab</symbol>. +Events in which the pointer grab deactivates +are identified by +<type>XEnterWindowEvent</type> +or +<type>XLeaveWindowEvent</type> +structures whose mode member is set to +<symbol>NotifyUngrab</symbol> +(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 +<symbol>ButtonPress</symbol> +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 +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol> +events (see <link linkend="Normal_Entry_Exit_Events">section 10.6.1</link>) +with the mode members of the +<type>XEnterWindowEvent</type> +and +<type>XLeaveWindowEvent</type> +structures set to +<symbol>NotifyGrab</symbol>. +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 +<symbol>ButtonRelease</symbol> +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 +<symbol>EnterNotify</symbol> +and +<symbol>LeaveNotify</symbol> +events (see <link linkend="Normal_Entry_Exit_Events">section 10.6.1</link>) +with the mode members of the +<type>XEnterWindowEvent</type> +and +<type>XLeaveWindowEvent</type> +structures set to +<symbol>NotifyUngrab</symbol>. +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 --> +<indexterm><primary>Events</primary><secondary>FocusIn</secondary></indexterm> +<indexterm><primary>Events</primary><secondary>FocusOut</secondary></indexterm> +This section describes the processing that occurs for the input focus events +<symbol>FocusIn</symbol> +and +<symbol>FocusOut</symbol>. +<indexterm significance="preferred"><primary>FocusIn</primary></indexterm> +<indexterm significance="preferred"><primary>FocusOut</primary></indexterm> +The X server can report +<symbol>FocusIn</symbol> +or +<symbol>FocusOut</symbol> +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 +<symbol>FocusIn</symbol> +or +<symbol>FocusOut</symbol> +events, set the +<symbol>FocusChangeMask</symbol> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for these event types contains: +</para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XFocusChangeEvent</primary></indexterm> +<indexterm significance="preferred"><primary>XFocusInEvent</primary></indexterm> +<indexterm significance="preferred"><primary>XFocusOutEvent</primary></indexterm> +<!-- .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 +<symbol>FocusIn</symbol> +or +<symbol>FocusOut</symbol> +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 +<symbol>NotifyNormal</symbol>, +<symbol>NotifyWhileGrabbed</symbol>, +<symbol>NotifyGrab</symbol>, +or +<symbol>NotifyUngrab</symbol>. +</para> +<para> +<!-- .LP --> +All +<symbol>FocusOut</symbol> +events caused by a window unmap are generated after any +<symbol>UnmapNotify</symbol> +event; however, the X protocol does not constrain the ordering of +<symbol>FocusOut</symbol> +events with respect to +generated +<symbol>EnterNotify</symbol>, +<symbol>LeaveNotify</symbol>, +<symbol>VisibilityNotify</symbol>, +and +<symbol>Expose</symbol> +events. +</para> +<para> +<!-- .LP --> +Depending on the event mode, +the detail member is set to indicate the notify detail and can be +<symbol>NotifyAncestor</symbol>, +<symbol>NotifyVirtual</symbol>, +<symbol>NotifyInferior</symbol>, +<symbol>NotifyNonlinear</symbol>, +<symbol>NotifyNonlinearVirtual</symbol>, +<symbol>NotifyPointer</symbol>, +<symbol>NotifyPointerRoot</symbol>, +or +<symbol>NotifyDetailNone</symbol>. +</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 +<type>XFocusInEvent</type> +or +<type>XFocusOutEvent</type> +structures whose mode member is set to +<symbol>NotifyNormal</symbol>. +Focus events while grabbed are identified by +<type>XFocusInEvent</type> +or +<type>XFocusOutEvent</type> +structures whose mode member is set to +<symbol>NotifyWhileGrabbed</symbol>. +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 +<symbol>FocusOut</symbol> +event on window A, with the detail member of the +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyAncestor</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusOut</symbol> +event on each window between window A and window B, exclusive, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on window B, with the detail member of the +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyInferior</symbol>. + </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 +<symbol>FocusIn</symbol> +event on each window below window B, down to and including window P, +with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. +<!-- .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 +<symbol>FocusOut</symbol> +event on each window from window P up to but not including window A, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusOut</symbol> +event on window A, +with the detail member of the +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyInferior</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on each window between window A and window B, exclusive, with the +detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on window B, with the detail member of the +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyAncestor</symbol>. +<!-- .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 +<symbol>FocusOut</symbol> +event on each window from window P up to but not including window A, +with the detail member of the +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusOut</symbol> +event on window A, +with the detail member of the +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusOut</symbol> +event on each window between window A and window C, exclusive, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on each window between C and B, exclusive, +with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on window B, with the detail member of the +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window B, it generates a +<symbol>FocusIn</symbol> +event on each window below window B down to and including window P, +with the detail member of the +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. +<!-- .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 +<symbol>FocusOut</symbol> +event on each window from window P up to but not including window A, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusOut</symbol> +event on window A, +with the detail member of the +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. + </para> + </listitem> + <listitem> + <para> +If window A is not a root window, +it generates a +<symbol>FocusOut</symbol> +event on each window above window A up to and including its root, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +If window B is not a root window, +it generates a +<symbol>FocusIn</symbol> +event on each window from window B's root down to but not including +window B, with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on window B, with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window B, it generates a +<symbol>FocusIn</symbol> +event on each window below window B down to and including window P, +with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from window A to +<symbol>PointerRoot</symbol> +(events sent to the window under the pointer) +or +<symbol>None</symbol> +(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 +<symbol>FocusOut</symbol> +event on each window from window P up to but not including window A, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusOut</symbol> +event on window A, with the detail member of the +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. + </para> + </listitem> + <listitem> + <para> +If window A is not a root window, +it generates a +<symbol>FocusOut</symbol> +event on each window above window A up to and including its root, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on the root window of all screens, with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyPointerRoot</symbol> +(or +<symbol>NotifyDetailNone</symbol>). + </para> + </listitem> + <listitem> + <para> +If the new focus is +<symbol>PointerRoot</symbol>, +it generates a +<symbol>FocusIn</symbol> +event on each window from window P's root down to and including window P, +with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from +<symbol>PointerRoot</symbol> +(events sent to the window under the pointer) +or +<symbol>None</symbol> +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 +<symbol>PointerRoot</symbol>, +it generates a +<symbol>FocusOut</symbol> +event on each window from window P up to and including window P's root, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusOut</symbol> +event on all root windows, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyPointerRoot</symbol> +(or +<symbol>NotifyDetailNone</symbol>). + </para> + </listitem> + <listitem> + <para> +If window A is not a root window, +it generates a +<symbol>FocusIn</symbol> +event on each window from window A's root down to but not including window A, +with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyNonlinearVirtual</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on window A, +with the detail member of the +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyNonlinear</symbol>. + </para> + </listitem> + <listitem> + <para> +If window P is an inferior of window A, it generates a +<symbol>FocusIn</symbol> +event on each window below window A down to and including window P, +with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. +<!-- .RE --> + </para> + </listitem> + <listitem> + <para> +When the focus moves from +<symbol>PointerRoot</symbol> +(events sent to the window under the pointer) +to +<symbol>None</symbol> +(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 +<symbol>PointerRoot</symbol>, +it generates a +<symbol>FocusOut</symbol> +event on each window from window P up to and including window P's root, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusOut</symbol> +event on all root windows, +with the detail member of each +<type>XFocusOutEvent</type> +structure set to either +<symbol>NotifyPointerRoot</symbol> +or +<symbol>NotifyDetailNone</symbol>. + </para> + </listitem> + <listitem> + <para> +It generates a +<symbol>FocusIn</symbol> +event on all root windows, +with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyDetailNone</symbol> +or +<symbol>NotifyPointerRoot</symbol>. + </para> + </listitem> + <listitem> + <para> +If the new focus is +<symbol>PointerRoot</symbol>, +it generates a +<symbol>FocusIn</symbol> +event on each window from window P's root down to and including window P, +with the detail member of each +<type>XFocusInEvent</type> +structure set to +<symbol>NotifyPointer</symbol>. +<!-- .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 +<type>XFocusInEvent</type> +or +<type>XFocusOutEvent</type> +structures whose mode member is set to +<symbol>NotifyGrab</symbol>. +Focus events in which the keyboard grab deactivates +are identified by +<type>XFocusInEvent</type> +or +<type>XFocusOutEvent</type> +structures whose mode member is set to +<symbol>NotifyUngrab</symbol> +(see +<function>XGrabKeyboard</function>). +</para> +<itemizedlist> + <listitem> + <para> +When a keyboard grab activates before generating any actual +<symbol>KeyPress</symbol> +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 +<symbol>FocusIn</symbol> +and +<symbol>FocusOut</symbol> +events, with the mode members of the +<type>XFocusInEvent</type> +and +<type>XFocusOutEvent</type> +structures set to +<symbol>NotifyGrab</symbol>. +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 +<symbol>KeyRelease</symbol> +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 +<symbol>FocusIn</symbol> +and +<symbol>FocusOut</symbol> +events, with the mode members of the +<type>XFocusInEvent</type> +and +<type>XFocusOutEvent</type> +structures set to +<symbol>NotifyUngrab</symbol>. +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 --> +<indexterm><primary>Events</primary><secondary>KeymapNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>KeymapNotify</primary></indexterm> +The X server can report +<symbol>KeymapNotify</symbol> +events to clients that want information about changes in their keyboard state. +</para> +<para> +<!-- .LP --> +To receive +<symbol>KeymapNotify</symbol> +events, set the +<symbol>KeymapStateMask</symbol> +bit in the event-mask attribute of the window. +The X server generates this event immediately after every +<symbol>EnterNotify</symbol> +and +<symbol>FocusIn</symbol> +event. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XKeymapEvent</primary></indexterm> +<!-- .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 +<symbol>Expose</symbol> +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 --> +<indexterm><primary>Events</primary><secondary>Expose</secondary></indexterm> +<indexterm significance="preferred"><primary>Expose</primary></indexterm> +The X server can report +<symbol>Expose</symbol> +events to clients wanting information about when the contents of window regions +have been lost. +The circumstances in which the X server generates +<symbol>Expose</symbol> +events are not as definite as those for other events. +However, the X server never generates +<symbol>Expose</symbol> +events on windows whose class you specified as +<symbol>InputOnly</symbol>. +The X server can generate +<symbol>Expose</symbol> +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 +<symbol>Always</symbol> +or +<symbol>WhenMapped</symbol>. +The regions decompose into an (arbitrary) set of rectangles, +and an +<symbol>Expose</symbol> +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 +<symbol>Expose</symbol> +events, such as raising a window. +</para> +<para> +<!-- .LP --> +To receive +<symbol>Expose</symbol> +events, set the +<symbol>ExposureMask</symbol> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XExposeEvent</primary></indexterm> +<!-- .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 +<symbol>Expose</symbol> +events that are to follow. +If count is zero, no more +<symbol>Expose</symbol> +events follow for this window. +However, if count is nonzero, at least that number of +<symbol>Expose</symbol> +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 +<symbol>Expose</symbol> +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 --> +<indexterm><primary>Events</primary><secondary>GraphicsExpose</secondary></indexterm> +<indexterm><primary>Events</primary><secondary>NoExpose</secondary></indexterm> +<indexterm significance="preferred"><primary>GraphicsExpose</primary></indexterm> +The X server can report +<symbol>GraphicsExpose</symbol> +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 --> +<indexterm significance="preferred"><primary>NoExpose</primary></indexterm> +The X server generates a +<symbol>NoExpose</symbol> +event whenever a graphics request that might +produce a +<symbol>GraphicsExpose</symbol> +event does not produce any. +In other words, the client is really asking for a +<symbol>GraphicsExpose</symbol> +event but instead receives a +<symbol>NoExpose</symbol> +event. +</para> +<para> +<!-- .LP --> +To receive +<symbol>GraphicsExpose</symbol> +or +<symbol>NoExpose</symbol> +events, you must first set the graphics-exposure +attribute of the graphics context to +<symbol>True</symbol>. +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 --> +<indexterm significance="preferred"><primary>XGraphicsExposeEvent</primary></indexterm> +<!-- .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 --> +<indexterm significance="preferred"><primary>XNoExposeEvent</primary></indexterm> +<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 +<symbol>X_CopyArea</symbol> +or +<symbol>X_CopyPlane</symbol>. +If it is +<symbol>X_CopyArea</symbol>, +a call to +<function>XCopyArea</function> +initiated the request. +If it is +<symbol>X_CopyPlane</symbol>, +a call to +<function>XCopyPlane</function> +initiated the request. +These constants are defined in +<filename class="headerfile"><X11/Xproto.h></filename>. +<indexterm type="file"><primary><filename class="headerfile">X11/Xproto.h</filename></primary></indexterm> +<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xproto.h></filename></secondary></indexterm> +<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xproto.h></filename></secondary></indexterm> +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 +<structname>XGraphicsExposeEvent</structname> +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 +<symbol>GraphicsExpose</symbol> +events to follow. +If count is zero, no more +<symbol>GraphicsExpose</symbol> +events follow for this window. +However, if count is nonzero, at least that number of +<symbol>GraphicsExpose</symbol> +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> +<symbol>CirculateNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>ConfigureNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>CreateNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>DestroyNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>GravityNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>MapNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>MappingNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>ReparentNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>UnmapNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>VisibilityNotify</symbol> +events +<!-- .\" .SH 3 --> + </para> + </listitem> +</itemizedlist> +<sect2 id="CirculateNotify_Events"> +<title>CirculateNotify Events</title> +<!-- .XS --> +<!-- (SN CirculateNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>CirculateNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>CirculateNotify</primary></indexterm> +The X server can report +<symbol>CirculateNotify</symbol> +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 +<symbol>CirculateNotify</symbol> +events, set the +<symbol>StructureNotifyMask</symbol> +bit in the event-mask attribute of the window +or the +<symbol>SubstructureNotifyMask</symbol> +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 --> +<indexterm significance="preferred"><primary>XCirculateEvent</primary></indexterm> +<!-- .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 +<systemitem class="event">StructureNotify</systemitem> +or +<systemitem class="event">SubstructureNotify</systemitem> +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 +<symbol>PlaceOnTop</symbol> +or +<symbol>PlaceOnBottom</symbol>. +If it is +<symbol>PlaceOnTop</symbol>, +the window is now on top of all siblings. +If it is +<symbol>PlaceOnBottom</symbol>, +the window is now below all siblings. +</para> +</sect2> +<sect2 id="ConfigureNotify_Events"> +<title>ConfigureNotify Events</title> +<!-- .XS --> +<!-- (SN ConfigureNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>ConfigureNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>ConfigureNotify</primary></indexterm> +The X server can report +<symbol>ConfigureNotify</symbol> +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 +<symbol>ConfigureNotify</symbol> +events, set the +<symbol>StructureNotifyMask</symbol> +bit in the event-mask attribute of the window or the +<symbol>SubstructureNotifyMask</symbol> +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 --> +<indexterm significance="preferred"><primary>XConfigureEvent</primary></indexterm> +<!-- .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 +<systemitem class="event">StructureNotify</systemitem> +or +<systemitem class="event">SubstructureNotify</systemitem> +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 +<symbol>None</symbol>, +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 +<symbol>True</symbol>. +</para> +</sect2> +<sect2 id="CreateNotify_Events"> +<title>CreateNotify Events</title> +<!-- .XS --> +<!-- (SN CreateNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>CreateNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>CreateNotify</primary></indexterm> +The X server can report +<symbol>CreateNotify</symbol> +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 +<symbol>CreateNotify</symbol> +events, set the +<symbol>SubstructureNotifyMask</symbol> +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 --> +<indexterm significance="preferred"><primary>XCreateWindowEvent</primary></indexterm> +<!-- .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 +<symbol>True</symbol>. +</para> +</sect2> +<sect2 id="DestroyNotify_Events"> +<title>DestroyNotify Events</title> +<!-- .XS --> +<!-- (SN DestroyNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>DestroyNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>DestroyNotify</primary></indexterm> +The X server can report +<symbol>DestroyNotify</symbol> +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 +<symbol>DestroyNotify</symbol> +events is such that for any given window, +<symbol>DestroyNotify</symbol> +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 +<symbol>DestroyNotify</symbol> +events, set the +<symbol>StructureNotifyMask</symbol> +bit in the event-mask attribute of the window or the +<symbol>SubstructureNotifyMask</symbol> +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 --> +<indexterm significance="preferred"><primary>XDestroyWindowEvent</primary></indexterm> +<!-- .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 +<systemitem class="event">StructureNotify</systemitem> +or +<systemitem class="event">SubstructureNotify</systemitem> +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 --> +<indexterm><primary>Events</primary><secondary>GravityNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>GravityNotify</primary></indexterm> +The X server can report +<symbol>GravityNotify</symbol> +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 +<symbol>GravityNotify</symbol> +events, set the +<symbol>StructureNotifyMask</symbol> +bit in the event-mask attribute of the window or the +<symbol>SubstructureNotifyMask</symbol> +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 --> +<indexterm significance="preferred"><primary>XGravityEvent</primary></indexterm> +<!-- .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 +<systemitem class="event">StructureNotify</systemitem> +or +<systemitem class="event">SubstructureNotify</systemitem> +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 --> +<indexterm><primary>Events</primary><secondary>MapNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>MapNotify</primary></indexterm> +The X server can report +<symbol>MapNotify</symbol> +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 +<symbol>MapNotify</symbol> +events, set the +<symbol>StructureNotifyMask</symbol> +bit in the event-mask attribute of the window or the +<symbol>SubstructureNotifyMask</symbol> +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 --> +<indexterm significance="preferred"><primary>XMapEvent</primary></indexterm> +<!-- .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 +<systemitem class="event">StructureNotify</systemitem> +or +<systemitem class="event">SubstructureNotify</systemitem> +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 +<symbol>True</symbol>, +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 --> +<indexterm><primary>Events</primary><secondary>MappingNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>MappingNotify</primary></indexterm> +The X server reports +<symbol>MappingNotify</symbol> +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 --> +<indexterm significance="preferred"><primary>XMappingEvent</primary></indexterm> +<!-- .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 +<symbol>MappingModifier</symbol>, +<symbol>MappingKeyboard</symbol>, +or +<symbol>MappingPointer</symbol>. +If it is +<symbol>MappingModifier</symbol>, +the modifier mapping was changed. +If it is +<symbol>MappingKeyboard</symbol>, +the keyboard mapping was changed. +If it is +<symbol>MappingPointer</symbol>, +the pointer button mapping was changed. +The first_keycode and count members are set only +if the request member was set to +<symbol>MappingKeyboard</symbol>. +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 --> +<indexterm><primary>Events</primary><secondary>ReparentNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>ReparentNotify</primary></indexterm> +The X server can report +<symbol>ReparentNotify</symbol> +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 +<symbol>ReparentNotify</symbol> +events, set the +<symbol>StructureNotifyMask</symbol> +bit in the event-mask attribute of the window or the +<symbol>SubstructureNotifyMask</symbol> +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 --> +<indexterm significance="preferred"><primary>XReparentEvent</primary></indexterm> +<!-- .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 +<systemitem class="event">StructureNotify</systemitem> +or +<systemitem class="event">SubstructureNotify</systemitem> +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 +<symbol>True</symbol>. +</para> +</sect2> +<sect2 id="UnmapNotify_Events"> +<title>UnmapNotify Events</title> +<!-- .XS --> +<!-- (SN UnmapNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>UnmapNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>UnmapNotify</primary></indexterm> +The X server can report +<symbol>UnmapNotify</symbol> +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 +<symbol>UnmapNotify</symbol> +events, set the +<symbol>StructureNotifyMask</symbol> +bit in the event-mask attribute of the window or the +<symbol>SubstructureNotifyMask</symbol> +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 --> +<indexterm significance="preferred"><primary>XUnmapEvent</primary></indexterm> +<!-- .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 +<systemitem class="event">StructureNotify</systemitem> +or +<systemitem class="event">SubstructureNotify</systemitem> +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 +<symbol>True</symbol> +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 +<symbol>UnmapGravity</symbol>. +</para> +</sect2> +<sect2 id="VisibilityNotify_Events"> +<title>VisibilityNotify Events</title> +<!-- .XS --> +<!-- (SN VisibilityNotify Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>VisibilityNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>VisibilityNotify</primary></indexterm> +The X server can report +<symbol>VisibilityNotify</symbol> +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 +<symbol>InputOnly</symbol>. +</para> +<para> +<!-- .LP --> +All +<symbol>VisibilityNotify</symbol> +events caused by a hierarchy change are generated +after any hierarchy event +(<symbol>UnmapNotify</symbol>, +<symbol>MapNotify</symbol>, +<symbol>ConfigureNotify</symbol>, +<symbol>GravityNotify</symbol>, +<symbol>CirculateNotify</symbol>) +caused by that change. Any +<symbol>VisibilityNotify</symbol> +event on a given window is generated before any +<symbol>Expose</symbol> +events on that window, but it is not required that all +<symbol>VisibilityNotify</symbol> +events on all windows be generated before all +<symbol>Expose</symbol> +events on all windows. +The X protocol does not constrain the ordering of +<symbol>VisibilityNotify</symbol> +events with +respect to +<symbol>FocusOut</symbol>, +<symbol>EnterNotify</symbol>, +and +<symbol>LeaveNotify</symbol> +events. +</para> +<para> +<!-- .LP --> +To receive +<symbol>VisibilityNotify</symbol> +events, set the +<symbol>VisibilityChangeMask</symbol> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XVisibilityEvent</primary></indexterm> +<!-- .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 +<symbol>VisibilityUnobscured</symbol>, +<symbol>VisibilityPartiallyObscured</symbol>, +or +<symbol>VisibilityFullyObscured</symbol>. +The X server ignores all of a window's subwindows +when determining the visibility state of the window and processes +<symbol>VisibilityNotify</symbol> +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 +<structname>XVisibilityEvent</structname> +structure set to +<symbol>VisibilityUnobscured</symbol>. + </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 +<structname>XVisibilityEvent</structname> +structure set to +<symbol>VisibilityPartiallyObscured</symbol>. + </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 +<structname>XVisibilityEvent</structname> +structure set to +<symbol>VisibilityFullyObscured</symbol>. + </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> +<symbol>CirculateRequest</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>ConfigureRequest</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>MapRequest</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>ResizeRequest</symbol> +events + </para> + </listitem> +</itemizedlist> +<sect2 id="CirculateRequest_Events"> +<title>CirculateRequest Events</title> +<!-- .XS --> +<!-- (SN CirculateRequest Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>CirculateRequest</secondary></indexterm> +<indexterm significance="preferred"><primary>CirculateRequest</primary></indexterm> +The X server can report +<symbol>CirculateRequest</symbol> +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 +<symbol>CirculateRequest</symbol> +events, set the +<symbol>SubstructureRedirectMask</symbol> +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 +<symbol>SubstructureRedirectMask</symbol> +on the window, the X server reports to you a +<symbol>CirculateRequest</symbol> +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 --> +<indexterm significance="preferred"><primary>XCirculateRequestEvent</primary></indexterm> +<!-- .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 +<symbol>PlaceOnTop</symbol> +or +<symbol>PlaceOnBottom</symbol>. +If it is +<symbol>PlaceOnTop</symbol>, +the subwindow should be on top of all siblings. +If it is +<symbol>PlaceOnBottom</symbol>, +the subwindow should be below all siblings. +</para> +</sect2> +<sect2 id="ConfigureRequest_Events"> +<title>ConfigureRequest Events</title> +<!-- .XS --> +<!-- (SN ConfigureRequest Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>ConfigureRequest</secondary></indexterm> +<indexterm significance="preferred"><primary>ConfigureRequest</primary></indexterm> +The X server can report +<symbol>ConfigureRequest</symbol> +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 +<symbol>ConfigureRequest</symbol> +events, set the +<symbol>SubstructureRedirectMask</symbol> +bit in the event-mask attribute of the window. +<symbol>ConfigureRequest</symbol> +events are generated when a +<systemitem>ConfigureWindow</systemitem> +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 +<symbol>SubstructureRedirectMask</symbol> +on the parent window and if the override-redirect attribute +of the window is set to +<symbol>False</symbol>, +the X server reports a +<symbol>ConfigureRequest</symbol> +event to you and does not lower the specified window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XConfigureRequestEvent</primary></indexterm> +<!-- .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 +<systemitem>ConfigureWindow</systemitem> +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 +<symbol>None</symbol> +and +<symbol>Above</symbol>, +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 --> +<indexterm><primary>Events</primary><secondary>MapRequest</secondary></indexterm> +<indexterm significance="preferred"><primary>MapRequest</primary></indexterm> +The X server can report +<symbol>MapRequest</symbol> +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 +<symbol>False</symbol>. +Clients initiate map window requests by calling +<function>XMapWindow</function>, +<function>XMapRaised</function>, +or +<function>XMapSubwindows</function>. +</para> +<para> +<!-- .LP --> +To receive +<symbol>MapRequest</symbol> +events, set the +<symbol>SubstructureRedirectMask</symbol> +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 +<symbol>MapRequest</symbol> +instead. +For example, suppose a client application calls +<function>XMapWindow</function> +to map a window. +If you (usually a window manager) had selected +<symbol>SubstructureRedirectMask</symbol> +on the parent window and if the override-redirect attribute +of the window is set to +<symbol>False</symbol>, +the X server reports a +<symbol>MapRequest</symbol> +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 --> +<indexterm significance="preferred"><primary>XMapRequestEvent</primary></indexterm> +<!-- .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 --> +<indexterm><primary>Events</primary><secondary>ResizeRequest</secondary></indexterm> +<indexterm significance="preferred"><primary>ResizeRequest</primary></indexterm> +The X server can report +<symbol>ResizeRequest</symbol> +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 +<symbol>ResizeRequest</symbol> +events, set the +<symbol>ResizeRedirect</symbol> +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 --> +<indexterm significance="preferred"><primary>XResizeRequestEvent</primary></indexterm> +<!-- .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 --> +<indexterm><primary>Events</primary><secondary>ColormapNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>ColormapNotify</primary></indexterm> +The X server can report +<symbol>ColormapNotify</symbol> +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 +<structname>XSetWindowAttributes</structname> +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 +<symbol>ColormapNotify</symbol> +events, set the +<symbol>ColormapChangeMask</symbol> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XColormapEvent</primary></indexterm> +<!-- .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 +<symbol>None</symbol>. +The new member is set to indicate whether the colormap +for the specified window was changed or installed or uninstalled +and can be +<symbol>True</symbol> +or +<symbol>False</symbol>. +If it is +<symbol>True</symbol>, +the colormap was changed. +If it is +<symbol>False</symbol>, +the colormap was installed or uninstalled. +The state member is always set to indicate whether the colormap is installed or +uninstalled and can be +<symbol>ColormapInstalled</symbol> +or +<symbol>ColormapUninstalled</symbol>. +</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> +<symbol>ClientMessage</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>PropertyNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>SelectionClear</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>SelectionNotify</symbol> +events + </para> + </listitem> + <listitem> + <para> +<symbol>SelectionRequest</symbol> +events + </para> + </listitem> +</itemizedlist> +<sect2 id="ClientMessage_Events"> +<title>ClientMessage Events</title> +<!-- .XS --> +<!-- (SN ClientMessage Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm><primary>Events</primary><secondary>ClientMessage</secondary></indexterm> +<indexterm significance="preferred"><primary>ClientMessage</primary></indexterm> +The X server generates +<symbol>ClientMessage</symbol> +events only when a client calls the function +<function>XSendEvent</function>. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XClientMessageEvent</primary></indexterm> +<!-- .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 --> +<indexterm><primary>Events</primary><secondary>PropertyNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>PropertyNotify</primary></indexterm> +The X server can report +<symbol>PropertyNotify</symbol> +events to clients wanting information about property changes +for a specified window. +</para> +<para> +<!-- .LP --> +To receive +<symbol>PropertyNotify</symbol> +events, set the +<symbol>PropertyChangeMask</symbol> +bit in the event-mask attribute of the window. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XPropertyEvent</primary></indexterm> +<!-- .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 +<symbol>PropertyNewValue</symbol> +or +<symbol>PropertyDelete</symbol>. +The state member is set to +<symbol>PropertyNewValue</symbol> +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 +<symbol>PropertyDelete</symbol> +when a property of the window is deleted using +<function>XDeleteProperty</function> +or, if the delete argument is +<symbol>True</symbol>, +<function>XGetWindowProperty</function>. +</para> +</sect2> +<sect2 id="SelectionClear_Events"> +<title>SelectionClear Events</title> +<!-- .XS --> +<!-- (SN SelectionClear Events --> +<!-- .XE --> +<para> +<!-- .LP --> +<indexterm ><primary>Events</primary><secondary>SelectionClear</secondary></indexterm> +<indexterm significance="preferred"><primary>SelectionClear</primary></indexterm> +The X server reports +<symbol>SelectionClear</symbol> +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 --> +<indexterm significance="preferred"><primary>XSelectionClearEvent</primary></indexterm> +<!-- .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 --> +<indexterm><primary>Events</primary><secondary>SelectionRequest</secondary></indexterm> +<indexterm significance="preferred"><primary>SelectionRequest</primary></indexterm> +The X server reports +<symbol>SelectionRequest</symbol> +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 --> +<indexterm significance="preferred"><primary>XSelectionRequestEvent</primary></indexterm> +<!-- .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 +<symbol>None</symbol>. +The time member is set to the timestamp or +<symbol>CurrentTime</symbol> +value from the +<systemitem>ConvertSelection</systemitem> +request. +</para> +<para> +<!-- .LP --> +The owner should convert the selection based on the specified target type +and send a +<symbol>SelectionNotify</symbol> +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 --> +<indexterm><primary>Events</primary><secondary>SelectionNotify</secondary></indexterm> +<indexterm significance="preferred"><primary>SelectionNotify</primary></indexterm> +This event is generated by the X server in response to a +<systemitem>ConvertSelection</systemitem> +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 +<symbol>None</symbol>). +</para> +<para> +<!-- .LP --> +If +<symbol>None</symbol> +is specified as the property in the +<systemitem>ConvertSelection</systemitem> +protocol request, the owner should choose a property name, +store the result as that property on the requestor window, +and then send a +<symbol>SelectionNotify</symbol> +giving that actual property name. +</para> +<para> +<!-- .LP --> +The structure for this event type contains: +</para> +<para> +<!-- .LP --> +<indexterm significance="preferred"><primary>XSelectionEvent</primary></indexterm> +<!-- .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 +<symbol>None</symbol>. +The time member is set to the time the conversion took place and +can be a timestamp or +<symbol>CurrentTime</symbol>. +<!-- .bp --> + + +</para> +</sect2> +</sect1> +</chapter> diff --git a/libX11/specs/libX11/CH11.xml b/libX11/specs/libX11/CH11.xml index df8a9630a..3fe6f23de 100644 --- a/libX11/specs/libX11/CH11.xml +++ b/libX11/specs/libX11/CH11.xml @@ -273,7 +273,8 @@ and processed by the X server. Any errors generated must be handled by the error handler. For each protocol error received by Xlib, <function>XSync</function> -calls the client application's error handling routine (see section 11.8.2). +calls the client application's error handling routine +(see <link linkend="Using_the_Default_Error_Handlers">section 11.8.2</link>). Any events generated by the server are enqueued into the library's event queue. </para> @@ -1512,7 +1513,7 @@ determines which clients should receive the specified events, and ignores any active grabs. This function requires you to pass an event mask. For a discussion of the valid event mask names, -see section 10.3. +see <link linkend="Event_Masks">section 10.3</link>. This function uses the w argument to identify the destination window as follows: </para> <itemizedlist> @@ -2029,7 +2030,7 @@ It is the number that was the value of immediately before the failing call was made. The request_code member is a protocol request of the procedure that failed, as defined in -< X11/Xproto.h .> +<filename class="headerfile"><X11/Xproto.h></filename>. The following error codes can be returned by the functions described in this chapter: </para> diff --git a/libX11/specs/libX11/CH13.xml b/libX11/specs/libX11/CH13.xml index 4219fa981..37121ba47 100644 --- a/libX11/specs/libX11/CH13.xml +++ b/libX11/specs/libX11/CH13.xml @@ -3520,7 +3520,8 @@ and except that they work with font sets instead of single fonts and interpret the text based on the locale of the font set instead of treating the bytes of the string as direct font indexes. -See section 8.6 for details of the use of Graphics Contexts (GCs) +See <link linkend="Drawing_Text">section 8.6</link> for details +of the use of Graphics Contexts (GCs) and possible protocol errors. If a <errorname>BadFont</errorname> @@ -4553,7 +4554,7 @@ is being used to do input for multiple text entry areas, it will also be necessary to set the focus window of the input context whenever the focus window changes -(see section 13.5.6.3). +(see <link linkend="Focus_Window">section 13.5.6.3</link>). </para> </sect3> <sect3 id="Geometry_Management"> @@ -4671,7 +4672,8 @@ may change the geometry desired by the input method. </para> <para> <!-- .LP --> -The table of <acronym>XIC</acronym> values (see section 13.5.6) +The table of <acronym>XIC</acronym> values +(see <link linkend="Input_Context_Values">section 13.5.6</link>) indicates the values that can cause the desired geometry to change when they are set. It is the responsibility of the client to renegotiate the geometry @@ -5857,7 +5859,8 @@ The following keys apply to this table. <para> <!-- .LP --> <symbol>XNR6PreeditCallback</symbol> -is obsolete and its use is not recommended (see section 13.5.4.6). +is obsolete and its use is not recommended +(see <link linkend="Preedit_Callback_Behavior">section 13.5.4.6</link>). </para> <sect3 id="Query_Input_Style"> @@ -7506,7 +7509,7 @@ The <symbol>XNGeometryCallback</symbol> argument is a structure of type <structname>XIMCallback</structname> -(see section 13.5.6.13.12). +(see <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>). </para> <para> <!-- .LP --> @@ -7561,7 +7564,8 @@ The <symbol>XNDestroyCallback</symbol> argument is a pointer to a structure of type <structname>XIMCallback</structname> -(see section 13.5.6.13.12). This callback is triggered when the input method +(see <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>). +This callback is triggered when the input method stops its service for any reason; for example, when a connection to an IM server is broken. After the destroy callback is called, the input context is destroyed and the input method is closed. @@ -7585,7 +7589,7 @@ The <symbol>XNStringConversionCallback</symbol> argument is a structure of type <structname>XIMCallback</structname> -(see section 13.5.6.13.12). +(see <link linkend="Preedit_and_Status_Callbacks">section 13.5.6.13.12</link>). </para> <para> <!-- .LP --> @@ -8034,7 +8038,7 @@ or <symbol>XIMStatusArea</symbol>. It is used for geometry negotiation between the client and the input method and has no other effect on the input method -(see section 13.5.1.5). +(see <link linkend="Geometry_Management">section 13.5.1.5</link>). </para> </sect4> <sect4 id="Spot_Location"> @@ -8783,7 +8787,8 @@ The callback is passed an structure in the call_data argument. The text member is an <structname>XIMStringConversionText</structname> -structure (see section 13.5.6.9) to be filled in by the client +structure (see <link linkend="String_Conversion_">section 13.5.6.9</link>) +to be filled in by the client and describes the text to be sent to the input method. The data pointed to by the string and feedback elements of the @@ -10285,7 +10290,7 @@ called back the client and obtained no response <para> <!-- .LP --> The following symbols for string constants are defined in -<X11/Xlib.h> . +<filename class="headerfile"><X11/Xlib.h></filename>. Although they are shown here with particular macro definitions, they may be implemented as macros, as global symbols, or as a mixture of the two. The string pointer value itself diff --git a/libX11/specs/libX11/CH14.xml b/libX11/specs/libX11/CH14.xml index d0eb36f10..b64830667 100644 --- a/libX11/specs/libX11/CH14.xml +++ b/libX11/specs/libX11/CH14.xml @@ -14,11 +14,14 @@ see the Inter-Client Communication Conventions Manual. Xlib provides a number of standard properties and programming interfaces that are <acronym>ICCCM</acronym> compliant. The predefined atoms for some of these properties are defined in the <X11/Xatom.h> header file, where to avoid name conflicts with user symbols their #define name has an XA_ prefix. -For further information about atoms and properties, see section 4.3. +For further information about atoms and properties, +see <link linkend="Properties_and_Atoms">section 4.3</link>. </para> <para> Xlib’s selection and cut buffer mechanisms provide the primary programming interfaces by which -peer client applications communicate with each other (see sections 4.5 and 16.6). The functions +peer client applications communicate with each other +(see sections <link linkend="Selections">4.5</link> and +<link linkend="Using_Cut_Buffers">16.6</link>). The functions discussed in this chapter provide the primary programming interfaces by which client applications communicate with their window and session managers as well as share standard colormaps. </para> @@ -248,7 +251,8 @@ of top-level windows (that is, those that were created as children of the root window). Note that the subwindows that you create are ignored by window managers. Therefore, -you should use the basic window functions described in chapter 3 +you should use the basic window functions described in +<link linkend="window_functions">chapter 3</link> to manipulate your application's subwindows. </para> <para> @@ -1179,7 +1183,12 @@ In addition, Xlib provides separate convenience functions that you can use to set each of these properties. For further information about these convenience functions, -see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively. +see sections +<link linkend="Setting_and_Reading_the_WM_NAME_Property">14.1.4</link>, +<link linkend="Setting_and_Reading_the_WM_ICON_NAME_Property">14.1.5</link>, +<link linkend="Setting_and_Reading_the_WM_COMMAND_Property">14.2.1</link>, and +<link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">14.2.2</link>, +respectively. <!-- .sp --> </para> <para> @@ -3926,12 +3935,14 @@ If the normal_hints argument is non-NULL, <function>XmbSetWMProperties</function> calls <function>XSetWMNormalHints</function>, -which sets the <property>WM_NORMAL_HINTS</property> property (see section 14.1.7). +which sets the <property>WM_NORMAL_HINTS</property> property +(see <link linkend="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">section 14.1.7</link>). If the wm_hints argument is non-NULL, <function>XmbSetWMProperties</function> calls <function>XSetWMHints</function>, -which sets the <property>WM_HINTS</property> property (see section 14.1.6). +which sets the <property>WM_HINTS</property> property +(see <link linkend="Setting_and_Reading_the_WM_HINTS_Property">section 14.1.6</link>). </para> <para> <!-- .LP --> @@ -3944,7 +3955,7 @@ An argc of zero indicates a zero-length command. <!-- .LP --> The hostname of the machine is stored using <function>XSetWMClientMachine</function> -(see section 14.2.2). +(see <link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">section 14.2.2</link>). </para> <para> <!-- .LP --> @@ -4129,21 +4140,24 @@ If the window_name argument is non-NULL, <function>XSetWMProperties</function> calls <function>XSetWMName</function>, -which, in turn, sets the <property>WM_NAME</property> property (see section 14.1.4). +which, in turn, sets the <property>WM_NAME</property> property +(see <link linkend="Setting_and_Reading_the_WM_NAME_Property">section 14.1.4</link>). If the icon_name argument is non-NULL, <function>XSetWMProperties</function> calls <function>XSetWMIconName</function>, -which sets the <property>WM_ICON_NAME</property> property (see section 14.1.5). +which sets the <property>WM_ICON_NAME</property> property +(see <link linkend="Setting_and_Reading_the_WM_ICON_NAME_Property">section 14.1.5</link>). If the argv argument is non-NULL, <function>XSetWMProperties</function> calls <function>XSetCommand</function>, -which sets the <property>WM_COMMAND</property> property (see section 14.2.1). +which sets the <property>WM_COMMAND</property> property +(see <link linkend="Setting_and_Reading_the_WM_COMMAND_Property">section 14.2.1</link>). Note that an argc of zero is allowed to indicate a zero-length command. Note also that the hostname of this machine is stored using <function>XSetWMClientMachine</function> -(see section 14.2.2). +(see <link linkend="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">section 14.2.2</link>). </para> <para> <!-- .LP --> @@ -4151,12 +4165,14 @@ If the normal_hints argument is non-NULL, <function>XSetWMProperties</function> calls <function>XSetWMNormalHints</function>, -which sets the <property>WM_NORMAL_HINTS</property> property (see section 14.1.7). +which sets the <property>WM_NORMAL_HINTS</property> property +(see <link linkend="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">section 14.1.7</link>). If the wm_hints argument is non-NULL, <function>XSetWMProperties</function> calls <function>XSetWMHints</function>, -which sets the <property>WM_HINTS</property> property (see section 14.1.6). +which sets the <property>WM_HINTS</property> property +(see <link linkend="Setting_and_Reading_the_WM_HINTS_Property">section 14.1.6</link>). </para> <para> <!-- .LP --> @@ -4164,7 +4180,8 @@ If the class_hints argument is non-NULL, <function>XSetWMProperties</function> calls <function>XSetClassHint</function>, -which sets the <property>WM_CLASS</property> property (see section 14.1.8). +which sets the <property>WM_CLASS</property> property +(see <link linkend="Setting_and_Reading_the_WM_CLASS_Property">section 14.1.8</link>). If the res_name member in the <structname>XClassHint</structname> structure is set to the NULL pointer and the RESOURCE_NAME environment diff --git a/libX11/specs/libX11/CH15.xml b/libX11/specs/libX11/CH15.xml index 7abc6173e..760adcfe5 100644 --- a/libX11/specs/libX11/CH15.xml +++ b/libX11/specs/libX11/CH15.xml @@ -566,7 +566,7 @@ The function converts the null-terminated string (generally a fully qualified name) to a list of quarks. Note that the string must be in the valid ResourceName format -(see section 15.1). +(see <link linkend="Resource_File_Syntax">section 15.1</link>). If the string is not in the Host Portable Character Encoding, the conversion is implementation-dependent. </para> @@ -650,7 +650,8 @@ The caller must allocate sufficient space for the quarks list before calling <!-- .eM --> Component names in the list are separated by a period or an asterisk character. -The string must be in the format of a valid ResourceName (see section 15.1). +The string must be in the format of a valid ResourceName +(see <link linkend="Resource_File_Syntax">section 15.1</link>). If the string does not start with a period or an asterisk, a tight binding is assumed. For example, the string ``*a.b*c'' becomes: @@ -752,7 +753,8 @@ function opens the specified file, creates a new resource database, and loads it with the specifications read in from the specified file. The specified file should contain a sequence of entries in valid ResourceLine -format (see section 15.1); the database that results from reading a file +format (see <link linkend="Resource_File_Syntax">section 15.1</link>); +the database that results from reading a file with incorrect syntax is implementation-dependent. The file is parsed in the current locale, and the database is created in the current locale. @@ -805,7 +807,8 @@ The <function>XrmPutFileDatabase</function> function stores a copy of the specified database in the specified file. Text is written to the file as a sequence of entries in valid -ResourceLine format (see section 15.1). +ResourceLine format +(see <link linkend="Resource_File_Syntax">section 15.1</link>). The file is written in the locale of the database. Entries containing resource names that are not in the Host Portable Character Encoding or containing values that are not in the encoding of the database @@ -940,7 +943,8 @@ is similar to <function>XrmGetFileDatabase</function> except that it reads the information out of a string instead of out of a file. The string should contain a sequence of entries in valid ResourceLine -format (see section 15.1) terminated by a null character; +format (see <link linkend="Resource_File_Syntax">section 15.1</link>) +terminated by a null character; the database that results from using a string with incorrect syntax is implementation-dependent. The string is parsed in the current locale, @@ -2077,7 +2081,8 @@ If database contains NULL, creates a new database and returns a pointer to it. <function>XrmPutLineResource</function> adds a single resource entry to the specified database. -The line should be in valid ResourceLine format (see section 15.1) +The line should be in valid ResourceLine format +(see <link linkend="Resource_File_Syntax">section 15.1</link>) terminated by a newline or null character; the database that results from using a string with incorrect syntax is implementation-dependent. diff --git a/libX11/specs/libX11/CH16.xml b/libX11/specs/libX11/CH16.xml index db42bb170..fecbb2f49 100644 --- a/libX11/specs/libX11/CH16.xml +++ b/libX11/specs/libX11/CH16.xml @@ -655,7 +655,8 @@ if the specified KeySym is a PF key. <!-- .XE --> <para> <!-- .LP --> -Chapter 13 describes internationalized text input facilities, +<link linkend="locales_and_internationalized_text_functions">Chapter 13</link> +describes internationalized text input facilities, but sometimes it is expedient to write an application that only deals with Latin-1 characters and ASCII controls, so Xlib provides a simple function for that purpose. @@ -2132,7 +2133,8 @@ if the rectangle is partially in the specified region. Xlib provides functions to manipulate cut buffers, a very simple form of cut-and-paste inter-client communication. Selections are a much more powerful and useful mechanism for -interchanging data between clients (see section 4.5) +interchanging data between client +(see <link linkend="Selections">section 4.5</link>) and generally should be used instead of cut buffers. </para> <para> @@ -2736,7 +2738,7 @@ plane n must be located at the address (data + (n * height * bytes_per_line)). For a description of the <structname>XImage</structname> structure, -see section 8.7. +see <link linkend="Transferring_Images_between_Client_and_Server">section 8.7</link>. </para> <para> <!-- .LP --> |