xserver libX11 libXdmcp pixman git update 22-12-2010

1 files changed, 2510 insertions, 2510 deletions

diff --git a/libX11/specs/libX11/CH04.xml b/libX11/specs/libX11/CH04.xml
index 0469b2cde..8a3e8c535 100644
--- a/libX11/specs/libX11/CH04.xml
+++ b/libX11/specs/libX11/CH04.xml
@@ -1,2510 +1,2510 @@
-<?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="window_information_functions">

-<title>Window Information Functions</title>

-

-<para>

-After you connect the display to the X server and create a window, you can use the Xlib window

-information functions to:

-</para>

-<itemizedlist>

-  <listitem><para>Obtain information about a window</para></listitem>

-  <listitem><para>Translate screen coordinates</para></listitem>

-  <listitem><para>Manipulate property lists</para></listitem>

-  <listitem><para>Obtain and change window properties</para></listitem>

-  <listitem><para>Manipulate selections</para></listitem>

-</itemizedlist>

-

-<sect1 id="Obtaining_Window_Information">

-<title>Obtaining Window Information</title>

-<!-- .XS -->

-<!-- (SN Obtaining Window Information  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to obtain information about 

-the window tree, the window's current attributes, 

-the window's current geometry, or the current pointer coordinates.

-Because they are most frequently used by window managers,

-these functions all return a status to indicate whether the window still

-exists.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the parent, a list of children, and number of children for 

-a given window, use 

-<function>XQueryTree</function>.

-<indexterm><primary>Child Window</primary></indexterm>

-<indexterm><primary>Parent Window</primary></indexterm>

-<indexterm significance="preferred"><primary>XQueryTree</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XQueryTree</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Window<parameter> *root_return</parameter></paramdef>

-  <paramdef>Window<parameter> *parent_return</parameter></paramdef>

-  <paramdef>Window<parameter> **children_return</parameter></paramdef>

-  <paramdef>unsignedint<parameter> *nchildren_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose list of children, root, parent, and number of children \ -->

-you want to obtain

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>root_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the root window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>parent_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the parent window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>children_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the list of children.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nchildren_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of children.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryTree</function>

-function returns the root ID, the parent window ID, 

-a pointer to the list of children windows

-(NULL when there are no children), 

-and the number of children in the list for the specified window.

-The children are listed in current stacking order, from bottom-most 

-(first) to top-most (last).

-<function>XQueryTree</function>

-returns zero if it fails and nonzero if it succeeds.

-To free a non-NULL children list when it is no longer needed, use 

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryTree</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the current attributes of a given window, use 

-<function>XGetWindowAttributes</function>.

-<indexterm significance="preferred"><primary>XGetWindowAttributes</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetWindowAttributes</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>XWindowAttributes<parameter> *window_attributes_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose current attributes you want to obtain -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>window_attributes_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the specified window's attributes in the

-<structname>XWindowAttributes</structname>

-structure.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetWindowAttributes</function>

-function returns the current attributes for the specified window to an

-<structname>XWindowAttributes</structname>

-structure.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XWindowAttributes</primary></indexterm>

-<!-- .sM -->

-<literallayout class="monospaced">

-<!-- .TA .5i 3i -->

-<!-- .ta .5i 3i -->

-typedef struct {

-     int x, y;                     /* location of window */

-     int width, height;            /* width and height of window */

-     int border_width;             /* border width of window */

-     int depth;                    /* depth of window */

-     Visual *visual;               /* the associated visual structure */

-     Window root;                  /* root of screen containing window */

-     int class;                    /* InputOutput, InputOnly*/

-     int bit_gravity;              /* one of the bit gravity values */

-     int win_gravity;              /* one of the window gravity values */

-     int backing_store;            /* NotUseful, WhenMapped, Always */

-     unsigned long backing_planes; /* planes to be preserved if possible */

-     unsigned long backing_pixel;  /* value to be used when restoring planes */

-     Bool save_under;              /* boolean, should bits under be saved? */

-     Colormap colormap;            /* color map to be associated with window */

-     Bool map_installed;           /* boolean, is color map currently installed*/

-     int map_state;                /* IsUnmapped, IsUnviewable, IsViewable */

-     long all_event_masks;         /* set of events all people have interest in*/

-     long your_event_mask;         /* my event mask */

-     long do_not_propagate_mask;   /* set of events that should not propagate */

-     Bool override_redirect;       /* boolean value for override-redirect */

-     Screen *screen;               /* back pointer to correct screen */

-} XWindowAttributes;

-</literallayout>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The x and y members are set to the upper-left outer

-corner relative to the parent window's origin.

-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 window's border width in pixels.

-The depth member is set to the depth of the window 

-(that is, bits per pixel for the object).

-The visual member is a pointer to the screen's associated

-<structname>Visual</structname>

-structure.

-The root member is set to the root window of the screen containing the window.

-The class member is set to the window's class and can be either

-<symbol>InputOutput</symbol>

-or

-<symbol>InputOnly</symbol>.

-</para>

-<para>

-<!-- .LP -->

-The bit_gravity member is set to the window's bit gravity

-and can be one of the following:

-  <simplelist type="vert" columns="2">

-    <member><symbol>ForgetGravity</symbol></member>

-    <member><symbol>NorthWestGravity</symbol></member>

-    <member><symbol>NorthGravity</symbol></member>

-    <member><symbol>NorthEastGravity</symbol></member>

-    <member><symbol>WestGravity</symbol></member>

-

-    <member><symbol>EastGravity</symbol></member>

-    <member><symbol>SouthWestGravity</symbol></member>

-    <member><symbol>SouthGravity</symbol></member>

-    <member><symbol>SouthEastGravity</symbol></member>

-    <member><symbol>StaticGravity</symbol></member>

-  </simplelist>

-</para>

-<para>

-The win_gravity member is set to the window's window gravity

-and can be one of the following:

-  <simplelist type="vert" columns="2">

-    <member><symbol>UnmapGravity</symbol></member>

-    <member><symbol>NorthWestGravity</symbol></member>

-    <member><symbol>NorthGravity</symbol></member>

-    <member><symbol>NorthEastGravity</symbol></member>

-    <member><symbol>WestGravity</symbol></member>

-

-    <member><symbol>EastGravity</symbol></member>

-    <member><symbol>SouthWestGravity</symbol></member>

-    <member><symbol>SouthGravity</symbol></member>

-    <member><symbol>SouthEastGravity</symbol></member>

-    <member><symbol>StaticGravity</symbol></member>

-    <member><symbol>CenterGravity</symbol></member>

-  </simplelist>

-</para>

-<para>

-<!-- .LP -->

-For additional information on gravity,

-see section 3.2.3. <!-- xref -->

-</para>

-<para>

-<!-- .LP -->

-The backing_store member is set to indicate how the X server should maintain

-the contents of a window 

-and can be 

-<symbol>WhenMapped</symbol>,

-<symbol>Always</symbol>,

-or

-<symbol>NotUseful</symbol>.

-The backing_planes member is set to indicate (with bits set to 1) which bit 

-planes of the window hold dynamic data that must be preserved in backing_stores 

-and during save_unders.

-The backing_pixel member is set to indicate what values to use 

-for planes not set in backing_planes.

-</para>

-<para>

-<!-- .LP -->

-The save_under member is set to 

-<symbol>True</symbol>

-or

-<symbol>False</symbol>.

-The colormap member is set to the colormap for the specified window and can be

-a colormap ID or 

-<symbol>None</symbol>.

-The map_installed member is set to indicate whether the colormap is 

-currently installed and can be 

-<symbol>True</symbol>

-or

-<symbol>False</symbol>.

-The map_state member is set to indicate the state of the window and can be

-<symbol>IsUnmapped</symbol>,

-<symbol>IsUnviewable</symbol>,

-or

-<symbol>IsViewable</symbol>.

-<symbol>IsUnviewable</symbol>

-is used if the window is mapped but some ancestor is unmapped.

-</para>

-<para>

-<!-- .LP -->

-The all_event_masks member is set to the bitwise inclusive OR of all event 

-masks selected on the window by all clients.

-The your_event_mask member is set to the bitwise inclusive OR of all event 

-masks selected by the querying client.

-The do_not_propagate_mask member is set to the bitwise inclusive OR of the 

-set of events that should not propagate.

-</para>

-<para>

-<!-- .LP -->

-The override_redirect member is set to indicate whether this window overrides

-structure control facilities and can be 

-<symbol>True</symbol>

-or

-<symbol>False</symbol>.

-Window manager clients should ignore the window if this member is

-<symbol>True</symbol>.

-</para>

-<para>

-<!-- .LP -->

-The screen member is set to a screen pointer that gives you a back pointer 

-to the correct screen.

-This makes it easier to obtain the screen information without

-having to loop over the root window fields to see which field matches.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetWindowAttributes</function>

-can generate

-<errorname>BadDrawable</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the current geometry of a given drawable, use 

-<function>XGetGeometry</function>.

-<indexterm significance="preferred"><primary>XGetGeometry</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetGeometry</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Drawable<parameter> d</parameter></paramdef>

-  <paramdef>Window<parameter> *root_return</parameter></paramdef>

-  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>

-  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>

-  <paramdef>unsignedint<parameter> *border_width_return</parameter></paramdef>

-  <paramdef>unsignedint<parameter> *depth_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Dr , which can be a window or a pixmap -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>d</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the drawable(Dr. 

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>root_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the root window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>x_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>y_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the x and y coordinates that define the location of the drawable.

-For a window, 

-these coordinates specify the upper-left outer corner relative to

-its parent's origin.

-For pixmaps, these coordinates are always zero.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>height_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the drawable's dimensions (width and height).

-For a window, 

-these dimensions specify the inside size, not including the border.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>border_width_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the border width in pixels. 

-If the drawable is a pixmap, it returns zero.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>depth_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the depth of the drawable (bits per pixel for the object).

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetGeometry</function>

-function returns the root window and the current geometry of the drawable.

-The geometry of the drawable includes the x and y coordinates, width and height,

-border width, and depth.

-These are described in the argument list.

-It is legal to pass to this function a window whose class is

-<symbol>InputOnly</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetGeometry</function>

-can generate a

-<errorname>BadDrawable</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Translating_Screen_Coordinates">

-<title>Translating Screen Coordinates</title>

-<!-- .XS -->

-<!-- (SN Translating Screen Coordinates  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-Applications sometimes

-need to perform a coordinate transformation from the coordinate

-space of one window to another window or need to determine which

-window the pointing device is in.

-<function>XTranslateCoordinates</function>

-and

-<function>XQueryPointer</function>

-fulfill these needs (and avoid any race conditions) by

-asking the X server to perform these operations.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To translate a coordinate in one window to the coordinate

-space of another window, use

-<function>XTranslateCoordinates</function>.

-<indexterm significance="preferred"><primary>XTranslateCoordinates</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XTranslateCoordinates</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>

-  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>

-  <paramdef>int*dest_x_return,<parameter> *dest_y_return</parameter></paramdef>

-  <paramdef>Window<parameter> *child_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the source window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the destination window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_x</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>src_y</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specify the x and y coordinates within the source window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_x_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>dest_y_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the x and y coordinates within the destination window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>child_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the child if the coordinates are contained in a mapped child of the

-destination window.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-If

-<function>XTranslateCoordinates</function>

-returns

-<symbol>True</symbol>,

-it takes the src_x and src_y coordinates relative

-to the source window's origin and returns these coordinates to 

-dest_x_return and dest_y_return

-relative to the destination window's origin.

-If

-<function>XTranslateCoordinates</function>

-returns 

-<symbol>False</symbol>,

-src_w and dest_w are on different screens,

-and dest_x_return and dest_y_return are zero.

-If the coordinates are contained in a mapped child of dest_w,

-that child is returned to child_return.

-Otherwise, child_return is set to

-<symbol>None</symbol>.

-</para>

-<para>

-<!-- .LP -->

-<function>XTranslateCoordinates</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the screen coordinates of the pointer

-or to determine the pointer coordinates relative to a specified window, use 

-<function>XQueryPointer</function>.

-<indexterm significance="preferred"><primary>XQueryPointer</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Bool <function>XQueryPointer</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Window*root_return,<parameter> *child_return</parameter></paramdef>

-  <paramdef>int*root_x_return,<parameter> *root_y_return</parameter></paramdef>

-  <paramdef>int*win_x_return,<parameter> *win_y_return</parameter></paramdef>

-  <paramdef>unsignedint<parameter> *mask_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-<!-- .ds Ro that the pointer is in -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>root_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the root window (Ro.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>child_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the child window that the pointer is located in, if any.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>root_x_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>root_y_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the pointer coordinates relative to the root window's origin.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>win_x_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-<!-- .br -->

-<!-- .ns -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>win_y_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Return the pointer coordinates relative to the specified window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mask_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the current state of the modifier keys and pointer buttons.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XQueryPointer</function>

-function returns the root window the pointer is logically on and the pointer

-coordinates relative to the root window's origin.

-If

-<function>XQueryPointer</function>

-returns 

-<symbol>False</symbol>,

-the pointer is not on the same screen as the specified window, and

-<function>XQueryPointer</function>

-returns 

-<symbol>None</symbol>

-to child_return and zero to win_x_return and win_y_return.

-If 

-<function>XQueryPointer</function>

-returns 

-<symbol>True</symbol>,

-the pointer coordinates returned to win_x_return and win_y_return

-are relative to the origin of the specified window.

-In this case, 

-<function>XQueryPointer</function>

-returns the child that contains the pointer, if any,

-or else

-<symbol>None</symbol>

-to child_return.

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryPointer</function>

-returns the current logical state of the keyboard buttons 

-and the modifier keys in mask_return.

-It sets mask_return to the bitwise inclusive OR of one or more

-of the button or modifier key bitmasks to match 

-the current state of the mouse buttons and the modifier keys.

-</para>

-<para>

-<!-- .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 -->

-</para>

-<para>

-<!-- .LP -->

-<function>XQueryPointer</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Properties_and_Atoms">

-<title>Properties and Atoms</title>

-<!-- .XS -->

-<!-- (SN Properties and Atoms  -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-A property is a collection of named, typed data.

-The window system has a set of predefined properties

-<indexterm><primary>Atom</primary><secondary>predefined</secondary></indexterm>

-(for example, the name of a window, size hints, and so on), and users can

-define any other arbitrary information and associate it with windows.

-Each property has a name,

-which is an ISO Latin-1 string.

-For each named property,

-a unique identifier (atom) is associated with it. 

-A property also has a type, for example, string or integer.

-These types are also indicated using atoms, so arbitrary new

-types can be defined.

-Data of only one type may be associated with a single

-property name.

-Clients can store and retrieve properties associated with windows.

-For efficiency reasons,

-an atom is used rather than a character string.

-<function>XInternAtom</function>

-can be used to obtain the atom for property names.

-<indexterm><primary>Atom</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-A property is also stored in one of several possible formats.

-The X server can store the information as 8-bit quantities, 16-bit

-quantities, or 32-bit quantities.

-This permits the X server to present the data in the byte order that the

-client expects.

-<!-- .NT Note -->

-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 -->

-<!-- .NE -->

-The type of a property is defined by an atom, which allows for

-arbitrary extension in this type scheme.

-<indexterm><primary>Atom</primary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-Certain property names are

-predefined in the server for commonly used functions.

-The atoms for these properties are defined in 

-<filename class="headerfile">&lt;X11/Xatom.h&gt;</filename>.

-<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>

-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>

-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>

-To avoid name clashes with user symbols, the 

-<code>#define</code>

-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 -->

-</para>

-<para>

-<!-- .LP -->

-The core protocol imposes no semantics on these property names,

-but semantics are specified in other X Consortium standards,

-such as the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>

-and the <emphasis remap='I'>X Logical Font Description Conventions</emphasis>.

-</para>

-<para>

-<!-- .LP -->

-You can use properties to communicate other information between

-applications.

-The functions described in this section let you define new properties 

-and get the unique atom IDs in your applications.

-</para>

-<para>

-<!-- .LP -->

-Although any particular atom can have some client interpretation 

-within each of the name spaces, 

-atoms occur in five distinct name spaces within the protocol: 

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-Selections

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Property names

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Property types

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Font properties 

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-Type of a 

-<symbol>ClientMessage</symbol>

-event (none are built into the X server)

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-</para>

-<para>

-<!-- .LP -->

-The built-in selection property names are:

-<simplelist type="vert" columns="2">

-  <member><property>PRIMARY</property></member>

-  <member><property>SECONDARY</property></member>

-</simplelist>

-</para>

-<para>

-<!-- .LP -->

-The built-in property names are: 

-  <simplelist type="vert" columns="2">

-    <member><property>CUT_BUFFER0</property></member>

-    <member><property>CUT_BUFFER1</property></member>

-    <member><property>CUT_BUFFER2</property></member>

-    <member><property>CUT_BUFFER3</property></member>

-    <member><property>CUT_BUFFER4</property></member>

-    <member><property>CUT_BUFFER5</property></member>

-    <member><property>CUT_BUFFER6</property></member>

-    <member><property>CUT_BUFFER7</property></member>

-    <member><property>RGB_BEST_MAP</property></member>

-    <member><property>RGB_BLUE_MAP</property></member>

-    <member><property>RGB_DEFAULT_MAP</property></member>

-    <member><property>RGB_GRAY_MAP</property></member>

-    <member><property>RGB_GREEN_MAP</property></member>

-    <member><property>RGB_RED_MAP</property></member>

-

-    <member><property>RESOURCE_MANAGER</property></member>

-    <member><property>WM_CLASS</property></member>

-    <member><property>WM_CLIENT_MACHINE</property></member>

-    <member><property>WM_COLORMAP_WINDOWS</property></member>

-    <member><property>WM_COMMAND</property></member>

-    <member><property>WM_HINTS</property></member>

-    <member><property>WM_ICON_NAME</property></member>

-    <member><property>WM_ICON_SIZE</property></member>

-    <member><property>WM_NAME</property></member>

-    <member><property>WM_NORMAL_HINTS</property></member>

-    <member><property>WM_PROTOCOLS</property></member>

-    <member><property>WM_STATE</property></member>

-    <member><property>WM_TRANSIENT_FOR</property></member>

-    <member><property>WM_ZOOM_HINTS</property></member>

-  </simplelist>

-</para>

-<para>

-The built-in property types are: 

-  <simplelist type="vert" columns="2">

-    <member><property>ARC</property></member>

-    <member><property>ATOM</property></member>

-    <member><property>BITMAP</property></member>

-    <member><property>CARDINAL</property></member>

-    <member><property>COLORMAP</property></member>

-    <member><property>CURSOR</property></member>

-    <member><property>DRAWABLE</property></member>

-    <member><property>FONT</property></member>

-    <member><property>INTEGER</property></member>

-    <member><property>PIXMAP</property></member>

-    <member><property>POINT</property></member>

-    <member><property>RGB_COLOR_MAP</property></member>

-    <member><property>RECTANGLE</property></member>

-    <member><property>STRING</property></member>

-    <member><property>VISUALID</property></member>

-    <member><property>WINDOW</property></member>

-    <member><property>WM_HINTS</property></member>

-    <member><property>WM_SIZE_HINTS</property></member>

-  </simplelist>

-</para>

-<para>

-The built-in font property names are: 

-  <simplelist type="vert" columns="2">

-    <member><property>MIN_SPACE</property></member>

-    <member><property>NORM_SPACE</property></member>

-    <member><property>MAX_SPACE</property></member>

-    <member><property>END_SPACE</property></member>

-    <member><property>SUPERSCRIPT_X</property></member>

-    <member><property>SUPERSCRIPT_Y</property></member>

-    <member><property>SUBSCRIPT_X</property></member>

-    <member><property>SUBSCRIPT_Y</property></member>

-    <member><property>UNDERLINE_POSITION</property></member>

-    <member><property>UNDERLINE_THICKNESS</property></member>

-    <member><property>FONT_NAME</property></member>

-    <member><property>FULL_NAME</property></member>

-

-    <member><property>STRIKEOUT_DESCENT</property></member>

-    <member><property>STRIKEOUT_ASCENT</property></member>

-    <member><property>ITALIC_ANGLE</property></member>

-    <member><property>X_HEIGHT</property></member>

-    <member><property>QUAD_WIDTH</property></member>

-    <member><property>WEIGHT</property></member>

-    <member><property>POINT_SIZE</property></member>

-    <member><property>RESOLUTION</property></member>

-    <member><property>COPYRIGHT</property></member>

-    <member><property>NOTICE</property></member>

-    <member><property>FAMILY_NAME</property></member>

-    <member><property>CAP_HEIGHT</property></member>

-  </simplelist>

-</para>

-<para>

-<!-- .LP -->

-For further information about font properties,

-see section 8.5. <!-- xref -->

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return an atom for a given name, use 

-<function>XInternAtom</function>.

-<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>

-<indexterm significance="preferred"><primary>XInternAtom</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Atom <function>XInternAtom</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>const char<parameter> *atom_name</parameter></paramdef>

-  <paramdef>Bool<parameter> only_if_exists</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>atom_name</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the name associated with the atom you want returned.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>only_if_exists</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether the atom must be created.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XInternAtom</function>

-function returns the atom identifier associated with the specified atom_name

-string.

-If only_if_exists is 

-<symbol>False</symbol>,

-the atom is created if it does not exist.

-Therefore,

-<function>XInternAtom</function>

-can return

-<symbol>None</symbol>.

-If the atom name is not in the Host Portable Character Encoding, 

-the result is implementation-dependent.

-Uppercase and lowercase matter;

-the strings ``thing'', ``Thing'', and ``thinG'' 

-all designate different atoms.  

-The atom will remain defined even after the client's connection closes.

-It will become undefined only when the last connection to

-the X server closes.

-</para>

-<para>

-<!-- .LP -->

-<function>XInternAtom</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return atoms for an array of names, use 

-<function>XInternAtoms</function>.

-<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>

-<indexterm significance="preferred"><primary>XInternAtoms</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XInternAtoms</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>const char<parameter> **names</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-  <paramdef>Bool<parameter> only_if_exists</parameter></paramdef>

-  <paramdef>Atom<parameter> *atoms_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>names</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the array of atom names.

-<!-- .ds Cn atom names in the array -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of (Cn.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>only_if_exists</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that indicates whether the atom must be created.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>atoms_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the atoms.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XInternAtoms</function>

-function returns the atom identifiers associated with the specified names.

-The atoms are stored in the atoms_return array supplied by the caller.

-Calling this function is equivalent to calling

-<function>XInternAtom</function>

-for each of the names in turn with the specified value of only_if_exists,

-but this function minimizes the number of round-trip protocol exchanges

-between the client and the X server.

-</para>

-<para>

-<!-- .LP -->

-This function returns a nonzero status if atoms are returned for

-all of the names;

-otherwise, it returns zero.

-</para>

-<para>

-<!-- .LP -->

-<function>XInternAtoms</function>

-can generate

-<errorname>BadAlloc</errorname>

-and

-<errorname>BadValue</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return a name for a given atom identifier, use 

-<function>XGetAtomName</function>.

-<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGetAtomName</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>char *<function>XGetAtomName</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Atom<parameter> atom</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>atom</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the atom for the property name you want returned.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetAtomName</function>

-function returns the name associated with the specified atom.

-If the data returned by the server is in the Latin Portable Character Encoding,

-then the returned string is in the Host Portable Character Encoding.

-Otherwise, the result is implementation-dependent.

-To free the resulting string,

-call

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetAtomName</function>

-can generate a

-<errorname>BadAtom</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return the names for an array of atom identifiers, use 

-<function>XGetAtomNames</function>.

-<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGetAtomNames</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Status <function>XGetAtomNames</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Atom<parameter> *atoms</parameter></paramdef>

-  <paramdef>int<parameter> count</parameter></paramdef>

-  <paramdef>char<parameter> **names_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>atoms</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the array of atoms.

-<!-- .ds Cn atoms in the array -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>count</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of (Cn.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>names_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the atom names.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetAtomNames</function>

-function returns the names associated with the specified atoms.

-The names are stored in the names_return array supplied by the caller.

-Calling this function is equivalent to calling

-<function>XGetAtomName</function>

-for each of the atoms in turn,

-but this function minimizes the number of round-trip protocol exchanges

-between the client and the X server.

-</para>

-<para>

-<!-- .LP -->

-This function returns a nonzero status if names are returned for

-all of the atoms;

-otherwise, it returns zero.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetAtomNames</function>

-can generate a

-<errorname>BadAtom</errorname>

-error.

-</para>

-</sect1>

-<sect1 id="Obtaining_and_Changing_Window_Properties">

-<title>Obtaining and Changing Window Properties</title>

-<!-- .XS -->

-<!-- (SN Obtaining and Changing Window Properties  -->

-<!-- .XE -->

-<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 -->

-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>

-is used to represent 8-bit quantities, the type

-<type>short</type>

-is used to represent 16-bit quantities, and the type

-<type>long</type>

-is used to represent 32-bit quantities.

-</para>

-<para>

-<!-- .LP -->

-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 -->

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain the type, format, and value of a property of a given window, use 

-<function>XGetWindowProperty</function>.

-<indexterm><primary>Property</primary><secondary>getting</secondary></indexterm>

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XGetWindowProperty</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>int <function>XGetWindowProperty</function></funcdef>

-  <paramdef><parameter> display</parameter></paramdef>

-  <paramdef><parameter> w</parameter></paramdef>

-  <paramdef><parameter> property</parameter></paramdef>

-  <paramdef><parameter> long_offset</parameter></paramdef>

-  <paramdef><parameter> long_length</parameter></paramdef>

-  <paramdef><parameter> delete</parameter></paramdef>

-  <paramdef><parameter> req_type</parameter></paramdef>

-  <paramdef><parameter> actual_type_return</parameter></paramdef>

-  <paramdef><parameter> actual_format_return</parameter></paramdef>

-  <paramdef><parameter> nitems_return</parameter></paramdef>

-  <paramdef><parameter> bytes_after_return</parameter></paramdef>

-  <paramdef>.br<parameter> prop_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose property you want to obtain -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>long_offset</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the offset in the specified property (in 32-bit quantities) 

-where the data is to be retrieved.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>long_length</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the length in 32-bit multiples of the data to be retrieved.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>delete</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies a Boolean value that determines whether the property is deleted.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>req_type</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the atom identifier associated with the property type or

-<symbol>AnyPropertyType</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>actual_type_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the atom identifier  that defines the actual type of the property.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>actual_format_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the actual format of the property.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nitems_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the actual number of 8-bit, 16-bit, or 32-bit items 

-stored in the prop_return data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>bytes_after_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the number of bytes remaining to be read in the property if 

-a partial read was performed.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>prop_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the data in the specified format.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetWindowProperty</function>

-function returns the actual type of the property; the actual format of the property;

-the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining

-to be read in the property; and a pointer to the data actually returned.

-<function>XGetWindowProperty</function>

-sets the return arguments as follows:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If the specified property does not exist for the specified window,

-<function>XGetWindowProperty</function>

-returns 

-<symbol>None</symbol>

-to actual_type_return and the value zero to 

-actual_format_return and bytes_after_return.

-The nitems_return argument is empty.

-In this case, the delete argument is ignored.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the specified property exists 

-but its type does not match the specified type,

-<function>XGetWindowProperty</function>

-returns the actual property type to actual_type_return, 

-the actual property format (never zero) to actual_format_return, 

-and the property length in bytes

-(even if the actual_format_return is 16 or 32) 

-to bytes_after_return.

-It also ignores the delete argument.

-The nitems_return argument is empty.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If the specified property exists and either you assign 

-<symbol>AnyPropertyType</symbol>

-to the req_type argument or the specified type matches the actual property type,

-<function>XGetWindowProperty</function>

-returns the actual property type to actual_type_return and the actual

-property format (never zero) to actual_format_return. 

-It also returns a value to bytes_after_return and nitems_return, by 

-defining the following

-values:

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-<!-- .nf -->

-     N = actual length of the stored property in bytes

-          (even if the format is 16 or 32)

-     I = 4 * long_offset

-     T = N - I

-     L = MINIMUM(T, 4 * long_length)

-     A = N - (I + L)

-<!-- .fi -->

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-The returned value starts at byte index I in the property (indexing

-from zero), and its length in bytes is L.

-If the value for long_offset causes L to be negative,

-a

-<errorname>BadValue</errorname>

-error results. 

-The value of bytes_after_return is A, 

-giving the number of trailing unread bytes in the stored property.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-If the returned format is 8, the returned data is represented as a

-<type>char</type>

-array.

-If the returned format is 16, the returned data is represented as a

-<type>short</type>

-array and should be cast to that type to obtain the elements.

-If the returned format is 32, the returned data is represented as a

-<type>long</type>

-array and should be cast to that type to obtain the elements.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetWindowProperty</function>

-always allocates one extra byte in prop_return 

-(even if the property is zero length) 

-and sets it to zero so that simple properties consisting of characters

-do not have to be copied into yet another string before use.

-</para>

-<para>

-<!-- .LP -->

-If delete is 

-<symbol>True</symbol>

-and bytes_after_return is zero, 

-<function>XGetWindowProperty</function>

-deletes the property 

-from the window and generates a 

-<symbol>PropertyNotify</symbol>

-event on the window.

-</para>

-<para>

-<!-- .LP -->

-The function returns

-<symbol>Success</symbol>

-if it executes successfully.

-To free the resulting data,

-use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetWindowProperty</function>

-can generate

-<errorname>BadAtom</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To obtain a given window's property list, use 

-<function>XListProperties</function>.

-<indexterm><primary>Property</primary><secondary>listing</secondary></indexterm>

-<indexterm significance="preferred"><primary>XListProperties</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Atom *<function>XListProperties</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>int<parameter> *num_prop_return</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose property list you want to obtain -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_prop_return</emphasis>

-    </term>

-    <listitem>

-      <para>

-Returns the length of the properties array.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XListProperties</function>

-function returns a pointer to an array of atom properties that are defined for 

-the specified window or returns NULL if no properties were found.

-To free the memory allocated by this function, use

-<function>XFree</function>.

-</para>

-<para>

-<!-- .LP -->

-<function>XListProperties</function>

-can generate a

-<errorname>BadWindow</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To change a property of a given window, use

-<function>XChangeProperty</function>.

-<indexterm><primary>Property</primary><secondary>changing</secondary></indexterm>

-<indexterm><primary>Property</primary><secondary>appending</secondary></indexterm>

-<indexterm><primary>Property</primary><secondary>prepending</secondary></indexterm>

-<indexterm><primary>Property</primary><secondary>replacing</secondary></indexterm>

-<indexterm><primary>Property</primary><secondary>format</secondary></indexterm>

-<indexterm><primary>Property</primary><secondary>type</secondary></indexterm>

-<indexterm significance="preferred"><primary>XChangeProperty</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XChangeProperty</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Atomproperty,<parameter> type</parameter></paramdef>

-  <paramdef>int<parameter> format</parameter></paramdef>

-  <paramdef>int<parameter> mode</parameter></paramdef>

-  <paramdef>unsignedchar<parameter> *data</parameter></paramdef>

-  <paramdef>int<parameter> nelements</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose property you want to change -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>type</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the type of the property.

-The X server does not interpret the type but simply

-passes it back to an application that later calls 

-<function>XGetWindowProperty</function>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>format</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies whether the data should be viewed as a list

-of 8-bit, 16-bit, or 32-bit quantities.

-Possible values are 8, 16, and 32.

-This information allows the X server to correctly perform

-byte-swap operations as necessary.

-If the format is 16-bit or 32-bit,

-you must explicitly cast your data pointer to an (unsigned char *) in the call

-to 

-<function>XChangeProperty</function>.

-<!-- .\" Changed name of this file to prop_mode.a on 1/13/87 -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>mode</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the mode of the operation.

-You can pass

-<symbol>PropModeReplace</symbol>,

-<symbol>PropModePrepend</symbol>,

-or

-<symbol>PropModeAppend</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>data</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property data.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>nelements</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the number of elements of the specified data format.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XChangeProperty</function>

-function alters the property for the specified window and

-causes the X server to generate a

-<symbol>PropertyNotify</symbol>

-event on that window.

-<function>XChangeProperty</function>

-performs the following:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If mode is

-<symbol>PropModeReplace</symbol>,

-<function>XChangeProperty</function>

-discards the previous property value and stores the new data.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If mode is

-<symbol>PropModePrepend</symbol>

-or

-<symbol>PropModeAppend</symbol>,

-<function>XChangeProperty</function>

-inserts the specified data before the beginning of the existing data

-or onto the end of the existing data, respectively.

-The type and format must match the existing property value,

-or a

-<errorname>BadMatch</errorname>

-error results.

-If the property is undefined, 

-it is treated as defined with the correct type and

-format with zero-length data.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-If the specified format is 8, the property data must be a

-<type>char</type>

-array.

-If the specified format is 16, the property data must be a

-<type>short</type>

-array.

-If the specified format is 32, the property data must be a

-<type>long</type>

-array.

-</para>

-<para>

-<!-- .LP -->

-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 -->

-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

-<errorname>BadAlloc</errorname>

-error results.)

-</para>

-<para>

-<!-- .LP -->

-<function>XChangeProperty</function>

-can generate

-<errorname>BadAlloc</errorname>,

-<errorname>BadAtom</errorname>,

-<errorname>BadMatch</errorname>,

-<errorname>BadValue</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To rotate a window's property list, use

-<function>XRotateWindowProperties</function>.

-</para>

-<para>

-<!-- .LP -->

-<indexterm significance="preferred"><primary>XRotateWindowProperties</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XRotateWindowProperties</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Atom<parameter> properties[]</parameter></paramdef>

-  <paramdef>int<parameter> num_prop</parameter></paramdef>

-  <paramdef>int<parameter> npositions</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>properties</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the array of properties that are to be rotated.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>num_prop</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the length of the properties array.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>npositions</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the rotation amount.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XRotateWindowProperties</function>

-function allows you to rotate properties on a window and causes

-the X server to generate

-<symbol>PropertyNotify</symbol>

-events.

-If the property names in the properties array are viewed as being numbered 

-starting from zero and if there are num_prop property names in the list,

-then the value associated with property name I becomes the value associated 

-with property name (I + npositions) mod N for all I from zero to N &minus; 1.

-The effect is to rotate the states by npositions places around the virtual ring

-of property names (right for positive npositions, 

-left for negative npositions).

-If npositions mod N is nonzero,

-the X server generates a

-<symbol>PropertyNotify</symbol>

-event for each property in the order that they are listed in the array.

-If an atom occurs more than once in the list or no property with that 

-name is defined for the window,

-a 

-<errorname>BadMatch</errorname>

-error results.

-If a 

-<errorname>BadAtom</errorname>

-or 

-<errorname>BadMatch</errorname>

-error results,

-no properties are changed.

-</para>

-<para>

-<!-- .LP -->

-<function>XRotateWindowProperties</function>

-can generate

-<errorname>BadAtom</errorname>,

-<errorname>BadMatch</errorname>,

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To delete a property on a given window, use 

-<function>XDeleteProperty</function>.

-<indexterm><primary>Property</primary><secondary>deleting</secondary></indexterm>

-<indexterm significance="preferred"><primary>XDeleteProperty</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XDeleteProperty</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Window<parameter> w</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Wi whose property you want to delete -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>w</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the window (Wi.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XDeleteProperty</function>

-function deletes the specified property only if the

-property was defined on the specified window

-and causes the X server to generate a

-<symbol>PropertyNotify</symbol>

-event on the window unless the property does not exist.

-</para>

-<para>

-<!-- .LP -->

-<function>XDeleteProperty</function>

-can generate

-<errorname>BadAtom</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-</sect1>

-<sect1 id="Selections">

-<title>Selections</title>

-<!-- .XS -->

-<!-- (SN Selections -->

-<!-- .XE -->

-<para>

-<!-- .LP -->

-<indexterm><primary>Selection</primary></indexterm>

-Selections are one method used by applications to exchange data.

-By using the property mechanism,

-applications can exchange data of arbitrary types and can negotiate

-the type of the data.

-A selection can be thought of as an indirect property with a dynamic type.

-That is, rather than having the property stored in the X server,

-the property is maintained by some client (the owner).

-A selection is global in nature (considered to belong to the user 

-but be maintained by clients) rather than being private to a particular 

-window subhierarchy or a particular set of clients.

-</para>

-<para>

-<!-- .LP -->

-Xlib provides functions that you can use to set, get, or request conversion

-of selections.

-This allows applications to implement the notion of current selection,

-which requires that notification be sent to applications when they no 

-longer own the selection.

-Applications that support selection often highlight the current selection

-and so must be informed when another application has

-acquired the selection so that they can unhighlight the selection.

-</para>

-<para>

-<!-- .LP -->

-When a client asks for the contents of

-a selection, it specifies a selection target type.

-This target type

-can be used to control the transmitted representation of the contents.

-For example, if the selection is ``the last thing the user clicked on''

-and that is currently an image, then the target type might specify

-whether the contents of the image should be sent in XY format or Z format.

-</para>

-<para>

-<!-- .LP -->

-The target type can also be used to control the class of

-contents transmitted, for example, 

-asking for the ``looks'' (fonts, line

-spacing, indentation, and so forth) of a paragraph selection, not the

-text of the paragraph.

-The target type can also be used for other

-purposes.

-The protocol does not constrain the semantics.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To set the selection owner, use 

-<function>XSetSelectionOwner</function>.

-<indexterm><primary>Selection</primary><secondary>setting the owner</secondary></indexterm>

-<indexterm significance="preferred"><primary>XSetSelectionOwner</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XSetSelectionOwner</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Atom<parameter> selection</parameter></paramdef>

-  <paramdef>Window<parameter> owner</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>selection</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the selection atom.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>owner</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the owner of the specified selection atom.

-You can pass a window or

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XSetSelectionOwner</function>

-function changes the owner and last-change time for the specified selection

-and has no effect if the specified time is earlier than the current

-last-change time of the specified selection 

-or is later than the current X server time.

-Otherwise, the last-change time is set to the specified time,

-with

-<symbol>CurrentTime</symbol>

-replaced by the current server time.

-If the owner window is specified as

-<symbol>None</symbol>,

-then the owner of the selection becomes 

-<symbol>None</symbol>

-(that is, no owner).

-Otherwise, the owner of the selection becomes the client executing

-the request.

-</para>

-<para>

-<!-- .LP  -->

-If the new owner (whether a client or

-<symbol>None</symbol>)

-is not

-the same as the current owner of the selection and the current

-owner is not

-<symbol>None</symbol>,

-the current owner is sent a 

-<symbol>SelectionClear</symbol>

-event.

-If the client that is the owner of a selection is later

-terminated (that is, its connection is closed)

-or if the owner window it has specified in the request is later

-destroyed,

-the owner of the selection automatically

-reverts to

-<symbol>None</symbol>,

-but the last-change time is not affected.

-The selection atom is uninterpreted by the X server.

-<function>XGetSelectionOwner</function>

-returns the owner window, which is reported in 

-<symbol>SelectionRequest</symbol>

-and

-<symbol>SelectionClear</symbol>

-events.

-Selections are global to the X server.

-</para>

-<para>

-<!-- .LP -->

-<function>XSetSelectionOwner</function>

-can generate

-<errorname>BadAtom</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To return the selection owner, use 

-<function>XGetSelectionOwner</function>.

-<indexterm><primary>Selection</primary><secondary>getting the owner</secondary></indexterm>

-<indexterm significance="preferred"><primary>XGetSelectionOwner</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef>Window <function>XGetSelectionOwner</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Atom<parameter> selection</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-<!-- .ds Se whose owner you want returned -->

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>selection</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the selection atom (Se.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-The

-<function>XGetSelectionOwner</function>

-function

-returns the window ID associated with the window that currently owns the

-specified selection.

-If no selection was specified, the function returns the constant

-<symbol>None</symbol>.

-If

-<symbol>None</symbol>

-is returned,

-there is no owner for the selection.

-</para>

-<para>

-<!-- .LP -->

-<function>XGetSelectionOwner</function>

-can generate a

-<errorname>BadAtom</errorname>

-error.

-</para>

-<para>

-<!-- .LP -->

-<!-- .sp -->

-To request conversion of a selection, use 

-<function>XConvertSelection</function>.

-<indexterm><primary>Selection</primary><secondary>converting</secondary></indexterm>

-<indexterm significance="preferred"><primary>XConvertSelection</primary></indexterm>

-<!-- .sM -->

-<funcsynopsis>

-<funcprototype>

-  <funcdef><function>XConvertSelection</function></funcdef>

-  <paramdef>Display<parameter> *display</parameter></paramdef>

-  <paramdef>Atomselection,<parameter> target</parameter></paramdef>

-  <paramdef>Atom<parameter> property</parameter></paramdef>

-  <paramdef>Window<parameter> requestor</parameter></paramdef>

-  <paramdef>Time<parameter> time</parameter></paramdef>

-</funcprototype>

-</funcsynopsis>

-<!-- .FN -->

-<variablelist>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>display</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the connection to the X server.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>selection</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the selection atom.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>target</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the target atom.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>property</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the property name.

-You also can pass 

-<symbol>None</symbol>.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>requestor</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the requestor.

-      </para>

-    </listitem>

-  </varlistentry>

-  <varlistentry>

-    <term>

-      <emphasis remap='I'>time</emphasis>

-    </term>

-    <listitem>

-      <para>

-Specifies the time.

-You can pass either a timestamp or

-<symbol>CurrentTime</symbol>.

-    </para>

-  </listitem>

-  </varlistentry>

-</variablelist>

-</para>

-<para>

-<!-- .LP -->

-<!-- .eM -->

-<function>XConvertSelection</function>

-requests that the specified selection be converted to the specified target

-type:

-</para>

-<itemizedlist>

-  <listitem>

-    <para>

-If the specified selection has an owner, the X server sends a

-<symbol>SelectionRequest</symbol>

-event to that owner.

-    </para>

-  </listitem>

-  <listitem>

-    <para>

-If no owner for the specified

-selection exists, the X server generates a

-<symbol>SelectionNotify</symbol>

-event to the

-requestor with property

-<symbol>None</symbol>.

-    </para>

-  </listitem>

-</itemizedlist>

-<para>

-<!-- .LP -->

-The arguments are passed on unchanged in either of the events.

-There are two predefined selection atoms: PRIMARY and SECONDARY.

-</para>

-<para>

-<!-- .LP -->

-<function>XConvertSelection</function>

-can generate

-<errorname>BadAtom</errorname>

-and

-<errorname>BadWindow</errorname>

-errors.

-<!-- .bp -->

-

-

-</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="window_information_functions">
+<title>Window Information Functions</title>
+
+<para>
+After you connect the display to the X server and create a window, you can use the Xlib window
+information functions to:
+</para>
+<itemizedlist>
+  <listitem><para>Obtain information about a window</para></listitem>
+  <listitem><para>Translate screen coordinates</para></listitem>
+  <listitem><para>Manipulate property lists</para></listitem>
+  <listitem><para>Obtain and change window properties</para></listitem>
+  <listitem><para>Manipulate selections</para></listitem>
+</itemizedlist>
+
+<sect1 id="Obtaining_Window_Information">
+<title>Obtaining Window Information</title>
+<!-- .XS -->
+<!-- (SN Obtaining Window Information  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to obtain information about 
+the window tree, the window's current attributes, 
+the window's current geometry, or the current pointer coordinates.
+Because they are most frequently used by window managers,
+these functions all return a status to indicate whether the window still
+exists.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the parent, a list of children, and number of children for 
+a given window, use 
+<function>XQueryTree</function>.
+<indexterm><primary>Child Window</primary></indexterm>
+<indexterm><primary>Parent Window</primary></indexterm>
+<indexterm significance="preferred"><primary>XQueryTree</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XQueryTree</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Window<parameter> *root_return</parameter></paramdef>
+  <paramdef>Window<parameter> *parent_return</parameter></paramdef>
+  <paramdef>Window<parameter> **children_return</parameter></paramdef>
+  <paramdef>unsignedint<parameter> *nchildren_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose list of children, root, parent, and number of children \ -->
+you want to obtain
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>root_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the root window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>parent_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the parent window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>children_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the list of children.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nchildren_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of children.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryTree</function>
+function returns the root ID, the parent window ID, 
+a pointer to the list of children windows
+(NULL when there are no children), 
+and the number of children in the list for the specified window.
+The children are listed in current stacking order, from bottom-most 
+(first) to top-most (last).
+<function>XQueryTree</function>
+returns zero if it fails and nonzero if it succeeds.
+To free a non-NULL children list when it is no longer needed, use 
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryTree</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current attributes of a given window, use 
+<function>XGetWindowAttributes</function>.
+<indexterm significance="preferred"><primary>XGetWindowAttributes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XGetWindowAttributes</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>XWindowAttributes<parameter> *window_attributes_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose current attributes you want to obtain -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>window_attributes_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the specified window's attributes in the
+<structname>XWindowAttributes</structname>
+structure.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWindowAttributes</function>
+function returns the current attributes for the specified window to an
+<structname>XWindowAttributes</structname>
+structure.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XWindowAttributes</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+     int x, y;                     /* location of window */
+     int width, height;            /* width and height of window */
+     int border_width;             /* border width of window */
+     int depth;                    /* depth of window */
+     Visual *visual;               /* the associated visual structure */
+     Window root;                  /* root of screen containing window */
+     int class;                    /* InputOutput, InputOnly*/
+     int bit_gravity;              /* one of the bit gravity values */
+     int win_gravity;              /* one of the window gravity values */
+     int backing_store;            /* NotUseful, WhenMapped, Always */
+     unsigned long backing_planes; /* planes to be preserved if possible */
+     unsigned long backing_pixel;  /* value to be used when restoring planes */
+     Bool save_under;              /* boolean, should bits under be saved? */
+     Colormap colormap;            /* color map to be associated with window */
+     Bool map_installed;           /* boolean, is color map currently installed*/
+     int map_state;                /* IsUnmapped, IsUnviewable, IsViewable */
+     long all_event_masks;         /* set of events all people have interest in*/
+     long your_event_mask;         /* my event mask */
+     long do_not_propagate_mask;   /* set of events that should not propagate */
+     Bool override_redirect;       /* boolean value for override-redirect */
+     Screen *screen;               /* back pointer to correct screen */
+} XWindowAttributes;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x and y members are set to the upper-left outer
+corner relative to the parent window's origin.
+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 window's border width in pixels.
+The depth member is set to the depth of the window 
+(that is, bits per pixel for the object).
+The visual member is a pointer to the screen's associated
+<structname>Visual</structname>
+structure.
+The root member is set to the root window of the screen containing the window.
+The class member is set to the window's class and can be either
+<symbol>InputOutput</symbol>
+or
+<symbol>InputOnly</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The bit_gravity member is set to the window's bit gravity
+and can be one of the following:
+  <simplelist type="vert" columns="2">
+    <member><symbol>ForgetGravity</symbol></member>
+    <member><symbol>NorthWestGravity</symbol></member>
+    <member><symbol>NorthGravity</symbol></member>
+    <member><symbol>NorthEastGravity</symbol></member>
+    <member><symbol>WestGravity</symbol></member>
+
+    <member><symbol>EastGravity</symbol></member>
+    <member><symbol>SouthWestGravity</symbol></member>
+    <member><symbol>SouthGravity</symbol></member>
+    <member><symbol>SouthEastGravity</symbol></member>
+    <member><symbol>StaticGravity</symbol></member>
+  </simplelist>
+</para>
+<para>
+The win_gravity member is set to the window's window gravity
+and can be one of the following:
+  <simplelist type="vert" columns="2">
+    <member><symbol>UnmapGravity</symbol></member>
+    <member><symbol>NorthWestGravity</symbol></member>
+    <member><symbol>NorthGravity</symbol></member>
+    <member><symbol>NorthEastGravity</symbol></member>
+    <member><symbol>WestGravity</symbol></member>
+
+    <member><symbol>EastGravity</symbol></member>
+    <member><symbol>SouthWestGravity</symbol></member>
+    <member><symbol>SouthGravity</symbol></member>
+    <member><symbol>SouthEastGravity</symbol></member>
+    <member><symbol>StaticGravity</symbol></member>
+    <member><symbol>CenterGravity</symbol></member>
+  </simplelist>
+</para>
+<para>
+<!-- .LP -->
+For additional information on gravity,
+see section 3.2.3. <!-- xref -->
+</para>
+<para>
+<!-- .LP -->
+The backing_store member is set to indicate how the X server should maintain
+the contents of a window 
+and can be 
+<symbol>WhenMapped</symbol>,
+<symbol>Always</symbol>,
+or
+<symbol>NotUseful</symbol>.
+The backing_planes member is set to indicate (with bits set to 1) which bit 
+planes of the window hold dynamic data that must be preserved in backing_stores 
+and during save_unders.
+The backing_pixel member is set to indicate what values to use 
+for planes not set in backing_planes.
+</para>
+<para>
+<!-- .LP -->
+The save_under member is set to 
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+The colormap member is set to the colormap for the specified window and can be
+a colormap ID or 
+<symbol>None</symbol>.
+The map_installed member is set to indicate whether the colormap is 
+currently installed and can be 
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+The map_state member is set to indicate the state of the window and can be
+<symbol>IsUnmapped</symbol>,
+<symbol>IsUnviewable</symbol>,
+or
+<symbol>IsViewable</symbol>.
+<symbol>IsUnviewable</symbol>
+is used if the window is mapped but some ancestor is unmapped.
+</para>
+<para>
+<!-- .LP -->
+The all_event_masks member is set to the bitwise inclusive OR of all event 
+masks selected on the window by all clients.
+The your_event_mask member is set to the bitwise inclusive OR of all event 
+masks selected by the querying client.
+The do_not_propagate_mask member is set to the bitwise inclusive OR of the 
+set of events that should not propagate.
+</para>
+<para>
+<!-- .LP -->
+The override_redirect member is set to indicate whether this window overrides
+structure control facilities and can be 
+<symbol>True</symbol>
+or
+<symbol>False</symbol>.
+Window manager clients should ignore the window if this member is
+<symbol>True</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The screen member is set to a screen pointer that gives you a back pointer 
+to the correct screen.
+This makes it easier to obtain the screen information without
+having to loop over the root window fields to see which field matches.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWindowAttributes</function>
+can generate
+<errorname>BadDrawable</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the current geometry of a given drawable, use 
+<function>XGetGeometry</function>.
+<indexterm significance="preferred"><primary>XGetGeometry</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XGetGeometry</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Drawable<parameter> d</parameter></paramdef>
+  <paramdef>Window<parameter> *root_return</parameter></paramdef>
+  <paramdef>int*x_return,<parameter> *y_return</parameter></paramdef>
+  <paramdef>unsignedint*width_return,<parameter> *height_return</parameter></paramdef>
+  <paramdef>unsignedint<parameter> *border_width_return</parameter></paramdef>
+  <paramdef>unsignedint<parameter> *depth_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Dr , which can be a window or a pixmap -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>d</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the drawable(Dr. 
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>root_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the root window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>x_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>y_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the x and y coordinates that define the location of the drawable.
+For a window, 
+these coordinates specify the upper-left outer corner relative to
+its parent's origin.
+For pixmaps, these coordinates are always zero.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>height_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the drawable's dimensions (width and height).
+For a window, 
+these dimensions specify the inside size, not including the border.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>border_width_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the border width in pixels. 
+If the drawable is a pixmap, it returns zero.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>depth_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the depth of the drawable (bits per pixel for the object).
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetGeometry</function>
+function returns the root window and the current geometry of the drawable.
+The geometry of the drawable includes the x and y coordinates, width and height,
+border width, and depth.
+These are described in the argument list.
+It is legal to pass to this function a window whose class is
+<symbol>InputOnly</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetGeometry</function>
+can generate a
+<errorname>BadDrawable</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Translating_Screen_Coordinates">
+<title>Translating Screen Coordinates</title>
+<!-- .XS -->
+<!-- (SN Translating Screen Coordinates  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications sometimes
+need to perform a coordinate transformation from the coordinate
+space of one window to another window or need to determine which
+window the pointing device is in.
+<function>XTranslateCoordinates</function>
+and
+<function>XQueryPointer</function>
+fulfill these needs (and avoid any race conditions) by
+asking the X server to perform these operations.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To translate a coordinate in one window to the coordinate
+space of another window, use
+<function>XTranslateCoordinates</function>.
+<indexterm significance="preferred"><primary>XTranslateCoordinates</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool <function>XTranslateCoordinates</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Windowsrc_w,<parameter> dest_w</parameter></paramdef>
+  <paramdef>intsrc_x,<parameter> src_y</parameter></paramdef>
+  <paramdef>int*dest_x_return,<parameter> *dest_y_return</parameter></paramdef>
+  <paramdef>Window<parameter> *child_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the source window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the destination window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_x</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>src_y</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specify the x and y coordinates within the source window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_x_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>dest_y_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the x and y coordinates within the destination window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>child_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the child if the coordinates are contained in a mapped child of the
+destination window.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If
+<function>XTranslateCoordinates</function>
+returns
+<symbol>True</symbol>,
+it takes the src_x and src_y coordinates relative
+to the source window's origin and returns these coordinates to 
+dest_x_return and dest_y_return
+relative to the destination window's origin.
+If
+<function>XTranslateCoordinates</function>
+returns 
+<symbol>False</symbol>,
+src_w and dest_w are on different screens,
+and dest_x_return and dest_y_return are zero.
+If the coordinates are contained in a mapped child of dest_w,
+that child is returned to child_return.
+Otherwise, child_return is set to
+<symbol>None</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<function>XTranslateCoordinates</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the screen coordinates of the pointer
+or to determine the pointer coordinates relative to a specified window, use 
+<function>XQueryPointer</function>.
+<indexterm significance="preferred"><primary>XQueryPointer</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Bool <function>XQueryPointer</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Window*root_return,<parameter> *child_return</parameter></paramdef>
+  <paramdef>int*root_x_return,<parameter> *root_y_return</parameter></paramdef>
+  <paramdef>int*win_x_return,<parameter> *win_y_return</parameter></paramdef>
+  <paramdef>unsignedint<parameter> *mask_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+<!-- .ds Ro that the pointer is in -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>root_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the root window (Ro.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>child_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the child window that the pointer is located in, if any.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>root_x_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>root_y_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the pointer coordinates relative to the root window's origin.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>win_x_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+<!-- .br -->
+<!-- .ns -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>win_y_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Return the pointer coordinates relative to the specified window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mask_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the current state of the modifier keys and pointer buttons.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XQueryPointer</function>
+function returns the root window the pointer is logically on and the pointer
+coordinates relative to the root window's origin.
+If
+<function>XQueryPointer</function>
+returns 
+<symbol>False</symbol>,
+the pointer is not on the same screen as the specified window, and
+<function>XQueryPointer</function>
+returns 
+<symbol>None</symbol>
+to child_return and zero to win_x_return and win_y_return.
+If 
+<function>XQueryPointer</function>
+returns 
+<symbol>True</symbol>,
+the pointer coordinates returned to win_x_return and win_y_return
+are relative to the origin of the specified window.
+In this case, 
+<function>XQueryPointer</function>
+returns the child that contains the pointer, if any,
+or else
+<symbol>None</symbol>
+to child_return.
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryPointer</function>
+returns the current logical state of the keyboard buttons 
+and the modifier keys in mask_return.
+It sets mask_return to the bitwise inclusive OR of one or more
+of the button or modifier key bitmasks to match 
+the current state of the mouse buttons and the modifier keys.
+</para>
+<para>
+<!-- .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 -->
+</para>
+<para>
+<!-- .LP -->
+<function>XQueryPointer</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Properties_and_Atoms">
+<title>Properties and Atoms</title>
+<!-- .XS -->
+<!-- (SN Properties and Atoms  -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+A property is a collection of named, typed data.
+The window system has a set of predefined properties
+<indexterm><primary>Atom</primary><secondary>predefined</secondary></indexterm>
+(for example, the name of a window, size hints, and so on), and users can
+define any other arbitrary information and associate it with windows.
+Each property has a name,
+which is an ISO Latin-1 string.
+For each named property,
+a unique identifier (atom) is associated with it. 
+A property also has a type, for example, string or integer.
+These types are also indicated using atoms, so arbitrary new
+types can be defined.
+Data of only one type may be associated with a single
+property name.
+Clients can store and retrieve properties associated with windows.
+For efficiency reasons,
+an atom is used rather than a character string.
+<function>XInternAtom</function>
+can be used to obtain the atom for property names.
+<indexterm><primary>Atom</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+A property is also stored in one of several possible formats.
+The X server can store the information as 8-bit quantities, 16-bit
+quantities, or 32-bit quantities.
+This permits the X server to present the data in the byte order that the
+client expects.
+<!-- .NT Note -->
+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 -->
+<!-- .NE -->
+The type of a property is defined by an atom, which allows for
+arbitrary extension in this type scheme.
+<indexterm><primary>Atom</primary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+Certain property names are
+predefined in the server for commonly used functions.
+The atoms for these properties are defined in 
+<filename class="headerfile">&lt;X11/Xatom.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xatom.h&gt;</filename></secondary></indexterm>
+To avoid name clashes with user symbols, the 
+<code>#define</code>
+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 -->
+</para>
+<para>
+<!-- .LP -->
+The core protocol imposes no semantics on these property names,
+but semantics are specified in other X Consortium standards,
+such as the <emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>
+and the <emphasis remap='I'>X Logical Font Description Conventions</emphasis>.
+</para>
+<para>
+<!-- .LP -->
+You can use properties to communicate other information between
+applications.
+The functions described in this section let you define new properties 
+and get the unique atom IDs in your applications.
+</para>
+<para>
+<!-- .LP -->
+Although any particular atom can have some client interpretation 
+within each of the name spaces, 
+atoms occur in five distinct name spaces within the protocol: 
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+Selections
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Property names
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Property types
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Font properties 
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+Type of a 
+<symbol>ClientMessage</symbol>
+event (none are built into the X server)
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+</para>
+<para>
+<!-- .LP -->
+The built-in selection property names are:
+<simplelist type="vert" columns="2">
+  <member><property>PRIMARY</property></member>
+  <member><property>SECONDARY</property></member>
+</simplelist>
+</para>
+<para>
+<!-- .LP -->
+The built-in property names are: 
+  <simplelist type="vert" columns="2">
+    <member><property>CUT_BUFFER0</property></member>
+    <member><property>CUT_BUFFER1</property></member>
+    <member><property>CUT_BUFFER2</property></member>
+    <member><property>CUT_BUFFER3</property></member>
+    <member><property>CUT_BUFFER4</property></member>
+    <member><property>CUT_BUFFER5</property></member>
+    <member><property>CUT_BUFFER6</property></member>
+    <member><property>CUT_BUFFER7</property></member>
+    <member><property>RGB_BEST_MAP</property></member>
+    <member><property>RGB_BLUE_MAP</property></member>
+    <member><property>RGB_DEFAULT_MAP</property></member>
+    <member><property>RGB_GRAY_MAP</property></member>
+    <member><property>RGB_GREEN_MAP</property></member>
+    <member><property>RGB_RED_MAP</property></member>
+
+    <member><property>RESOURCE_MANAGER</property></member>
+    <member><property>WM_CLASS</property></member>
+    <member><property>WM_CLIENT_MACHINE</property></member>
+    <member><property>WM_COLORMAP_WINDOWS</property></member>
+    <member><property>WM_COMMAND</property></member>
+    <member><property>WM_HINTS</property></member>
+    <member><property>WM_ICON_NAME</property></member>
+    <member><property>WM_ICON_SIZE</property></member>
+    <member><property>WM_NAME</property></member>
+    <member><property>WM_NORMAL_HINTS</property></member>
+    <member><property>WM_PROTOCOLS</property></member>
+    <member><property>WM_STATE</property></member>
+    <member><property>WM_TRANSIENT_FOR</property></member>
+    <member><property>WM_ZOOM_HINTS</property></member>
+  </simplelist>
+</para>
+<para>
+The built-in property types are: 
+  <simplelist type="vert" columns="2">
+    <member><property>ARC</property></member>
+    <member><property>ATOM</property></member>
+    <member><property>BITMAP</property></member>
+    <member><property>CARDINAL</property></member>
+    <member><property>COLORMAP</property></member>
+    <member><property>CURSOR</property></member>
+    <member><property>DRAWABLE</property></member>
+    <member><property>FONT</property></member>
+    <member><property>INTEGER</property></member>
+    <member><property>PIXMAP</property></member>
+    <member><property>POINT</property></member>
+    <member><property>RGB_COLOR_MAP</property></member>
+    <member><property>RECTANGLE</property></member>
+    <member><property>STRING</property></member>
+    <member><property>VISUALID</property></member>
+    <member><property>WINDOW</property></member>
+    <member><property>WM_HINTS</property></member>
+    <member><property>WM_SIZE_HINTS</property></member>
+  </simplelist>
+</para>
+<para>
+The built-in font property names are: 
+  <simplelist type="vert" columns="2">
+    <member><property>MIN_SPACE</property></member>
+    <member><property>NORM_SPACE</property></member>
+    <member><property>MAX_SPACE</property></member>
+    <member><property>END_SPACE</property></member>
+    <member><property>SUPERSCRIPT_X</property></member>
+    <member><property>SUPERSCRIPT_Y</property></member>
+    <member><property>SUBSCRIPT_X</property></member>
+    <member><property>SUBSCRIPT_Y</property></member>
+    <member><property>UNDERLINE_POSITION</property></member>
+    <member><property>UNDERLINE_THICKNESS</property></member>
+    <member><property>FONT_NAME</property></member>
+    <member><property>FULL_NAME</property></member>
+
+    <member><property>STRIKEOUT_DESCENT</property></member>
+    <member><property>STRIKEOUT_ASCENT</property></member>
+    <member><property>ITALIC_ANGLE</property></member>
+    <member><property>X_HEIGHT</property></member>
+    <member><property>QUAD_WIDTH</property></member>
+    <member><property>WEIGHT</property></member>
+    <member><property>POINT_SIZE</property></member>
+    <member><property>RESOLUTION</property></member>
+    <member><property>COPYRIGHT</property></member>
+    <member><property>NOTICE</property></member>
+    <member><property>FAMILY_NAME</property></member>
+    <member><property>CAP_HEIGHT</property></member>
+  </simplelist>
+</para>
+<para>
+<!-- .LP -->
+For further information about font properties,
+see section 8.5. <!-- xref -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return an atom for a given name, use 
+<function>XInternAtom</function>.
+<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>
+<indexterm significance="preferred"><primary>XInternAtom</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Atom <function>XInternAtom</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> *atom_name</parameter></paramdef>
+  <paramdef>Bool<parameter> only_if_exists</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>atom_name</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the name associated with the atom you want returned.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>only_if_exists</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether the atom must be created.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInternAtom</function>
+function returns the atom identifier associated with the specified atom_name
+string.
+If only_if_exists is 
+<symbol>False</symbol>,
+the atom is created if it does not exist.
+Therefore,
+<function>XInternAtom</function>
+can return
+<symbol>None</symbol>.
+If the atom name is not in the Host Portable Character Encoding, 
+the result is implementation-dependent.
+Uppercase and lowercase matter;
+the strings ``thing'', ``Thing'', and ``thinG'' 
+all designate different atoms.  
+The atom will remain defined even after the client's connection closes.
+It will become undefined only when the last connection to
+the X server closes.
+</para>
+<para>
+<!-- .LP -->
+<function>XInternAtom</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return atoms for an array of names, use 
+<function>XInternAtoms</function>.
+<indexterm><primary>Atom</primary><secondary>interning</secondary></indexterm>
+<indexterm significance="preferred"><primary>XInternAtoms</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XInternAtoms</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>char<parameter> **names</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+  <paramdef>Bool<parameter> only_if_exists</parameter></paramdef>
+  <paramdef>Atom<parameter> *atoms_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>names</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the array of atom names.
+<!-- .ds Cn atom names in the array -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of (Cn.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>only_if_exists</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that indicates whether the atom must be created.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>atoms_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the atoms.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XInternAtoms</function>
+function returns the atom identifiers associated with the specified names.
+The atoms are stored in the atoms_return array supplied by the caller.
+Calling this function is equivalent to calling
+<function>XInternAtom</function>
+for each of the names in turn with the specified value of only_if_exists,
+but this function minimizes the number of round-trip protocol exchanges
+between the client and the X server.
+</para>
+<para>
+<!-- .LP -->
+This function returns a nonzero status if atoms are returned for
+all of the names;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XInternAtoms</function>
+can generate
+<errorname>BadAlloc</errorname>
+and
+<errorname>BadValue</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return a name for a given atom identifier, use 
+<function>XGetAtomName</function>.
+<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetAtomName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>char *<function>XGetAtomName</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Atom<parameter> atom</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>atom</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the atom for the property name you want returned.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetAtomName</function>
+function returns the name associated with the specified atom.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned string is in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+To free the resulting string,
+call
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetAtomName</function>
+can generate a
+<errorname>BadAtom</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the names for an array of atom identifiers, use 
+<function>XGetAtomNames</function>.
+<indexterm><primary>Atom</primary><secondary>getting name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetAtomNames</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Status <function>XGetAtomNames</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Atom<parameter> *atoms</parameter></paramdef>
+  <paramdef>int<parameter> count</parameter></paramdef>
+  <paramdef>char<parameter> **names_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>atoms</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the array of atoms.
+<!-- .ds Cn atoms in the array -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>count</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of (Cn.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>names_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the atom names.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetAtomNames</function>
+function returns the names associated with the specified atoms.
+The names are stored in the names_return array supplied by the caller.
+Calling this function is equivalent to calling
+<function>XGetAtomName</function>
+for each of the atoms in turn,
+but this function minimizes the number of round-trip protocol exchanges
+between the client and the X server.
+</para>
+<para>
+<!-- .LP -->
+This function returns a nonzero status if names are returned for
+all of the atoms;
+otherwise, it returns zero.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetAtomNames</function>
+can generate a
+<errorname>BadAtom</errorname>
+error.
+</para>
+</sect1>
+<sect1 id="Obtaining_and_Changing_Window_Properties">
+<title>Obtaining and Changing Window Properties</title>
+<!-- .XS -->
+<!-- (SN Obtaining and Changing Window Properties  -->
+<!-- .XE -->
+<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 -->
+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>
+is used to represent 8-bit quantities, the type
+<type>short</type>
+is used to represent 16-bit quantities, and the type
+<type>long</type>
+is used to represent 32-bit quantities.
+</para>
+<para>
+<!-- .LP -->
+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 -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the type, format, and value of a property of a given window, use 
+<function>XGetWindowProperty</function>.
+<indexterm><primary>Property</primary><secondary>getting</secondary></indexterm>
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XGetWindowProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>int <function>XGetWindowProperty</function></funcdef>
+  <paramdef><parameter> display</parameter></paramdef>
+  <paramdef><parameter> w</parameter></paramdef>
+  <paramdef><parameter> property</parameter></paramdef>
+  <paramdef><parameter> long_offset</parameter></paramdef>
+  <paramdef><parameter> long_length</parameter></paramdef>
+  <paramdef><parameter> delete</parameter></paramdef>
+  <paramdef><parameter> req_type</parameter></paramdef>
+  <paramdef><parameter> actual_type_return</parameter></paramdef>
+  <paramdef><parameter> actual_format_return</parameter></paramdef>
+  <paramdef><parameter> nitems_return</parameter></paramdef>
+  <paramdef><parameter> bytes_after_return</parameter></paramdef>
+  <paramdef>.br<parameter> prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose property you want to obtain -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>long_offset</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the offset in the specified property (in 32-bit quantities) 
+where the data is to be retrieved.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>long_length</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the length in 32-bit multiples of the data to be retrieved.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>delete</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies a Boolean value that determines whether the property is deleted.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>req_type</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the atom identifier associated with the property type or
+<symbol>AnyPropertyType</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>actual_type_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the atom identifier  that defines the actual type of the property.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>actual_format_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the actual format of the property.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nitems_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the actual number of 8-bit, 16-bit, or 32-bit items 
+stored in the prop_return data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>bytes_after_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the number of bytes remaining to be read in the property if 
+a partial read was performed.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>prop_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the data in the specified format.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWindowProperty</function>
+function returns the actual type of the property; the actual format of the property;
+the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
+to be read in the property; and a pointer to the data actually returned.
+<function>XGetWindowProperty</function>
+sets the return arguments as follows:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If the specified property does not exist for the specified window,
+<function>XGetWindowProperty</function>
+returns 
+<symbol>None</symbol>
+to actual_type_return and the value zero to 
+actual_format_return and bytes_after_return.
+The nitems_return argument is empty.
+In this case, the delete argument is ignored.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the specified property exists 
+but its type does not match the specified type,
+<function>XGetWindowProperty</function>
+returns the actual property type to actual_type_return, 
+the actual property format (never zero) to actual_format_return, 
+and the property length in bytes
+(even if the actual_format_return is 16 or 32) 
+to bytes_after_return.
+It also ignores the delete argument.
+The nitems_return argument is empty.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If the specified property exists and either you assign 
+<symbol>AnyPropertyType</symbol>
+to the req_type argument or the specified type matches the actual property type,
+<function>XGetWindowProperty</function>
+returns the actual property type to actual_type_return and the actual
+property format (never zero) to actual_format_return. 
+It also returns a value to bytes_after_return and nitems_return, by 
+defining the following
+values:
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+<!-- .nf -->
+     N = actual length of the stored property in bytes
+          (even if the format is 16 or 32)
+     I = 4 * long_offset
+     T = N - I
+     L = MINIMUM(T, 4 * long_length)
+     A = N - (I + L)
+<!-- .fi -->
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+The returned value starts at byte index I in the property (indexing
+from zero), and its length in bytes is L.
+If the value for long_offset causes L to be negative,
+a
+<errorname>BadValue</errorname>
+error results. 
+The value of bytes_after_return is A, 
+giving the number of trailing unread bytes in the stored property.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If the returned format is 8, the returned data is represented as a
+<type>char</type>
+array.
+If the returned format is 16, the returned data is represented as a
+<type>short</type>
+array and should be cast to that type to obtain the elements.
+If the returned format is 32, the returned data is represented as a
+<type>long</type>
+array and should be cast to that type to obtain the elements.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWindowProperty</function>
+always allocates one extra byte in prop_return 
+(even if the property is zero length) 
+and sets it to zero so that simple properties consisting of characters
+do not have to be copied into yet another string before use.
+</para>
+<para>
+<!-- .LP -->
+If delete is 
+<symbol>True</symbol>
+and bytes_after_return is zero, 
+<function>XGetWindowProperty</function>
+deletes the property 
+from the window and generates a 
+<symbol>PropertyNotify</symbol>
+event on the window.
+</para>
+<para>
+<!-- .LP -->
+The function returns
+<symbol>Success</symbol>
+if it executes successfully.
+To free the resulting data,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWindowProperty</function>
+can generate
+<errorname>BadAtom</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a given window's property list, use 
+<function>XListProperties</function>.
+<indexterm><primary>Property</primary><secondary>listing</secondary></indexterm>
+<indexterm significance="preferred"><primary>XListProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Atom *<function>XListProperties</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>int<parameter> *num_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose property list you want to obtain -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_prop_return</emphasis>
+    </term>
+    <listitem>
+      <para>
+Returns the length of the properties array.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XListProperties</function>
+function returns a pointer to an array of atom properties that are defined for 
+the specified window or returns NULL if no properties were found.
+To free the memory allocated by this function, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XListProperties</function>
+can generate a
+<errorname>BadWindow</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To change a property of a given window, use
+<function>XChangeProperty</function>.
+<indexterm><primary>Property</primary><secondary>changing</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>appending</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>prepending</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>replacing</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>format</secondary></indexterm>
+<indexterm><primary>Property</primary><secondary>type</secondary></indexterm>
+<indexterm significance="preferred"><primary>XChangeProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function>XChangeProperty</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Atomproperty,<parameter> type</parameter></paramdef>
+  <paramdef>int<parameter> format</parameter></paramdef>
+  <paramdef>int<parameter> mode</parameter></paramdef>
+  <paramdef>unsignedchar<parameter> *data</parameter></paramdef>
+  <paramdef>int<parameter> nelements</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose property you want to change -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>type</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the type of the property.
+The X server does not interpret the type but simply
+passes it back to an application that later calls 
+<function>XGetWindowProperty</function>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>format</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies whether the data should be viewed as a list
+of 8-bit, 16-bit, or 32-bit quantities.
+Possible values are 8, 16, and 32.
+This information allows the X server to correctly perform
+byte-swap operations as necessary.
+If the format is 16-bit or 32-bit,
+you must explicitly cast your data pointer to an (unsigned char *) in the call
+to 
+<function>XChangeProperty</function>.
+<!-- .\" Changed name of this file to prop_mode.a on 1/13/87 -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>mode</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the mode of the operation.
+You can pass
+<symbol>PropModeReplace</symbol>,
+<symbol>PropModePrepend</symbol>,
+or
+<symbol>PropModeAppend</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>data</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property data.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>nelements</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the number of elements of the specified data format.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XChangeProperty</function>
+function alters the property for the specified window and
+causes the X server to generate a
+<symbol>PropertyNotify</symbol>
+event on that window.
+<function>XChangeProperty</function>
+performs the following:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If mode is
+<symbol>PropModeReplace</symbol>,
+<function>XChangeProperty</function>
+discards the previous property value and stores the new data.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If mode is
+<symbol>PropModePrepend</symbol>
+or
+<symbol>PropModeAppend</symbol>,
+<function>XChangeProperty</function>
+inserts the specified data before the beginning of the existing data
+or onto the end of the existing data, respectively.
+The type and format must match the existing property value,
+or a
+<errorname>BadMatch</errorname>
+error results.
+If the property is undefined, 
+it is treated as defined with the correct type and
+format with zero-length data.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+If the specified format is 8, the property data must be a
+<type>char</type>
+array.
+If the specified format is 16, the property data must be a
+<type>short</type>
+array.
+If the specified format is 32, the property data must be a
+<type>long</type>
+array.
+</para>
+<para>
+<!-- .LP -->
+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 -->
+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
+<errorname>BadAlloc</errorname>
+error results.)
+</para>
+<para>
+<!-- .LP -->
+<function>XChangeProperty</function>
+can generate
+<errorname>BadAlloc</errorname>,
+<errorname>BadAtom</errorname>,
+<errorname>BadMatch</errorname>,
+<errorname>BadValue</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To rotate a window's property list, use
+<function>XRotateWindowProperties</function>.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XRotateWindowProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function>XRotateWindowProperties</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Atom<parameter> properties[]</parameter></paramdef>
+  <paramdef>int<parameter> num_prop</parameter></paramdef>
+  <paramdef>int<parameter> npositions</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>properties</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the array of properties that are to be rotated.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>num_prop</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the length of the properties array.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>npositions</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the rotation amount.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XRotateWindowProperties</function>
+function allows you to rotate properties on a window and causes
+the X server to generate
+<symbol>PropertyNotify</symbol>
+events.
+If the property names in the properties array are viewed as being numbered 
+starting from zero and if there are num_prop property names in the list,
+then the value associated with property name I becomes the value associated 
+with property name (I + npositions) mod N for all I from zero to N &minus; 1.
+The effect is to rotate the states by npositions places around the virtual ring
+of property names (right for positive npositions, 
+left for negative npositions).
+If npositions mod N is nonzero,
+the X server generates a
+<symbol>PropertyNotify</symbol>
+event for each property in the order that they are listed in the array.
+If an atom occurs more than once in the list or no property with that 
+name is defined for the window,
+a 
+<errorname>BadMatch</errorname>
+error results.
+If a 
+<errorname>BadAtom</errorname>
+or 
+<errorname>BadMatch</errorname>
+error results,
+no properties are changed.
+</para>
+<para>
+<!-- .LP -->
+<function>XRotateWindowProperties</function>
+can generate
+<errorname>BadAtom</errorname>,
+<errorname>BadMatch</errorname>,
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To delete a property on a given window, use 
+<function>XDeleteProperty</function>.
+<indexterm><primary>Property</primary><secondary>deleting</secondary></indexterm>
+<indexterm significance="preferred"><primary>XDeleteProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function>XDeleteProperty</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Window<parameter> w</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Wi whose property you want to delete -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>w</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the window (Wi.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDeleteProperty</function>
+function deletes the specified property only if the
+property was defined on the specified window
+and causes the X server to generate a
+<symbol>PropertyNotify</symbol>
+event on the window unless the property does not exist.
+</para>
+<para>
+<!-- .LP -->
+<function>XDeleteProperty</function>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+</sect1>
+<sect1 id="Selections">
+<title>Selections</title>
+<!-- .XS -->
+<!-- (SN Selections -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Selection</primary></indexterm>
+Selections are one method used by applications to exchange data.
+By using the property mechanism,
+applications can exchange data of arbitrary types and can negotiate
+the type of the data.
+A selection can be thought of as an indirect property with a dynamic type.
+That is, rather than having the property stored in the X server,
+the property is maintained by some client (the owner).
+A selection is global in nature (considered to belong to the user 
+but be maintained by clients) rather than being private to a particular 
+window subhierarchy or a particular set of clients.
+</para>
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set, get, or request conversion
+of selections.
+This allows applications to implement the notion of current selection,
+which requires that notification be sent to applications when they no 
+longer own the selection.
+Applications that support selection often highlight the current selection
+and so must be informed when another application has
+acquired the selection so that they can unhighlight the selection.
+</para>
+<para>
+<!-- .LP -->
+When a client asks for the contents of
+a selection, it specifies a selection target type.
+This target type
+can be used to control the transmitted representation of the contents.
+For example, if the selection is ``the last thing the user clicked on''
+and that is currently an image, then the target type might specify
+whether the contents of the image should be sent in XY format or Z format.
+</para>
+<para>
+<!-- .LP -->
+The target type can also be used to control the class of
+contents transmitted, for example, 
+asking for the ``looks'' (fonts, line
+spacing, indentation, and so forth) of a paragraph selection, not the
+text of the paragraph.
+The target type can also be used for other
+purposes.
+The protocol does not constrain the semantics.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the selection owner, use 
+<function>XSetSelectionOwner</function>.
+<indexterm><primary>Selection</primary><secondary>setting the owner</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSetSelectionOwner</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function>XSetSelectionOwner</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Atom<parameter> selection</parameter></paramdef>
+  <paramdef>Window<parameter> owner</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>selection</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the selection atom.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>owner</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the owner of the specified selection atom.
+You can pass a window or
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetSelectionOwner</function>
+function changes the owner and last-change time for the specified selection
+and has no effect if the specified time is earlier than the current
+last-change time of the specified selection 
+or is later than the current X server time.
+Otherwise, the last-change time is set to the specified time,
+with
+<symbol>CurrentTime</symbol>
+replaced by the current server time.
+If the owner window is specified as
+<symbol>None</symbol>,
+then the owner of the selection becomes 
+<symbol>None</symbol>
+(that is, no owner).
+Otherwise, the owner of the selection becomes the client executing
+the request.
+</para>
+<para>
+<!-- .LP  -->
+If the new owner (whether a client or
+<symbol>None</symbol>)
+is not
+the same as the current owner of the selection and the current
+owner is not
+<symbol>None</symbol>,
+the current owner is sent a 
+<symbol>SelectionClear</symbol>
+event.
+If the client that is the owner of a selection is later
+terminated (that is, its connection is closed)
+or if the owner window it has specified in the request is later
+destroyed,
+the owner of the selection automatically
+reverts to
+<symbol>None</symbol>,
+but the last-change time is not affected.
+The selection atom is uninterpreted by the X server.
+<function>XGetSelectionOwner</function>
+returns the owner window, which is reported in 
+<symbol>SelectionRequest</symbol>
+and
+<symbol>SelectionClear</symbol>
+events.
+Selections are global to the X server.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetSelectionOwner</function>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To return the selection owner, use 
+<function>XGetSelectionOwner</function>.
+<indexterm><primary>Selection</primary><secondary>getting the owner</secondary></indexterm>
+<indexterm significance="preferred"><primary>XGetSelectionOwner</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef>Window <function>XGetSelectionOwner</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Atom<parameter> selection</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+<!-- .ds Se whose owner you want returned -->
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>selection</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the selection atom (Se.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetSelectionOwner</function>
+function
+returns the window ID associated with the window that currently owns the
+specified selection.
+If no selection was specified, the function returns the constant
+<symbol>None</symbol>.
+If
+<symbol>None</symbol>
+is returned,
+there is no owner for the selection.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetSelectionOwner</function>
+can generate a
+<errorname>BadAtom</errorname>
+error.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To request conversion of a selection, use 
+<function>XConvertSelection</function>.
+<indexterm><primary>Selection</primary><secondary>converting</secondary></indexterm>
+<indexterm significance="preferred"><primary>XConvertSelection</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+  <funcdef><function>XConvertSelection</function></funcdef>
+  <paramdef>Display<parameter> *display</parameter></paramdef>
+  <paramdef>Atomselection,<parameter> target</parameter></paramdef>
+  <paramdef>Atom<parameter> property</parameter></paramdef>
+  <paramdef>Window<parameter> requestor</parameter></paramdef>
+  <paramdef>Time<parameter> time</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>display</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the connection to the X server.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>selection</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the selection atom.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>target</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the target atom.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>property</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the property name.
+You also can pass 
+<symbol>None</symbol>.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>requestor</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the requestor.
+      </para>
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>
+      <emphasis remap='I'>time</emphasis>
+    </term>
+    <listitem>
+      <para>
+Specifies the time.
+You can pass either a timestamp or
+<symbol>CurrentTime</symbol>.
+    </para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<function>XConvertSelection</function>
+requests that the specified selection be converted to the specified target
+type:
+</para>
+<itemizedlist>
+  <listitem>
+    <para>
+If the specified selection has an owner, the X server sends a
+<symbol>SelectionRequest</symbol>
+event to that owner.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+If no owner for the specified
+selection exists, the X server generates a
+<symbol>SelectionNotify</symbol>
+event to the
+requestor with property
+<symbol>None</symbol>.
+    </para>
+  </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+The arguments are passed on unchanged in either of the events.
+There are two predefined selection atoms: PRIMARY and SECONDARY.
+</para>
+<para>
+<!-- .LP -->
+<function>XConvertSelection</function>
+can generate
+<errorname>BadAtom</errorname>
+and
+<errorname>BadWindow</errorname>
+errors.
+<!-- .bp -->
+
+
+</para>
+</sect1>
+</chapter>