diff options
Diffstat (limited to 'libX11/specs/libX11/CH14')
| -rw-r--r-- | libX11/specs/libX11/CH14 | 3590 |
1 files changed, 3590 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH14 b/libX11/specs/libX11/CH14 new file mode 100644 index 000000000..34c09da8b --- /dev/null +++ b/libX11/specs/libX11/CH14 @@ -0,0 +1,3590 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 14\fP\s-1 + +\s+1\fBInter-Client Communication Functions\fP\s-1 +.sp 2 +.nr H1 14 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 14: Inter-Client Communication Functions +.XE +The \fIInter-Client Communication Conventions Manual\fP, +hereafter referred to as the 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 are ICCCM compliant. +The predefined atoms for some of these properties are defined in the +.hN 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.3. +.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.5 and 16.6). +The functions discussed in this chapter provide +the primary programming interfaces by which client applications communicate +with their window and session managers as well as share standard colormaps. +.LP +The standard properties that are of special interest for communicating +with window and session managers are: +.IN "Atom" "predefined" +.TS H +lw(2i) lw(1.1i) lw(.4i) lw(2.25i) +lw(2i) lw(1.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{ +The list of window IDs that may need a different colormap +from 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, null-separated, 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 the 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{ +The name to be used in an 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{ +The 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 +.XS +\*(SN Client to Window Manager Communication +.XE +.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 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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +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) +and a window of w +to the root window of the specified screen +with an event mask set to +.PN SubstructureNotifyMask | +.PN SubstructureRedirectMask . +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. +.sp +.LP +To request that a top-level window be withdrawn, use +.PN XWithdrawWindow . +.IN "XWithdrawWindow" "" "@DEF@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.LP +.eM +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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIscreen_number\fP 1i +Specifies the appropriate screen number on the host server. +.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. +.IP \fIvalues\fP 1i +Specifies the +.PN XWindowChanges +structure. +.LP +.eM +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 is trapped by Xlib 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. +It returns a nonzero status if the request or event is successfully sent; +otherwise, it returns a zero status. +.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, an +.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@" +.sM +.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 +.eM +Xlib provides functions to convert localized text to or from encodings +that support the inter-client communication conventions for text. +In addition, functions are provided for converting between lists of pointers +to character strings and text properties in the STRING encoding. +.LP +The functions for localized text return a signed integer error status +that encodes +.PN Success +as zero, specific error conditions as negative numbers, and partial conversion +as a count of unconvertible characters. +.LP +.IN "XICCEncodingStyle" "" "@DEF@" +.sM +.TS +lw(.5i) lw(2i) lw(2.5i). +T{ +#define +T} T{ +.PN XNoMemory +T} T{ +\-1 +T} +T{ +#define +T} T{ +.PN XLocaleNotSupported +T} T{ +\-2 +T} +T{ +#define +T} T{ +.PN XConverterNotFound +T} T{ +\-3 +T} +.TE +.Ds 0 +.TA .5i 2.5i +.ta .5i 2.5i +typedef enum { + XStringStyle, /* STRING */ + XCompoundTextStyle, /* COMPOUND_TEXT */ + XTextStyle, /* text in owner's encoding (current locale) */ + XStdICCTextStyle /* STRING, else COMPOUND_TEXT */ +} XICCEncodingStyle; +.De +.LP +.eM +.sp +.LP +To convert a list of text strings to an +.PN XTextProperty +structure, use +.PN XmbTextListToTextProperty +or +.PN XwcTextListToTextProperty . +.IN "XmbTextListToTextProperty" "" "@DEF@" +.IN "XwcTextListToTextProperty" "" "@DEF@" +.sM +.FD 0 +int XmbTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + char **\fIlist\fP\^; +.br + int \fIcount\fP\^; +.br + XICCEncodingStyle \fIstyle\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN +.FD 0 +int XwcTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + wchar_t **\fIlist\fP\^; +.br + int \fIcount\fP\^; +.br + XICCEncodingStyle \fIstyle\fP\^; +.br + XTextProperty *\fItext_prop_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIlist\fP 1i +Specifies a list of null-terminated character strings. +.IP \fIcount\fP 1i +Specifies the number of strings specified. +.IP \fIstyle\fP 1i +Specifies the manner in which the property is encoded. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XmbTextListToTextProperty +and +.PN XwcTextListToTextProperty +functions set the specified +.PN XTextProperty +value to a set of null-separated elements representing the concatenation +of the specified list of null-terminated text strings. +A final terminating null is stored at the end of the value field +of text_prop_return but is not included in the nitems member. +.LP +The functions set the encoding field of text_prop_return to an +.PN Atom +for the specified display +naming the encoding determined by the specified style +and convert the specified text list to this encoding for storage in +the text_prop_return value field. +If the style +.PN XStringStyle +or +.PN XCompoundTextStyle +is specified, +this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively. +If the style +.PN XTextStyle +is specified, +this encoding is the encoding of the current locale. +If the style +.PN XStdICCTextStyle +is specified, +this encoding is ``STRING'' if the text is fully convertible to STRING, +else ``COMPOUND_TEXT''. +.LP +If insufficient memory is available for the new value string, +the functions return +.PN XNoMemory . +If the current locale is not supported, +the functions return +.PN XLocaleNotSupported . +In both of these error cases, +the functions do not set text_prop_return. +.LP +To determine if the functions are guaranteed not to return +.PN XLocaleNotSupported , +use +.PN XSupportsLocale . +.LP +If the supplied text is not fully convertible to the specified encoding, +the functions return the number of unconvertible characters. +Each unconvertible character is converted to an implementation-defined and +encoding-specific default string. +Otherwise, the functions return +.PN Success . +Note that full convertibility to all styles except +.PN XStringStyle +is guaranteed. +.LP +To free the storage for the value field, use +.PN XFree . +.sp +.LP +To obtain a list of text strings from an +.PN XTextProperty +structure, use +.PN XmbTextPropertyToTextList +or +.PN XwcTextPropertyToTextList . +.IN "XmbTextPropertyToTextList" "" "@DEF@" +.IN "XwcTextPropertyToTextList" "" "@DEF@" +.sM +.FD 0 +int XmbTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.br + char ***\fIlist_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.FD 0 +int XwcTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + XTextProperty *\fItext_prop\fP\^; +.br + wchar_t ***\fIlist_return\fP\^; +.br + int *\fIcount_return\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +The +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList +functions return a list of text strings in the current locale representing the +null-separated elements of the specified +.PN XTextProperty +structure. +The data in text_prop must be format 8. +.LP +Multiple elements of the property (for example, the strings in a disjoint +text selection) are separated by a null byte. +The contents of the property are not required to be null-terminated; +any terminating null should not be included in text_prop.nitems. +.LP +If insufficient memory is available for the list and its elements, +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList +return +.PN XNoMemory . +If the current locale is not supported, +the functions return +.PN XLocaleNotSupported . +Otherwise, if the encoding field of text_prop is not convertible +to the encoding of the current locale, +the functions return +.PN XConverterNotFound . +For supported locales, +existence of a converter from COMPOUND_TEXT, STRING +or the encoding of the current locale is guaranteed if +.PN XSupportsLocale +returns +.PN True +for the current locale (but the actual text +may contain unconvertible characters). +Conversion of other encodings is implementation-dependent. +In all of these error cases, +the functions do not set any return values. +.LP +Otherwise, +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList +return the list of null-terminated text strings to list_return +and the number of text strings to count_return. +.LP +If the value field of text_prop is not fully convertible to the encoding of +the current locale, +the functions return the number of unconvertible characters. +Each unconvertible character is converted to a string in the +current locale that is specific to the current locale. +To obtain the value of this string, +use +.PN XDefaultString . +Otherwise, +.PN XmbTextPropertyToTextList +and +.PN XwcTextPropertyToTextList +return +.PN Success . +.LP +To free the storage for the list and its contents returned by +.PN XmbTextPropertyToTextList , +use +.PN XFreeStringList . +To free the storage for the list and its contents returned by +.PN XwcTextPropertyToTextList , +use +.PN XwcFreeStringList . +.sp +.LP +To free the in-memory data associated with the specified +wide character string list, use +.PN XwcFreeStringList . +.IN "XwcFreeStringList" "" "@DEF@" +.sM +.FD 0 +void XwcFreeStringList\^(\^\fIlist\fP\^) +.br + wchar_t **\fIlist\fP\^; +.FN +.IP \fIlist\fP 1i +Specifies the list of strings to be freed. +.LP +.eM +The +.PN XwcFreeStringList +function frees memory allocated by +.PN XwcTextPropertyToTextList . +.sp +.LP +To obtain the default string for text conversion in the current locale, +use +.PN XDefaultString . +.IN "XDefaultString" "" "@DEF@" +.sM +.FD 0 +char *XDefaultString\^(\|) +.FN +.LP +.eM +The +.PN XDefaultString +function returns the default string used by Xlib for text conversion +(for example, in +.PN XmbTextPropertyToTextList ). +The default string is the string in the current locale that is output +when an unconvertible character is found during text conversion. +If the string returned by +.PN XDefaultString +is the empty string ("\^"), +no character is output in the converted text. +.PN XDefaultString +does not return NULL. +.LP +The string returned by +.PN XDefaultString +is independent of the default string for text drawing; +see +.PN XCreateFontSet +to obtain the default string for an +.PN XFontSet . +.LP +The behavior when an invalid codepoint is supplied to any Xlib function is +undefined. +.LP +The returned string is null-terminated. +It is owned by Xlib and should not be modified or freed by the client. +It may be freed after the current locale is changed. +Until freed, it will not be modified by Xlib. +.sp +.LP +To set the specified list of strings in the STRING encoding to a +.PN XTextProperty +structure, use +.PN XStringListToTextProperty . +.IN "XStringListToTextProperty" "" "@DEF@" +.sM +.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 +.eM +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 null byte (which is not included in the nitems member) +is stored at the end of the value field of text_prop_return. +The strings are assumed (without verification) to be in the STRING encoding. +If insufficient memory is available for the new value string, +.PN XStringListToTextProperty +does not set any fields in the +.PN XTextProperty +structure and returns a zero status. +Otherwise, it returns a nonzero 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 in the STRING encoding, use +.PN XTextPropertyToStringList . +.IN "XTextPropertyToStringList" "" "@DEF@" +.sM +.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 +.eM +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 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 nonzero 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@" +.sM +.FD 0 +void XFreeStringList\^(\^\fIlist\fP\^) +.br + char **\fIlist\fP\^; +.FN +.IP \fIlist\fP 1i +Specifies the list of strings to be freed. +.LP +.eM +The +.PN XFreeStringList +function releases memory allocated by +.PN XmbTextPropertyToTextList +and +.PN XTextPropertyToStringList +and the missing charset list allocated by +.PN XCreateFontSet . +.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 use these functions to set and read those properties of type TEXT +(WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE). +In addition, +Xlib provides separate convenience functions that you can use to set each +of these properties. +For further information about these convenience functions, +see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively. +.sp +.LP +To set one of a window's text properties, use +.PN XSetTextProperty . +.IN "XSetTextProperty" "" "@DEF@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +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. +An extra byte containing null (which is not included in the nitems member) +is stored at the end of the value field of text_prop_return. +The particular interpretation of the property's encoding +and data as text is left to the calling application. +If the specified property does not exist on the window, +.PN XGetTextProperty +sets the value field to NULL, +the encoding field to +.PN None , +the format field to zero, +and the nitems field to zero. +.LP +If it was able to read and store the data in the +.PN XTextProperty +structure, +.PN XGetTextProperty +returns a nonzero 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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.LP +.eM +The +.PN XSetWMName +convenience function calls +.PN XSetTextProperty +to set the WM_NAME property. +.sp +.LP +To read a window's WM_NAME property with the supplied convenience function, use +.PN XGetWMName . +.IN "XGetWMName" "" "@DEF@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XGetWMName +convenience function calls +.PN XGetTextProperty +to obtain the WM_NAME property. +It returns a nonzero status on success; +otherwise, it returns a zero status. +.LP +The following two functions have been superseded 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@" +.sM +.FD 0 +XStoreName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char *\fIwindow_name\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name\fP 1i +Specifies the window name, +which should be a null-terminated string. +.LP +.eM +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. +If the string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +.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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name_return\fP 1i +Returns the window name, which is a null-terminated string. +.LP +.eM +The +.PN XFetchName +function returns the name of the specified window. +If it succeeds, +it returns a nonzero status; +otherwise, no name has been set for the window, +and it returns zero. +If the WM_NAME property has not been set for this window, +.PN XFetchName +sets window_name_return to NULL. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned string is in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +When finished with it, a client must free +the window name string using +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.LP +.eM +The +.PN XSetWMIconName +convenience function calls +.PN XSetTextProperty +to set the WM_ICON_NAME property. +.sp +.LP +To read a window's WM_ICON_NAME property, +use +.PN XGetWMIconName . +.IN "XGetWMIconName" "" "@DEF@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XGetWMIconName +convenience function calls +.PN XGetTextProperty +to obtain the WM_ICON_NAME property. +It returns a nonzero status on success; +otherwise, it returns a zero status. +.LP +The next two functions have been superseded 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@" +.sM +.FD 0 +XSetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char *\fIicon_name\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIicon_name\fP 1i +Specifies the icon name, +which should be a null-terminated string. +.LP +.eM +If the string is not in the Host Portable Character Encoding, +the result is implementation-dependent. +.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@" +.sM +.FD 0 +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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIicon_name_return\fP 1i +Returns the window's icon name, +which is a null-terminated string. +.LP +.eM +The +.PN XGetIconName +function returns the name to be displayed in the specified window's icon. +If it succeeds, it returns a nonzero status; otherwise, +if no icon name has been set for the window, +it returns zero. +If you never assigned a name to the window, +.PN XGetIconName +sets icon_name_return to NULL. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned string is in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +When finished with it, a client must free +the icon name string using +.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 +.hN X11/Xutil.h +header file. +.sp +.LP +To allocate an +.PN XWMHints +structure, use +.PN XAllocWMHints . +.IN "XAllocWMHints" "" "@DEF@" +.sM +.FD 0 +XWMHints *XAllocWMHints\^(\|) +.FN +.LP +.eM +The +.PN XAllocWMHints +function allocates and returns a pointer to an +.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 +.sM +/* 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 UrgencyHint +T} T{ +(1L << 8) +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 +.eM +The input member is used to communicate to the window manager the input focus +model used by the application. +Applications that expect input but never explicitly set focus to any +of their subwindows (that is, use the push model of focus management), +such as X Version 10 style applications that use real-estate +driven focus, should set this member to +.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(.2i) lw(2.8i). +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 +The +.PN UrgencyHint +flag, if set in the flags field, indicates that the client deems the window +contents to be urgent, requiring the timely response of the user. The +window manager will make some effort to draw the user's attention to this +window while this flag is set. The client must provide some means by which the +user can cause the urgency flag to be cleared (either mitigating +the condition that made the window urgent or merely shutting off the alarm) +or the window to be withdrawn. +.LP +.sp +To set a window's WM_HINTS property, use +.PN XSetWMHints . +.IN "XSetWMHints" "" "@DEF@" +.sM +.FD 0 +XSetWMHints\^(\^\fIdisplay\fP, \fIw\fP, \fIwmhints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XWMHints *\fIwmhints\fP\^; + +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwmhints\fP 1i +Specifies the +.PN XWMHints +structure to be used. +.LP +.eM +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@" +.sM +.FD 0 +XWMHints *XGetWMHints\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +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 an +.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 +.hN X11/Xutil.h +header file. +.LP +The size of the +.PN XSizeHints +structure may grow in future releases, as new components are +added to support new ICCCM features. +Passing statically allocated instances of this structure into +Xlib may result in memory corruption when running against a +future release of the library. +As such, it is recommended that only dynamically allocated +instances of the structure be used. +.sp +.LP +To allocate an +.PN XSizeHints +structure, use +.PN XAllocSizeHints . +.IN "XAllocSizeHints" "" "@DEF@" +.sM +.FD 0 +XSizeHints *XAllocSizeHints\^(\|) +.FN +.LP +.eM +The +.PN XAllocSizeHints +function allocates and returns a pointer to an +.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 +.sM +/* Size hints mask bits */ +.TS +lw(.5i) lw(1.1i) lw(1.5i) lw(3.1i). +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{ +(PPosition|PSize| +.br +PMinSize|PMaxSize| +.br +PResizeInc|PAspect) +T} T{ +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; + /* this structure may be extended in the future */ +} XSizeHints; +.De +.LP +.eM +The x, y, width, and height members are now obsolete +and are left solely for compatibility reasons. +The min_width and min_height members specify the +minimum window size that still allows the application to be useful. +The max_width and max_height members specify the maximum window size. +The width_inc and height_inc members define an arithmetic progression of +sizes (minimum to maximum) into which the window prefers to be resized. +The min_aspect and max_aspect members are expressed +as ratios of x and y, +and they allow an application to specify the range of aspect +ratios it prefers. +The base_width and base_height members define the desired size of the window. +The window manager will interpret the position of the window +and its border width to position the point of the outer rectangle +of the overall window specified by the win_gravity member. +The outer rectangle of the window includes any borders or decorations +supplied by the window manager. +In other words, +if the window manager decides to place the window where the client asked, +the position on the parent window's border named by the win_gravity +will be placed where the client window would have been placed +in the absence of a window manager. +.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@" +.sM +.FD 0 +void XSetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XSizeHints *\fIhints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints\fP 1i +Specifies the size hints for the window in its normal state. +.LP +.eM +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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +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, is 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 nonzero 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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIhints\fP 1i +Specifies the +.PN XSizeHints +structure to be used. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +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, is 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 nonzero 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 the +.hN X11/Xutil.h +header file. +.sp +.LP +To allocate an +.PN XClassHint +structure, use +.PN XAllocClassHint . +.IN "XAllocClassHint" "" "@DEF@" +.sM +.FD 0 +XClassHint *XAllocClassHint\^(\|) +.FN +.LP +.eM +The +.PN XAllocClassHint +function allocates and returns a pointer to an +.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 +.sM +.IN "XClassHint" "" "@DEF@" +.Ds 0 +.TA .5i +.ta .5i +typedef struct { + char *res_name; + char *res_class; +} XClassHint; +.De +.LP +.eM +The res_name member contains the application name, +and the res_class member contains the application class. +Note that the name set in this property may differ from the name set as WM_NAME. +That is, WM_NAME specifies what should be displayed in the title bar and, +therefore, can contain temporal information (for example, the name of +a file currently in an editor's buffer). +On the other hand, +the name specified as part of WM_CLASS is the formal name of the application +that should be used when retrieving the application's resources from the +resource database. +.LP +.sp +To set a window's WM_CLASS property, use +.PN XSetClassHint . +.IN "XSetClassHint" "" "@DEF@" +.sM +.FD 0 +XSetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + XClassHint *\fIclass_hints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIclass_hints\fP 1i +Specifies the +.PN XClassHint +structure that is to be used. +.LP +.eM +The +.PN XSetClassHint +function sets the class hint for the specified window. +If the strings are not in the Host Portable Character Encoding, +the result is implementation-dependent. +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIclass_hints_return\fP 1i +Returns the +.PN XClassHint +structure. +.LP +.eM +The +.PN XGetClassHint +function returns the class hint of the specified window to the members +of the supplied structure. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +It returns a nonzero status on success; +otherwise, it returns a zero status. +To free res_name and res_class when finished with the strings, +use +.PN XFree +on each individually. +.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@" +.sM +.FD 0 +XSetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Window \fIprop_window\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIprop_window_return\fP 1i +Returns the WM_TRANSIENT_FOR property of the specified window. +.LP +.eM +The +.PN XGetTransientForHint +function returns the WM_TRANSIENT_FOR property for the specified window. +It returns a nonzero status on success; +otherwise, it returns a zero status. +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +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 nonzero 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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +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 the list, +and returns a nonzero status. +Otherwise, it sets neither of the return arguments +and returns a zero status. +To release the list of atoms, use +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +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. +If 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 nonzero 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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +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 the list, +and returns a nonzero status. +Otherwise, it sets neither of the return arguments +and returns a zero status. +To release the list of window identifiers, use +.PN XFree . +.LP +.PN XGetWMColormapWindows +can generate a +.PN BadWindow +error. +.NH 3 +Setting and Reading the WM_ICON_SIZE Property +.XS +\*(SN Setting and Reading the WM_ICON_SIZE Property +.XE +.LP +Xlib provides functions that you can use to set and read +the WM_ICON_SIZE property for a given window. +These functions use the +.PN XIconSize +.IN "XIconSize" +structure, which is defined in the +.hN X11/Xutil.h +header file. +.sp +.LP +To allocate an +.PN XIconSize +structure, use +.PN XAllocIconSize . +.IN "XAllocIconSize" "" "@DEF@" +.sM +.FD 0 +XIconSize *XAllocIconSize\^(\|) +.FN +.LP +.eM +The +.PN XAllocIconSize +function allocates and returns a pointer to an +.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 +.sM +.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 +.eM +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_SIZE property, use +.PN XSetIconSizes . +.IN "XSetIconSizes" "" "@DEF@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIsize_list\fP 1i +Specifies the size list. +.IP \fIcount\fP 1i +Specifies the number of items in the size list. +.LP +.eM +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_SIZE property, use +.PN XGetIconSizes . +.IN "XGetIconSizes" "" "@DEF@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIsize_list_return\fP 1i +Returns the size list. +.IP \fIcount_return\fP 1i +Returns the number of items in the size list. +.LP +.eM +The +.PN XGetIconSizes +function returns zero if a window manager has not set icon sizes; +otherwise, it returns nonzero. +.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 +The +.PN XmbSetWMProperties +function stores the standard set of window manager properties, +with text properties in standard encodings +for internationalized text communication. +The standard window manager properties for a given window are +WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, +WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME. +.IN "XmbSetWMProperties" "" "@DEF@" +.sM +.FD 0 +void XmbSetWMProperties\^(\^\fIdisplay\fP\^, \fIw\fP\^, \fIwindow_name\fP\^, \fIicon_name\fP\^, \fIargv\fP\^, \fIargc\fP\^, +.br + \fInormal_hints\fP\^, \fIwm_hints\fP\^, \fIclass_hints\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + char *\fIwindow_name\fP\^; +.br + char *\fIicon_name\fP\^; +.br + char *\fIargv\fP\^[]; +.br + int \fIargc\fP\^; +.br + XSizeHints *\fInormal_hints\fP\^; +.br + XWMHints *\fIwm_hints\fP\^; +.br + XClassHint *\fIclass_hints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name\fP 1i +Specifies the window name, +which should be a null-terminated string. +.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 \fIhints\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 +.eM +The +.PN XmbSetWMProperties +convenience function provides a simple programming interface +for setting those essential window properties that are used +for communicating with other clients +(particularly window and session managers). +.LP +If the window_name argument is non-NULL, +.PN XmbSetWMProperties +sets the WM_NAME property. +If the icon_name argument is non-NULL, +.PN XmbSetWMProperties +sets the WM_ICON_NAME property. +The window_name and icon_name arguments are null-terminated strings +in the encoding of the current locale. +If the arguments can be fully converted to the STRING encoding, +the properties are created with type ``STRING''; +otherwise, the arguments are converted to Compound Text, +and the properties are created with type ``COMPOUND_TEXT''. +.LP +If the normal_hints argument is non-NULL, +.PN XmbSetWMProperties +calls +.PN XSetWMNormalHints , +which sets the WM_NORMAL_HINTS property (see section 14.1.7). +If the wm_hints argument is non-NULL, +.PN XmbSetWMProperties +calls +.PN XSetWMHints , +which sets the WM_HINTS property (see section 14.1.6). +.LP +If the argv argument is non-NULL, +.PN XmbSetWMProperties +sets the WM_COMMAND property from argv and argc. +An argc of zero indicates a zero-length command. +.LP +The hostname of the machine is stored using +.PN XSetWMClientMachine +(see section 14.2.2). +.LP +If the class_hints argument is non-NULL, +.PN XmbSetWMProperties +sets the WM_CLASS property. +If the res_name member in the +.PN XClassHint +structure is set to the NULL pointer and the RESOURCE_NAME +environment variable is set, +the value of the environment variable is substituted for res_name. +If the res_name member is NULL, +the environment variable is not set, and argv and argv[0] are set, +then the value of argv[0], stripped of any directory prefixes, +is substituted for res_name. +.LP +It is assumed that the supplied class_hints.res_name and argv, +the RESOURCE_NAME environment variable, and the hostname of the machine +are in the encoding of the locale announced for the LC_CTYPE category +(on POSIX-compliant systems, the LC_CTYPE, else LANG environment variable). +The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties +are typed according to the local host locale announcer. +No encoding conversion is performed prior to storage in the properties. +.LP +For clients that need to process the property text in a locale, +.PN XmbSetWMProperties +sets the WM_LOCALE_NAME property to be the name of the current locale. +The name is assumed to be in the Host Portable Character Encoding +and is converted to STRING for storage in the property. +.LP +.PN XmbSetWMProperties +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.sp +.LP +To set a window's standard window manager properties +with strings in client-specified encodings, 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@" +.sM +.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 + XSizeHints *\fInormal_hints\fP\^; +.br + XWMHints *\fIwm_hints\fP\^; +.br + XClassHint *\fIclass_hints\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwindow_name\fP 1i +Specifies the window name, +which should be a null-terminated string. +.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 +.eM +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 14.1.4). +If the icon_name argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetWMIconName , +which sets the WM_ICON_NAME property (see section 14.1.5). +If the argv argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetCommand , +which sets the WM_COMMAND property (see section 14.2.1). +Note that an argc of zero is allowed to indicate a zero-length command. +Note also that the hostname of this machine is stored using +.PN XSetWMClientMachine +(see section 14.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 14.1.7). +If the wm_hints argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetWMHints , +which sets the WM_HINTS property (see section 14.1.6). +.LP +If the class_hints argument is non-NULL, +.PN XSetWMProperties +calls +.PN XSetClassHint , +which sets the WM_CLASS property (see section 14.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 the value of the environment variable is substituted for res_name. +If the res_name member is NULL, +the environment variable is not set, +and argv and argv[0] are set, +then the value of argv[0], stripped of +any directory prefixes, is substituted for res_name. +.LP +.PN XSetWMProperties +can generate +.PN BadAlloc +and +.PN BadWindow +errors. +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +The +.PN XSetCommand +function sets the command and arguments used to invoke the +application. +(Typically, argv is the argv array of your main program.) +If the strings are not in the Host Portable Character Encoding, +the result is implementation-dependent. +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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 +.eM +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 nonzero status. +Otherwise, it returns a zero status. +If the data returned by the server is in the Latin Portable Character Encoding, +then the returned strings are in the Host Portable Character Encoding. +Otherwise, the result is implementation-dependent. +To free the memory allocated to the string list, use +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop\fP 1i +Specifies the +.PN XTextProperty +structure to be used. +.LP +.eM +The +.PN XSetWMClientMachine +convenience function calls +.PN XSetTextProperty +to set the WM_CLIENT_MACHINE property. +.sp +.LP +To read a window's WM_CLIENT_MACHINE property, use +.PN XGetWMClientMachine . +.IN "XGetWMClientMachine" "" "@DEF@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fItext_prop_return\fP 1i +Returns the +.PN XTextProperty +structure. +.LP +.eM +The +.PN XGetWMClientMachine +convenience function performs an +.PN XGetTextProperty +on the WM_CLIENT_MACHINE property. +It returns a nonzero status on success; +otherwise, it returns a zero status. +.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 three-dimensional display program that wants +to draw a smoothly shaded sphere. +At each pixel in the image of the sphere, +the program computes the intensity and color of light +reflected back to the viewer. +The result of each computation is a triple of red, green, and blue (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, for a total of 256 colors. +Because some colors are already in use in the default colormap, +the image processing program allocates and installs a new colormap. +.LP +The user decides to alter some of the colors in the image +by invoking a color palette program to mix and choose colors. +The color palette program also needs a +colormap with eight reds, eight greens, and four blues, so just like +the image processing program, it must allocate and +install a new colormap. +.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 +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@" +.sM +.FD 0 +XStandardColormap *XAllocStandardColormap\^(\|) +.FN +.LP +.eM +The +.PN XAllocStandardColormap +function allocates and returns a pointer to an +.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 +.sM +/* 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 +.eM +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) & 0xFFFFFFFF +.De +.LP +For +.PN GrayScale +colormaps, +only the colormap, red_max, red_mult, +and base_pixel members are defined. +The other members are ignored. +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) & 0xFFFFFFFF +.De +.LP +Negative multipliers can be represented by converting the 2's +complement representation of the multiplier into an unsigned long and +storing the result in the appropriate _mult field. +The step of masking by 0xFFFFFFFF effectively converts the resulting +positive multiplier into a negative one. +The masking step will take place automatically on many machine architectures, +depending on the size of the integer type used to do the computation. +.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 +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 +.hN 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 array of +.PN XStandardColormap +structures. +Each entry in the array describes an RGB subset of the default color +map for the Visual specified by visual_id. +.IP +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 three-dimensional applications need to +use all available colormap cells and to distribute as many +perceptually distinct colors as possible over those cells. +This implies that there may be more green values available than +red, as well as more green or red than blue. +.IP +For an 8-plane +.PN PseudoColor +visual, +RGB_BEST_MAP is likely to be a 3/3/2 allocation. +For a 24-plane +.PN DirectColor +visual, +RGB_BEST_MAP is normally an 8/8/8 allocation. +.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@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +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 +The +.PN XSetRGBColormaps +function usually is only used by window or session 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 (unless you are using the default colormap of the screen). +.IP \(bu 5 +Determine the color characteristics of the visual. +.IP \(bu 5 +Allocate cells in the colormap (or create it with +.PN AllocAll ). +.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 +.PN XSetRGBColormaps +can generate +.PN BadAlloc , +.PN BadAtom , +and +.PN BadWindow +errors. +.sp +.LP +To obtain the +.PN XStandardColormap +structure associated with the specified property, use +.PN XGetRGBColormaps . +.IN "XGetRGBColormaps" "" "@DEF@" +.sM +.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 +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.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. +.IP \fIproperty\fP 1i +Specifies the property name. +.LP +.eM +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, +.PN XGetRGBColormaps +allocates and fills in space for the returned colormaps +and returns a nonzero status. +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 +is assumed, which indicates that the resources cannot be released. +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 |