aboutsummaryrefslogtreecommitdiff
path: root/libX11/specs/libX11/CH14.xml
diff options
context:
space:
mode:
Diffstat (limited to 'libX11/specs/libX11/CH14.xml')
-rw-r--r--libX11/specs/libX11/CH14.xml5190
1 files changed, 5190 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH14.xml b/libX11/specs/libX11/CH14.xml
new file mode 100644
index 000000000..dd301bf9f
--- /dev/null
+++ b/libX11/specs/libX11/CH14.xml
@@ -0,0 +1,5190 @@
+<chapter id="inter_client_communication_functions">
+<title>Inter-Client Communication Functions</title>
+<para>
+The Inter-Client Communication Conventions Manual, hereafter referred to as the <acronym>ICCCM</acronym>,
+details the X Consortium approved conventions that govern inter-client communications. These
+conventions ensure peer-to-peer client cooperation in the use of selections, cut buffers, and shared
+resources as well as client cooperation with window and session managers. For further informa-
+tion, see the Inter-Client Communication Conventions Manual.
+</para>
+<para>
+Xlib provides a number of standard properties and programming interfaces that are <acronym>ICCCM</acronym> com-
+pliant. The predefined atoms for some of these properties are defined in the &lt;X11/Xatom.h&gt;
+header file, where to avoid name conflicts with user symbols their #define name has an XA_ pre-
+fix. For further information about atoms and properties, see section 4.3.
+</para>
+<para>
+Xlib’s selection and cut buffer mechanisms provide the primary programming interfaces by which
+peer client applications communicate with each other (see sections 4.5 and 16.6). The functions
+discussed in this chapter provide the primary programming interfaces by which client applications
+communicate with their window and session managers as well as share standard colormaps.
+</para>
+<para>
+The standard properties that are of special interest for communicating with window and session
+managers are:
+</para>
+
+<informaltable>
+ <tgroup cols='4' align='center'>
+ <colspec colname='c1'/>
+ <colspec colname='c2'/>
+ <colspec colname='c3'/>
+ <colspec colname='c4'/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Format</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>WM_CLASS</entry>
+ <entry>STRING</entry>
+ <entry>8</entry>
+ <entry>Set by application programs to allow
+ window and session managers to
+ obtain the application’s resources
+ from the resource database.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_CLIENT_MACHINE</entry>
+ <entry>TEXT</entry>
+ <entry></entry>
+ <entry>The string name of the machine on
+ which the client application is run-
+ ning.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_COLORMAP_WINDOWS</entry>
+ <entry>WINDOWS</entry>
+ <entry>32</entry>
+ <entry>The list of window IDs that may
+ need a different colormap from that
+ of their top-level window.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_COMMAND</entry>
+ <entry>TEXT</entry>
+ <entry></entry>
+ <entry>The command and arguments, null-
+ separated, used to invoke the application.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_HINTS</entry>
+ <entry>WM_HINTS</entry>
+ <entry>32</entry>
+ <entry>Additional hints set by the client for
+ use by the window manager. The C
+ type of this property is XWMHints.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_ICON_NAME</entry>
+ <entry>TEXT</entry>
+ <entry></entry>
+ <entry>The name to be used in an icon.</entry>
+ </row>
+ <row>
+ <entry>WM_ICON_SIZE</entry>
+ <entry>WM_ICON_SIZE</entry>
+ <entry>32</entry>
+ <entry>The window manager may set this
+ property on the root window to
+ specify the icon sizes it supports.
+ The C type of this property is
+ XIconSize.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_NAME</entry>
+ <entry>TEXT</entry>
+ <entry></entry>
+ <entry>The name of the application.</entry>
+ </row>
+ <row>
+ <entry>WM_NORMAL_HINTS</entry>
+ <entry>WM_NORMAL_HINTS</entry>
+ <entry>32</entry>
+ <entry>Size hints for a window in its
+ normal state. The C type of this
+ property is XSizeHints.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_PROTOCOLS</entry>
+ <entry>ATOM</entry>
+ <entry>32</entry>
+ <entry>List of atoms that identify the
+ communications protocols between the
+ client and window manager in
+ which the client is willing to participate.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_STATE</entry>
+ <entry>WM_STATE</entry>
+ <entry>32</entry>
+ <entry>Intended for communication
+ between window and session man-
+ agers only.
+ </entry>
+ </row>
+ <row>
+ <entry>WM_TRANSIENT_FOR</entry>
+ <entry>WINDOW</entry>
+ <entry>32</entry>
+ <entry>Set by application programs to
+ indicate to the window manager that a
+ transient top-level window, such as a
+ dialog box.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+</informaltable>
+
+<para>
+The remainder of this chapter discusses:
+</para>
+
+<itemizedlist>
+ <listitem><para>Client to window manager communication</para></listitem>
+ <listitem><para>Client to session manager communication</para></listitem>
+ <listitem><para>Standard colormaps</para></listitem>
+</itemizedlist>
+
+<sect1 id="Client_to_Window_Manager_Communication">
+<title>Client to Window Manager Communication</title>
+<!-- .XS -->
+<!-- (SN Client to Window Manager Communication -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Manipulate top-level windows
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Convert string lists
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read text properties
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_NAME property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_ICON_NAME property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_HINTS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_NORMAL_HINTS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_CLASS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_TRANSIENT_FOR property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_PROTOCOLS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_COLORMAP_WINDOWS property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_ICON_SIZE property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use window manager convenience functions
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Manipulating_Top_Level_Windows">
+<title>Manipulating Top-Level Windows</title>
+<!-- .XS -->
+<!-- (SN Manipulating Top-Level Windows -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to change the visibility or size
+of top-level windows (that is, those that were created as children
+of the root window).
+Note that the subwindows that you create are ignored by window managers.
+Therefore,
+you should use the basic window functions described in chapter 3
+to manipulate your application's subwindows.
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be iconified, use
+<function>XIconifyWindow</function>.
+<indexterm significance="preferred"><primary>XIconifyWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XIconifyWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</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'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XIconifyWindow </function>
+function sends a WM_CHANGE_STATE
+<function>ClientMessage </function>
+event with a format of 32 and a first data element of
+<function>IconicState </function>
+(as described in section 4.1.4 of the
+<emphasis remap='I'>Inter-Client Communication Conventions Manual</emphasis>)
+and a window of w
+to the root window of the specified screen
+with an event mask set to
+<function>SubstructureNotifyMask |</function>
+<function>SubstructureRedirectMask</function>.
+Window managers may elect to receive this message and
+if the window is in its normal state,
+may treat it as a request to change the window's state from normal to iconic.
+If the WM_CHANGE_STATE property cannot be interned,
+<function>XIconifyWindow</function>
+does not send a message and returns a zero status.
+It returns a nonzero status if the client message is sent successfully;
+otherwise, it returns a zero status.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be withdrawn, use
+<function>XWithdrawWindow</function>.
+<indexterm significance="preferred"><primary>XWithdrawWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XWithdrawWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</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'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XWithdrawWindow </function>
+function unmaps the specified window
+and sends a synthetic
+<function>UnmapNotify </function>
+event to the root window of the specified screen.
+Window managers may elect to receive this message
+and may treat it as a request to change the window's state to withdrawn.
+When a window is in the withdrawn state,
+neither its normal nor its iconic representations is visible.
+It returns a nonzero status if the
+<function>UnmapNotify </function>
+event is successfully sent;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XWithdrawWindow</function>
+can generate a
+<function>BadWindow</function>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To request that a top-level window be reconfigured, use
+<function>XReconfigureWMWindow</function>.
+<indexterm significance="preferred"><primary>XReconfigureWMWindow</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XReconfigureWMWindow</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>int<parameter> screen_number</parameter></paramdef>
+ <paramdef>unsignedint<parameter> value_mask</parameter></paramdef>
+ <paramdef>XWindowChanges<parameter> *values</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'>screen_number</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the appropriate screen number on the host server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_mask</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies which values are to be set using information in
+the values structure.
+This mask is the bitwise inclusive OR of the valid configure window values bits.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>values</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWindowChanges </function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XReconfigureWMWindow </function>
+function issues a
+<function>ConfigureWindow </function>
+request on the specified top-level window.
+If the stacking mode is changed and the request fails with a
+<function>BadMatch </function>
+error,
+the error is trapped by Xlib and a synthetic
+<function>ConfigureRequestEvent </function>
+containing the same configuration parameters is sent to the root
+of the specified window.
+Window managers may elect to receive this event
+and treat it as a request to reconfigure the indicated window.
+It returns a nonzero status if the request or event is successfully sent;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XReconfigureWMWindow </function>
+can generate
+<function>BadValue </function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Converting_String_Lists">
+<title>Converting String Lists</title>
+<!-- .XS -->
+<!-- (SN Converting String Lists -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Many of the text properties allow a variety of types and formats.
+Because the data stored in these properties are not
+simple null-terminated strings, an
+<function>XTextProperty</function>
+structure is used to describe the encoding, type, and length of the text
+as well as its value.
+The
+<function>XTextProperty</function>
+structure contains:
+<indexterm significance="preferred"><primary>XTextProperty</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ unsigned char *value; /* property data */
+ Atom encoding; /* type of property */
+ int format; /* 8, 16, or 32 */
+ unsigned long nitems; /* number of items in value */
+} XTextProperty;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Xlib provides functions to convert localized text to or from encodings
+that support the inter-client communication conventions for text.
+In addition, functions are provided for converting between lists of pointers
+to character strings and text properties in the STRING encoding.
+</para>
+<para>
+<!-- .LP -->
+The functions for localized text return a signed integer error status
+that encodes
+<function>Success</function>
+as zero, specific error conditions as negative numbers, and partial conversion
+as a count of unconvertible characters.
+</para>
+
+<literallayout class="monospaced">
+
+#define #XNoMemory -1
+#define #XLocaleNotSupported -2
+#define #XConverterNotFound -3
+
+typedef enum {
+ XStringStyle, /* STRING */
+ XCompoundTextStyle, /* COMPOUND_TEXT */
+ XTextStyle, /* text in owner's encoding (current locale) */
+ XStdICCTextStyle /* STRING, else COMPOUND_TEXT */
+} XICCEncodingStyle;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To convert a list of text strings to an
+<function>XTextProperty</function>
+structure, use
+<function>XmbTextListToTextProperty</function>
+or
+<function>XwcTextListToTextProperty</function>.
+<indexterm significance="preferred"><primary>XmbTextListToTextProperty</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextListToTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XmbTextListToTextProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>char<parameter> **list</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XwcTextListToTextProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>wchar_t<parameter> **list</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>XICCEncodingStyle<parameter> style</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of null-terminated character strings.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of strings specified.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>style</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the manner in which the property is encoded.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextListToTextProperty</function>
+and
+<function>XwcTextListToTextProperty</function>
+functions set the specified
+<function>XTextProperty</function>
+value to a set of null-separated elements representing the concatenation
+of the specified list of null-terminated text strings.
+A final terminating null is stored at the end of the value field
+of text_prop_return but is not included in the nitems member.
+</para>
+<para>
+<!-- .LP -->
+The functions set the encoding field of text_prop_return to an
+<function>Atom </function>
+for the specified display
+naming the encoding determined by the specified style
+and convert the specified text list to this encoding for storage in
+the text_prop_return value field.
+If the style
+<function>XStringStyle</function>
+or
+<function>XCompoundTextStyle</function>
+is specified,
+this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
+If the style
+<function>XTextStyle</function>
+is specified,
+this encoding is the encoding of the current locale.
+If the style
+<function>XStdICCTextStyle</function>
+is specified,
+this encoding is ``STRING'' if the text is fully convertible to STRING,
+else ``COMPOUND_TEXT''.
+</para>
+<para>
+<!-- .LP -->
+If insufficient memory is available for the new value string,
+the functions return
+<function>XNoMemory</function>.
+If the current locale is not supported,
+the functions return
+<function>XLocaleNotSupported</function>.
+In both of these error cases,
+the functions do not set text_prop_return.
+</para>
+<para>
+<!-- .LP -->
+To determine if the functions are guaranteed not to return
+<function>XLocaleNotSupported</function>,
+use
+<function>XSupportsLocale</function>.
+</para>
+<para>
+<!-- .LP -->
+If the supplied text is not fully convertible to the specified encoding,
+the functions return the number of unconvertible characters.
+Each unconvertible character is converted to an implementation-defined and
+encoding-specific default string.
+Otherwise, the functions return
+<function>Success</function>.
+Note that full convertibility to all styles except
+<function>XStringStyle</function>
+is guaranteed.
+</para>
+<para>
+<!-- .LP -->
+To free the storage for the value field, use
+<function>XFree</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a list of text strings from an
+<function>XTextProperty </function>
+structure, use
+<function>XmbTextPropertyToTextList</function>
+or
+<function>XwcTextPropertyToTextList</function>.
+<indexterm significance="preferred"><primary>XmbTextPropertyToTextList</primary></indexterm>
+<indexterm significance="preferred"><primary>XwcTextPropertyToTextList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XmbTextPropertyToTextList</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+ <paramdef>char<parameter> ***list_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>int<function> XwcTextPropertyToTextList</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+ <paramdef>wchar_t<parameter> ***list_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_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'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+functions return a list of text strings in the current locale representing the
+null-separated elements of the specified
+<function>XTextProperty</function>
+structure.
+The data in text_prop must be format 8.
+</para>
+<para>
+<!-- .LP -->
+Multiple elements of the property (for example, the strings in a disjoint
+text selection) are separated by a null byte.
+The contents of the property are not required to be null-terminated;
+any terminating null should not be included in text_prop.nitems.
+</para>
+<para>
+<!-- .LP -->
+If insufficient memory is available for the list and its elements,
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return
+<function>XNoMemory</function>.
+If the current locale is not supported,
+the functions return
+<function>XLocaleNotSupported</function>.
+Otherwise, if the encoding field of text_prop is not convertible
+to the encoding of the current locale,
+the functions return
+<function>XConverterNotFound</function>.
+For supported locales,
+existence of a converter from COMPOUND_TEXT, STRING
+or the encoding of the current locale is guaranteed if
+<function>XSupportsLocale </function>
+returns
+<function>True</function>
+for the current locale (but the actual text
+may contain unconvertible characters).
+Conversion of other encodings is implementation-dependent.
+In all of these error cases,
+the functions do not set any return values.
+</para>
+<para>
+<!-- .LP -->
+Otherwise,
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return the list of null-terminated text strings to list_return
+and the number of text strings to count_return.
+</para>
+<para>
+<!-- .LP -->
+If the value field of text_prop is not fully convertible to the encoding of
+the current locale,
+the functions return the number of unconvertible characters.
+Each unconvertible character is converted to a string in the
+current locale that is specific to the current locale.
+To obtain the value of this string,
+use
+<function>XDefaultString</function>.
+Otherwise,
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XwcTextPropertyToTextList</function>
+return
+<function>Success</function>.
+</para>
+<para>
+<!-- .LP -->
+To free the storage for the list and its contents returned by
+<function>XmbTextPropertyToTextList</function>,
+use
+<function>XFreeStringList</function>.
+To free the storage for the list and its contents returned by
+<function>XwcTextPropertyToTextList</function>,
+use
+<function>XwcFreeStringList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To free the in-memory data associated with the specified
+wide character string list, use
+<function>XwcFreeStringList</function>.
+<indexterm significance="preferred"><primary>XwcFreeStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XwcFreeStringList</function></funcdef>
+ <paramdef>wchar_t<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of strings to be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XwcFreeStringList</function>
+function frees memory allocated by
+<function>XwcTextPropertyToTextList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the default string for text conversion in the current locale,
+use</para>
+
+<para>char *XDefaultString()</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XDefaultString</function>
+function returns the default string used by Xlib for text conversion
+(for example, in
+<function>XmbTextPropertyToTextList</function>).
+The default string is the string in the current locale that is output
+when an unconvertible character is found during text conversion.
+If the string returned by
+<function>XDefaultString</function>
+is the empty string (""),
+no character is output in the converted text.
+<function>XDefaultString</function>
+does not return NULL.
+</para>
+<para>
+<!-- .LP -->
+The string returned by
+<function>XDefaultString</function>
+is independent of the default string for text drawing;
+see
+<function>XCreateFontSet</function>
+to obtain the default string for an
+<function>XFontSet</function>.
+</para>
+<para>
+<!-- .LP -->
+The behavior when an invalid codepoint is supplied to any Xlib function is
+undefined.
+</para>
+<para>
+<!-- .LP -->
+The returned string is null-terminated.
+It is owned by Xlib and should not be modified or freed by the client.
+It may be freed after the current locale is changed.
+Until freed, it will not be modified by Xlib.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set the specified list of strings in the STRING encoding to a
+<function>XTextProperty</function>
+structure, use
+<function>XStringListToTextProperty</function>.
+<indexterm significance="preferred"><primary>XStringListToTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XStringListToTextProperty</function></funcdef>
+ <paramdef>char<parameter> **list</parameter></paramdef>
+ <paramdef>int<parameter> count</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+ </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'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStringListToTextProperty </function>
+function sets the specified
+<function>XTextProperty</function>
+to be of type STRING (format 8) with a value representing the
+concatenation of the specified list of null-separated character strings.
+An extra null byte (which is not included in the nitems member)
+is stored at the end of the value field of text_prop_return.
+The strings are assumed (without verification) to be in the STRING encoding.
+If insufficient memory is available for the new value string,
+<function>XStringListToTextProperty</function>
+does not set any fields in the
+<function>XTextProperty</function>
+structure and returns a zero status.
+Otherwise, it returns a nonzero status.
+To free the storage for the value field, use
+<function>XFree</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain a list of strings from a specified
+<function>XTextProperty</function>
+structure in the STRING encoding, use
+<function>XTextPropertyToStringList</function>.
+<indexterm significance="preferred"><primary>XTextPropertyToStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XTextPropertyToStringList</function></funcdef>
+ <paramdef>XTextProperty<parameter> *text_prop</parameter></paramdef>
+ <paramdef>char<parameter> ***list_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a list of null-terminated character strings.
+<!-- .ds Cn strings -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XTextPropertyToStringList </function>
+function returns a list of strings representing the null-separated elements
+of the specified
+<function>XTextProperty</function>
+structure.
+The data in text_prop must be of type STRING and format 8.
+Multiple elements of the property
+(for example, the strings in a disjoint text selection)
+are separated by NULL (encoding 0).
+The contents of the property are not null-terminated.
+If insufficient memory is available for the list and its elements,
+<function>XTextPropertyToStringList</function>
+sets no return values and returns a zero status.
+Otherwise, it returns a nonzero status.
+To free the storage for the list and its contents, use
+<function>XFreeStringList</function>.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To free the in-memory data associated with the specified string list, use
+<function>XFreeStringList</function>.
+<indexterm significance="preferred"><primary>XFreeStringList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XFreeStringList</function></funcdef>
+ <paramdef>char<parameter> **list</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of strings to be freed.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFreeStringList </function>
+function releases memory allocated by
+<function>XmbTextPropertyToTextList</function>
+and
+<function>XTextPropertyToStringList</function>
+and the missing charset list allocated by
+<function>XCreateFontSet</function>.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_Text_Properties">
+<title>Setting and Reading Text Properties</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading Text Properties -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides two functions that you can use to set and read
+the text properties for a given window.
+You can use these functions to set and read those properties of type TEXT
+(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE).
+In addition,
+Xlib provides separate convenience functions that you can use to set each
+of these properties.
+For further information about these convenience functions,
+see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set one of a window's text properties, use
+<function>XSetTextProperty</function>.
+<indexterm significance="preferred"><primary>XSetTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetTextProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </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>XSetTextProperty</function>
+function replaces the existing specified property for the named window
+with the data, type, format, and number of items determined
+by the value field, the encoding field, the format field,
+and the nitems field, respectively, of the specified
+<function>XTextProperty</function>
+structure.
+If the property does not already exist,
+<function>XSetTextProperty</function>
+sets it for the specified window.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTextProperty</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+<function>BadValue</function>,
+and
+<function>BadWindow </function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read one of a window's text properties, use
+<function>XGetTextProperty</function>.
+<indexterm significance="preferred"><primary>XGetTextProperty</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetTextProperty</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop_return</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </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>XGetTextProperty </function>
+function reads the specified property from the window
+and stores the data in the returned
+<function>XTextProperty</function>
+structure.
+It stores the data in the value field,
+the type of the data in the encoding field,
+the format of the data in the format field,
+and the number of items of data in the nitems field.
+An extra byte containing null (which is not included in the nitems member)
+is stored at the end of the value field of text_prop_return.
+The particular interpretation of the property's encoding
+and data as text is left to the calling application.
+If the specified property does not exist on the window,
+<function>XGetTextProperty</function>
+sets the value field to NULL,
+the encoding field to
+<function>None</function>,
+the format field to zero,
+and the nitems field to zero.
+</para>
+<para>
+<!-- .LP -->
+If it was able to read and store the data in the
+<function>XTextProperty</function>
+structure,
+<function>XGetTextProperty</function>
+returns a nonzero status;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetTextProperty</function>
+can generate
+<function>BadAtom </function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_NAME_Property">
+<title>Setting and Reading the WM_NAME Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_NAME Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides convenience functions that you can use to set and read
+the WM_NAME property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_NAME property with the supplied convenience function, use
+<function>XSetWMName</function>.
+<indexterm significance="preferred"><primary>XSetWMName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</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'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMName</function>
+convenience function calls
+<function>XSetTextProperty </function>
+to set the WM_NAME property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_NAME property with the supplied convenience function, use
+<function>XGetWMName</function>.
+<indexterm significance="preferred"><primary>XGetWMName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMName </function>
+convenience function calls
+<function>XGetTextProperty </function>
+to obtain the WM_NAME property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+The following two functions have been superseded by
+<function>XSetWMName</function>
+and
+<function>XGetWMName</function>,
+respectively.
+You can use these additional convenience functions
+for window names that are encoded as STRING properties.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To assign a name to a window, use
+<function>XStoreName</function>.
+<indexterm><primary>Window</primary><secondary>name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XStoreName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XStoreName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> *window_name</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'>window_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XStoreName</function>
+function assigns the name passed to window_name to the specified window.
+A window manager can display the window name in some prominent
+place, such as the title bar, to allow users to identify windows easily.
+Some window managers may display a window's name in the window's icon,
+although they are encouraged to use the window's icon name
+if one is provided by the application.
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XStoreName</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the name of a window, use
+<function>XFetchName</function>.
+<indexterm significance="preferred"><primary>XFetchName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XFetchName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> **window_name_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>window_name_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the window name, which is a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XFetchName</function>
+function returns the name of the specified window.
+If it succeeds,
+it returns a nonzero status;
+otherwise, no name has been set for the window,
+and it returns zero.
+If the WM_NAME property has not been set for this window,
+<function>XFetchName</function>
+sets window_name_return to NULL.
+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.
+When finished with it, a client must free
+the window name string using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XFetchName</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_ICON_NAME_Property">
+<title>Setting and Reading the WM_ICON_NAME Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_ICON_NAME Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides convenience functions that you can use to set and read
+the WM_ICON_NAME property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_ICON_NAME property,
+use
+<function>XSetWMIconName</function>.
+<indexterm significance="preferred"><primary>XSetWMIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMIconName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</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'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMIconName</function>
+convenience function calls
+<function>XSetTextProperty</function>
+to set the WM_ICON_NAME property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_ICON_NAME property,
+use
+<function>XGetWMIconName</function>.
+<indexterm significance="preferred"><primary>XGetWMIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMIconName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMIconName </function>
+convenience function calls
+<function>XGetTextProperty </function>
+to obtain the WM_ICON_NAME property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+The next two functions have been superseded by
+<function>XSetWMIconName</function>
+and
+<function>XGetWMIconName</function>,
+respectively.
+You can use these additional convenience functions
+for window names that are encoded as STRING properties.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set the name to be displayed in a window's icon, use
+<function>XSetIconName</function>.
+<indexterm><primary>Window</primary><secondary>icon name</secondary></indexterm>
+<indexterm significance="preferred"><primary>XSetIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetIconName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> *icon_name</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'>icon_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the icon name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If the string is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+<function>XSetIconName</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the name a window wants displayed in its icon, use
+<function>XGetIconName</function>.
+<indexterm significance="preferred"><primary>XGetIconName</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetIconName</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> **icon_name_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_name_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the window's icon name,
+which is a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetIconName</function>
+function returns the name to be displayed in the specified window's icon.
+If it succeeds, it returns a nonzero status; otherwise,
+if no icon name has been set for the window,
+it returns zero.
+If you never assigned a name to the window,
+<function>XGetIconName</function>
+sets icon_name_return to NULL.
+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.
+When finished with it, a client must free
+the icon name string using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetIconName</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_HINTS_Property">
+<title>Setting and Reading the WM_HINTS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_HINTS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_HINTS property for a given window.
+These functions use the flags and the
+<function>XWMHints </function>
+structure, as defined in the
+<!-- .hN X11/Xutil.h -->
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XWMHints</function>
+structure, use
+<function>XAllocWMHints</function>.
+</para>
+
+<para>
+ XWMHints *XAllocWMHints()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocWMHints</function>
+function allocates and returns a pointer to an
+<function>XWMHints</function>
+structure.
+Note that all fields in the
+<function>XWMHints</function>
+structure are initially set to zero.
+If insufficient memory is available,
+<function>XAllocWMHints</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XWMHints</function>
+structure contains:
+</para>
+
+<literallayout class="monospaced">
+/* Window manager hints mask bits */
+
+#define InputHint (1L&lt;&lt;0)
+#define StateHint (1L&lt;&lt;1)
+#define IconPixmapHint (1L&lt;&lt;2)
+#define IconWindowHint (1L&lt;&lt;3)
+#define IconPositionHint (1L&lt;&lt;4)
+#define IconMaskHint (1L&lt;&lt;5)
+#define WindowGroupHint (1L&lt;&lt;6)
+#define UrgencyHint (1L&lt;&lt;8)
+#define AllHints (InputHint|StateHint|IconPixmapHint|
+ IconWIndowHint|IconPositionHint|
+ IconMaskHint|WindowGroupHint)
+
+
+/* Values */
+
+typedef struct {
+ long flags; /* marks which fields in this structure are defined */
+ Bool input; /* does this application rely on the window manager to
+ get keyboard input? */
+ int initial_state; /* see below */
+ Pixmap icon_pixmap; /* pixmap to be used as icon */
+ Window icon_window; /* window to be used as icon */
+ int icon_x, icon_y; /* initial position of icon */
+ Pixmap icon_mask; /* pixmap to be used as mask for icon_pixmap */
+ XID window_group; /* id of related window group */
+ /* this structure may be extended in the future */
+} XWMHints;
+</literallayout>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The input member is used to communicate to the window manager the input focus
+model used by the application.
+Applications that expect input but never explicitly set focus to any
+of their subwindows (that is, use the push model of focus management),
+such as X Version 10 style applications that use real-estate
+driven focus, should set this member to
+<function>True</function>.
+Similarly, applications
+that set input focus to their subwindows only when it is given to their
+top-level window by a window manager should also set this member to
+<function>True</function>.
+Applications that manage their own input focus by explicitly setting
+focus to one of their subwindows whenever they want keyboard input
+(that is, use the pull model of focus management) should set this member to
+<function>False</function>.
+Applications that never expect any keyboard input also should set this member
+to
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+Pull model window managers should make it possible for push model
+applications to get input by setting input focus to the top-level windows of
+applications whose input member is
+<function>True</function>.
+Push model window managers should
+make sure that pull model applications do not break them
+by resetting input focus to
+<function>PointerRoot </function>
+when it is appropriate (for example, whenever an application whose
+input member is
+<function>False </function>
+sets input focus to one of its subwindows).
+</para>
+<para>
+<!-- .LP -->
+The definitions for the initial_state flag are:
+</para>
+
+<literallayout class="monospaced">
+#define WithdrawnState 0
+#define NormalState 1 /* most applications start this way */
+#define IconicState 2 /* application wants to start as an icon */
+
+</literallayout>
+<para>
+The icon_mask specifies which pixels of the icon_pixmap should be used as the
+icon.
+This allows for nonrectangular icons.
+Both icon_pixmap and icon_mask must be bitmaps.
+The icon_window lets an application provide a window for use as an icon
+for window managers that support such use.
+The window_group lets you specify that this window belongs to a group
+of other windows.
+For example, if a single application manipulates multiple
+top-level windows, this allows you to provide enough
+information that a window manager can iconify all of the windows
+rather than just the one window.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>UrgencyHint</function>
+flag, if set in the flags field, indicates that the client deems the window
+contents to be urgent, requiring the timely response of the user. The
+window manager will make some effort to draw the user's attention to this
+window while this flag is set. The client must provide some means by which the
+user can cause the urgency flag to be cleared (either mitigating
+the condition that made the window urgent or merely shutting off the alarm)
+or the window to be withdrawn.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_HINTS property, use
+<function>XSetWMHints</function>.
+<indexterm significance="preferred"><primary>XSetWMHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetWMHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XWMHints<parameter> *wmhints</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'>wmhints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWMHints</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMHints</function>
+function sets the window manager hints that include icon information and location,
+the initial state of the window, and whether the application relies on the
+window manager to get keyboard input.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMHints</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's WM_HINTS property, use
+<function>XGetWMHints</function>.
+<indexterm significance="preferred"><primary>XGetWMHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>XWMHints<function> *XGetWMHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</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>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMHints</function>
+function reads the window manager hints and
+returns NULL if no WM_HINTS property was set on the window
+or returns a pointer to an
+<function>XWMHints </function>
+structure if it succeeds.
+When finished with the data,
+free the space used for it by calling
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMHints</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_NORMAL_HINTS_Property">
+<title>Setting and Reading the WM_NORMAL_HINTS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_NORMAL_HINTS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set or read
+the WM_NORMAL_HINTS property for a given window.
+The functions use the flags and the
+<function>XSizeHints </function>
+structure, as defined in the
+<!-- .hN X11/Xutil.h -->
+header file.
+</para>
+<para>
+<!-- .LP -->
+The size of the
+<function>XSizeHints</function>
+structure may grow in future releases, as new components are
+added to support new <acronym>ICCCM</acronym> features.
+Passing statically allocated instances of this structure into
+Xlib may result in memory corruption when running against a
+future release of the library.
+As such, it is recommended that only dynamically allocated
+instances of the structure be used.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XSizeHints</function>
+structure, use
+<function>XAllocSizeHints</function>.
+</para>
+
+<para>
+XSizeHints *XAllocSizeHints()
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocSizeHints</function>
+function allocates and returns a pointer to an
+<function>XSizeHints</function>
+structure.
+Note that all fields in the
+<function>XSizeHints</function>
+structure are initially set to zero.
+If insufficient memory is available,
+<function>XAllocSizeHints</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XSizeHints</function>
+structure contains:
+</para>
+
+
+<literallayout class="monospaced">
+/* Size hints mask bits */
+
+#define USPosition (1L&lt;&lt;0) /* user specified x,y */
+#define USSize (1L&lt;&lt;1) /* user specified width,height */
+#define PPosition (1L&lt;&lt;2) /* program specified posistion */
+#define PSize (1L&lt;&lt;3) /* program specified size */
+#define PMinSize (1L&lt;&lt;4) /* program specified minimum size */
+#define PMaxSize (1L&lt;&lt;5) /* program specified maximum size */
+#define PResizeInc (1L&lt;&lt;5) /* program specified resize increments */
+#define PAspect (1L&lt;&lt;6) /* program specified min and max aspect ratios */
+#define PBaseSize (1L&lt;&lt;8)
+#define PWinGravity (1L&lt;&lt;9)
+#define PAllHints (PPosition|Psize|
+ PMinSize|PMaxSize|
+ PResizeInc|PAspect)
+
+
+/* Values */
+
+typedef struct {
+ long flags; /* marks which fields in this structure are defined */
+ int x, y; /* Obsolete */
+ int width, height; /* Obsolete */
+ int min_width, min_height;
+ int max_width, max_height;
+ int width_inc, height_inc;
+ struct {
+ int x; /* numerator */
+ int y; /* denominator */
+ } min_aspect, max_aspect;
+ int base_width, base_height;
+ int win_gravity;
+ /* this structure may be extended in the future */
+} XSizeHints;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The x, y, width, and height members are now obsolete
+and are left solely for compatibility reasons.
+The min_width and min_height members specify the
+minimum window size that still allows the application to be useful.
+The max_width and max_height members specify the maximum window size.
+The width_inc and height_inc members define an arithmetic progression of
+sizes (minimum to maximum) into which the window prefers to be resized.
+The min_aspect and max_aspect members are expressed
+as ratios of x and y,
+and they allow an application to specify the range of aspect
+ratios it prefers.
+The base_width and base_height members define the desired size of the window.
+The window manager will interpret the position of the window
+and its border width to position the point of the outer rectangle
+of the overall window specified by the win_gravity member.
+The outer rectangle of the window includes any borders or decorations
+supplied by the window manager.
+In other words,
+if the window manager decides to place the window where the client asked,
+the position on the parent window's border named by the win_gravity
+will be placed where the client window would have been placed
+in the absence of a window manager.
+</para>
+<para>
+<!-- .LP -->
+Note that use of the
+<function>PAllHints</function>
+macro is highly discouraged.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_NORMAL_HINTS property, use
+<function>XSetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XSetWMNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMNormalHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints</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'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMNormalHints </function>
+function replaces the size hints for the WM_NORMAL_HINTS property
+on the specified window.
+If the property does not already exist,
+<function>XSetWMNormalHints</function>
+sets the size hints for the WM_NORMAL_HINTS property on the specified window.
+The property is stored with a type of WM_SIZE_HINTS and a format of 32.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMNormalHints</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_NORMAL_HINTS property, use
+<function>XGetWMNormalHints</function>.
+<indexterm significance="preferred"><primary>XGetWMNormalHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMNormalHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+ <paramdef>long<parameter> *supplied_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>supplied_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the hints that were supplied by the user.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMNormalHints </function>
+function returns the size hints stored in the WM_NORMAL_HINTS property
+on the specified window.
+If the property is of type WM_SIZE_HINTS, is of format 32,
+and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>)
+or new size hints structure,
+<function>XGetWMNormalHints</function>
+sets the various fields of the
+<function>XSizeHints</function>
+structure, sets the supplied_return argument to the list of fields
+that were supplied by the user (whether or not they contained defined values),
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XGetWMNormalHints</function>
+returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read,
+the supplied_return argument will contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(USPosition|USSize|PPosition|PSize|PMinSize|
+ PMaxSize|PResizeInc|PAspect)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If the property is large enough to contain the base size
+and window gravity fields as well,
+the supplied_return argument will also contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+PBaseSize|PWinGravity
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMNormalHints</function>
+can generate a
+<function>BadWindow</function>
+error.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_SIZE_HINTS property, use
+<function>XSetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XSetWMSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMSizeHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XSizeHints</function>
+structure to be used.
+ </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>XSetWMSizeHints </function>
+function replaces the size hints for the specified property
+on the named window.
+If the specified property does not already exist,
+<function>XSetWMSizeHints</function>
+sets the size hints for the specified property
+on the named window.
+The property is stored with a type of WM_SIZE_HINTS and a format of 32.
+To set a window's normal size hints,
+you can use the
+<function>XSetWMNormalHints</function>
+function.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMSizeHints</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_SIZE_HINTS property, use
+<function>XGetWMSizeHints</function>.
+<indexterm significance="preferred"><primary>XGetWMSizeHints</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMSizeHints</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *hints_return</parameter></paramdef>
+ <paramdef>long<parameter> *supplied_return</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XSizeHints</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>supplied_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the hints that were supplied by the user.
+ </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>XGetWMSizeHints</function>
+function returns the size hints stored in the specified property
+on the named window.
+If the property is of type WM_SIZE_HINTS, is of format 32,
+and is long enough to contain either an old (pre-<acronym>ICCCM</acronym>)
+or new size hints structure,
+<function>XGetWMSizeHints</function>
+sets the various fields of the
+<function>XSizeHints</function>
+structure, sets the supplied_return argument to the
+list of fields that were supplied by the user
+(whether or not they contained defined values),
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+To get a window's normal size hints,
+you can use the
+<function>XGetWMNormalHints </function>
+function.
+</para>
+<para>
+<!-- .LP -->
+If
+<function>XGetWMSizeHints</function>
+returns successfully and a pre-<acronym>ICCCM</acronym> size hints property is read,
+the supplied_return argument will contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+(USPosition|USSize|PPosition|PSize|PMinSize|
+ PMaxSize|PResizeInc|PAspect)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+If the property is large enough to contain the base size
+and window gravity fields as well,
+the supplied_return argument will also contain the following bits:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+PBaseSize|PWinGravity
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMSizeHints</function>
+can generate
+<function>BadAtom </function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_CLASS_Property">
+<title>Setting and Reading the WM_CLASS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_CLASS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and get
+the WM_CLASS property for a given window.
+These functions use the
+<function>XClassHint </function>
+structure, which is defined in the
+<!-- .hN X11/Xutil.h -->
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XClassHint</function>
+structure, use
+<function>XAllocClassHint</function>.
+<indexterm significance="preferred"><primary>XAllocClassHint</primary></indexterm>
+<!-- .sM -->
+</para>
+<para>
+
+ XClassHint *XAllocClassHint()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocClassHint</function>
+function allocates and returns a pointer to an
+<function>XClassHint</function>
+structure.
+Note that the pointer fields in the
+<function>XClassHint</function>
+structure are initially set to NULL.
+If insufficient memory is available,
+<function>XAllocClassHint</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XClassHint</function>
+contains:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XClassHint</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i -->
+<!-- .ta .5i -->
+typedef struct {
+ char *res_name;
+ char *res_class;
+} XClassHint;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The res_name member contains the application name,
+and the res_class member contains the application class.
+Note that the name set in this property may differ from the name set as WM_NAME.
+That is, WM_NAME specifies what should be displayed in the title bar and,
+therefore, can contain temporal information (for example, the name of
+a file currently in an editor's buffer).
+On the other hand,
+the name specified as part of WM_CLASS is the formal name of the application
+that should be used when retrieving the application's resources from the
+resource database.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_CLASS property, use
+<function>XSetClassHint</function>.
+<indexterm significance="preferred"><primary>XSetClassHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetClassHint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XClassHint<parameter> *class_hints</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'>class_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XClassHint</function>
+structure that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetClassHint</function>
+function sets the class hint for the specified window.
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetClassHint</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's WM_CLASS property, use
+<function>XGetClassHint</function>.
+<indexterm significance="preferred"><primary>XGetClassHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetClassHint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XClassHint<parameter> *class_hints_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_hints_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XClassHint</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetClassHint</function>
+function returns the class hint of the specified window to the members
+of the supplied structure.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+To free res_name and res_class when finished with the strings,
+use
+<function>XFree</function>
+on each individually.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetClassHint</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_TRANSIENT_FOR_Property">
+<title>Setting and Reading the WM_TRANSIENT_FOR Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_TRANSIENT_FOR Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_TRANSIENT_FOR property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_TRANSIENT_FOR property, use
+<function>XSetTransientForHint</function>.
+<indexterm significance="preferred"><primary>XSetTransientForHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetTransientForHint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> prop_window</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'>prop_window</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window that the WM_TRANSIENT_FOR property is to be set to.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetTransientForHint</function>
+function sets the WM_TRANSIENT_FOR property of the specified window to the
+specified prop_window.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetTransientForHint</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's WM_TRANSIENT_FOR property, use
+<function>XGetTransientForHint</function>.
+<indexterm significance="preferred"><primary>XGetTransientForHint</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetTransientForHint</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> *prop_window_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>prop_window_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the WM_TRANSIENT_FOR property of the specified window.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetTransientForHint</function>
+function returns the WM_TRANSIENT_FOR property for the specified window.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetTransientForHint</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_PROTOCOLS_Property">
+<title>Setting and Reading the WM_PROTOCOLS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_PROTOCOLS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_PROTOCOLS property for a given window.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_PROTOCOLS property, use
+<function>XSetWMProtocols</function>.
+<indexterm significance="preferred"><primary>XSetWMProtocols</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XSetWMProtocols</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Atom<parameter> *protocols</parameter></paramdef>
+ <paramdef>int<parameter> count</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'>protocols</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of protocols.
+<!-- .ds Cn protocols in the list -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMProtocols </function>
+function replaces the WM_PROTOCOLS property on the specified window
+with the list of atoms specified by the protocols argument.
+If the property does not already exist,
+<function>XSetWMProtocols</function>
+sets the WM_PROTOCOLS property on the specified window
+to the list of atoms specified by the protocols argument.
+The property is stored with a type of ATOM and a format of 32.
+If it cannot intern the WM_PROTOCOLS atom,
+<function>XSetWMProtocols</function>
+returns a zero status.
+Otherwise, it returns a nonzero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMProtocols</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_PROTOCOLS property, use
+<function>XGetWMProtocols</function>.
+<indexterm significance="preferred"><primary>XGetWMProtocols</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMProtocols</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Atom<parameter> **protocols_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>protocols_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of protocols.
+<!-- .ds Cn protocols in the list -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMProtocols </function>
+function returns the list of atoms stored in the WM_PROTOCOLS property
+on the specified window.
+These atoms describe window manager protocols in which the owner
+of this window is willing to participate.
+If the property exists, is of type ATOM, is of format 32,
+and the atom WM_PROTOCOLS can be interned,
+<function>XGetWMProtocols</function>
+sets the protocols_return argument to a list of atoms,
+sets the count_return argument to the number of elements in the list,
+and returns a nonzero status.
+Otherwise, it sets neither of the return arguments
+and returns a zero status.
+To release the list of atoms, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMProtocols</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_COLORMAP_WINDOWS_Property">
+<title>Setting and Reading the WM_COLORMAP_WINDOWS Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_COLORMAP_WINDOWS Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_COLORMAP_WINDOWS property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_COLORMAP_WINDOWS property, use
+<function>XSetWMColormapWindows</function>.
+<indexterm significance="preferred"><primary>XSetWMColormapWindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XSetWMColormapWindows</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> *colormap_windows</parameter></paramdef>
+ <paramdef>int<parameter> count</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'>colormap_windows</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the list of windows.
+<!-- .ds Cn windows in the list -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMColormapWindows </function>
+function replaces the WM_COLORMAP_WINDOWS property on the specified
+window with the list of windows specified by the colormap_windows argument.
+If the property does not already exist,
+<function>XSetWMColormapWindows</function>
+sets the WM_COLORMAP_WINDOWS property on the specified
+window to the list of windows specified by the colormap_windows argument.
+The property is stored with a type of WINDOW and a format of 32.
+If it cannot intern the WM_COLORMAP_WINDOWS atom,
+<function>XSetWMColormapWindows</function>
+returns a zero status.
+Otherwise, it returns a nonzero status.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMColormapWindows</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_COLORMAP_WINDOWS property, use
+<function>XGetWMColormapWindows</function>.
+<indexterm significance="preferred"><primary>XGetWMColormapWindows</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMColormapWindows</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>Window<parameter> **colormap_windows_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>colormap_windows_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of windows.
+<!-- .ds Cn windows in the list -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMColormapWindows </function>
+function returns the list of window identifiers stored
+in the WM_COLORMAP_WINDOWS property on the specified window.
+These identifiers indicate the colormaps that the window manager
+may need to install for this window.
+If the property exists, is of type WINDOW, is of format 32,
+and the atom WM_COLORMAP_WINDOWS can be interned,
+<function>XGetWMColormapWindows</function>
+sets the windows_return argument to a list of window identifiers,
+sets the count_return argument to the number of elements in the list,
+and returns a nonzero status.
+Otherwise, it sets neither of the return arguments
+and returns a zero status.
+To release the list of window identifiers, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetWMColormapWindows</function>
+can generate a
+<function>BadWindow</function>
+error.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_ICON_SIZE_Property">
+<title>Setting and Reading the WM_ICON_SIZE Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_ICON_SIZE Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_ICON_SIZE property for a given window.
+These functions use the
+<function>XIconSize </function>
+<indexterm><primary>XIconSize</primary></indexterm>
+structure, which is defined in the
+<!-- .hN X11/Xutil.h -->
+header file.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XIconSize</function>
+structure, use
+<function>XAllocIconSize</function>.
+</para>
+
+<para>
+ XIconSize *XAllocIconSize()
+</para>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocIconSize </function>
+function allocates and returns a pointer to an
+<function>XIconSize </function>
+structure.
+Note that all fields in the
+<function>XIconSize</function>
+structure are initially set to zero.
+If insufficient memory is available,
+<function>XAllocIconSize</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XIconSize</function>
+structure contains:
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<indexterm significance="preferred"><primary>XIconSize</primary></indexterm>
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ int min_width, min_height;
+ int max_width, max_height;
+ int width_inc, height_inc;
+} XIconSize;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The width_inc and height_inc members define an arithmetic progression of
+sizes (minimum to maximum) that represent the supported icon sizes.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To set a window's WM_ICON_SIZE property, use
+<function>XSetIconSizes</function>.
+<indexterm significance="preferred"><primary>XSetIconSizes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetIconSizes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XIconSize<parameter> *size_list</parameter></paramdef>
+ <paramdef>int<parameter> count</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'>size_list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of items in the size list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetIconSizes</function>
+function is used only by window managers to set the supported icon sizes.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetIconSizes</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To read a window's WM_ICON_SIZE property, use
+<function>XGetIconSizes</function>.
+<indexterm significance="preferred"><primary>XGetIconSizes</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetIconSizes</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XIconSize<parameter> **size_list_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>size_list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the size list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of items in the size list.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetIconSizes</function>
+function returns zero if a window manager has not set icon sizes;
+otherwise, it returns nonzero.
+<function>XGetIconSizes</function>
+should be called by an application that
+wants to find out what icon sizes would be most appreciated by the
+window manager under which the application is running.
+The application
+should then use
+<function>XSetWMHints</function>
+to supply the window manager with an icon pixmap or window in one of the
+supported sizes.
+To free the data allocated in size_list_return, use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetIconSizes</function>
+can generate a
+<function>BadWindow </function>
+error.
+</para>
+</sect2>
+<sect2 id="Using_Window_Manager_Convenience_Functions">
+<title>Using Window Manager Convenience Functions</title>
+<!-- .XS -->
+<!-- (SN Using Window Manager Convenience Functions -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XmbSetWMProperties</function>
+function stores the standard set of window manager properties,
+with text properties in standard encodings
+for internationalized text communication.
+The standard window manager properties for a given window are
+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
+WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME.
+<indexterm significance="preferred"><primary>XmbSetWMProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XmbSetWMProperties</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> *window_name</parameter></paramdef>
+ <paramdef>char<parameter> *icon_name</parameter></paramdef>
+ <paramdef>char<parameter> *argv[]</parameter></paramdef>
+ <paramdef>int<parameter> argc</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>
+ <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>
+ <paramdef>XClassHint<parameter> *class_hints</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'>window_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the icon name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>wm_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWMHints</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XClassHint</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XmbSetWMProperties</function>
+convenience function provides a simple programming interface
+for setting those essential window properties that are used
+for communicating with other clients
+(particularly window and session managers).
+</para>
+<para>
+<!-- .LP -->
+If the window_name argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the WM_NAME property.
+If the icon_name argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the WM_ICON_NAME property.
+The window_name and icon_name arguments are null-terminated strings
+in the encoding of the current locale.
+If the arguments can be fully converted to the STRING encoding,
+the properties are created with type ``STRING'';
+otherwise, the arguments are converted to Compound Text,
+and the properties are created with type ``COMPOUND_TEXT''.
+</para>
+<para>
+<!-- .LP -->
+If the normal_hints argument is non-NULL,
+<function>XmbSetWMProperties</function>
+calls
+<function>XSetWMNormalHints</function>,
+which sets the WM_NORMAL_HINTS property (see section 14.1.7).
+If the wm_hints argument is non-NULL,
+<function>XmbSetWMProperties</function>
+calls
+<function>XSetWMHints</function>,
+which sets the WM_HINTS property (see section 14.1.6).
+</para>
+<para>
+<!-- .LP -->
+If the argv argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the WM_COMMAND property from argv and argc.
+An argc of zero indicates a zero-length command.
+</para>
+<para>
+<!-- .LP -->
+The hostname of the machine is stored using
+<function>XSetWMClientMachine </function>
+(see section 14.2.2).
+</para>
+<para>
+<!-- .LP -->
+If the class_hints argument is non-NULL,
+<function>XmbSetWMProperties</function>
+sets the WM_CLASS property.
+If the res_name member in the
+<function>XClassHint</function>
+structure is set to the NULL pointer and the RESOURCE_NAME
+environment variable is set,
+the value of the environment variable is substituted for res_name.
+If the res_name member is NULL,
+the environment variable is not set, and argv and argv[0] are set,
+then the value of argv[0], stripped of any directory prefixes,
+is substituted for res_name.
+</para>
+<para>
+<!-- .LP -->
+It is assumed that the supplied class_hints.res_name and argv,
+the RESOURCE_NAME environment variable, and the hostname of the machine
+are in the encoding of the locale announced for the LC_CTYPE category
+(on <acronym>POSIX</acronym>-compliant systems, the LC_CTYPE, else LANG environment variable).
+The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties
+are typed according to the local host locale announcer.
+No encoding conversion is performed prior to storage in the properties.
+</para>
+<para>
+<!-- .LP -->
+For clients that need to process the property text in a locale,
+<function>XmbSetWMProperties</function>
+sets the WM_LOCALE_NAME property to be the name of the current locale.
+The name is assumed to be in the Host Portable Character Encoding
+and is converted to STRING for storage in the property.
+</para>
+<para>
+<!-- .LP -->
+<function>XmbSetWMProperties</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's standard window manager properties
+with strings in client-specified encodings, use
+<function>XSetWMProperties</function>.
+The standard window manager properties for a given window are
+WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
+WM_COMMAND, and WM_CLIENT_MACHINE.
+<indexterm significance="preferred"><primary>XSetWMProperties</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMProperties</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *window_name</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *icon_name</parameter></paramdef>
+ <paramdef>char<parameter> **argv</parameter></paramdef>
+ <paramdef>int<parameter> argc</parameter></paramdef>
+ <paramdef>XSizeHints<parameter> *normal_hints</parameter></paramdef>
+ <paramdef>XWMHints<parameter> *wm_hints</parameter></paramdef>
+ <paramdef>XClassHint<parameter> *class_hints</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'>window_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>icon_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the icon name,
+which should be a null-terminated string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>normal_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the size hints for the window in its normal state.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>wm_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XWMHints</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_hints</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XClassHint</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMProperties </function>
+convenience function provides a single programming interface
+for setting those essential window properties that are used
+for communicating with other clients (particularly window and session
+managers).
+</para>
+<para>
+<!-- .LP -->
+If the window_name argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMName</function>,
+which, in turn, sets the WM_NAME property (see section 14.1.4).
+If the icon_name argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMIconName</function>,
+which sets the WM_ICON_NAME property (see section 14.1.5).
+If the argv argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetCommand</function>,
+which sets the WM_COMMAND property (see section 14.2.1).
+Note that an argc of zero is allowed to indicate a zero-length command.
+Note also that the hostname of this machine is stored using
+<function>XSetWMClientMachine </function>
+(see section 14.2.2).
+</para>
+<para>
+<!-- .LP -->
+If the normal_hints argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMNormalHints</function>,
+which sets the WM_NORMAL_HINTS property (see section 14.1.7).
+If the wm_hints argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetWMHints</function>,
+which sets the WM_HINTS property (see section 14.1.6).
+</para>
+<para>
+<!-- .LP -->
+If the class_hints argument is non-NULL,
+<function>XSetWMProperties</function>
+calls
+<function>XSetClassHint</function>,
+which sets the WM_CLASS property (see section 14.1.8).
+If the res_name member in the
+<function>XClassHint</function>
+structure is set to the NULL pointer and the RESOURCE_NAME environment
+variable is set,
+then the value of the environment variable is substituted for res_name.
+If the res_name member is NULL,
+the environment variable is not set,
+and argv and argv[0] are set,
+then the value of argv[0], stripped of
+any directory prefixes, is substituted for res_name.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetWMProperties</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow</function>
+errors.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Client_to_Session_Manager_Communication">
+<title>Client to Session Manager Communication</title>
+<!-- .XS -->
+<!-- (SN Client to Session Manager Communication -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+This section discusses how to:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Set and read the WM_COMMAND property
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Set and read the WM_CLIENT_MACHINE property
+ </para>
+ </listitem>
+</itemizedlist>
+<sect2 id="Setting_and_Reading_the_WM_COMMAND_Property">
+<title>Setting and Reading the WM_COMMAND Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_COMMAND Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_COMMAND property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_COMMAND property, use
+<function>XSetCommand</function>.
+<indexterm significance="preferred"><primary>XSetCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef><function> XSetCommand</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> **argv</parameter></paramdef>
+ <paramdef>int<parameter> argc</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'>argv</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetCommand</function>
+function sets the command and arguments used to invoke the
+application.
+(Typically, argv is the argv array of your main program.)
+If the strings are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+<function>XSetCommand</function>
+can generate
+<function>BadAlloc</function>
+and
+<function>BadWindow </function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_COMMAND property, use
+<function>XGetCommand</function>.
+<indexterm significance="preferred"><primary>XGetCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetCommand</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>char<parameter> ***argv_return</parameter></paramdef>
+ <paramdef>int<parameter> *argc_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the application's argument list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of arguments returned.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetCommand </function>
+function reads the WM_COMMAND property from the specified window
+and returns a string list.
+If the WM_COMMAND property exists,
+it is of type STRING and format 8.
+If sufficient memory can be allocated to contain the string list,
+<function>XGetCommand</function>
+fills in the argv_return and argc_return arguments
+and returns a nonzero status.
+Otherwise, it returns a zero status.
+If the data returned by the server is in the Latin Portable Character Encoding,
+then the returned strings are in the Host Portable Character Encoding.
+Otherwise, the result is implementation-dependent.
+To free the memory allocated to the string list, use
+<function>XFreeStringList</function>.
+</para>
+</sect2>
+<sect2 id="Setting_and_Reading_the_WM_CLIENT_MACHINE_Property">
+<title>Setting and Reading the WM_CLIENT_MACHINE Property</title>
+<!-- .XS -->
+<!-- (SN Setting and Reading the WM_CLIENT_MACHINE Property -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and read
+the WM_CLIENT_MACHINE property for a given window.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set a window's WM_CLIENT_MACHINE property, use
+<function>XSetWMClientMachine</function>.
+<indexterm significance="preferred"><primary>XSetWMClientMachine</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetWMClientMachine</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_prop</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'>text_prop</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XTextProperty</function>
+structure to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetWMClientMachine</function>
+convenience function calls
+<function>XSetTextProperty</function>
+to set the WM_CLIENT_MACHINE property.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To read a window's WM_CLIENT_MACHINE property, use
+<function>XGetWMClientMachine</function>.
+<indexterm significance="preferred"><primary>XGetWMClientMachine</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetWMClientMachine</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XTextProperty<parameter> *text_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>text_prop_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XTextProperty</function>
+structure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XGetWMClientMachine</function>
+convenience function performs an
+<function>XGetTextProperty </function>
+on the WM_CLIENT_MACHINE property.
+It returns a nonzero status on success;
+otherwise, it returns a zero status.
+</para>
+</sect2>
+</sect1>
+<sect1 id="Standard_Colormaps">
+<title>Standard Colormaps</title>
+<!-- .XS -->
+<!-- (SN Standard Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Applications with color palettes, smooth-shaded drawings, or digitized
+images demand large numbers of colors.
+In addition, these applications often require an efficient mapping
+from color triples to pixel values that display the appropriate colors.
+</para>
+<para>
+<!-- .LP -->
+As an example, consider a three-dimensional display program that wants
+to draw a smoothly shaded sphere.
+At each pixel in the image of the sphere,
+the program computes the intensity and color of light
+reflected back to the viewer.
+The result of each computation is a triple of red, green, and blue (<acronym>RGB</acronym>)
+coefficients in the range 0.0 to 1.0.
+To draw the sphere, the program needs a colormap that provides a
+large range of uniformly distributed colors.
+The colormap should be arranged so that the program can
+convert its <acronym>RGB</acronym> triples into pixel values very quickly,
+because drawing the entire sphere requires many such
+conversions.
+</para>
+<para>
+<!-- .LP -->
+On many current workstations,
+the display is limited to 256 or fewer colors.
+Applications must allocate colors carefully,
+not only to make sure they cover the entire range they need
+but also to make use of as many of the available colors as possible.
+On a typical X display,
+many applications are active at once.
+Most workstations have only one hardware look-up table for colors,
+so only one application colormap can be installed at a given time.
+The application using the installed colormap is displayed correctly,
+and the other applications go technicolor and are
+displayed with false colors.
+</para>
+<para>
+<!-- .LP -->
+As another example, consider a user who is running an
+image processing program to display earth-resources data.
+The image processing program needs a colormap set up with 8 reds,
+8 greens, and 4 blues, for a total of 256 colors.
+Because some colors are already in use in the default colormap,
+the image processing program allocates and installs a new colormap.
+</para>
+<para>
+<!-- .LP -->
+The user decides to alter some of the colors in the image
+by invoking a color palette program to mix and choose colors.
+The color palette program also needs a
+colormap with eight reds, eight greens, and four blues, so just like
+the image processing program, it must allocate and
+install a new colormap.
+</para>
+<para>
+<!-- .LP -->
+Because only one colormap can be installed at a time,
+the color palette may be displayed incorrectly
+whenever the image processing program is active.
+Conversely, whenever the palette program is active,
+the image may be displayed incorrectly.
+The user can never match or compare colors in the palette and image.
+Contention for colormap resources can be reduced if applications
+with similar color needs share colormaps.
+</para>
+<para>
+<!-- .LP -->
+The image processing program and the color palette program
+could share the same colormap if there existed a convention that described
+how the colormap was set up.
+Whenever either program was active,
+both would be displayed correctly.
+</para>
+<para>
+<!-- .LP -->
+The standard colormap properties define a set of commonly used
+colormaps.
+Applications that share these colormaps and conventions display
+true colors more often and provide a better interface to the user.
+</para>
+<para>
+<!-- .LP -->
+Standard colormaps allow applications to share commonly used color
+resources.
+This allows many applications to be displayed in true colors
+simultaneously, even when each application needs an entirely filled
+colormap.
+</para>
+<para>
+<!-- .LP -->
+Several standard colormaps are described in this section.
+Usually, a window manager creates these colormaps.
+Applications should use the standard colormaps if they already exist.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To allocate an
+<function>XStandardColormap</function>
+structure, use
+<function>XAllocStandardColormap</function>.
+</para>
+
+<para>
+XStandardColormap *XAllocStandardColormap()
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XAllocStandardColormap</function>
+function allocates and returns a pointer to an
+<function>XStandardColormap</function>
+structure.
+Note that all fields in the
+<function>XStandardColormap</function>
+structure are initially set to zero.
+If insufficient memory is available,
+<function>XAllocStandardColormap</function>
+returns NULL.
+To free the memory allocated to this structure,
+use
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XStandardColormap </function>
+structure contains:
+</para>
+<literallayout class="monospaced">
+/* Hints */
+
+#define ReeaseByFreeingColormap ((XID)1L)
+
+/* Values */
+
+typedef struct {
+ Colormap colormap;
+ unsigned long red_max;
+ unsigned long red_mult;
+ unsigned long green_max;
+ unsigned long green_mult;
+ unsigned long blue_max;
+ unsigned long blue_mult;
+ unsigned long base_pixel;
+ VisualID visualid;
+ XID killid;
+} XStandardColormap;
+</literallayout>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The colormap member is the colormap created by the
+<function>XCreateColormap</function>
+function.
+The red_max, green_max, and blue_max members give the maximum
+red, green, and blue values, respectively.
+Each color coefficient ranges from zero to its max, inclusive.
+For example,
+a common colormap allocation is 3/3/2 (3 planes for red, 3
+planes for green, and 2 planes for blue).
+This colormap would have red_max = 7, green_max = 7,
+and blue_max = 3.
+An alternate allocation that uses only 216 colors is red_max = 5,
+green_max = 5, and blue_max = 5.
+</para>
+<para>
+<!-- .LP -->
+The red_mult, green_mult, and blue_mult members give the
+scale factors used to compose a full pixel value.
+(See the discussion of the base_pixel members for further information.)
+For a 3/3/2 allocation, red_mult might be 32,
+green_mult might be 4, and blue_mult might be 1.
+For a 6-colors-each allocation, red_mult might be 36,
+green_mult might be 6, and blue_mult might be 1.
+</para>
+<para>
+<!-- .LP -->
+The base_pixel member gives the base pixel value used to
+compose a full pixel value.
+Usually, the base_pixel is obtained from a call to the
+<function>XAllocColorPlanes</function>
+function.
+Given integer red, green, and blue coefficients in their appropriate
+ranges, one then can compute a corresponding pixel value by
+using the following expression:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+(r * red_mult + g * green_mult + b * blue_mult + base_pixel) &amp; 0xFFFFFFFF
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+For
+<function>GrayScale</function>
+colormaps,
+only the colormap, red_max, red_mult,
+and base_pixel members are defined.
+The other members are ignored.
+To compute a
+<function>GrayScale </function>
+pixel value, use the following expression:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .5i 1.5i -->
+<!-- .ta .5i 1.5i -->
+(gray * red_mult + base_pixel) &amp; 0xFFFFFFFF
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Negative multipliers can be represented by converting the 2's
+complement representation of the multiplier into an unsigned long and
+storing the result in the appropriate _mult field.
+The step of masking by 0xFFFFFFFF effectively converts the resulting
+positive multiplier into a negative one.
+The masking step will take place automatically on many machine architectures,
+depending on the size of the integer type used to do the computation.
+</para>
+<para>
+<!-- .LP -->
+The visualid member gives the ID number of the visual from which the
+colormap was created.
+The killid member gives a resource ID that indicates whether
+the cells held by this standard colormap are to be released
+by freeing the colormap ID or by calling the
+<function>XKillClient</function>
+function on the indicated resource.
+(Note that this method is necessary for allocating out of an existing colormap.)
+</para>
+<para>
+<!-- .LP -->
+The properties containing the
+<function>XStandardColormap </function>
+information have
+the type RGB_COLOR_MAP.
+</para>
+<para>
+<!-- .LP -->
+The remainder of this section discusses standard colormap properties and atoms
+as well as how to manipulate standard colormaps.
+</para>
+<sect2 id="Standard_Colormap_Properties_and_Atoms">
+<title>Standard Colormap Properties and Atoms</title>
+<!-- .XS -->
+<!-- (SN Standard Colormap Properties and Atoms -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm><primary>Standard Colormaps</primary></indexterm>
+<indexterm><primary>Colormaps</primary><secondary>standard</secondary></indexterm>
+Several standard colormaps are available.
+Each standard colormap is defined by a property,
+and each such property is identified by an atom.
+The following list names the atoms and describes the colormap
+associated with each one.
+The
+<!-- .hN X11/Xatom.h -->
+header file contains the definitions for each of the following atoms,
+which are prefixed with XA_.
+</para>
+
+
+
+<variablelist>
+ <varlistentry>
+ <term>RGB_DEFAULT_MAP</term>
+ <listitem>
+ <para>
+This atom names a property.
+The value of the property is an array of
+<function>XStandardColormap</function>
+structures.
+Each entry in the array describes an <acronym>RGB</acronym> subset of the default color
+map for the Visual specified by visual_id.
+ </para>
+ <para>
+Some applications only need a few <acronym>RGB</acronym> colors and
+may be able to allocate them from the system default colormap.
+This is the ideal situation because the fewer colormaps that are
+active in the system the more applications are displayed
+with correct colors at all times.
+ </para>
+ <para>
+A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays
+is 6 reds, 6 greens, and 6 blues.
+This gives 216 uniformly distributed colors
+(6 intensities of 36 different hues) and still leaves 40 elements
+of a 256-element colormap available for special-purpose colors
+for text, borders, and so on.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RGB_BEST_MAP</term>
+ <listitem>
+ <para>
+This atom names a property. The value of the property is an
+<function>XStandardColormap</function>.
+ </para>
+ <para>
+The property defines the best <acronym>RGB</acronym> colormap available on
+the screen.
+(Of course, this is a subjective evaluation.)
+Many image processing and three-dimensional applications need to
+use all available colormap cells and to distribute as many
+perceptually distinct colors as possible over those cells.
+This implies that there may be more green values available than
+red, as well as more green or red than blue.
+ </para>
+ <para>
+For an 8-plane
+<function>PseudoColor </function>
+visual,
+RGB_BEST_MAP is likely to be a 3/3/2 allocation.
+For a 24-plane
+<function>DirectColor </function>
+visual,
+RGB_BEST_MAP is normally an 8/8/8 allocation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RGB_RED_MAP,RGB_GREEN_MAP,RGB_BLUE_MAP</term>
+ <listitem>
+ <para>
+These atoms name properties.
+The value of each property is an
+<function>XStandardColormap</function>.
+ </para>
+ <para>
+The properties define all-red, all-green, and all-blue
+colormaps, respectively.
+These maps are used by applications that want to make color-separated
+images.
+For example, a user might generate a full-color image
+on an 8-plane display both by rendering an image three times
+(once with high color resolution in red, once with green,
+and once with blue) and by multiply exposing a single frame in a camera.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RGB_GRAY_MAP</term>
+ <listitem>
+ <para>
+This atom names a property.
+The value of the property is an
+<function>XStandardColormap</function>.
+ </para>
+ <para>
+The property describes the best
+<function>GrayScale </function>
+colormap available on the screen.
+As previously mentioned,
+only the colormap, red_max, red_mult, and base_pixel members of the
+<function>XStandardColormap </function>
+structure are used for
+<function>GrayScale </function>
+colormaps.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="Setting_and_Obtaining_Standard_Colormaps">
+<title>Setting and Obtaining Standard Colormaps</title>
+<!-- .XS -->
+<!-- (SN Setting and Obtaining Standard Colormaps -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Xlib provides functions that you can use to set and obtain an
+<function>XStandardColormap</function>
+structure.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To set an
+<function>XStandardColormap</function>
+structure, use
+<function>XSetRGBColormaps</function>.
+<indexterm significance="preferred"><primary>XSetRGBColormaps</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>void<function> XSetRGBColormaps</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XStandardColormap<parameter> *std_colormap</parameter></paramdef>
+ <paramdef>int<parameter> count</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>std_colormap</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the
+<function>XStandardColormap</function>
+structure to be used.
+<!-- .ds Cn colormaps -->
+ </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'>property</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the property name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XSetRGBColormaps </function>
+function replaces the <acronym>RGB</acronym> colormap definition in the specified property
+on the named window.
+If the property does not already exist,
+<function>XSetRGBColormaps</function>
+sets the <acronym>RGB</acronym> colormap definition in the specified property
+on the named window.
+The property is stored with a type of RGB_COLOR_MAP and a format of 32.
+Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>
+restriction that only RGB_DEFAULT_MAP contain more than one definition.
+</para>
+<para>
+<!-- .LP -->
+The
+<function>XSetRGBColormaps</function>
+function usually is only used by window or session managers.
+To create a standard colormap,
+follow this procedure:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+Open a new connection to the same server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Grab the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+See if the property is on the property list of the root window for the screen.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+If the desired property is not present:
+<!-- .RS -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Create a colormap (unless you are using the default colormap of the screen).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Determine the color characteristics of the visual.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Allocate cells in the colormap (or create it with
+<function>AllocAll</function>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Call
+<function>XStoreColors</function>
+to store appropriate color values in the colormap.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Fill in the descriptive members in the
+<function>XStandardColormap</function>
+structure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Attach the property to the root window.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Use
+<function>XSetCloseDownMode</function>
+to make the resource permanent.
+<!-- .RE -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Ungrab the server.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+<function>XSetRGBColormaps</function>
+can generate
+<function>BadAlloc</function>,
+<function>BadAtom</function>,
+and
+<function>BadWindow</function>
+errors.
+<!-- .sp -->
+</para>
+<para>
+<!-- .LP -->
+To obtain the
+<function>XStandardColormap </function>
+structure associated with the specified property, use
+<function>XGetRGBColormaps</function>.
+<indexterm significance="preferred"><primary>XGetRGBColormaps</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis>
+<funcprototype>
+ <funcdef>Status<function> XGetRGBColormaps</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>Window<parameter> w</parameter></paramdef>
+ <paramdef>XStandardColormap<parameter> **std_colormap_return</parameter></paramdef>
+ <paramdef>int<parameter> *count_return</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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>w</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the window.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>std_colormap_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the
+<function>XStandardColormap</function>
+structure.
+<!-- .ds Cn colormaps -->
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>count_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the number of (Cn.
+ </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>XGetRGBColormaps</function>
+function returns the <acronym>RGB</acronym> colormap definitions stored
+in the specified property on the named window.
+If the property exists, is of type RGB_COLOR_MAP, is of format 32,
+and is long enough to contain a colormap definition,
+<function>XGetRGBColormaps</function>
+allocates and fills in space for the returned colormaps
+and returns a nonzero status.
+If the visualid is not present,
+<function>XGetRGBColormaps </function>
+assumes the default visual for the screen on which the window is located;
+if the killid is not present,
+<function>None</function>
+is assumed, which indicates that the resources cannot be released.
+Otherwise,
+none of the fields are set, and
+<function>XGetRGBColormaps</function>
+returns a zero status.
+Note that it is the caller's responsibility to honor the <acronym>ICCCM</acronym>
+restriction that only RGB_DEFAULT_MAP contain more than one definition.
+</para>
+<para>
+<!-- .LP -->
+<function>XGetRGBColormaps</function>
+can generate
+<function>BadAtom</function>
+and
+<function>BadWindow</function>
+errors.
+<!-- .bp -->
+
+</para>
+</sect2>
+</sect1>
+</chapter>
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-11 06:51:28 +0000