<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="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 <X11/Xatom.h>
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><property>WM_CLASS</property></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><property>WM_CLIENT_MACHINE</property></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><property>WM_COLORMAP_WINDOWS</property></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><property>WM_COMMAND</property></entry>
<entry>TEXT</entry>
<entry></entry>
<entry>The command and arguments, null-
separated, used to invoke the application.
</entry>
</row>
<row>
<entry><property>WM_HINTS</property></entry>
<entry><property>WM_HINTS</property></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><property>WM_ICON_NAME</property></entry>
<entry>TEXT</entry>
<entry></entry>
<entry>The name to be used in an icon.</entry>
</row>
<row>
<entry><property>WM_ICON_SIZE</property></entry>
<entry><property>WM_ICON_SIZE</property></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><property>WM_NAME</property></entry>
<entry>TEXT</entry>
<entry></entry>
<entry>The name of the application.</entry>
</row>
<row>
<entry><property>WM_NORMAL_HINTS</property></entry>
<entry><property>WM_NORMAL_HINTS</property></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><property>WM_PROTOCOLS</property></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><property>WM_STATE</property></entry>
<entry><property>WM_STATE</property></entry>
<entry>32</entry>
<entry>Intended for communication
between window and session man-
agers only.
</entry>
</row>
<row>
<entry><property>WM_TRANSIENT_FOR</property></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 <property>WM_NAME</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_ICON_NAME</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_HINTS</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_NORMAL_HINTS</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_CLASS</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_TRANSIENT_FOR</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_PROTOCOLS</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_COLORMAP_WINDOWS</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_ICON_SIZE</property> 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 <property>WM_CHANGE_STATE</property>
<symbol>ClientMessage</symbol>
event with a format of 32 and a first data element of
<symbol>IconicState</symbol>
(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
<symbol>SubstructureNotifyMask</symbol> |
<symbol>SubstructureRedirectMask</symbol>.
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 <property>WM_CHANGE_STATE</property> 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
<symbol>UnmapNotify</symbol>
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
<symbol>UnmapNotify</symbol>
event is successfully sent;
otherwise, it returns a zero status.
</para>
<para>
<!-- .LP -->
<function>XWithdrawWindow</function>
can generate a
<errorname>BadWindow</errorname>
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
<structname>XWindowChanges</structname>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XReconfigureWMWindow</function>
function issues a
<systemitem>ConfigureWindow</systemitem>
request on the specified top-level window.
If the stacking mode is changed and the request fails with a
<errorname>BadMatch</errorname>
error,
the error is trapped by Xlib and a synthetic
<systemitem class="event">ConfigureRequestEvent</systemitem>
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
<errorname>BadValue</errorname>
and
<errorname>BadWindow</errorname>
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
<structname>XTextProperty</structname>
structure is used to describe the encoding, type, and length of the text
as well as its value.
The
<structname>XTextProperty</structname>
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
<symbol>Success</symbol>
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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XmbTextListToTextProperty</function>
and
<function>XwcTextListToTextProperty</function>
functions set the specified
<structname>XTextProperty</structname>
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
<type>Atom</type>
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
<constant>XStringStyle</constant>
or
<constant>XCompoundTextStyle</constant>
is specified,
this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
If the style
<constant>XTextStyle</constant>
is specified,
this encoding is the encoding of the current locale.
If the style
<constant>XStdICCTextStyle</constant>
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
<symbol>XNoMemory</symbol>.
If the current locale is not supported,
the functions return
<symbol>XLocaleNotSupported</symbol>.
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
<symbol>XLocaleNotSupported</symbol>,
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
<symbol>Success</symbol>.
Note that full convertibility to all styles except
<constant>XStringStyle</constant>
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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
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
<symbol>XNoMemory</symbol>.
If the current locale is not supported,
the functions return
<symbol>XLocaleNotSupported</symbol>.
Otherwise, if the encoding field of text_prop is not convertible
to the encoding of the current locale,
the functions return
<symbol>XConverterNotFound</symbol>.
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
<symbol>True</symbol>
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
<symbol>Success</symbol>.
</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
<type>XFontSet</type>.
</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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XStringListToTextProperty</function>
function sets the specified
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
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
(<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property>).
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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
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
<errorname>BadAlloc</errorname>,
<errorname>BadAtom</errorname>,
<errorname>BadValue</errorname>,
and
<errorname>BadWindow</errorname>
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
<structname>XTextProperty</structname>
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
<structname>XTextProperty</structname>
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
<symbol>None</symbol>,
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
<structname>XTextProperty</structname>
structure,
<function>XGetTextProperty</function>
returns a nonzero status;
otherwise, it returns a zero status.
</para>
<para>
<!-- .LP -->
<function>XGetTextProperty</function>
can generate
<errorname>BadAtom</errorname>
and
<errorname>BadWindow</errorname>
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 <property>WM_NAME</property> property for a given window.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set a window's <property>WM_NAME</property> 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
<structname>XTextProperty</structname>
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 <property>WM_NAME</property> property.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To read a window's <property>WM_NAME</property> 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
<structname>XTextProperty</structname>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XGetWMName</function>
convenience function calls
<function>XGetTextProperty</function>
to obtain the <property>WM_NAME</property> 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
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
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 <property>WM_NAME</property> 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
<errorname>BadWindow</errorname>
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 <property>WM_ICON_NAME</property> property for a given window.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To set a window's <property>WM_ICON_NAME</property> 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
<structname>XTextProperty</structname>
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 <property>WM_ICON_NAME</property> property.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To read a window's <property>WM_ICON_NAME</property> 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
<structname>XTextProperty</structname>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XGetWMIconName</function>
convenience function calls
<function>XGetTextProperty</function>
to obtain the <property>WM_ICON_NAME</property> 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
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
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
<errorname>BadWindow</errorname>
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 <property>WM_HINTS</property> property for a given window.
These functions use the flags and the
<structname>XWMHints</structname>
structure, as defined in the
<filename class="headerfile"><X11/Xutil.h></filename>
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
header file.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To allocate an
<structname>XWMHints</structname>
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
<structname>XWMHints</structname>
structure.
Note that all fields in the
<structname>XWMHints</structname>
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
<structname>XWMHints</structname>
structure contains:
</para>
<literallayout class="monospaced">
/* Window manager hints mask bits */
#define InputHint (1L<<0)
#define StateHint (1L<<1)
#define IconPixmapHint (1L<<2)
#define IconWindowHint (1L<<3)
#define IconPositionHint (1L<<4)
#define IconMaskHint (1L<<5)
#define WindowGroupHint (1L<<6)
#define UrgencyHint (1L<<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
<symbol>True</symbol>.
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
<symbol>True</symbol>.
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
<symbol>False</symbol>.
Applications that never expect any keyboard input also should set this member
to
<symbol>False</symbol>.
</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
<symbol>True</symbol>.
Push model window managers should
make sure that pull model applications do not break them
by resetting input focus to
<symbol>PointerRoot</symbol>
when it is appropriate (for example, whenever an application whose
input member is
<symbol>False</symbol>
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
<symbol>UrgencyHint</symbol>
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 <property>WM_HINTS</property> 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
<structname>XWMHints</structname>
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
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To read a window's <property>WM_HINTS</property> 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 <property>WM_HINTS</property> property was set on the window
or returns a pointer to an
<structname>XWMHints</structname>
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
<errorname>BadWindow</errorname>
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 <property>WM_NORMAL_HINTS</property> property for a given window.
The functions use the flags and the
<structname>XSizeHints</structname>
structure, as defined in the
<filename class="headerfile"><X11/Xutil.h></filename>
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
header file.
</para>
<para>
<!-- .LP -->
The size of the
<structname>XSizeHints</structname>
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
<structname>XSizeHints</structname>
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
<structname>XSizeHints</structname>
structure.
Note that all fields in the
<structname>XSizeHints</structname>
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
<structname>XSizeHints</structname>
structure contains:
</para>
<literallayout class="monospaced">
/* Size hints mask bits */
#define USPosition (1L<<0) /* user specified x,y */
#define USSize (1L<<1) /* user specified width,height */
#define PPosition (1L<<2) /* program specified posistion */
#define PSize (1L<<3) /* program specified size */
#define PMinSize (1L<<4) /* program specified minimum size */
#define PMaxSize (1L<<5) /* program specified maximum size */
#define PResizeInc (1L<<5) /* program specified resize increments */
#define PAspect (1L<<6) /* program specified min and max aspect ratios */
#define PBaseSize (1L<<8)
#define PWinGravity (1L<<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
<symbol>PAllHints</symbol>
macro is highly discouraged.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set a window's <property>WM_NORMAL_HINTS</property> 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 <property>WM_NORMAL_HINTS</property> property
on the specified window.
If the property does not already exist,
<function>XSetWMNormalHints</function>
sets the size hints for the <property>WM_NORMAL_HINTS</property> property on the specified window.
The property is stored with a type of <property>WM_SIZE_HINTS</property> and a format of 32.
</para>
<para>
<!-- .LP -->
<function>XSetWMNormalHints</function>
can generate
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
errors.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To read a window's <property>WM_NORMAL_HINTS</property> 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 <property>WM_NORMAL_HINTS</property> property
on the specified window.
If the property is of type <property>WM_SIZE_HINTS</property>, 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
<structname>XSizeHints</structname>
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
<errorname>BadWindow</errorname>
error.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set a window's <property>WM_SIZE_HINTS</property> 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
<structname>XSizeHints</structname>
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 <property>WM_SIZE_HINTS</property> 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
<errorname>BadAlloc</errorname>,
<errorname>BadAtom</errorname>,
and
<errorname>BadWindow</errorname>
errors.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To read a window's <property>WM_SIZE_HINTS</property> 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
<structname>XSizeHints</structname>
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 <property>WM_SIZE_HINTS</property>, 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
<structname>XSizeHints</structname>
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
<errorname>BadAtom</errorname>
and
<errorname>BadWindow</errorname>
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 <property>WM_CLASS</property> property for a given window.
These functions use the
<structname>XClassHint</structname>
structure, which is defined in the
<filename class="headerfile"><X11/Xutil.h></filename>
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
header file.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To allocate an
<structname>XClassHint</structname>
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
<structname>XClassHint</structname>
structure.
Note that the pointer fields in the
<structname>XClassHint</structname>
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
<structname>XClassHint</structname>
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 <property>WM_NAME</property>.
That is, <property>WM_NAME</property> 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 <property>WM_CLASS</property> 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 <property>WM_CLASS</property> 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
<structname>XClassHint</structname>
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
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To read a window's <property>WM_CLASS</property> 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
<structname>XClassHint</structname>
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
<errorname>BadWindow</errorname>
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 <property>WM_TRANSIENT_FOR</property> property for a given window.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To set a window's <property>WM_TRANSIENT_FOR</property> 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 <property>WM_TRANSIENT_FOR</property> property is to be set to.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XSetTransientForHint</function>
function sets the <property>WM_TRANSIENT_FOR</property> property of the specified window to the
specified prop_window.
</para>
<para>
<!-- .LP -->
<function>XSetTransientForHint</function>
can generate
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To read a window's <property>WM_TRANSIENT_FOR</property> 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 <property>WM_TRANSIENT_FOR</property> property of the specified window.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XGetTransientForHint</function>
function returns the <property>WM_TRANSIENT_FOR</property> 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
<errorname>BadWindow</errorname>
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 <property>WM_PROTOCOLS</property> property for a given window.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To set a window's <property>WM_PROTOCOLS</property> 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 <property>WM_PROTOCOLS</property> 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 <property>WM_PROTOCOLS</property> 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 <property>WM_PROTOCOLS</property> atom,
<function>XSetWMProtocols</function>
returns a zero status.
Otherwise, it returns a nonzero status.
</para>
<para>
<!-- .LP -->
<function>XSetWMProtocols</function>
can generate
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
errors.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To read a window's <property>WM_PROTOCOLS</property> 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 <property>WM_PROTOCOLS</property> 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 <property>WM_PROTOCOLS</property> 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
<errorname>BadWindow</errorname>
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 <property>WM_COLORMAP_WINDOWS</property> property for a given window.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set a window's <property>WM_COLORMAP_WINDOWS</property> 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 <property>WM_COLORMAP_WINDOWS</property> 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 <property>WM_COLORMAP_WINDOWS</property> 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 <property>WM_COLORMAP_WINDOWS</property> atom,
<function>XSetWMColormapWindows</function>
returns a zero status.
Otherwise, it returns a nonzero status.
</para>
<para>
<!-- .LP -->
<function>XSetWMColormapWindows</function>
can generate
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
errors.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To read a window's <property>WM_COLORMAP_WINDOWS</property> 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 <property>WM_COLORMAP_WINDOWS</property> 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 <property>WM_COLORMAP_WINDOWS</property> 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
<errorname>BadWindow</errorname>
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 <property>WM_ICON_SIZE</property> property for a given window.
These functions use the
<structname>XIconSize</structname>
<indexterm><primary>XIconSize</primary></indexterm>
structure, which is defined in the
<filename class="headerfile"><X11/Xutil.h></filename>
<indexterm type="file"><primary><filename class="headerfile">X11/Xutil.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xutil.h></filename></secondary></indexterm>
header file.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To allocate an
<structname>XIconSize</structname>
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
<structname>XIconSize</structname>
structure.
Note that all fields in the
<structname>XIconSize</structname>
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
<structname>XIconSize</structname>
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 <property>WM_ICON_SIZE</property> 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
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
errors.
</para>
<para>
<!-- .LP -->
<!-- .sp -->
To read a window's <property>WM_ICON_SIZE</property> 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
<errorname>BadWindow</errorname>
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
<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_NORMAL_HINTS</property>, <property>WM_CLASS</property>,
<property>WM_COMMAND</property>, <property>WM_CLIENT_MACHINE</property>, and <property>WM_LOCALE_NAME</property>.
<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
<structname>XWMHints</structname>
structure to be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>class_hints</emphasis>
</term>
<listitem>
<para>
Specifies the
<structname>XClassHint</structname>
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 <property>WM_NAME</property> property.
If the icon_name argument is non-NULL,
<function>XmbSetWMProperties</function>
sets the <property>WM_ICON_NAME</property> 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 <property>WM_NORMAL_HINTS</property> property (see section 14.1.7).
If the wm_hints argument is non-NULL,
<function>XmbSetWMProperties</function>
calls
<function>XSetWMHints</function>,
which sets the <property>WM_HINTS</property> property (see section 14.1.6).
</para>
<para>
<!-- .LP -->
If the argv argument is non-NULL,
<function>XmbSetWMProperties</function>
sets the <property>WM_COMMAND</property> 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 <property>WM_CLASS</property> property.
If the res_name member in the
<structname>XClassHint</structname>
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 <property>WM_CLASS</property>, <property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property> 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 <property>WM_LOCALE_NAME</property> 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
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
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
<property>WM_NAME</property>, <property>WM_ICON_NAME</property>, <property>WM_HINTS</property>, <property>WM_NORMAL_HINTS</property>, <property>WM_CLASS</property>,
<property>WM_COMMAND</property>, and <property>WM_CLIENT_MACHINE</property>.
<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
<structname>XWMHints</structname>
structure to be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis remap='I'>class_hints</emphasis>
</term>
<listitem>
<para>
Specifies the
<structname>XClassHint</structname>
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 <property>WM_NAME</property> property (see section 14.1.4).
If the icon_name argument is non-NULL,
<function>XSetWMProperties</function>
calls
<function>XSetWMIconName</function>,
which sets the <property>WM_ICON_NAME</property> property (see section 14.1.5).
If the argv argument is non-NULL,
<function>XSetWMProperties</function>
calls
<function>XSetCommand</function>,
which sets the <property>WM_COMMAND</property> property (see section 14.2.1).
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 <property>WM_NORMAL_HINTS</property> property (see section 14.1.7).
If the wm_hints argument is non-NULL,
<function>XSetWMProperties</function>
calls
<function>XSetWMHints</function>,
which sets the <property>WM_HINTS</property> property (see section 14.1.6).
</para>
<para>
<!-- .LP -->
If the class_hints argument is non-NULL,
<function>XSetWMProperties</function>
calls
<function>XSetClassHint</function>,
which sets the <property>WM_CLASS</property> property (see section 14.1.8).
If the res_name member in the
<structname>XClassHint</structname>
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
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
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 <property>WM_COMMAND</property> property
</para>
</listitem>
<listitem>
<para>
Set and read the <property>WM_CLIENT_MACHINE</property> 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 <property>WM_COMMAND</property> property for a given window.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set a window's <property>WM_COMMAND</property> 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
<errorname>BadAlloc</errorname>
and
<errorname>BadWindow</errorname>
errors.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To read a window's <property>WM_COMMAND</property> 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 <property>WM_COMMAND</property> property from the specified window
and returns a string list.
If the <property>WM_COMMAND</property> 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 <property>WM_CLIENT_MACHINE</property> property for a given window.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set a window's <property>WM_CLIENT_MACHINE</property> 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
<structname>XTextProperty</structname>
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 <property>WM_CLIENT_MACHINE</property> property.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To read a window's <property>WM_CLIENT_MACHINE</property> 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
<structname>XTextProperty</structname>
structure.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<!-- .LP -->
<!-- .eM -->
The
<function>XGetWMClientMachine</function>
convenience function performs an
<function>XGetTextProperty</function>
on the <property>WM_CLIENT_MACHINE</property> 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
<structname>XStandardColormap</structname>
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
<structname>XStandardColormap</structname>
structure.
Note that all fields in the
<structname>XStandardColormap</structname>
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
<structname>XStandardColormap</structname>
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) & 0xFFFFFFFF
</literallayout>
</para>
<para>
<!-- .LP -->
For
<symbol>GrayScale</symbol>
colormaps,
only the colormap, red_max, red_mult,
and base_pixel members are defined.
The other members are ignored.
To compute a
<symbol>GrayScale</symbol>
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) & 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
<structname>XStandardColormap</structname>
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
<filename class="headerfile"><X11/Xatom.h></filename>
<indexterm type="file"><primary><filename class="headerfile">X11/Xatom.h</filename></primary></indexterm>
<indexterm><primary>Files</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
<indexterm><primary>Headers</primary><secondary><filename class="headerfile"><X11/Xatom.h></filename></secondary></indexterm>
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
<structname>XStandardColormap</structname>
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
<structname>XStandardColormap</structname>.
</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
<symbol>PseudoColor</symbol>
visual,
RGB_BEST_MAP is likely to be a 3/3/2 allocation.
For a 24-plane
<symbol>DirectColor</symbol>
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
<structname>XStandardColormap</structname>.
</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
<structname>XStandardColormap</structname>.
</para>
<para>
The property describes the best
<symbol>GrayScale</symbol>
colormap available on the screen.
As previously mentioned,
only the colormap, red_max, red_mult, and base_pixel members of the
<structname>XStandardColormap</structname>
structure are used for
<symbol>GrayScale</symbol>
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
<structname>XStandardColormap</structname>
structure.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To set an
<structname>XStandardColormap</structname>
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
<structname>XStandardColormap</structname>
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
<symbol>AllocAll</symbol>).
</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
<structname>XStandardColormap</structname>
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
<errorname>BadAlloc</errorname>,
<errorname>BadAtom</errorname>,
and
<errorname>BadWindow</errorname>
errors.
<!-- .sp -->
</para>
<para>
<!-- .LP -->
To obtain the
<structname>XStandardColormap</structname>
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
<structname>XStandardColormap</structname>
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,
<symbol>None</symbol>
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
<errorname>BadAtom</errorname>
and
<errorname>BadWindow</errorname>
errors.
<!-- .bp -->
</para>
</sect2>
</sect1>
</chapter>