.\".U7
.\".UT "Predefined Property Functions" 9
\&
.sp 1
.ce 3
\s+1\fBChapter 9\fP\s-1

\s+1\fBPredefined Property 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: Predefined Property Functions 
.XE
There are a number of predefined properties for information commonly
associated with windows.
The atoms for these predefined properties can be found in 
.Pn < X11/Xatom.h >,
where the prefix XA_ is added to each atom name.
.LP
Xlib provides functions that you can use to perform 
operations on predefined properties. 
This chapter discusses how to:
.IP \(bu 5
Communicate with window managers
.IP \(bu 5
Manipulate standard colormaps
.NH 2
Communicating with Window Managers
.XS
\*(SN Communicating with Window Managers 
.XE
.LP
This section discusses a set of properties and functions that are
necessary for clients to communicate effectively with window managers.
Some of these properties have complex structures.
Because all the data in a single property on the server has to be of the same 
format (8-bit, 16-bit, or 32-bit) 
and because the C structures representing property 
types cannot be guaranteed to be uniform in the same way,
Set and Get functions are provided for properties with complex structures.
.LP
These functions define but do not enforce minimal policy among window
managers.
Writers of window managers are urged to use the information in these
properties rather than invent their own properties and types.
A window manager writer, however, can define additional properties
beyond this least common denominator.
.LP
In addition to Set and Get functions for individual properties, Xlib
includes one function,
.PN XSetStandardProperties ,
that sets all or portions of several properties.
Applications are encouraged to provide the window manager 
more information than is possible with
.PN XSetStandardProperties .
To do so, 
they should call the Set functions for the additional 
or specific properties that they need.
.LP
To work well with most window managers, every
application should specify the following information:
.IP \(bu 5
Name of the application
.IP \(bu 5
Name to be used in the icon
.IP \(bu 5
Command used to invoke the application
.IP \(bu 5
Size and window manager hints
.LP
Xlib does not set defaults for the properties described in this section.
Thus, the default behavior is determined by the window manager and may be
based on the presence or absence of certain properties.
All the properties are considered to be hints to a window manager.
When implementing window management policy, a window manager determines
what to do with this information and can ignore it.
.ne 10
.LP
The supplied properties are:
.IN "Atom" "predefined"
.TS H
lw(1.4i) lw(1.2i) lw(.4i) lw(2.25i)
lw(1.4i) lw(1.2i) cw(.4i) lw(2.25i).
_
.sp 6p
.B
Name	Type	Format	Description
.sp 6p
_
.TH
.R
T{
\s-1WM_NAME\s+1
T}	T{
\s-1STRING\s+1
T}	T{
8
T}	T{
Name of the application.
T}
.sp 6p
T{
\s-1WM_ICON_NAME\s+1
T}	T{
\s-1STRING\s+1
T}	T{
8
T}	T{
Name to be used in icon.
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_ZOOM_HINTS\s+1
T}	T{
\s-1WM_SIZE_HINTS\s+1
T}	T{
32
T}	T{
Size hints for a zoomed window.
The C type of this property is 
.PN XSizeHints .
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_COMMAND\s+1
T}	T{
\s-1STRING\s+1
T}	T{
8
T}	T{
The command and arguments, separated by ASCII nulls, used to invoke the
application.
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_CLASS\s+1
T}	T{
\s-1STRING\s+1
T}	T{
32
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_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, is not really a normal application
window.
T}
_
.TE
.LP
The atom names stored in 
.Pn < X11/Xatom.h >
are named XA_\fIPROPERTY\fP_\fINAME\fP.
.LP
Xlib provides functions that you can use to set and get predefined
properties.  
Note that calling the Set function for a property with complex structure
redefines all members in that property, even though only some of those members
may have a specified new value.
Simple properties for which Xlib does not provide a Set or Get function
can be set by using
.PN XChangeProperty ,
and their values can be retrieved using
.PN XGetWindowProperty .
The remainder of this section discusses how to:
.IP \(bu 5
Set standard properties
.IP \(bu 5
Set and get the name of a window
.IP \(bu 5
Set and get the icon name of a window
.IP \(bu 5
Set the command and arguments of the application
.IP \(bu 5
Set and get window manager hints
.IP \(bu 5
Set and get window size hints
.IP \(bu 5
Set and get icon size hints
.IP \(bu 5
Set and get the class of a window
.IP \(bu 5
Set and get the transient property for a window
.IP
.NH 3
Setting Standard Properties
.XS
\*(SN Setting Standard Properties 
.XE
.LP
To specify a minimum set of properties describing the ``quickie'' application,
use
.PN XSetStandardProperties .
This function sets all or portions of the 
WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, and WM_NORMAL_HINTS properties.
.IN "XSetStandardProperties" "" "@DEF@"
.FD 0
XSetStandardProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \fIicon_name\fP, \fIicon_pixmap\fP, \fIargv\fP, \fIargc\fP, \fIhints\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char *\fIwindow_name\fP\^;
.br
      char *\fIicon_name\fP\^;
.br
      Pixmap \fIicon_pixmap\fP\^;
.br
      char **\fIargv\fP\^;
.br
      int \fIargc\fP\^;
.br
      XSizeHints *\fIhints\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIwindow_name\fP 1i
Specifies the window name,
which should be a null-terminated string.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIicon_name\fP 1i
Specifies the icon name,
which should be a null-terminated string.
.IP \fIicon_pixmap\fP 1i
Specifies the bitmap that is to be used for the icon or
.PN None .
.IP \fIargv\fP 1i
Specifies the application's argument list.
.IP \fIargc\fP 1i
Specifies the number of arguments.
.IP \fIhints\fP 1i
Specifies a pointer to the size hints for the window in its normal state.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XSetStandardProperties
function provides a means by which simple applications set the
most essential properties with a single call.
.PN XSetStandardProperties
should be used to give a window manager some information about 
your program's preferences. 
It should not be used by applications that need
to communicate more information than is possible with
.PN XSetStandardProperties .
(Typically, argv is the argv array of your main program.)
.LP
.ds fd .PN XSetStandardProperties
\*(fd
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.NH 3
Setting and Getting Window Names
.XS
\*(SN Setting and Getting Window Names 
.XE
.LP
Xlib provides functions that you can use to set and read the name of a window.
These functions set and read the WM_NAME property.
.LP
.sp
To assign a name to a window, use
.PN XStoreName .
.IN "Window" "name"
.IN "XStoreName" "" "@DEF@"
.FD 0
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
XStoreName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char *\fIwindow_name\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIwindow_name\fP 1i
Specifies the window name,
which should be a null-terminated string.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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
.ds fd .PN XStoreName
\*(fd
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: CH09,v 1.1 88/10/21 17:59:07 rws 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIwindow_name_return\fP 1i
Returns a pointer to the window name, which is a null-terminated string.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XFetchName
function returns the name of the specified window.
If it succeeds,
it returns nonzero; 
otherwise, if no name has been set for the window,
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
.ds fd .PN XFetchName
\*(fd 
can generate a
.PN BadWindow 
error.
.NH 3
Setting and Getting Icon Names
.XS
\*(SN Setting and Getting Icon Names 
.XE
.LP
Xlib provides functions that you can use to set and read 
the name to be displayed in a window's icon.  
These functions set and read the WM_ICON_NAME property.
.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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
XSetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      char *\fIicon_name\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIicon_name\fP 1i
Specifies the icon name,
which should be a null-terminated string.
.LP
.ds fd .PN XSetIconName
\*(fd
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: CH09,v 1.1 88/10/21 17:59:07 rws 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIicon_name_return\fP 1i
Returns a pointer to the window's icon name,
which is a null-terminated string.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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
.ds fd .PN XGetIconName
\*(fd 
can generate a
.PN BadWindow 
error.
.NH 3
Setting the Command
.XS
\*(SN Setting the Command
.XE
.LP
To set the command property, use
.PN XSetCommand .
This function sets the WM_COMMAND property.
.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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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: CH09,v 1.1 88/10/21 17:59:07 rws 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
.ds fd .PN XSetCommand
\*(fd
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.NH 3
Setting and Getting Window Manager Hints
.XS
\*(SN Setting and Getting Window Manager Hints 
.XE
.LP
The functions discussed in this section set and read the WM_HINTS property
and use the flags and the
.PN XWMHints 
structure, as defined in the
.Pn < X11/Xutil.h >
header file:
.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 DontCareState
T}	T{
0
T}	T{
/* don't know or care */
T}
T{
#define
T}	T{
.PN NormalState
T}	T{
1
T}	T{
/* most applications start this way */
T}
T{
#define
T}	T{
.PN ZoomState
T}	T{
2
T}	T{
/* application wants to start zoomed */
T}
T{
#define
T}	T{
.PN IconicState
T}	T{
3
T}	T{
/* application wants to start as an icon */
T}
T{
#define
T}	T{
.PN InactiveState
T}	T{
4
T}	T{
/* application believes it is seldom used;
.br
   some wm's may put it on inactive menu */
T}
.TE
The icon_mask specifies which pixels of the icon_pixmap should be used as the
icon.  
This allows for nonrectangular icons.
Both the 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 the window manager hints for a window, 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIwmhints\fP 1i
Specifies a pointer to the window manager hints.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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
.ds fd .PN XSetWMHints
\*(fd
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.LP
.sp
To read the window manager hints for a window, use
.PN XGetWMHints .
.IN "XGetWMHints" "" "@DEF@"
.FD 0
XWMHints *XGetWMHints\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XGetWMHints
function reads the window manager hints and 
returns NULL if no WM_HINTS property was set on the window 
or 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
.ds fd .PN XGetWMHints
\*(fd 
can generate a
.PN BadWindow 
error.
.NH 3
Setting and Getting Window Sizing Hints
.XS
\*(SN Setting and Getting Window Sizing Hints 
.XE
.LP
Xlib provides functions that you can use to set or get window sizing hints.
.LP
The functions discussed in this section use the flags and the
.PN XSizeHints 
structure, as defined in the
.Pn < X11/Xutil.h >
header file:
.LP
/* Size hints mask bits */
.TS
lw(.5i) lw(1.5i) 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 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;
	int width, height;
	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;
} XSizeHints;
.De
.LP
The x, y, width, and height members describe a desired position and size
for the window.
To indicate that this information was specified by the user, set the
.PN USPosition
and
.PN USSize
flags. 
To indicate that it was specified by the application without any user
involvement, set 
.PN PPosition
and 
.PN PSize .
This lets a window manager know that the user specifically asked where
the window should be placed or how the window should be sized and that
the window manager does not have to rely on the program's opinion.
.LP
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.
.LP
.sp
The next two functions set and read the WM_NORMAL_HINTS property.
.LP
To set the size hints for a given window in its normal state, use
.PN XSetNormalHints .
.IN "XSetNormalHints" "" "@DEF@"
.FD 0
XSetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIhints\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIhints\fP 1i
Specifies a pointer to the size hints for the window in its normal state.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XSetNormalHints
function sets the size hints structure for the specified window.
Applications use
.PN XSetNormalHints
to inform the window manager of the size
or position desirable for that window.
In addition, 
an application that wants to move or resize itself should call
.PN XSetNormalHints
and specify its new desired location and size
as well as making direct Xlib calls to move or resize.  
This is because window managers may ignore redirected
configure requests, but they pay attention to property changes.
.LP
To set size hints, 
an application not only must assign values to the appropriate members
in the hints structure but also must set the flags member of the structure 
to indicate which information is present and where it came from.  
A call to
.PN XSetNormalHints
is meaningless, unless the flags member is set to indicate which members of
the structure have been assigned values.
.LP
.ds fd .PN XSetNormalHints
\*(fd
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.LP
.sp
To return the size hints for a window in its normal state, use
.PN XGetNormalHints .
.IN "XGetNormalHints" "" "@DEF@"
.FD 0
Status XGetNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIhints_return\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIhints_return\fP 1i
Returns the size hints for the window in its normal state.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XGetNormalHints
function returns the size hints for a window in its normal state.
It returns a nonzero status if it succeeds or zero if
the application specified no normal size hints for this window.
.LP
.ds fd .PN XGetNormalHints
\*(fd 
can generate a
.PN BadWindow 
error.
.LP
.sp
The next two functions set and read the WM_ZOOM_HINTS property.
.LP
To set the zoom hints for a window, use
.PN XSetZoomHints .
.IN "XSetZoomHints" "" "@DEF@"
.FD 0
XSetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIzhints\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIzhints\fP 1i
Specifies a pointer to the zoom hints.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
Many window managers think of windows in one of three states:
iconic, normal, or zoomed.
The
.PN XSetZoomHints
function provides the window manager with information for the window in the
zoomed state.
.LP
.ds fd .PN XSetZoomHints
\*(fd
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.LP
.sp
To read the zoom hints for a window, use
.PN XGetZoomHints .
.IN "XGetZoomHints" "" "@DEF@"
.FD 0
Status XGetZoomHints\^(\^\fIdisplay\fP, \fIw\fP, \fIzhints_return\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIzhints_return\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIzhints_return\fP 1i
Returns the zoom hints.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XGetZoomHints
function returns the size hints for a window in its zoomed state.
It returns a nonzero status if it succeeds or zero if
the application specified no zoom size hints for this window.
.LP
.ds fd .PN XGetZoomHints
\*(fd 
can generate a
.PN BadWindow 
error.
.LP
.sp
To set the value of any property of type WM_SIZE_HINTS, use
.PN XSetSizeHints .
.IN "XSetSizeHints" "" "@DEF@"
.FD 0
XSetSizeHints\^(\^\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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIhints\fP 1i
Specifies a pointer to the size hints.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XSetSizeHints
function sets the
.PN XSizeHints
structure for the named property and the specified window.
This is used by
.PN XSetNormalHints
and
.PN XSetZoomHints ,
and can be used to set the value of any property of type WM_SIZE_HINTS.
Thus, it may be useful if other properties of that type get defined.
.LP
.ds fd .PN XSetSizeHints
\*(fd
can generate
.PN BadAlloc ,
.PN BadAtom ,
and
.PN BadWindow 
errors.
.LP
.sp
To read the value of any property of type WM_SIZE_HINTS, use
.PN XGetSizeHints .
.IN "XGetSizeHints" "" "@DEF@"
.FD 0
Status XGetSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XSizeHints *\fIhints_return\fP\^;
.br
      Atom \fIproperty\fP\^;
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIhints_return\fP 1i
Returns the size hints.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.PN XGetSizeHints
returns the
.PN XSizeHints
structure for the named property and the specified window.
This is used by
.PN XGetNormalHints
and
.PN XGetZoomHints .
It also can be used to retrieve the value of any property of type
WM_SIZE_HINTS.
Thus, it may be useful if other properties of that type get defined.
.PN XGetSizeHints
returns a nonzero status if a size hint was defined
or zero otherwise.
.LP
.ds fd .PN XGetSizeHints
\*(fd
can generate
.PN BadAtom
and 
.PN BadWindow 
errors.
.NH 3
Setting and Getting Icon Size Hints
.XS
\*(SN Setting and Getting Icon Size Hints 
.XE
.LP
Applications can cooperate with window managers by providing
icons in sizes supported by a window manager.  To communicate the supported
icon sizes to the applications, a window manager should set the icon size
property on the root window of the screen.
To find out what icon sizes a window manager supports, 
applications should read the icon size property from the root window 
of the screen.
.LP
The functions discussed in this section set or read the WM_ICON_SIZE property.
In addition, they use the 
.PN XIconSize 
.IN "XIconSize"
structure, which is defined in
.Pn < X11/Xutil.h >
and 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 the icon size hints for a window, 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XSetIconSizes
function is used only by window managers to set the supported icon sizes.
.LP
.ds fd .PN XSetIconSizes
\*(fd
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.LP
.sp
To return the icon sizes hints for a window, 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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: CH09,v 1.1 88/10/21 17:59:07 rws 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
.ds fd .PN XGetIconSizes
\*(fd 
can generate a
.PN BadWindow 
error.
.NH 3
Setting and Getting the Class of a Window
.XS
\*(SN Setting and Getting the Class of a Window 
.XE
.LP
Xlib provides functions to set and get the class of a window.
These functions set and read the WM_CLASS property.
In addition, they use the
.PN XClassHint 
structure, which is defined in 
.Pn < X11/Xutil.h >
and 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 the class of a window, 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIclass_hints\fP 1i
Specifies a pointer to a
.PN XClassHint
structure that is to be used.
.LP
The
.PN XSetClassHint
function sets the class hint for the specified window.
.LP
.ds fd .PN XSetClassHint
\*(fd
can generate
.PN BadAlloc
and
.PN BadWindow
errors. 
.LP
.sp
To get the class of a window, 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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
.ds fd .PN XGetClassHint
\*(fd 
can generate a
.PN BadWindow 
error.
.NH 3
Setting and Getting the Transient Property
.XS
\*(SN Setting and Getting the Transient Property 
.XE
.LP
An application may want to indicate to the window manager that a transient,
top-level window (for example, a dialog box) is operating on behalf of 
(or is transient for) another window.
To do so,
the application would set the WM_TRANSIENT_FOR
property of the dialog box to be the window ID of its main window.
Some window managers use this information to unmap an application's 
dialog boxes (for example, when the main application window gets iconified).
.LP
The functions discussed in this section set and read the WM_TRANSIENT_FOR
property.
.LP
.sp
To set the WM_TRANSIENT_FOR property for a window, 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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
.ds fd .PN XSetTransientForHint
\*(fd
can generate
.PN BadAlloc
and
.PN BadWindow 
errors.
.LP
.sp
To get the WM_TRANSIENT_FOR value for a window, 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: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws 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
.ds fd .PN XGetTransientForHint
\*(fd 
can generate a
.PN BadWindow 
error.
.NH 2
Manipulating Standard Colormaps
.XS
\*(SN Manipulating 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.  
He invokes 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.
.NH 3
Standard Colormaps
.XS
\*(SN Standard Colormaps 
.XE
.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.
If the standard colormaps do not exist,
you should create them by opening a new connection,
creating the properties, and setting the close-down mode of the connection to
.PN RetainPermanent .
.LP
The 
.PN XStandardColormap 
structure contains:
.LP
.IN "XStandardColormap" "" "@DEF@"
.Ds 0
.TA .5i 1.5i
.ta .5i 1.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;
} XStandardColormap;
.De
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
For 
.PN GrayScale
colormaps, 
only the colormap, red_max, red_mult, 
and base_pixel members are defined. 
The other members are ignored.  
.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
The properties containing the 
.PN XStandardColormap 
information have 
the type RGB_COLOR_MAP.
.NH 3
Standard Colormap Properties and Atoms
.XS
\*(SN Standard Colormap Properties and Atoms 
.XE
.LP
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 .
.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
Getting and Setting an XStandardColormap Structure
.XS
\*(SN Getting and Setting an XStandardColormap Structure 
.XE
.LP
To get the 
.PN XStandardColormap 
structure associated with one of the described atoms, use
.PN XGetStandardColormap .
.IN "XGetStandardColormap" "" "@DEF@"
.FD 0
Status XGetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap_return\fP, \fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XStandardColormap *\fIcolormap_return\fP\^;
.br
      Atom \fIproperty\fP\^;	/* RGB_BEST_MAP, etc. */
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIcolormap_return\fP 1i
Returns the colormap associated with the specified atom.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XGetStandardColormap
function returns the colormap definition associated with the atom supplied
as the property argument.
For example,
to fetch the standard
.PN GrayScale
colormap for a display,
you use
.PN XGetStandardColormap
with the following syntax:
.LP
.Ds 0
.TA .5i 1.5i
.ta .5i 1.5i
XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP);
.De
.LP
Once you have fetched a standard colormap,
you can use it to convert RGB values into pixel values.
For example, given an
.PN XStandardColormap
structure
and floating-point RGB coefficients in the range 0.0 to 1.0,
you can compose pixel values with the following C expression:
.LP
.Ds 0
.TA .5i 1.5i
.ta .5i 1.5i
pixel = base_pixel
.br
	+ ((unsigned long) (0.5 + r * red_max)) * red_mult
.br
	+ ((unsigned long) (0.5 + g * green_max)) * green_mult
.br
	+ ((unsigned long) (0.5 + b * blue_max)) * blue_mult;
.De
.LP
The use of addition rather than logical OR for composing pixel
values permits allocations where the RGB value is not aligned
to bit boundaries.
.LP
.ds fd .PN XGetStandardColormap
\*(fd
can generate
.PN BadAtom
and
.PN BadWindow 
errors.
.LP
.sp
To set a standard colormap, use
.PN XSetStandardColormap .
.IN "XSetStandardColormap" "" "@DEF@"
.FD 0
XSetStandardColormap(\^\fIdisplay\fP, \fIw\fP, \fIcolormap\fP, \fIproperty\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      XStandardColormap *\fIcolormap\fP\^;
.br
      Atom \fIproperty\fP\^;	/* RGB_BEST_MAP, etc. */
.FN
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIcolormap\fP 1i
Specifies the colormap.
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
.IP \fIproperty\fP 1i
Specifies the property name.
.LP
.\" $Header: CH09,v 1.1 88/10/21 17:59:07 rws Exp $
The
.PN XSetStandardColormap
function usually is only used by window managers.  
To create a standard colormap, 
follow this procedure:
.IP 1. 5
Open a new connection to the same server.
.IP 2. 5
Grab the server.
.IP 3. 5
See if the property is on the property list of the root window for the screen.
.IP 4. 5
If the desired property is not present:
.RS
.IP \(bu 5
Create a colormap (not required for RGB_DEFAULT_MAP)
.IP \(bu 5
Determine the color capabilities of the display.
.IP \(bu 5
Call 
.PN XAllocColorPlanes
or 
.PN XAllocColorCells
to allocate cells in the colormap.
.IP \(bu 5
Call 
.PN XStoreColors
to store appropriate color values in the colormap.
.IP \(bu 5
Fill in the descriptive members in the 
.PN XStandardColormap
structure.
.IP \(bu 5
Attach the property to the root window.
.IP \(bu 5
Use
.PN XSetCloseDownMode
to make the resource permanent.
.RE
.IP 5. 5
Ungrab the server.
.LP
.ds fd .PN XSetStandardColormap
\*(fd
can generate
.PN BadAlloc ,
.PN BadAtom ,
and
.PN BadWindow 
errors.
.bp
