aboutsummaryrefslogtreecommitdiff
path: root/libX11/specs
diff options
context:
space:
mode:
Diffstat (limited to 'libX11/specs')
-rw-r--r--libX11/specs/libX11/CH04.xml5020
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>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-01 12:40:48 +0000