| Page: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
|---|
The Inter-Client Communication Conventions in the SUPER-UX X Window System Programmer's Guide, 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 Inter-Client Communication Conventions in the SUPER-UX X Window System Programmer's Guide, .
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 <X11/Xatom.h> header file, where to avoid name conflicts with user symbols their #define name has an XA_ prefix. For further information about atoms and properties, see section 4.3.
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 chaplet provide the primary programming interfaces by which client applications communicate with their window and session managers as well as share standard colormaps.
The standard properties that are of special interest for communicating with window and session managers are:
| Name | Type | Format | Description |
|---|---|---|---|
| WM_CLASS | STRING | 8 | Set by application programs to allow window and session managers to obtain the application's resources from the resource database. |
| WM_CLENT_MACHINE | TEXT | The string name of the machine on which the client application is running. | |
| WM_COLORMAP_WINDOWS | WINDOW | 32 | The list of window IDs that may need a different colormap than that of their top-level window. |
| WM_COMMAND | TEXT | The command and arguments, null-separated, used to invoke the application. | |
| WM_HINTS | WM_HINTS | 32 | Additional hints set by the client for use by the window manager. The C type of this property is XWMHints. |
| WM_ICON_NAME | TEXT | The name to be used in an icon. | |
| WM_ICON_SIZE | WM_ICON_SIZE | 32 | The window manager may set this property on the root window to specify the icon sizes it supports. The C type of this property is XIconSize. |
| WM_NAME | TEXT | The name of the application. | |
| WM_NORMAL_HINTS | WM_SIZE_HINTS | 32 | Size hints for a window in its normal state. The C type of this property is XSizeHints. |
| WM_PROTOCOLS | ATOM | 32 | List of atoms that identify the communications protocols between the client and window manager in which the client is willing to participate. |
| WM_STATE | WM_STATE | 32 | Intended for communication between window and session managers only. |
| WM_TRANSIENT_FOR | WINDOW | 32 | Set by application programs to indicate to the window manager that a transient top-level window, such as a dialog box. |
The remainder of this chapter discusses:
| Home |
|---|
This section discusses how to:
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.
To request that a top-level window be iconified, use XIconifyWindow.
Status XIconifyWindow(display, w, screen_number)
Display *display;
Window w;
int screen_number;
The XIconifyWindow function sends a WM_CHANGE_STATE ClientMessage event with a format of 32 and a first data element of IconicSlate (as described in section 4.1.4 of the Inter-Client Communication Conventions in the SUPER-UX X Window System Programmer's Guide, ) and a window of w to the root window of the specified screen with an event mask set to SubstructureNotifyMask|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, 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.
To request that a top-level window be withdrawn, use XWithdrawWindow.
Status XWithdrawWindow(display, w, screen_number)
Display *display;
Window w;
in screen_number;
The XWithdrawWindow function unmaps the specified window and sends a synthetic 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 UnmapNotify event is successfully sent; otherwise, it returns a zero status.
XWithdrawWindow can generate a BadWindow error.
To request that a top-level window be reconfigured, use XReconfigureWMWindow.
Status XReconfigureWMWindow(display, w, screen_number, value_mask, values)
Display *display;
Window w;
int screen_number;
unsigned int value_mask;
XWindowChanges *values;
The XReconfigureWMWindow function issues a ConfigureWindow request on the specified top-level window. If the stacking mode is changed and the request fails with a BadMatch error, the error is trapped by Xlib and a synthetic 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.
XReconfigureWMWindow can generate BadValue and BadWindow errors.
| Home |
|---|
Many of the text properties allow a variety of types and formats.
Because the data stored in these properties are not simple null-terminated
strings, a XTextProperty structure is used to describe
the encoding, type, and length of the text as well as its value.
The XTextProperty structure contains:
14.1.2. Converting String Lists
| typedef struct { | ||
| unsigned
char *value; Atom encoding; int format; unsigned long nitems; | /* property data */ /* type of property */ /*8, 16, or 32 */ /* number of items in value */ | |
| } XTextProperty; | ||
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.
The functions for localized text return a signed integer error status that encodes Success as zero, specific error conditions as negative numbers, and partial conversion as a count of unconvertible characters.
| #define #define #define | XNoMemory XLocaleNotSupported XConverterNotFound | -1 -2 -3 |
| typedef enum { | ||
| XStringStyle,
XCompoundTextStyle, XTextStyle, XStdICCTextStyle | /* STRING */ /* COMPOUND_TEXT */ /* text in owner's encoding (current locale) */ /* STRING, else COMPOUND_TEXT */ | |
| } XICCEncodingStyle; | ||
To convert a list of text strings to an XTextProperty structure, use XmbTextListToTextProperty or XwcTextListToTextProperty.
int XmbTextListToTextProperty(display, list, count, style, text_prop_return)
Display *display;
char **list;
int count;
XlCCEncodingStyle style;
XTextProperty *text_prop _return;
int XwcTextListToTextProperty(display, list, count, style, text_prop _return)
Display *display;
wchar_t **list;
int count;
XICCEncodingStyle style;
XTextProperty *text_prop_return;
The XmbTextListToTextProperty and XwcTextLislToTextProperty functions set the specified 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.
The functions set the encoding field of text_prop_return to an 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 XStringStyle or XCompoundTextStyle is specified, this encoding is "STRING" or "COMPOUND_TEXT", respectively. If the style XTextStyle is specified, this encoding is the encoding of the current locale. If the style XStdICCTextStyle is specified, this encoding is "STRING" if the text is fully convertible to STRING, else "COMPOUND_TEXT".
If insufficient memory is available for the new value string, the functions return XNoMemory. If the current locale is not supported, the functions return XLocaleNotSupported. In both of these error cases, the functions do not set text_prop_return.
To determine if the functions are guaranteed not to return XLocaleNotSupported, use XSupportsLocale.
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 Success. Note that full convertibility to all styles except XStringStyle is guaranteed.
To free the storage for the value field, use XFree.
To obtain a list of text strings from an XTextProperty structure, use XmbTextPropertyToTextList or XwcTextPropertyToTextList.
int XmbTextPropertyToTextList (display, text_prop, list_return, count_ return)
Display *display;
XTextProperty *text_prop;
char ***list_return;
int *count_return;
int XwcTextPropertyToTextList(display, text_prop, list_return, count_return)
Display *display;
XTextProperty *text prop;
wchar_t ***list_return;
int *count_return;
The XmbTextPropertyToTextList and XwcTextPropertyToTextList functions return a list of text strings in the current locale representing the null-separated elements of the specified XTextProperty structure. The data in text_prop must be format 8.
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.
If insufficient memory is available for the list and its elements, XmbTextPropertyToTextList and XwcTextPropertyToTextList return XNoMemory. If the current locale is not supported, the functions return XLocaleNotSupported. Otherwise, if the encoding field of text_prop is not convertible to the encoding of the current locale, the functions return XConverterNotFound. For supported locales, existence of a converter from COMPOUND_TEXT, STRING or the encoding of the current locale is guaranteed if XSupportsLocale returns 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.
Otherwise, XmbTextPropertyToTextList and XwcTextPropertyToTextList return the list of null-terminated text strings to list_return and the number of text strings to count_return.
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 XDefaultString. Otherwise, XmbTextPropertyToTextList and XwcTextPropertyToTextList return Success.
To free the storage for the list and its contents returned by XmbTextPropertyToTextList, use XFreeStringList. To free the storage for the list and its contents returned by XwcTextPropertyToTextList, use XwcFreeStringList.
To free the in-memory data associated with the specified wide character string list, use XwcFreeStringList.
void XwcFreeStringList(list)
wchar_t **list;
The XwcFreeStringList function frees memory allocated by XwcTextPropertyToTextList.
To obtain the default string for text conversion in the current locale, use XDefaultString.
char *XDefaultString()
The XDefaultString function returns the default string used by Xlib for text conversion (for example, in 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 XDefaultString is the empty string (" "), no character is output in the converted text. XDefaultString does not return NULL.
The string returned by XDefaultString is independent of the default string for text drawing; see XCreateFontSet. to obtain the default string for an XFontSet.
The behavior when an invalid codepoint is supplied to any Xlib function is undefined.
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.
To set the specified list of strings in the STRING encoding to a XTextProperty structure, use XStringListToTextProperty .
Status XStringListToTextProperty(list, count, text_prop_return)
char **list;
int count;
XTextProperty *text_prop_return;
The XStringListToTextProperty function sets the specified 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, XStringListToTextProperty does not set any fields in the XTextProperty structure and returns a zero status. Otherwise, it returns a nonzero status. To free the storage for the value field, use XFree.
To obtain a list of strings from a specified XTextProperty structure in the STRING encoding, use XTextPropertyToStringList.
Status XTextPropertyToStringList(text_prop, list_return, count_return)
XTextProperty *text_prop;
char ***list_return;
int *count_return;
The XTextPropertyToStringList function returns a list of strings representing the null-separated elements of the specified 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, 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 XFreeStringList.
To free the in-memory data associated with the specified string list, use XFreeStringList.
void XFreeStringList(list)
char **list;
The XFreeStringList function releases memory allocated by XmbTextPropertyToTextList and XTextPropertyToStringList and the missing charset list allocated by XCreateFontSet.
| Home |
|---|
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.
To set one of a window's text properties, use XSetTextProperty.
The 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
XTextProperty structure. If the property does not already
exist, XSetTextProperty sets it for the specified window.
XSetTextProperty can generate BadAlloc, BadAtom,
BadValue, and BadWindow errors.
To read one of a window's text properties, use XGetTextProperty.
The XGetTextProperty function reads the specified property
from the window and stores the data in the returned 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, XGetTextProperty sets the
value field to NULL, the encoding field to None, the format
field to zero, and the nitems field to zero.
If it was able to read and store the data in the XTextProperty
structure, XGetTextProperty returns a nonzero status; otherwise,
it returns a zero status.
XGetTextProperty can generate BadAtom and BadWindow
errors.
Xlib provides convenience functions that you can use to set and
read the WM_NAME property for a given window.
To set a window's WM_NAME property with the supplied convenience
function, use XSetWMName.
The XSetWMName convenience function calls XSetTextProperty
to set the WM_NAME property.
To read a window's WM_NAME property with the supplied convenience
function, use XGetWMName.
The XGetWMName convenience function calls XGetTextProperty
to obtain the WM_NAME property. It returns a nonzero status on
success; otherwise, it returns a zero status.
The following two functions have been superseded by XSetWMName
and XGetWMName, respectively. You can use these additional
convenience functions for window names that are encoded as STRING
properties.
To assign a name to a window, use XStoreName.
The 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.
XStoreName can generate BadAlloc and BadWindow
errors.
To get the name of a window, use XFetchName.
The 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, 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 XFree.
XFetchName can generate a BadWindow error.
Xlib provides convenience functions that you can use to set and
read the WM_ICON_NAME property for a given window.
To set a window's WM_ICON_NAME property, use XSetWMIconName.
The XSetWMIconName convenience function calls XSetTextProperty
to set the WM_ICON_NAME property.
To read a window's WM_ICON_NAME property, use XGetWMIconName.
The XGetWMIconName convenience function calls XGetTextProperty
to obtain the WM_ICON_NAME property. It returns a nonzero status
on success; otherwise, it returns a zero status.
The next two functions have been superseded by XSetWMIconName
and XGetWMIconName, respectively. You can use these additional
convenience functions for window names that are encoded as STRING
properties.
To set the name to be displayed in a window's icon, use XSetIconName.
If the string is not in the Host Portable Character Encoding,
the result is implementation dependent. XSetIconName can
generate BadAlloc and BadWindow errors.
To get the name a window wants displayed in its icon, use XGetIconName.
The 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, 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 XFree.
XGetIconName can generate a BadWindow error.
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 XWMHints structure, as defined in the <X11/Xutil.h>
header file.
To allocate an XWMHints structure, use XAllocWMHints.
XWMHints *XAllocWMHints()
The XAllocWMHints function allocates and returns a pointer
to a XWMHints structure. Note that all fields in the XWMHints
structure are initially set to zero. If insufficient memory is
available, XAllocWMHints returns NULL. To free the memory
allocated to this structure, use XFree.
The XWMHints structure contains:
14.1.3. Setting and Reading Text Properties
void XSetTextProperty(display, w, text_ prop, property)
Display *display;
Window w;
XTextProperty *text_prop;
Atom property;
Status XGetTextProperty(display, w, text_prop return, property)
Display *display;
Window w;
XTextProperty *text_prop_return;
Atom property;
Home
14.1.4. Setting and Reading the WM_NAME Property
void XSetWMName(display, w, text_prop)
Display *display;
Window w;
XTextProperty *text_prop;
Status XGetWMName(display, w, text_prop_return)
Display *display;
Window w;
XTextProperty *text_prop_return;
XStoreName(display, w, window_name)
Display *display;
Window w;
char *window_name;
StatusXFetchName(display,w,window_name_return)
Display *display;
Window w;
char **window_name_return;
Home
14.1.5. Setting and Reading the WM_ICON_NAME Property
void XSetWMIconName(display, w, text_prop)
Display *display;
Window w;
XTextProperty *text_prop;
Status XGetWMIconName(display, w, text_prop_return)
Display *display;
Window w;
XTextProperty *text_prop_return;
XSetIconName(display, w, icon_name)
Display *display;
Window w;
char *icon_name;
Status XGetIconName(display, w, icon_name_return)
Display *display;
Window w;
char **icon_name_return;
Home
14.1.6. Setting and Reading the WM_HINTS Property
| /* Window manager hints mask bits */ | ||
| #define #define #define #define #define #define #define #define #define | InputHint StateHint IconPixmapHint IconWindowHint IconPositionHint IconMaskHint WindowGroupHint Urgency Hint AllHints | (1L << 0) (1L << 1) (1L << 2) (1L << 3) (1L << 4) (1L << 5) (1L << 6) (1L << 8) (InputHint|StateHint|IconPixmapHint| IconWindowHint|IconPositionHint| IconMaskHint|WindowGroupHint) |
| /* Values */ | ||
| typedef struct { | ||
| long flags;
Bool input; int initial_state; Pixmap icon_pixmap; Window icon_window; int icon_x, icon_y; Pixmap icon_mask; XID window_group; /* this structure may be extended in the future */ | /*
marks which fields in this structure are defined */ /* does this application rely on the window manager to get keyboard input? */ /* see below */ /* pixmap to be used as icon */ /* window to be used as icon */ /* initial position of icon */ /* pixmap to be used as mask for icon_pixmap */ /* id of related window group */ | |
| } XWMHints; | ||
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 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 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 False. Applications that never expect any keyboard input also should set this member to False.
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 True. Push model window managers should make sure that pull model applications do not break them by resetting input focus to PointerRoot when it is appropriate (for example, whenever an application whose input member is False sets input focus to one of its subwindows).
| The definitions for the initial_state flag are: | |||
| #define #define #define | WithdrawnState NormalState IconicState | 0 1 3 | /* most applications start this way */ /* application wants to start as an icon */ |
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,
The 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.
To set a window's WM_HINTS property, use XSetWMHints.
XSetWMHints(display, w, wmhints)
Display *display;
Window w;
XWMHints *wmhints;
The 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.
XSetWMHints can generate BadAlloc and BadWindow errors.
To read a window's WM_HINTS property, use XGetWMHints.
XWMHints *XGetWMHints(display, w)
Display *display;
Window w;
The XGetWMHints function reads the window manager hints and returns NULL if no WM_HINTS property was set on the window or returns a pointer to a XWMHints structure if it succeeds. When finished with the data, free the space used for it by calling XFree.
XGetWMHints can generate a BadWindow error.
| Home |
|---|
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 XSizeHints structure, as defined in the <X11/Xutil.h> header file.
The size of the 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.
To allocate an XSizeHints structure, use XAllocSizeHints.
The XAllocSizeHints function allocates and returns a pointer to a XSizeHints structure. Note that all fields in the XSizeHints structure are initially set to zero. If insufficient memory is available, XAllocSizeHints returns NULL. To free the memory allocated to this structure, use XFree.
The XSizeHints structure contains:
| /* Size hints mask bits */ | |||
| #define #define #define #define #define #define #define #define #define #define #define | USPosition USSize PPosition Psize PMinSize PMaxSize PResizeInc PAspect PBaseSize PWinGravity PAllHints | (1L << 0) (1L << 1) (1L << 2) (1L << 3) (1L << 4) (1L << 5) (1L << 6) (1L << 7) (1L << 8) (1L << 9) (PPosition|PSize| PMinSize|PMaxSize| PResizeInc|PAspect) | /* user specified x, y
*/ /* user specified width, height */ /* program specified position */ /* program specified size */ /* program specified minimum size */ /* program specified maximum size */ /* program specified resize increments */ /* program specified min and max aspect ratios */ |
| /* Values */ | |||
| typedef struct { | |||
| long flags;
int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { | /* marks which fields in this structure are
defined */ /* Obsolete */ /* Obsolete */ | ||
| int
x; int y; | /* numerator */ /* denominator */ | ||
| } min_aspect, max_aspect; | |||
| } XSizeHints; | |||
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.
Note that use of the PAllHints macro is highly discouraged.
To set a window's WM_NORMAL_HINTS property, use XSetWMNormalHints.
void XSetWMNormalHints(display, w, hints)
Display *display;
Window w;
XSizeHints *hints;
The XSetWMNormalHints function replaces the size hints for the WM_NORMAL_HINTS property on the specified window. If the property does not already exist, 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.
XSetWMNormalHints can generate BadAlloc and BadWindow errors.
To read a window's WM_NORMAL_HINTS property, use XGetWMNormalHints.
Status XGetWMNormalHints(display, w, hints_return, supplied_return)
Display *display;
Window w;
XSizeHints *hints_return;
long *supplied_return;
The 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, XGetWMNormalHints sets the various fields of the 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.
If XGetWMNormalHints returns successfully and a pre-ICCCM size hints property is read, the supplied_return argument will contain the following bits:
(USPosition|USSize|PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect)
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:
XGetWMNormalHints can generate a BadWindow error.
To set a window's WM_SIZE_HINTS property, use XSetWMSizeHints.
void XSetWMSizeHints(display, w, hints, property)
Display *display;
Window w;
XSizeHints *hints;
Atom property;
The XSetWMSizeHints function replaces the size hints for the specified property on the named window. If the specified property does not already exist, 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 XSetWMNormalHints function.
XSetWMSizeHints can generate BadAlloc, BadAtom, and BadWindow errors.
To read a window's WM_SIZE_HINTS property, use XGetWMSizeHints.
Status XGetWMSizeHints(display, w, hints_return, supplied_return, property)
Display *display;
Window w;
XSizeHints *hints_return;
long *supplied_return;
Atom property;
The 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, XGetWMSizeHints sets the various fields of the 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 XGetWMNormalHints function.
If XGetWMSizeHints returns successfully and a pre-ICCCM size hints property is read, the supplied_return argument will contain the following bits:
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:
XGetWMSizeHints can generate BadAtom and BadWindow errors.
| Home |
|---|
Xlib provides functions that you can use to set and get the WM_CLASS property for a given window. These functions use the XClassHint structure, which is defined in the <X11/Xutil.h> header file.
To allocate an XClassHint structure, use XAllocClassHint.
The XAllocClassHint function allocates and returns a pointer to a XClassHint structure. Note that the pointer fields in the XClassHint structure are initially set to NULL. If insufficient memory is available, XAllocClassHint returns NULL. To free the memory allocated to this structure, use XFree.
The XClassHint contains:
| typedef struct { | |
| char
*res_name; char *res_class; | |
| } XClassHint; | |
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.
To set a window's WM_CLASS property, use XSetClassHint.
XSetClassHint(display, w, class_hints)
Display *display;
Window w;
XClassHint *class_hints;
The 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.
XSetClassHint can generate BadAlloc and BadWindow errors.
To read a window's WM_CLASS property, use XGetClassHint.
StatusXGetClassHint(display, w, class_hints_return)
Display *display;
Window w;
XClassHint *class_hints_return;
The 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 XFree on each individually.
XGetClassHint can generate a BadWindow error.
| Home |
|---|
Xlib provides functions that you can use to set and read the WM_TRANSIENT_FOR
property for a given window.
To set a window's WM_TRANSIENT_FOR property, use XSetTransientForHint.
The XSetTransientForHint function sets the WM_TRANSIENT_FOR
property of the specified window to the specified prop_window.
XSetTransientForHint
can generate BadAlloc and BadWindow errors.
To read a window's WM_TRANSIENT_FOR property, use XGetTransientForHint.
The 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.
XGetTransientForHint can generate a BadWindow error.
Xlib provides functions that you can use to set and read the WM_PROTOCOLS
property for a given window.
To set a window's WM_PROTOCOLS property, use XSetWMProtocols.
The 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,
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, XSetWMProtocols
returns a zero status. Otherwise, it returns a nonzero status.
XSetWMProtocols can generate BadAlloc and BadWindow
errors.
To read a window's WM_PROTOCOLS property, use XGetWMProtocols.
The 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, 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 XFree.
XGetWMProtocols can generate a BadWindow error.
Xlib provides functions that you can use to set and read the WM_COLORMAP_WINDOWS
property for a given window.
To set a window's WM_COLORMAP_WINDOWS property, use XSetWMColormapWindows.
The XSetWMColormapWindows function replaces the WM_COLORMAP_WINDOWS
property on the specified window with the list of windows specified
by the colormap_windows argument. It the property does not already
exist, 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, XSetWMColormapWindows returns a zero status. Otherwise,
it returns a nonzero status.
XSetWMColormapWindows can generate BadAlloc and
BadWindow errors.
To read a window's WM_COLORMAP_WINDOWS property, use XGetWMColormapWindows.
The 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, 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 XFree.
XGetWMColormapWindows can generate a BadWindow error.
Xlib provides functions that you can use to set and read the WM_ICON_SIZE
property for a given window. These functions use the XIconSize
structure, which is defined in the <X11/Xutil.h>
header file.
To allocate an XIconSize structure, use XAllocIconSize.
The XAllocIconSize function allocates and returns a pointer
to a XIconSize structure. Note that all fields in the XIconSize
structure are initially set to zero. If insufficient memory is
available, XAllocIconSize returns NULL. To free the memory
allocated to this structure, use XFree.
The XIconSize structure contains:
14.1.9. Setting and Reading the WM_TRANSIENT_FOR Property
XSetTransientForHint(display, w, prop_window)
Display *display;
Window w;
Window prop_window;
Status XGetTransientForHint (display, w, prop_window_return)
Display *display;
Window w;
Window *prop_window_return;
14.1.10. Setting and Reading the WM_PROTOCOLS Property
Status XSetWMProtocols(display, w, protocols, count)
Display *display;
Window w;
Atom *protocols;
int count;
Status XGetWMProtocols(display, w, protocols_return, count_return)
Display *display;
Window w;
Atom **protocols_return;
int *count_return;
Home
14.1.11. Setting and Reading the WM_COLORMAP_WINDOWS Property
Status XSetWMColormapWindows(display, w, colormap_windows, count)
Display *display;
Window w;
Window *colormap_windows;
int count;
Status XGetWMColormapWindows(display, w, colormap_windows_return, count_return)
Display *display;
Window w;
Window **colormap_windows_return;
int *count_return;
14.1.12. Setting and Reading the WM_ICON_SIZE Property
| typedef struct { | |
| int
min_width, min_height; int max_width, max_height; int width_inc, height_inc; | |
| } XIconSize; | |
The width_inc and height_inc members define an arithmetic progression of sizes (minimum to maximum) that represent the supported icon sizes.
To set a window's WM_ICON_SIZE property, use XSetIconSizes.
XSetIconSizes(display, w, size_list, count)
Display *display;
Window w;
XIconSize *size_list;
int count;
The XSetIconSizes function is used only by window managers to set the supported icon sizes. XSetIconSizes can generate BadAlloc and BadWindow errors.
To read a window's WM_ICON_SIZE property, use XGetIconSizes.
Status XGetIconSizes(display, w, size_list_return, count_return)
Display *display;
Window w;
XIconSize **size_list_return;
int *count_return;
The XGetIconSizes function returns zero if a window manager has not set icon sizes; otherwise, it return nonzero. XGetlconSizes 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 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 XFree.
XGetIconSizes can generate a BadWindow error.
| Home |
|---|
The 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.
The 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).
If the window_name argument is non-NULL, XmbSetWMProperties
sets the WM_NAME property. If the icon_name argument is non-NULL,
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".
If the normal_hints argument is non-NULL, XmbSetWMProperties
calls XSetWMNormalHints, which sets the WM_NORMAL_HINTS
property (see section 14.1.7). If the wm_hints argument is non-NULL,
XmbSetWMProperties calls XSetWMHints, which sets
the WM_HINTS property (see section 14.1.6).
If the argv argument is non-NULL, XmbSetWMProperties sets
the WM_COMMAND property from argv and argc. An argc of zero indicates
a zero-length command.
The hostname of the machine is stored using XSetWMClientMachine
(see section 14.2.2).
If the class_hints argument is non-NULL, XmbSetWMProperties
sets the WM_CLASS property. If the res_name member in the 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.
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.
For clients that need to process the property text in a locale,
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.
XmbSetWMProperties can generate BadAlloc and BadWindow
errors.
To set a window's standard window manager properties with strings
in client-specified encodings, use XSetWMProperties. The
standard window manager properties for a given window are WM_NAME,
WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINITS, WM_CLASS, WM_COMMAND,
and WM_CLIENT_MACHINE.
The 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).
If the window_name argument is non-NULL, XSetWMProperties
calls XSetWMName, which in turn, sets the WM_NAME property
(see section 14.1.4). If the icon_name argument is non-NULL, XSetWMProperties
calls XSetWMIconName, which sets the WM_ICON_NAME property
(see section 14.1.5). If the argv argument is non-NULL, XSetWMProperties
calls 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 XSetWMClientMachine (see section 14.2.2).
If the normal_hints argument is non-NULL, XSetWMProperties
calls XSetWMNormalHints, which sets the WM_NORMAL_HINTS
property (see section 14.1.7). If the wm_hints argument is non-NULL,
XSetWMProperties calls XSetWMHints, which sets the
WM_HINTS property (see section 14. 1.6).
If the class_hints argument is non-NULL, XSetWMProperties
calls XSetClassHint, which sets the WM_CLASS property (see
section 14.1.8). If the res_name member in the 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_narne 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.
XSetWMProperties can generate BadAlloc and BadWindow
errors.
This section discusses how to:
Xlib provides functions that you can use to set and read the WM_COMMAND
property for a given window.
To set a window's WM_COMMAND property, use XSetCommand.
The 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.
XSetCommand can generate BadAlloc and BadWindow
errors.
To read a window's WM_COMMAND property, use XGetCommand.
The 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, 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 XFreeStringList.
Xlib provides functions that you can use to set and read the WM_CLIENT_MACHINE
property for a given window.
To set a window's WM_CLIENT_MACHINE property, use XSetWMClientMachine.
The XSetWMClientMachine convenience function calls XSetTextProperty
to set the WM_CLIENT_MACHINE property.
To read a window's WM_CLIENT_MACHINE property, use XGetWMClientMachine.
The XGetWMClientMachine convenience function performs an
XGetTextProperty on the WM_CLIENT_MACHINE property. It
returns a nonzero status on success; otherwise, it returns a zero
status.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
To allocate an XStandardColormap structure, use XAllocStandardColormap.
XStandardColormap *XAllocStandardColormap ()
The XAllocStandardColormap function allocates and returns
a pointer to a XStandardColormap structure. Note that all
fields in the XStandardColormap structure are initially
set to zero. If insufficient memory is available, XAllocStandardColormap
returns NULL. To free the memory allocated to this structure,
use XFree.
The XStandardColormap structure contains:
14.1.13. Using Window Manager Convenience Functions
void XmbSetWMProperties(display, w, window_name, icon_name, argv, argc,
normal_hints, wm_hints, class_hints)
Display *display;
Window w;
char *window_name;
char *icon_name;
char *argv[];
int argc;
XSizeHints *normal_hints;
XWMHints *wm_hints;
XClassHint *class_hints;
void XSetWMProperties(display, w, window_name, icon_name, argv, argc, normal_hints, wm_hints,
class_hints)
Display *display;
Window w;
XTextProperty *window_name;
XTextProperty *icon_name;
char **argv;
int argc;
XSizeHints *normal_hints;
XWMHints *wm_hints;
XClassHint *class_hints;
Home
14.2. Client to Session Manager Communication
14.2.1. Setting and Reading the WM_COMMAND Property
XSetCommand(display, w, argv, argc)
Display *display;
Window w;
char **argv;
int argc;
Status XGetCommand(display, w, argv_return, argc_retarn)
Display *display;
Window w;
char ***argv_return;
int *argc_return;
14.2.2. Setting and Reading the WM_CLIENT_MACHINE Property
void XSetWMClientMachine(display, w, text_prop)
Display *display;
Window w;
XTextProperty *text_prop;
Status XGetWMClientMachine(display, w, text_prop_return)
Display *display;
Window w;
XTextProperty *text_prop_return;
Home
14.3. Standard Colormaps
| /* Hints */ | ||
| #define | ReleaseByFreeingColormap | ( (XID) 1L) |
| /* Values */ | |
| typedef struct { | |
| Colormap colormap;
unsigned long red_max; unsigned long red_mult; unsigned long green_max; unsigned long green_mult; unsigned long blue_max; unsigned long blue_mult; unsigned long base_pixel; VisualID visualid; XID killid; | |
| } XStandardColormap; | |
The colormap member is the colormap created by the 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.
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.
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 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:
For GrayScale colormaps, only the colormap, red_max, red_mult, and base_pixel members are defined. The other members are ignored. To compute a GrayScale pixel value, use the following expression:
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.
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 XKillClient function on the indicated resource. (Note that this method is necessary for allocating out of an existing colormap.)
The properties containing the XStandardColormap information have the type RGB_COLOR_MAP.
The remainder of this section discusses standard colormap properties
and atoms as well as how to manipulate standard colormaps.
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 <X11/Xatom.h>
header file contains the definitions for each of the following
atoms, which are prefixed with XA_.
Xlib provides functions that you can use to set and obtain an
XStandardColormap structure.
To set an XStandardColormap structure, use XSetRGBColormaps.
The XSetRGBColormaps function replaces the RGB colormap
definition in the specified property on the named window. If the
property does not already exist, 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.
The XSetRGBColormaps function usually is only used by window
or session managers. To create a standard colormap, follow this
procedure:
XSetRGBColormaps can generate BadAlloc, BadAtom,
and BadWindow errors.
To obtain the XStandardColormap structure associated with
the specified property, use XGetRGBColormaps.
The 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, XGetRGBColormaps
allocates and fills in space for the returned colormaps and returns
a nonzero status. If the visualid is not present, XGetRGBColormaps
assumes the default visual for the screen on which the window
is located; if the killid is not present, None is assumed,
which indicates that the resources cannot be released. Otherwise,
none of the fields are set, and 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.
XGetRGBColormaps can generate BadAtom and BadWindow
errors.
14.3.1. Standard Colormap Properties and Atoms
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.
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.
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.
For
an 8-plane PseudoColor visual, RGB_BEST_MAP is likely to
be a 3/3/2 allocation. For a 24-plane DirectColor visual,
RGB_BEST_MAP is normally an 8/8/8 allocation.
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.
The property describes the best GrayScale
colormap available on the screen. As previously mentioned, only
the colormap, red_max, red_mult, and base_pixel members of the
XStandardColormap structure are used for GrayScale
colormaps.
14.3.2. Setting and Obtaining Standard Colormaps
void XSetRGBColorrnaps(display, w, std_colormap, count, property)
Display *display;
Window w;
XStandardColormap *std_colormap;
int count;
Atom property;
Status XGetRGBColormaps(display, w,
std_colormap_return, count_rerurn, property)
Display *display;
Window w;
XStandardColormap **std_colormap_ return;
int *count_return;
Atom property;
Home
Contents
Previous Chapter
Next Chapter