\&
.sp 1
.ce 3
\s+1\fBChapter 9\fP\s-1

\s+1\fBInter-Client Communication Functions\fP\s-1
.sp 2
.nr H1 9
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 9: Inter-Client Communication Functions
.XE
The \fIInter-Client Communication Conventions Manual\fP (ICCCM) 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 information,
see the \fIInter-Client Communication Conventions Manual\fP.
.LP
Xlib provides a number of standard properties and programming interfaces
that comply with these ICCCM conventions.
The predefined atoms for some of these properties are defined in the
.Pn < X11/Xatom.h >
header file, where
to avoid name conflicts with user symbols, their
.PN #define
name has an XA_ prefix.
For further information about atoms and properties,
see section 4.2.
.LP
Xlib's selection and cut buffer mechanisms provide the primary programming 
interfaces by which peer client applications communicate with each other 
(see sections 4.4 and 10.7).
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.
.LP
The standard properties that are of special interest for communicating 
with window and session managers are:
.IN "Atom" "predefined"
.TS H
lw(1.6i) lw(1i) lw(.4i) lw(2.25i)
lw(1.6i) lw(1i) cw(.4i) lw(2.25i).
_
.sp 6p
.B
Name	Type	Format	Description
.sp 6p
_
.TH
.R
T{
\s-1WM_CLASS\s+1
T}	T{
\s-1STRING\s+1
T}	T{
8
T}	T{
Set by application programs to allow window and session
managers to obtain the application's resources from the resource database.
T}
.sp 6p
T{
\s-1WM_CLIENT_MACHINE\s+1
T}	T{
\s-1TEXT\s+1
T}	T{
T}	T{
The string name of the machine on which the client application is running.
T}
.sp 6p
T{
\s-1WM_COLORMAP_WINDOWS\s+1
T}	T{
\s-1WINDOW\s+1
T}	T{
32
T}	T{
List of window IDs that may need a different colormap
than that of their top-level window.
T}
.sp 6p
T{
\s-1WM_COMMAND\s+1
T}	T{
\s-1TEXT\s+1
T}	T{
T}	T{
The command and arguments, separated by ASCII nulls, used to invoke the
application.
T}
.sp 6p
T{
\s-1WM_HINTS\s+1
T}	T{
\s-1WM_HINTS\s+1
T}	T{
32
T}	T{
Additional hints set by client for use by the window manager.
The C type of this property is 
.PN XWMHints .
T}
.sp 6p
T{
\s-1WM_ICON_NAME\s+1
T}	T{
\s-1TEXT\s+1
T}	T{
T}	T{
Name to be used in icon.
T}
.sp 6p
T{
\s-1WM_ICON_SIZE\s+1
T}	T{
\s-1WM_ICON_SIZE\s+1
T}	T{
32
T}	T{
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 
.PN XIconSize .
T}
.sp 6p
T{
\s-1WM_NAME\s+1
T}	T{
\s-1TEXT\s+1
T}	T{
T}	T{
Name of the application.
T}
.sp 6p
T{
\s-1WM_NORMAL_HINTS\s+1
T}	T{
\s-1WM_SIZE_HINTS\s+1
T}	T{
32
T}	T{
Size hints for a window in its normal state.
The C type of this property is
.PN XSizeHints .
T}
.sp 6p
T{
\s-1WM_PROTOCOLS\s+1
T}	T{
\s-1ATOM\s+1
T}	T{
32
T}	T{
List of atoms that identify the communications protocols between the
client and window manager in which the client is willing to participate.
T}
.sp 6p
T{
\s-1WM_STATE\s+1
T}	T{
\s-1WM_STATE\s+1
T}	T{
32
T}	T{
Intended for communication between window and session managers only.
T}
.sp 6p
T{
\s-1WM_TRANSIENT_FOR\s+1
T}	T{
\s-1WINDOW\s+1
T}	T{
32
T}	T{
Set by application programs to indicate to the window manager that a transient
top-level window, such as a dialog box.
T}
.sp 6p
_
.TE
.LP
The remainder of this chapter discusses:
.IP \(bu 5
Client to window manager communication
.IP \(bu 5
Client to session manager communication
.IP \(bu 5
Standard colormaps
.NH 2
Client to Window Manager Communication
.LP
This section discusses how to:
.IP \(bu 5
Manipulate top-level windows
.IP \(bu 5
Convert string lists
.IP \(bu 5
Set and read text properties
.IP \(bu 5
Set and read the WM_NAME property
.IP \(bu 5
Set and read the WM_ICON_NAME property
.IP \(bu 5
Set and read the WM_HINTS property
.IP \(bu 5
Set and read the WM_NORMAL_HINTS property
.IP \(bu 5
Set and read the WM_CLASS property
.IP \(bu 5
Set and read the WM_TRANSIENT_FOR property
.IP \(bu 5
Set and read the WM_PROTOCOLS property
.IP \(bu 5
Set and read the WM_COLORMAP_WINDOWS property
.IP \(bu 5
Set and read the WM_ICON_SIZE property
.IP \(bu 5
Use window manager convenience functions
.NH 3
Manipulating Top-Level Windows
.XS
\*(SN Manipulating Top-Level Windows
.XE
.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 a 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.
.LP
To request that a top-level window be iconified, use
.PN XIconifyWindow .
.IN "XIconifyWindow" "" "@DEF@"
.FD 0
Status XIconifyWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.LP
The 
.PN XIconifyWindow 
function sends a WM_CHANGE_STATE 
.PN ClientMessage 
event with a format of 32 and a first data element of 
.PN IconicState 
(as described in Section 4.1.4 of the 
\fIInter-Client Communication Conventions Manual\fP)
to the root window of the specified screen.
Window managers may elect to receive this message and, 
if the window is in its normal state, 
may treat it as a request to change the window's state from normal to iconic.
If the WM_CHANGE_STATE property cannot be interned, 
.PN XIconifyWindow
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.
.LP
.PN XIconifyWindow 
can generate a
.PN BadWindow
error.
.sp
.LP
To request that a top-level window be withdrawn, use
.PN XWithdrawWindow .
.IN "XWithdrawWindow" "" "@DEF@"
.FD 0
Status XWithdrawWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      int \fIscreen_number\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.LP
The 
.PN XWithdrawWindow 
function unmaps the specified window 
and sends a synthetic 
.PN UnmapNotify 
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 
.PN UnmapNotify 
event is successfully sent; 
otherwise, it returns a zero status.
.LP
.PN XWithdrawWindow
can generate a
.PN BadWindow
error.
.sp
.LP
To request that a top-level window be reconfigured, use
.PN XReconfigureWMWindow .
.IN "XReconfigureWMWindow" "" "@DEF@"
.FD 0
Status XReconfigureWMWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP, \
\fIvalue_mask\fP, \fIvalues\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      int \fIscreen_number\fP\^;
.br
      unsigned int \fIvalue_mask\fP\^;
.br
      XWindowChanges *\fIvalues\fP;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIscreen_number\fP 1i
Specifies the appropriate screen number on the host server.
.\" $Header: value_mask.a,v 1.2 88/05/07 12:39:38 mento Exp $
.IP \fIvalue_mask\fP 1i
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.
.\" $Header: values.a,v 1.2 88/05/07 12:41:05 mento Exp $
.IP \fIvalues\fP 1i
Specifies a pointer to the 
.PN XWindowChanges 
structure.
.LP
The 
.PN XReconfigureWMWindow 
function issues a 
.PN ConfigureWindow 
request on the specified top-level window.
If the stacking mode is changed and the request fails with a 
.PN BadMatch 
error, 
the error event is trapped and a synthetic 
.PN ConfigureRequestEvent 
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.
.LP
.PN XReconfigureWMWindow 
can generate
.PN BadValue 
and 
.PN BadWindow 
errors.
.NH 3
Converting String Lists
.XS
\*(SN Converting String Lists
.XE
.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, a
.PN XTextProperty
structure is used to describe the encoding, type, and length of the text 
as well as its value.
The
.PN XTextProperty
structure contains:
.IN "XTextProperty" "" "@DEF@"
.Ds 0
.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;
.De
.LP
Xlib provides functions that you can use to convert between lists of pointers 
to character strings and text properties.
.sp
.LP
To set the specified list of strings to a 
.PN XTextProperty
structure, use
.PN XStringListToTextProperty .
.IN "XStringListToTextProperty" "" "@DEF@"
.FD 0
Status XStringListToTextProperty\^(\^\fIlist\fP, \fIcount\fP, \
\fItext_prop_return\fP\^)
.br
      char **\fIlist\fP\^;
.br
      int \fIcount\fP\^;
.br
      XTextProperty *\fItext_prop_return\fP\^;
.FN
.IP \fIlist\fP 1i
Specifies a list of null-terminated character strings.
.ds Cn strings
.IP \fIcount\fP 1i
Specifies the number of \*(Cn.
.IP \fItext_prop_return\fP 1i
Returns the
.PN XTextProperty
structure.
.LP
The 
.PN XStringListToTextProperty 
function sets the specified 
.PN XTextProperty
to be of type STRING (format 8) with a value representing the
concatenation of the specified list of null-separated character strings.
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.
If insufficient memory is available for the new value string, 
.PN XStringListToTextProperty
does not set any fields in the
.PN XTextProperty
structure and returns a zero status.
Otherwise, it returns a non-zero status.
To free the storage for the value field, use 
.PN XFree .
.sp
.LP
To obtain a list of strings from a specified
.PN XTextProperty
structure, use
.PN XTextPropertyToStringList .
.IN "XTextPropertyToStringList" "" "@DEF@"
.FD 0
Status XTextPropertyToStringList\^(\^\fItext_prop\fP, \fIlist_return\fP, \
\fIcount_return\fP\^)
.br
       XTextProperty *\fItext_prop\fP\^;
.br
       char ***\fIlist_return\fP\^;
.br
       int *\fIcount_return\fP\^;
.FN
.IP \fItext_prop\fP 1i
Specifies the
.PN XTextProperty
structure to be used.
.IP \fIlist_return\fP 1i
Returns a list of null-terminated character strings.
.ds Cn strings
.IP \fIcount_return\fP 1i
Returns the number of \*(Cn.
.LP
The 
.PN XTextPropertyToStringList 
function returns a list of strings representing the null-separated elements 
of the specified
.PN XTextProperty
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 a NULL (encoding 0).
The contents of the property are not null-terminated.
If insufficient memory is available for the list and its elements, 
.PN XTextPropertyToStringList
sets no return values and returns a zero status.
Otherwise, it returns a non-zero status.
To free the storage for the list and its contents, use 
.PN XFreeStringList .
.sp
.LP
To free the in-memory data associated with the specified string list, use
.PN XFreeStringList .
.IN "XFreeStringList" "" "@DEF@"
.FD 0
void XFreeStringList\^(\^\fIlist\fP\^)
.br
      char **\fIlist\fP\^;
.FN
.IP \fIlist\fP 1i
Specifies the list of strings to be freed.
.LP
The 
.PN XFreeStringList 
function releases memory allocated by 
.PN XTextPropertyToStringList .
.NH 3
Setting and Reading Text Properties
.XS
\*(SN Setting and Reading Text Properties
.XE
.LP
Xlib provides two functions that you can use to set and read
the text properties for a given window.
You can uses these functions set and read those properties of type TEXT
(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE).
In addition,
Xlib provides separate convenience functions that you can use to set each 
of these properties.
For further information about these convenience functions,
see sections 9.1.4, 9.1.5, 9.2.1, and 9.2.2, respectively.
.sp
.LP
To set one of a window's text properties, use
.PN XSetTextProperty .
.IN "XSetTextProperty" "" "@DEF@"
.FD 0
void XSetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP, \
\fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XTextProperty *\fItext_prop\fP\^;
.br
      Atom \fIproperty\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fItext_prop\fP 1i
Specifies the
.PN XTextProperty
structure to be used.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
The
.PN XSetTextProperty
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
.PN XTextProperty
structure.
If the property does not already exist,
.PN XSetTextProperty
sets it for the specified window.
.LP
.PN XSetTextProperty
can generate
.PN BadAlloc ,
.PN BadAtom , 
.PN BadValue , 
and 
.PN BadWindow  
errors.
.sp
.LP
To read one of a window's text properties, use
.PN XGetTextProperty .
.IN "XGetTextProperty" "" "@DEF@"
.FD 0
Status XGetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP, \
\fIproperty\fP\^)
.br
       Display *\fIdisplay\fP\^;
.br
       Window \fIw\fP\^;
.br
       XTextProperty *\fItext_prop_return\fP\^;
.br
       Atom \fIproperty\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fItext_prop_return\fP 1i
Returns the
.PN XTextProperty
structure.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
The
.PN XGetTextProperty 
function reads the specified property from the window
and stores the data in the returned
.PN XTextProperty
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.
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,
.PN XGetTextProperty
sets the value field to NULL, 
the encoding field to None, 
the format field to 0, 
and the nitems field to zero.
.LP
If it was able to set these files in the
.PN XTextProperty
structure,
.PN XGetTextProperty
returns a non-zero status; 
otherwise, it returns a zero status.
.LP
.PN XGetTextProperty
can generate
.PN BadAtom 
and 
.PN BadWindow 
errors.
.NH 3
Setting and Reading the WM_NAME Property
.XS
\*(SN Setting and Reading the WM_NAME Property
.XE
.LP
Xlib provides convenience functions that you can use to set and read 
the WM_NAME property for a given window.
.sp
.LP
To set a window's WM_NAME property with the supplied convenience function, use
.PN XSetWMName .
.IN "XSetWMName" "" "@DEF@"
.FD 0
void XSetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XTextProperty *\fItext_prop\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fItext_prop\fP 1i
Specifies the
.PN XTextProperty
structure to be used.
.LP
The
.PN XSetWMName
convenience function performs a 
.PN XSetTextProperty 
on the WM_NAME property (see section 9.1.3).
.sp
.LP
To read a window's WM_NAME property with the supplied convenience function, use
.PN XGetWMName .
.IN "XGetWMName" "" "@DEF@"
.FD 0
Status XGetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XTextProperty *\fItext_prop_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fItext_prop_return\fP 1i
Returns the
.PN XTextProperty
structure.
.LP
The
.PN XGetWMName 
convenience function performs an 
.PN XGetTextProperty 
on the WM_NAME property (see section 9.1.3).
.LP
The next two functions have been superceded by
.PN XSetWMName
and
.PN XGetWMName ,
respectively. 
You can use these additional convenience functions 
for window names that are encoded as STRING properties.
.sp
.LP
To assign a name to a window, use
.PN XStoreName .
.IN "Window" "name"
.IN "XStoreName" "" "@DEF@"
.FD 0
.\" $Header: XStoreName.f,v 1.1 88/02/26 10:03:53 mento Exp $
XStoreName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char *\fIwindow_name\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: window_name.a,v 1.2 88/05/18 05:22:36 mento Exp $
.IP \fIwindow_name\fP 1i
Specifies the window name,
which should be a null-terminated string.
.LP
.\" $Header: XStoreName.d,v 1.2 88/06/11 07:53:51 mento Exp $
The
.PN XStoreName
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.
.LP
.PN XStoreName
can generate
.PN BadAlloc
and
.PN BadWindow
errors.
.LP
.sp
To get the name of a window, use
.PN XFetchName .
.IN "XFetchName" "" "@DEF@"
.FD 0
.\" $Header: XFetchName.f,v 1.2 88/04/07 14:34:36 mento Exp $
Status XFetchName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char **\fIwindow_name_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: window_name1.a,v 1.2 88/05/17 11:14:20 mento Exp $
.IP \fIwindow_name_return\fP 1i
Returns a pointer to the window name, which is a null-terminated string.
.LP
.\" $Header: XFetchName.d,v 1.5 88/06/11 07:50:16 mento Exp $
The
.PN XFetchName
function returns the name of the specified window.
If it succeeds,
it returns nonzero; 
otherwise, no name has been set for the window,
and it returns zero.
If the WM_NAME property has not been set for this window,
.PN XFetchName
sets window_name_return to NULL.
When finished with it, a client must free
the window name string using
.PN XFree .
.LP
.PN XFetchName
can generate a
.PN BadWindow
error.
.NH 3
Setting and Reading the WM_ICON_NAME Property
.XS
\*(SN Setting and Reading the WM_ICON_NAME Property
.XE
.LP
Xlib provides convenience functions that you can use to set and read 
the WM_ICON_NAME property for a given window.
.LP
.sp
To set a window's WM_ICON_NAME property,
use
.PN XSetWMIconName .
.IN "XSetWMIconName" "" "@DEF@"
.FD 0
void XSetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XTextProperty *\fItext_prop\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fItext_prop\fP 1i
Specifies the
.PN XTextProperty
structure to be used.
.LP
The
.PN XSetWMIconName
convenience function performs a
.PN XSetTextProperty
on the WM_ICON_NAME property (see section 9.1.3).
.sp
.LP
To read a window's WM_ICON_NAME property,
use
.PN XGetWMIconName .
.IN "XGetWMIconName" "" "@DEF@"
.FD 0
Status XGetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XTextProperty *\fItext_prop_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fItext_prop_return\fP 1i
Returns the
.PN XTextProperty
structure.
.LP
The 
.PN XGetWMIconName 
convenience function performs an 
.PN XGetTextProperty 
on the WM_ICON_NAME property (see section 9.1.3).
.LP
The next two functions have been superceded by
.PN XSetWMIconName
and
.PN XGetWMIconName ,
respectively.
You can use these additional convenience functions 
for window names that are encoded as STRING properties.
.sp
.LP
.sp
To set the name to be displayed in a window's icon, use
.PN XSetIconName .
.IN "Window" "icon name"
.IN "XSetIconName" "" "@DEF@"
.FD 0
.\" $Header: XSetIName.f,v 1.1 88/02/26 10:03:16 mento Exp $
XSetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char *\fIicon_name\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: icon_name.a,v 1.2 88/05/17 11:22:33 mento Exp $
.IP \fIicon_name\fP 1i
Specifies the icon name,
which should be a null-terminated string.
.LP
.PN XSetIconName
can generate
.PN BadAlloc
and
.PN BadWindow
errors.
.LP
.sp
To get the name a window wants displayed in its icon, use
.PN XGetIconName .
.IN "XGetIconName" "" "@DEF@"
.FD 0
.\" $Header: XGetIName.f,v 1.2 88/04/07 14:39:05 mento Exp $
Status XGetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char **\fIicon_name_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: icon_name1.a,v 1.2 88/05/17 11:24:31 mento Exp $
.IP \fIicon_name_return\fP 1i
Returns a pointer to the window's icon name,
which is a null-terminated string.
.LP
.\" $Header: XGetIName.d,v 1.4 88/06/11 07:51:07 mento Exp $
The
.PN XGetIconName
function returns the name to be displayed in the specified window's icon.
If it succeeds, it returns nonzero; otherwise, 
if no icon name has been set for the window,
it returns zero.
If you never assigned a name to the window,
.PN XGetIconName
sets icon_name_return to NULL.
When finished with it, a client must free
the icon name string using
.PN XFree .
.LP
.PN XGetIconName
can generate a
.PN BadWindow
error.
.NH 3
Setting and Reading the WM_HINTS Property
.XS
\*(SN Setting and Reading the WM_HINTS Property
.XE
.LP
Xlib provides functions that you can use to set and read 
the WM_HINTS property for a given window.
These functions use the flags and the
.PN XWMHints 
structure, as defined in the
.Pn < X11/Xutil.h >
header file.
.sp
.LP
To allocate an
.PN XWMHints
structure, use
.PN XAllocWMHints .
.IN "XAllocWMHints" "" "@DEF@"
.FD 0
XWMHints *XAllocWMHints\^(\|)
.FN
.LP
The
.PN XAllocWMHints
function allocates and returns a pointer to a
.PN XWMHints
structure.
Note that all fields in the
.PN XWMHints
structure are initially set to zero.
If insufficient memory is available, 
.PN XAllocWMHints
returns NULL.
To free the memory allocated to this structure,
use
.PN XFree .
.LP
The
.PN XWMHints
structure contains:
.LP
/* Window manager hints mask bits */
.TS
lw(.5i) lw(2.5i) lw(2.5i).
T{
#define
T}	T{
.PN InputHint
T}	T{
(1L << 0)
T}
T{
#define
T}	T{
.PN StateHint
T}	T{
(1L << 1)
T}
T{
#define
T}	T{
.PN IconPixmapHint
T}	T{
(1L << 2)
T}
T{
#define
T}	T{
.PN IconWindowHint
T}	T{
(1L << 3)
T}
T{
#define
T}	T{
.PN IconPositionHint
T}	T{
(1L << 4)
T}
T{
#define
T}	T{
.PN IconMaskHint
T}	T{
(1L << 5)
T}
T{
#define
T}	T{
.PN WindowGroupHint
T}	T{
(1L << 6)
T}
T{
#define
T}	T{
.PN AllHints
T}	T{
(InputHint|StateHint|IconPixmapHint|
.br
IconWindowHint|IconPositionHint|
.br
IconMaskHint|WindowGroupHint)
T}
.TE
.IN "XWMHints" "" "@DEF@"
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
/* 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;
.De
.LP
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 X10-style applications that use real-estate
driven focus, should set this member to 
.PN True .  
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 
.PN True .
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 
.PN False .
Applications that never expect any keyboard input also should set this member
to 
.PN False .
.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 
.PN True .  
Push model window managers should
make sure that pull model applications do not break them 
by resetting input focus to 
.PN PointerRoot 
when it is appropriate (for example, whenever an application whose
input member is 
.PN False 
sets input focus to one of its subwindows).
.LP
The definitions for the initial_state flag are:
.TS
lw(.5i) lw(2i) lw(.15i) lw(2.75i).
T{
#define
T}	T{
.PN WithdrawnState
T}	T{
0
T}	T{
T}
T{
#define
T}	T{
.PN NormalState
T}	T{
1
T}	T{
/* most applications start this way */
T}
T{
#define
T}	T{
.PN IconicState
T}	T{
3
T}	T{
/* application wants to start as an icon */
T}
.TE
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.
.LP
.sp
To set a window's WM_HINTS property, use
.PN XSetWMHints .
.IN "XSetWMHints" "" "@DEF@"
.FD 0
XSetWMHints\^(\^\fIdisplay\fP, \fIw\fP, \fIwmhints\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XWMHints *\fIwmhints\fP\^;

.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIwmhints\fP 1i
Specifies the 
.PN XWMHints
structure to be used.
.LP
.\" $Header: XSetWMHnts.d,v 1.1 88/02/26 10:51:06 mento Exp $
The
.PN XSetWMHints
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.
.LP
.PN XSetWMHints
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.LP
.sp
To read a window's WM_HINTS property, use
.PN XGetWMHints .
.IN "XGetWMHints" "" "@DEF@"
.FD 0
XWMHints *XGetWMHints\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.LP
.\" $Header: XGetWMHnts.d,v 1.5 88/06/11 07:51:30 mento Exp $
The
.PN XGetWMHints
function reads the window manager hints and 
returns NULL if no WM_HINTS property was set on the window 
or returns a pointer to a 
.PN XWMHints 
structure if it succeeds.
When finished with the data,
free the space used for it by calling
.PN XFree .
.LP
.PN XGetWMHints
can generate a
.PN BadWindow 
error.
.NH 3
Setting and Reading the WM_NORMAL_HINTS Property
.XS
\*(SN Setting and Reading the WM_NORMAL_HINTS Property
.XE
.LP
Xlib provides functions that you can use to set or read 
the WM_NORMAL_HINTS property for a given window.
The functions use the flags and the
.PN XSizeHints 
structure, as defined in the
.Pn < X11/Xutil.h >
header file.
.sp
.LP
To allocate an
.PN XSizeHints
structure, use
.PN XAllocSizeHints .
.IN "XAllocSizeHints" "" "@DEF@"
.FD 0
XSizeHints *XAllocSizeHints\^(\|)
.FN
.LP
The
.PN XAllocSizeHints
function allocates and returns a pointer to a
.PN XSizeHints
structure.
Note that all fields in the
.PN XSizeHints
structure are initially set to zero.
If insufficient memory is available, 
.PN XAllocSizeHints
returns NULL.
To free the memory allocated to this structure,
use
.PN XFree .
.LP
The
.PN XSizeHints
structure contains:
.LP
/* Size hints mask bits */
.TS
lw(.5i) lw(1.25i) lw(.75i) lw(3.25i).
T{
#define
T}	T{
.PN USPosition
T}	T{
(1L << 0)
T}	T{
/* user specified x, y */
T}
T{
#define
T}	T{
.PN USSize
T}	T{
(1L << 1)
T}	T{
/* user specified width, height */
T}
T{
#define
T}	T{
.PN PPosition
T}	T{
(1L << 2)
T}	T{
/* program specified position */
T}
T{
#define
T}	T{
.PN PSize
T}	T{
(1L << 3)
T}	T{
/* program specified size */
T}
T{
#define
T}	T{
.PN PMinSize
T}	T{
(1L << 4)
T}	T{
/* program specified minimum size */
T}
T{
#define
T}	T{
.PN PMaxSize
T}	T{
(1L << 5)
T}	T{
/* program specified maximum size */
T}
T{
#define
T}	T{
.PN PResizeInc
T}	T{
(1L << 6)
T}	T{
/* program specified resize increments */
T}
T{
#define
T}	T{
.PN PAspect
T}	T{
(1L << 7)
T}	T{
/* program specified min and max aspect ratios */
T}
T{
#define
T}	T{
.PN PBaseSize
T}	T{
(1L << 8)
T}
T{
#define
T}	T{
.PN PWinGravity
T}	T{
(1L << 9)
T}
T{
#define
T}	T{
.PN PAllHints
T}	T{
T}	T{
(PPosition|PSize|PMinSize|PMaxSize|
.br
PResizeInc|PAspect)
T}
.TE
.IN "XSizeHints" "" "@DEF@"
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
/* 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;
} XSizeHints;
.De
.LP
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 win_gravity member defines the region of the window that is to be retained
when it is resized.
.LP
Note that use of the
.PN PAllHints
macro is highly discouraged.
.sp
.LP
To set a window's WM_NORMAL_HINTS property, use
.PN XSetWMNormalHints .
.IN "XSetWMNormalHints" "" "@DEF@"
.FD 0
void XSetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIhints\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIhints\fP 1i
Specifies the size hints for the window in its normal state.
.LP
The 
.PN XSetWMNormalHints 
function replaces the size hints for the WM_NORMAL_HINTS property 
on the specified window.
If the property does not already exist,
.PN XSetWMNormalHints
sets the size hints for the WM_NORMAL_HINTS property on the specified window.
The property is stored with a type of WM_SIZE_HINTS and a format of 32.
.LP
.PN XSetWMNormalHints
can generate
.PN BadAlloc
and
.PN BadWindow
errors.
.sp
.LP
To read a window's WM_NORMAL_HINTS property, use
.PN XGetWMNormalHints .
.IN "XGetWMNormalHints" "" "@DEF@"
.FD 0
Status XGetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \
\fIsupplied_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIhints_return\fP\^;
.br
      long *\fIsupplied_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIhints_return\fP 1i
Returns the size hints for the window in its normal state.
.IP \fIsupplied_return\fP 1i
Returns the hints that were supplied by the user.
.LP
The 
.PN XGetWMNormalHints 
function returns the size hints stored in the WM_NORMAL_HINTS property 
on the specified window.
If the property is of type WM_SIZE_HINTS, of format 32,
and is long enough to contain either an old (pre-ICCCM) 
or new size hints structure, 
.PN XGetWMNormalHints
sets the various fields of the 
.PN XSizeHints
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 non-zero status.
Otherwise, it returns a zero status.
.LP
If 
.PN XGetWMNormalHints
returns successfully and a pre-ICCCM size hints property is read, 
the supplied_return argument will contain the following bits:
.LP
.Ds
(USPosition|USSize|PPosition|PSize|PMinSize|
 PMaxSize|PResizeInc|PAspect)
.De
.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:
.LP
.Ds
PBaseSize|PWinGravity
.De
.LP
.PN XGetWMNormalHints
can generate a
.PN BadWindow
error.
.sp
.LP
To set a window's WM_SIZE_HINTS property, use
.PN XSetWMSizeHints .
.IN "XSetWMSizeHints" "" "@DEF@"
.FD 0
void XSetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIhints\fP\^;
.br
      Atom \fIproperty\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIhints\fP 1i
Specifies the
.PN XSizeHints
structure to be used.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
The 
.PN XSetWMSizeHints 
function replaces the size hints for the specified property 
on the named window.
If the specified property does not already exist,
.PN XSetWMSizeHints
sets the size hints for the specified property
on the named window.
The property is stored with a type of WM_SIZE_HINTS and a format of 32.
To set a window's normal size hints, 
you can use the 
.PN XSetWMNormalHints
function.
.LP
.PN XSetWMSizeHints
can generate
.PN BadAlloc ,
.PN BadAtom , 
and 
.PN BadWindow
errors.
.sp
.LP
To read a window's WM_SIZE_HINTS property, use
.PN XGetWMSizeHints .
.IN "XGetWMSizeHints" "" "@DEF@"
.FD 0
Status XGetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \
\fIsupplied_return\fP, \fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIhints_return\fP\^;
.br
      long *\fIsupplied_return\fP\^;
.br
      Atom \fIproperty\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIhints_return\fP 1i
Returns the
.PN XSizeHints
structure.
.IP \fIsupplied_return\fP 1i
Returns the hints that were supplied by the user.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
The 
.PN XGetWMSizeHints
function returns the size hints stored in the specified property 
on the named window.
If the property is of type WM_SIZE_HINTS, of format 32, 
and is long enough to contain either an old (pre-ICCCM) 
or new size hints structure, 
.PN XGetWMSizeHints
sets the various fields of the 
.PN XSizeHints
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 non-zero status.
Otherwise, it returns a zero status.
To get a window's normal size hints, 
you can use the 
.PN XGetWMNormalHints 
function.
.LP
If 
.PN XGetWMSizeHints
returns successfully and a pre-ICCCM size hints property is read, 
the supplied_return argument will contain the following bits:
.LP
.Ds
(USPosition|USSize|PPosition|PSize|PMinSize|
 PMaxSize|PResizeInc|PAspect)
.De
.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:
.LP
.Ds
PBaseSize|PWinGravity
.De
.LP
.PN XGetWMSizeHints
can generate
.PN BadAtom 
and 
.PN BadWindow
errors.
.NH 3
Setting and Reading the WM_CLASS Property
.XS
\*(SN Setting and Reading the WM_CLASS Property
.XE
.LP
Xlib provides functions that you can use to set and get 
the WM_CLASS property for a given window.
These functions use the
.PN XClassHint 
structure, which is defined in 
.Pn < X11/Xutil.h >.
.sp
.LP
To allocate an
.PN XClassHint
structure, use
.PN XAllocClassHint .
.IN "XAllocClassHint" "" "@DEF@"
.FD 0
XClassHint *XAllocClassHint\^(\|)
.FN
.LP
The
.PN XAllocClassHint
function allocates and returns a pointer to a
.PN XClassHint
structure.
Note that the pointer fields in the
.PN XClassHint
structure are initially set to NULL.
If insufficient memory is available, 
.PN XAllocClassHint
returns NULL.
To free the memory allocated to this structure,
use
.PN XFree .
.LP
The
.PN XClassHint
contains:
.LP
.IN "XClassHint" "" "@DEF@"
.Ds 0
.TA .5i
.ta .5i
typedef struct {
	char *res_name;
	char *res_class;
} XClassHint;
.De
.LP
The res_name member contains the application name, 
and the res_class member contains the application class. 
Note that the name set in this property may differ from the name set as WM_NAME.
That is, WM_NAME specifies what should be displayed in the title bar and,
therefore, can contain temporal information (for example, the name of
a file currently in an editor's buffer).
On the other hand, 
the name specified as part of WM_CLASS is the formal name of the application
that should be used when retrieving the application's resources from the 
resource database.
.LP
.sp
To set a window's WM_CLASS property, use
.PN XSetClassHint .
.IN "XSetClassHint" "" "@DEF@"
.FD 0
XSetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XClassHint *\fIclass_hints\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIclass_hints\fP 1i
Specifies the
.PN XClassHint
structure that is to be used.
.LP
The
.PN XSetClassHint
function sets the class hint for the specified window.
.LP
.PN XSetClassHint
can generate
.PN BadAlloc
and
.PN BadWindow
errors. 
.LP
.sp
To read a window's WM_CLASS property, use
.PN XGetClassHint .
.IN "XGetClassHint" "" "@DEF@"
.FD 0
Status XGetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP;
.br
      XClassHint *\fIclass_hints_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIclass_hints_return\fP 1i
Returns the 
.PN XClassHint
structure.
.LP
The
.PN XGetClassHint
function returns the class of the specified window.
To free res_name and res_class when finished with the strings,
use
.PN XFree .
.LP
.PN XGetClassHint
can generate a
.PN BadWindow 
error.
.NH 3
Setting and Reading the WM_TRANSIENT_FOR Property
.XS
\*(SN Setting and Reading the WM_TRANSIENT_FOR Property
.XE
.LP
Xlib provides functions that you can use to set and read
the WM_TRANSIENT_FOR property for a given window.
.LP
.sp
To set a window's WM_TRANSIENT_FOR property, use
.PN XSetTransientForHint .
.IN "XSetTransientForHint" "" "@DEF@"
.FD 0
XSetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Window \fIprop_window\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIprop_window\fP 1i
Specifies the window that the WM_TRANSIENT_FOR property is to be set to.
.LP
The
.PN XSetTransientForHint
function sets the WM_TRANSIENT_FOR property of the specified window to the 
specified prop_window.
.LP
.PN XSetTransientForHint
can generate
.PN BadAlloc
and
.PN BadWindow
errors.
.LP
.sp
To read a window's WM_TRANSIENT_FOR property, use
.PN XGetTransientForHint .
.IN "XGetTransientForHint" "" "@DEF@"
.FD 0
Status XGetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Window *\fIprop_window_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIprop_window_return\fP 1i
Returns the WM_TRANSIENT_FOR property of the specified window.
.LP
The
.PN XGetTransientForHint
function returns the WM_TRANSIENT_FOR property for the specified window.
.LP
.PN XGetTransientForHint
can generate a
.PN BadWindow 
error.
.NH 3
Setting and Reading the WM_PROTOCOLS Property
.XS
\*(SN Setting and Reading the WM_PROTOCOLS Property
.XE
.LP
Xlib provides functions that you can use to set and read
the WM_PROTOCOLS property for a given window.
.LP
.sp
To set a window's WM_PROTOCOLS property, use
.PN XSetWMProtocols .
.IN "XSetWMProtocols" "" "@DEF@"
.FD 0
Status XSetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols\fP, \
\fIcount\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Atom *\fIprotocols\fP\^;
.br
      int \fIcount\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIprotocols\fP 1i
Specifies the list of protocols.
.ds Cn protocols in the list
.IP \fIcount\fP 1i
Specifies the number of \*(Cn.
.LP
The 
.PN XSetWMProtocols 
function replaces the WM_PROTOCOLS property on the specified window 
with the list of atoms specified by the protocols argument.
If the property does not already exist,
.PN XSetWMProtocols
sets the WM_PROTOCOLS property on the specified window
to the list of atoms specified by the protocols argument.
The property is stored with a type of ATOM and a format of 32.
If it cannot intern the WM_PROTOCOLS atom, 
.PN XSetWMProtocols
returns a zero status.
Otherwise, it returns a non-zero status.
.LP
.PN XSetWMProtocols
can generate
.PN BadAlloc
and
.PN BadWindow
errors.
.sp
.LP
To read a window's WM_PROTOCOLS property, use
.PN XGetWMProtocols .
.IN "XGetWMProtocols" "" "@DEF@"
.FD 0
Status XGetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols_return\fP, \
\fIcount_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Atom **\fIprotocols_return\fP\^;
.br
      int *\fIcount_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIprotocols_return\fP 1i
Returns the list of protocols.
.ds Cn protocols in the list
.IP \fIcount_return\fP 1i
Returns the number of \*(Cn.
.LP
The 
.PN XGetWMProtocols 
function returns the list of atoms stored in the WM_PROTOCOLS property 
on the specified window.
These atoms describe window manager protocols in which the owner 
of this window is willing to participate.
If the property exists, is of type ATOM, is of format 32, 
and the atom WM_PROTOCOLS can be interned, 
.PN XGetWMProtocols
sets the protocols_return argument to a list of atoms, 
sets the count_return argument to the number of elements in list, 
and returns a a non-zero status.
Otherwise, it sets neither of the return arguments
and returns a zero status.
To release the list of atom, use
.PN XFree .
.LP
.PN XGetWMProtocols
can generate a
.PN BadWindow
error.
.NH 3
Setting and Reading the WM_COLORMAP_WINDOWS Property
.XS
\*(SN Setting and Reading the WM_COLORMAP_WINDOWS Property
.XE
.LP
Xlib provides functions that you can use to set and read
the WM_COLORMAP_WINDOWS property for a given window.
.sp
.LP
To set a window's WM_COLORMAP_WINDOWS property, use
.PN XSetWMColormapWindows .
.IN "XSetWMColormapWindows" "" "@DEF@"
.FD 0
Status XSetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \
\fIcolormap_windows\fP, \fIcount\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Window *\fIcolormap_windows\fP\^;
.br
      int \fIcount\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIcolormap_windows\fP 1i
Specifies the list of windows.
.ds Cn windows in the list
.IP \fIcount\fP 1i
Specifies the number of \*(Cn.
.LP
The 
.PN XSetWMColormapWindows 
function replaces the WM_COLORMAP_WINDOWS property on the specified
window with the list of windows specified by the colormap_windows argument.
It the property does not already exist,
.PN XSetWMColormapWindows
sets the WM_COLORMAP_WINDOWS property on the specified
window to the list of windows specified by the colormap_windows argument.
The property is stored with a type of WINDOW and a format of 32.
If it cannot intern the WM_COLORMAP_WINDOWS atom,
.PN XSetWMColormapWindows
returns a zero status.
Otherwise, it returns a non-zero status.
.LP
.PN XSetWMColormapWindows
can generate
.PN BadAlloc
and
.PN BadWindow
errors.
.sp
.LP
To read a window's WM_COLORMAP_WINDOWS property, use
.PN XGetWMColormapWindows .
.IN "XGetWMColormapWindows" "" "@DEF@"
.FD 0
Status XGetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \
\fIcolormap_windows_return\fP, \fIcount_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Window **\fIcolormap_windows_return\fP\^;
.br
      int *\fIcount_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIcolormap_windows_return\fP 1i
Returns the list of windows.
.ds Cn windows in the list
.IP \fIcount_return\fP 1i
Returns the number of \*(Cn.
.LP
The 
.PN XGetWMColormapWindows 
function returns the list of window identifiers stored 
in the WM_COLORMAP_WINDOWS property on the specified window.
These identifiers indicate the colormaps that the window manager
may need to install for this window.
If the property exists, is of type WINDOW, is of format 32, 
and the atom WM_COLORMAP_WINDOWS can be interned, 
.PN XGetWMColormapWindows
sets the windows_return argument to a list of window identifiers, 
sets the count_return argument to the number of elements in list, 
and returns a non-zero status.
Otherwise, it sets neither of the return arguments
and returns a zero status.
To release the list of window identifiers, use
.PN XFree . 
.LP
.PN XGetWMColormapWindows
can generate a
.PN BadWindow
error.
.NH 3
Setting and Reading the WM_ICON_SIZES Property
.XS
\*(SN Setting and Reading the WM_ICON_SIZES Property
.XE
.LP
Xlib provides functions that you can use to set and read 
the WM_ICON_SIZES property for a given window.
These functions use the 
.PN XIconSize 
.IN "XIconSize"
structure, which is defined in
.Pn < X11/Xutil.h >.
.sp
.LP
To allocate an
.PN XIconSize
structure, use
.PN XAllocIconSize .
.IN "XAllocIconSize" "" "@DEF@"
.FD 0
XIconSize *XAllocIconSize\^(\|)
.FN
.LP
The
.PN XAllocIconSize 
function allocates and returns a pointer to a
.PN XIconSize 
structure.
Note that all fields in the
.PN XIconSize
structure are initially set to zero.
If insufficient memory is available, 
.PN XAllocIconSize
returns NULL.
To free the memory allocated to this structure,
use
.PN XFree .
.LP
The
.PN XIconSize
structure contains:
.LP
.IN "XIconSize" "" "@DEF@"
.Ds 0
.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;
.De
.LP
The width_inc and height_inc members define an arithmetic progression of
sizes (minimum to maximum) that represent the supported icon sizes.
.LP
.sp
To set a window's WM_ICON_SIZES property, use
.PN XSetIconSizes .
.IN "XSetIconSizes" "" "@DEF@"
.FD 0
XSetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list\fP, \fIcount\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XIconSize *\fIsize_list\fP\^;
.br
      int \fIcount\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIsize_list\fP 1i
Specifies a pointer to the size list.
.IP \fIcount\fP 1i
Specifies the number of items in the size list.
.LP
.\" $Header: XSetISizes.d,v 1.2 88/06/11 07:53:16 mento Exp $
The
.PN XSetIconSizes
function is used only by window managers to set the supported icon sizes.
.LP
.PN XSetIconSizes
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.LP
.sp
To read a window's WM_ICON_SIZES property, use
.PN XGetIconSizes .
.IN "XGetIconSizes" "" "@DEF@"
.FD 0
Status XGetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list_return\fP, \fIcount_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XIconSize **\fIsize_list_return\fP\^;
.br
      int *\fIcount_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIsize_list_return\fP 1i
Returns a pointer to the size list.
.IP \fIcount_return\fP 1i
Returns the number of items in the size list.
.LP
.\" $Header: XGetISizes.d,v 1.2 88/06/11 07:51:07 mento Exp $
The
.PN XGetIconSizes
function returns zero if a window manager has not set icon sizes or nonzero
otherwise.
.PN XGetIconSizes
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
.PN XSetWMHints
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
.PN XFree .
.LP
.PN XGetIconSizes
can generate a
.PN BadWindow 
error.
.NH 3
Using Window Manager Convenience Functions
.XS
\*(SN Using Window Manager Convenience Functions
.XE
.LP
Xlib provides two additional convenience functions that you can use to:
.IP \(bu 5
Set the standard window manager properties for a given window
.IP \(bu 5
Obtain window geometry information
.sp
.LP
To set a window's standard window manager properties, use
.PN XSetWMProperties .
The standard window manager properties for a given window are
WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
WM_COMMAND, and WM_CLIENT_MACHINE.
.IN "XSetWMProperties" "" "@DEF@"
.FD 0
void XSetWMProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \
\fIicon_name\fP, \fIargv\fP, \fIargc\fP, \fInormal_hints\fP, \fIwm_hints\fP, \
\fIclass_hints\fP\^)
.br
      Display *\fIdisplay\fP\^; 
.br
      Window \fIw\fP\^;
.br
      XTextProperty *\fIwindow_name\fP\^;
.br
      XTextProperty *\fIicon_name\fP\^;
.br
      char **\fIargv\fP\^;
.br
      int \fIargc\fP\^;
.br
      XSize_hints *\fInormal_hints\fP\^;
.br
      XWMHints *\fIwm_hints\fP\^;
.br
      XClassHint *\fIclass_hints\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: window_name.a,v 1.2 88/05/18 05:22:36 mento Exp $
.IP \fIwindow_name\fP 1i
Specifies the window name,
which should be a null-terminated string.
.\" $Header: icon_name.a,v 1.2 88/05/17 11:22:33 mento Exp $
.IP \fIicon_name\fP 1i
Specifies the icon name,
which should be a null-terminated string.
.IP \fIargv\fP 1i
Specifies the application's argument list.
.IP \fIargc\fP 1i
Specifies the number of arguments.
.IP \fInormal_hints\fP 1i
Specifies the size hints for the window in its normal state.
.IP \fIwm_hints\fP 1i
Specifies the
.PN XWMHints
structure to be used.
.IP \fIclass_hints\fP 1i
Specifies the
.PN XClassHint
structure to be used.
.LP
The 
.PN XSetWMProperties 
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).
.LP
If the window_name argument is non-null, 
.PN XSetWMProperties
calls
.PN XSetWMName ,
which, in turn, sets the WM_NAME property (see section 9.1.4).
If the icon_name argument is non-null,
.PN XSetWMProperties
calls
.PN XSetWMIconName ,
which sets the WM_ICON_NAME property (see section 9.1.5).
If the argv argument is non-null, 
.PN XSetWMProperties
calls
.PN XSetCommand ,
which sets the WM_COMMAND property (see section 9.2.1).
Note that an argc of 0 is allowed to indicate a zero-length command.
Note also that the hostname of this machine is stored using
.PN XSetWMClientMachine 
(see section 9.2.2).
.LP
If the normal_hints argument is non-null, 
.PN XSetWMProperties
calls
.PN XSetWMNormalHints ,
which sets the WM_NORMAL_HINTS property (see section 9.1.7).
If the wm_hints argument is non-null, 
.PN XSetWMProperties
calls
.PN XSetWMHints ,
which sets the WM_HINTS property (see section 9.1.6).
.LP
If the class_hints argument is non-null, 
.PN XSetWMProperties
calls
.PN XSetClassHint ,
which sets the WM_CLASS property (see section 9.1.8).
If the res_name member in the
.PN XClassHint
structure is set to the null pointer and the RESOURCE_NAME environment 
variable is set, 
then 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.
.LP
.PN XSetWMProperties
can generate
.PN BadAlloc
and
.PN BadWindow
errors.
.sp
.LP
To obtain a window's geometry information, use
.PN XWMGeometry .
.IN "XWMGeometry" "" "@DEF@"
.FD 0
int XWMGeometry\^(\^\fIdisplay\fP, \fIscreen\fP, \fIuser_geom\fP, \
\fIdef_geom\fP, \fIbwidth\fP, \fIhints\fP, \fIx_return\fP, \fIy_return\fP,
.br
                \fIwidth_return\fP, \fIheight_return\fP, \fIgravity_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      int \fIscreen\fP\^;
.br
      char *\fIuser_geom\fP\^;
.br
      char *\fIdef_geom\fP\^;
.br
      unsigned int \fIbwidth\fP\^;
.br
      XSizeHints *\fIhints\fP\^;
.br
      int *\fIx_return\fP, *\fIy_return\fP\^; 
.br
      int *\fIwidth_return\fP\^;
.br
      int *\fIheight_return\fP\^;
.br
      int *\fIgravity_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.IP \fIscreen\fP 1i
Specifies the screen.
.IP \fIuser_geom\fP 1i
Specifies the user-specified geometry or NULL.
.IP \fIdef_geom\fP 1i
Specifies the application's default geometry or NULL.
.\" $Header: bwidth.a,v 1.1 88/02/26 10:05:23 mento Exp $
.IP \fIbwidth\fP 1i
Specifies the border width.
.IP \fIhints\fP 1i
Specifies the size hints for the window in its normal state.
.\" $Header: xy_ret.a,v 1.3 88/05/20 05:05:44 mento Exp $
.IP \fIx_return\fP 1i
.br
.ns
.IP \fIy_return\fP 1i
Return the x and y offsets.
.\" $Header: widtheight2.a,v 1.1 88/02/26 10:32:28 mento Exp $
.IP \fIwidth_return\fP 1i
.br
.ns
.IP \fIheight_return\fP 1i
Return the width and height determined.
.IP \fIgravity_return\fP 1i
Returns the window gravity.
.LP
The 
.PN XWMGeometry 
function combines any geometry information (given in the format used by 
.PN XParseGeometry )
specified by the user and by the calling program with size hints 
(usually the ones to be stored in WM_NORMAL_HINTS) and returns the position, 
size, and gravity
.Pn ( NorthWestGravity , 
.PN NorthEastGravity , 
.PN SouthEastGravity
or
.PN SouthWestGravity ) 
that describe the window.
If the base size is not set in the 
.PN XSizeHints
structure, 
the minimum size is used if set.
Otherwise, a base size of 0 is assumed.
If no minimum size is set in the hints structure, 
the base size is used.
A mask (in the form returned by 
.PN XParseGeometry ) 
that describes which values came from the user specification 
and whether or not the position coordinates are relative
to the right and bottom edges is returned (which will have already been
accounted for in the x_return and y_return values).
.LP
Note that invalid geometry specifications can cause a width or height of 0 
to be returned.
The caller may pass the address of the hints win_gravity field 
as gravity_return to update the hints directly.
.NH 2
Client to Session Manager Communication
.XS
\*(SN Client to Session Manager Communication
.XE
.LP
This section discusses how to:
.IP \(bu 5
Set and read the WM_COMMAND property
.IP \(bu 5
Set and read the WM_CLIENT_MACHINE_PROPERTY
.NH 3
Setting and Reading the WM_COMMAND property
.XS
\*(SN Setting and Reading the WM_COMMAND property
.XE
.LP
Xlib provides functions that you can use to set and read
the WM_COMMAND property for a given window.
.sp
.LP
To set a window's WM_COMMAND property, use
.PN XSetCommand .
.IN "XSetCommand" "" "@DEF@"
.FD 0
XSetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv\fP, \fIargc\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char **\fIargv\fP\^;
.br
      int \fIargc\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIargv\fP 1i
Specifies the application's argument list.
.IP \fIargc\fP 1i
Specifies the number of arguments.
.LP
.\" $Header: XSetCmd.d,v 1.3 88/06/11 07:53:04 mento Exp $
The
.PN XSetCommand
function sets the command and arguments used to invoke the
application.
(Typically, argv is the argv array of your main program.)
.LP
.PN XSetCommand
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.sp
.LP
To read a window's WM_COMMAND property, use
.PN XGetCommand .
.IN "XGetCommand" "" "@DEF@"
.FD 0
Status XGetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv_return\fP, \
\fIargc_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char ***\fIargv_return\fP\^;
.br
      int *\fIargc_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIargv_return\fP 1i
Returns the application's argument list.
.IP \fIargc_return\fP 1i
Returns the number of arguments returned.
.LP
The 
.PN XGetCommand 
function reads the WM_COMMAND property from the specified window 
and returns a string list.
If the WM_COMMAND property exists, 
it is of type STRING and format 8.
If sufficient memory can be allocated to contain the string list, 
.PN XGetCommand
fills in the argv_return and argc_return arguments
and returns a non-zero status.
Otherwise, it returns a zero status.
To free the memory allocated to the string list, use
.PN XFreeStringList .
.NH 3
Setting and Reading the WM_CLIENT_MACHINE property
.XS
\*(SN Setting and Reading the WM_CLIENT_MACHINE property
.XE
.LP
Xlib provides functions that you can use to set and read 
the WM_CLIENT_MACHINE property for a given window.
.sp
.LP
To set a window's WM_CLIENT_MACHINE property, use
.PN XSetWMClientMachine .
.IN "XSetWMClientMachine" "" "@DEF@"
.FD 0
void XSetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XTextProperty *\fItext_prop\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fItext_prop\fP 1i
Specifies the
.PN XTextProperty
structure to be used.
.LP
The
.PN XSetWMClientMachine
convenience function performs a
.PN XSetTextProperty
on the WM_CLIENT_MACHINE property.
Note that you also can set the client machine property by using
.PN XSetTextProperty
(see section 9.1.3).
.sp
.LP
To read a window's WM_CLIENT_MACHINE property, use
.PN XGetWMClientMachine .
.IN "XGetWMClientMachine" "" "@DEF@"
.FD 0
Status XGetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XTextProperty *\fItext_prop_return\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fItext_prop_return\fP 1i
Returns the
.PN XTextProperty
structure.
.LP
The
.PN XGetWMClientMachine
convenience function performs an 
.PN XGetTextProperty 
on the WM_CLIENT_MACHINE property.
Note that you also can read the client machine property by using
.PN XGetTextProperty
(see section 9.1.3).
.NH 2
Standard Colormaps
.XS
\*(SN Standard Colormaps 
.XE
.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.
.LP
As an example, consider a 3D 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 RGB
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 RGB triples into pixel values very quickly,
because drawing the entire sphere requires many such
conversions.
.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.
.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 (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.
.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 8 reds, 8 greens, and 4 blues, so just as
the image-processing program, it must allocate and
install a new colormap.
.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.
.LP
As another example, 
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.
.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.
.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.
.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
.LP
To allocate an
.PN XStandardColormap
structure, use
.PN XAllocStandardColormap .
.IN "XAllocStandardColormap" "" "@DEF@"
.FD 0
XStandardColormap *XAllocStandardColormap\^(\|)
.FN
.LP
The
.PN XAllocStandardColormap
function allocates and returns a pointer to a
.PN XStandardColormap
structure.
Note that all fields in the
.PN XStandardColormap
structure are initially set to zero.
If insufficient memory is available, 
.PN XAllocStandardColormap
returns NULL.
To free the memory allocated to this structure,
use
.PN XFree .
.LP
The 
.PN XStandardColormap 
structure contains:
.LP
/* Hints */
.TS
lw(.5i) lw(2i) lw(1i).
T{
#define
T}	T{
.PN ReleaseByFreeingColormap
T}	T{
( (XID) 1L)
T}
.TE
/* Values */
.IN "XStandardColormap" "" "@DEF@"
.Ds 0
.TA .5i 2.5i
.ta .5i 2.5i
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;
.De
.LP
The colormap member is the colormap created by the
.PN XCreateColormap
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.
.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.
.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 
.PN XAllocColorPlanes
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:
.LP
.Ds
.TA .5i 1.5i
.ta .5i 1.5i
r * red_mult + g * green_mult + b * blue_mult + base_pixel
.De
.LP
For 
.PN GrayScale
colormaps, 
only the colormap, red_max, red_mult, 
and base_pixel members are defined. 
The other members are ignored.  
.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
.PN XKillClient
function on the indicated resource.
(Note that this method is necessary for allocating out of an existing colormap).
.LP
To compute a 
.PN GrayScale 
pixel value, use the following expression:
.LP
.Ds
.TA .5i 1.5i
.ta .5i 1.5i
gray * red_mult + base_pixel
.De
.LP
The properties containing the 
.PN XStandardColormap 
information have 
the type RGB_COLOR_MAP.
.LP
The remainder of this section discusses standard colormap properties and atoms
as well as how to manipulate standard colormaps.
.NH 3
Standard Colormap Properties and Atoms
.XS
\*(SN Standard Colormap Properties and Atoms 
.XE
.LP
.IN "Standard Colormaps"
.IN "colormaps" "standard"
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
.Pn < X11/Xatom.h >
header file contains the definitions for each of the following atoms,
which are prefixed with XA_.
.IP RGB_DEFAULT_MAP 5
This atom names a property.
The value of the property is an 
.PN XStandardColormap .
Note that this property may contain more than one colormap description.
.IP
The property defines an RGB subset of the default colormap of the screen.
Some applications only need a few RGB 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.
.IP
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.
.IP RGB_BEST_MAP 5
.br
This atom names a property.
The value of the property is an 
.PN XStandardColormap .
.IP 
The property defines the best RGB colormap available on
the screen.
(Of course, this is a subjective evaluation.)
Many image processing and 3D 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.
.IP
On an 8-plane 
.PN PseudoColor 
display, 
RGB_BEST_MAP should be a 3/3/2 allocation.  
On a 24-plane 
.PN DirectColor 
display, 
RGB_BEST_MAP should be an 8/8/8 allocation.  
On other displays, 
the RGB_BEST_MAP allocation is purely up to the implementor of the display.
.IP RGB_RED_MAP 5
.br
.ns
.IP RGB_GREEN_MAP 5
.br
.ns
.IP RGB_BLUE_MAP 5
These atoms name properties.
The value of each property is an
.PN XStandardColormap . 
.IP
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.
.IP RGB_GRAY_MAP 5
This atom names a property.
The value of the property is an 
.PN XStandardColormap .
.IP
The property describes the best 
.PN GrayScale 
colormap available on the screen.  
As previously mentioned, 
only the colormap, red_max, red_mult, and base_pixel members of the
.PN XStandardColormap 
structure are used for 
.PN GrayScale 
colormaps.
.NH 3
Setting and Obtaining Standard Colormaps
.XS
\*(SN Setting and Obtaining Standard Colormaps
.XE
.LP
Xlib provides functions that you can use to set and obtain an
.PN XStandardColormap
structure.
.sp
.LP
To set an
.PN XStandardColormap
structure, use
.PN XSetRGBColormaps .
.IN "XSetRGBColormaps" "" "@DEF@"
.FD 0
void XSetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap\fP, \
\fIcount\fP, \fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XStandardColormap *\fIstd_colormap\fP\^;
.br
      int \fIcount\fP\^;
.br
      Atom \fIproperty\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIstd_colormap\fP 1i
Specifies the
.PN XStandardColormap
structure to be used.
.ds Cn colormaps
.IP \fIcount\fP 1i
Specifies the number of \*(Cn.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
The 
.PN XSetRGBColormaps 
function replaces the RGB colormap definition in the specified property 
on the named window.
If the property does not already exist,
.PN XSetRGBColormaps
sets the RGB 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 ICCCM
restriction that only RGB_DEFAULT_MAP contain more than one definition.
.LP
.PN XSetRGBColormaps
can generate
.PN BadAlloc ,
.PN BadAtom ,
and
.PN BadWindow
errors.
.LP
To obtain the 
.PN XStandardColormap 
structure associated with the specified property, use
.PN XGetRGBColormaps .
.IN "XGetRGBColormaps" "" "@DEF@"
.FD 0
Status XGetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap_return\fP, \
\fIcount_return\fP, \fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XStandardColormap **\fIstd_colormap_return\fP\^;
.br
      int *\fIcount_return\fP\^;
.br
      Atom \fIproperty\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIstd_colormap_return\fP 1i
Returns the
.PN XStandardColormap
structure.
.ds Cn colormaps
.IP \fIcount_return\fP 1i
Returns the number of \*(Cn.
.\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
The 
.PN XGetRGBColormaps
function returns the RGB 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 (if the visualid is not
present, 
.PN XGetRGBColormaps 
assumes the default visual for the screen on which the window is
located; if the killid is not present, 
.PN None , 
which indicates that the resources cannot be released, is assumed), 
.PN XGetRGBColormaps
allocates and fills in space for the returned colormaps, 
and returns a non-zero status.
Otherwise, 
none of the fields are set, and 
.PN XGetRGBColormaps
returns a zero status.
Note that it is the caller's responsibility to honor the ICCCM
restriction that only RGB_DEFAULT_MAP contain more than one definition.
.LP
.PN XGetRGBColormaps
can generate
.PN BadAtom
and
.PN BadWindow
errors.
.bp
