In most cases, a client communicates information about its windows to the window and session managers. For example, the client may want to provide the window manager with names for a specific window and icon. In addition, the client may want to provide hints to the window manager concerning window size and location. The X Consortium approves of certain methods and routines that govern this inter-client communication.

The Inter-Client Communications Conventions Manual (ICCCM) details these methods and, through their use, ensures compatibility in a multi-client environment. The X Window System contains the Inter-Client Communications Conventions Manual.

This chapter provides information and examples for communicating with the window manager using Xlib ICCCM-compliant routines and properties. For a reference to all Xlib ICCCM-compliant routines, see the X Window System. For more information about properties, see Chapter 8.

12.1 Communicating with Standard Properties

Xlib provides predefined properties to enable clients to communicate with the window manager and session manager about the following:

• Window names
• Icon names
• Pixmaps used to define window icons
• Commands used to start the application
• Position and size of windows in their startup state
• Initial state of windows
• Input that windows accept
• Names used to retrieve application resources

Table 12-1 describes the atom names, data types, and formats of these properties.

Table 12-1 Atom Names of Standard Properties

Atom	Data Type	Format	Description
XA_WM_CLASS	text	32	Application resources from the resource database
XA_WM_CLIENT_MACHINE	text	N/A	String name of the machine on which the client application is running
XA_WM_COLORMAP_WINDOWS	window	32	List of window IDs that may need a different colormap than that of their top-level window
XA_WM_COMMAND	text	8	Command used to start the client
XA_WM_HINTS	wm_hints	32	Hints about keyboard input, initial state, icon pixmap, icon window, icon position, and icon mask
XA_WM_ICON_NAME	text	8	Icon name
XA_WM_ICON_SIZE	wm_icon_size	32	Icon size supported by the window manager
XA_WM_NAME	string	8	Application name
XA_WM_NORMAL_HINTS	wm_size_hints	32	Size hints for a window in its normal state
XA_WM_PROTOCOLS	atom	32	List of atoms that identify the communications protocols between the client and the window manager
XA_WM_STATE	wm_state	32	Property intended for communicating between window manager and session manager
XA_WM_TRANSIENT_FOR	window	32	Property intended for a window that is transient, such as a dialog box

The remainder of this chapter illustrates how to use many of these properties.

12.2 Manipulating Top-Level Windows

Xlib provides routines that the client can use to change the visibility or size of top-level windows. Example 12-1 illustrates the use of the ICONIFY WINDOW and RECONFIGURE WINDOW routines. In the example, the client shrinks the window to an icon ten seconds after the client exposes the window. The user can also reconfigure the window by pressing MB2. Pressing MB3 unmaps and destroys the window.

It is important to note that the window manager ignores any subwindow of the top-level window. To manipulate subwindows, use the routines described in Chapter 3.

Example 12-1 Reconfiguring a Top-Level Window

#include <decw$include/Xlib.h> #include <decw$include/Xutil.h> #define FontName\ "-Adobe-New Century Schoolbook-Bold-I-NormaL--*-140-*-*-P-*-ISO8859-1" #define WindowName "Manipulating Top-Level Windows" Display *dpy; Window window; GC gc; Screen *screen; int scrNum; int n, i, y, state = 0; char *message[]= { "This window shrinks to an icon in 10 seconds.", "Click MB2 to reconfigure the window.", "Click MB3 to exit." }; float wait_time=10.0; . . . /***** Handle events *****/ static void doHandleEvents( ) { XEvent event; XNextEvent(dpy, &event); (1) doExpose(&event); (2) doWait_Iconify(); for ( ; ; ) { XNextEvent(dpy, &event); switch (event.type) { case Expose: doExpose(&event); break; case ButtonPress: doButtonPress(&event); break; } } } /***** Expose Event *****/ static void doExpose(eventP) XEvent *eventP; { if (eventP->xexpose.window != window) return; XClearWindow(dpy, window); for (y=75, i=0; i<3; y+=25, i++) { XDrawString(dpy, window, gc, 25, y, message[i], strlen(message[i])); } } /***** Wait, then shrink the window to an icon *****/ static void doWait_Iconify() { (3) lib$wait(&wait_time); XIconifyWindow(dpy, window, scrNum); return; } /***** Shutdown *****/ static void doButtonPress(eventP) XEvent *eventP; { if (eventP->xbutton.button == Button2) { XWindowChanges xwc; xwc.x = 200; xwc.y = 200; xwc.width = 600; xwc.height = 600; (4) XReconfigureWMWindow(dpy, window, scrNum, CWX | CWY | CWWidth | CWHeight, &xwc); return; } (5) if (eventP->xbutton.button == Button3) { XWithdrawWindow(dpy, window, scrNum); XCloseDisplay(dpy); sys$exit (1); } }

1. After the first expose event, the client calls the client-defined doExpose routine, which clears and draws the text in the window.
2. The client calls the client-defined routine doWait_Iconify.
3. The doWait_Iconify routine calls the Run-Time Library routine LIB$WAIT and waits ten seconds before shrinking the top-level window to an icon. The ICONIFY WINDOW routine sends a WM_CHANGE_STATE ClientMessage event to the root window of the specified screen. The routine returns a nonzero status if the client message is sent successfully; otherwise, it returns a zero status.
   The ICONIFY WINDOW routine has the following format:

   XIconifyWindow(display, window, screen_number)

4. The client has specified an interest in MB2 or MB3 button press events. If the user presses MB2, then the client reconfigures the window by calling the RECONFIGURE WINDOW routine. The RECONFIGURE routine requests that a top-level window be reconfigured as specified by the window changes data structure.
   The RECONFIGURE WINDOW routine has the following format:

   XReconfigureWindow(display, window, screen_number, value_mask, values)

   
   For more information about reconfiguring windows, refer to Chapter 3.

5. When the user presses MB3, the client exits.

This section describes how to communicate with the window manager by defining individual properties. Example 12-2 illustrates how to set these properties by using the following Xlib routines:

SET WM NORMAL HINTS
SET WM HINTS
SET WM WINDOW NAME
SET WM ICON NAME
SET CLASS HINT

Xlib also provides the convenience routine, SET WM PROPERIES, which allows the client to set the standard window manager properties with a single function. Example 12-3 illustrates how to use the SET WM PROPERTIES routine.

12.3.1 Setting Window Manager Hints

Xlib provides routines to set and read the WM_HINTS property. Use the WM hints data structure and the SET WM HINTS routine to provide the window manager with hints about keyboard input, initial window state, icon pixmap, icon window, icon position, icon mask, and window group. Use the GET WM HINTS routine to read the WM_HINTS property. Example 12-2 illustrates using the SET WM HINTS routine to provide hints about managing the initial state and icon pixmap of the window.

Note that each time the WM hints data structure is passed to SET WM HINTS, the flags field specifies only which fields are valid, not which fields are updated. Setting one flag and passing one value states that all other values are no longer valid. For those flags not set, the window manager uses the default values.

Table 12-2 lists the flags.

Table 12-2 Window Manager Hints Data Structure Flags

Flag Name	Description
Input Hint	Input focus model used by the client
StateHint	Initial state of the window
IconPixmapHint	Pixmap used as an icon
IconWindowHint	Window used as an icon
IconPositionHint	Initial position of icon
IconMaskHint	Pixmap to be used as a mask for the icon_pixmap
WindowGroupHint	ID of related window group
AllHints	The bitwise OR of InputHint, StateHint, IconPixmapHint, IconWindowHint, IconPositionHint, IconMaskHint, and WindowGroupHint

The following illustrates the WM hints data structure:

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; } XWMHints;

Table 12-3 defines the members of the data structure.

Table 12-3 WM Hints Data Structure Members

Member Name	Contents
flags	Specifies the members of the data structure that are defined.
input	Indicates whether or not the client relies on the window manager to get keyboard input.
initial_state	Defines how the window should appear in its initial configuration. Possible initial states are as follows: Constant Name Description WithdrawnState Neither client's top-level window nor icon window is visible. NormalState Client's top-level window is visible. IconicState Client's top-level window starts as an icon.
icon_pixmap	Identifies the pixmap used to create the window icon.
icon_window	Specifies the window to be used as an icon.
icon_x	Specifies the initial x-coordinate of the icon position.
icon_y	Specifies the initial y-coordinate of the icon position.
icon_mask	Specifies the pixels of the icon pixmap used to create the icon.
window_group	Specifies that a window belongs to a group of other windows.

12.3.2 Providing Size Hints

Xlib provides routines that the client can use to set or read the WM_NORMAL_HINTS property for a given window. These routines use the size hints data structure to communicate to the window manager about the size and position of windows in their normal and iconic startup states.

Use the SET WM NORMAL HINTS routine to set a window's WM_NORMAL_HINTS property. Use the GET WM NORMAL HINTS routine to read a window's WM_NORMAL_HINTS property. Example 12-2 illustrates the use of the SET WM NORMAL HINTS routine.

Table 12-4 lists the flags used in the size hints data structure.

Table 12-4 Size Hints Data Structure Flags

Flag Name	Description
USPosition	User-specified position of the window (obsolete)
USSize	User-specified size of the window (obsolete)
PPosition	Client-specified position of the window (obsolete)
PSize	Client-specified size of the window (obsolete)
PMinSize	Client-specified minimum size of the window
PMaxSize	Client-specified maximum size of the window
PResizeInc	Client-specified increments for resizing the window
PAspect	Client-specified minimum and maximum aspect ratios of the window
PBaseSize	Client-specified desired size of the window
PWinGravity	Client-specified window gravity
PAllHints	The bitwise OR of PPosition, PSize, PMinSize, PMaxSize, PResizeInc, and PAspect

The following illustrates the size hints data structure:

typedef struct { long flags; 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; int y; }min_aspect, max_aspect; int base_width, base_height; int win_gravity; }XSizeHints;

Table 12-5 describes the data structure contents.

Table 12-5 Size Hints Data Structure Members

Member Name	Contents
flags	Defines the members to which the client is assigning values
x	Specifies the x-coordinate that defines window position
y	Specifies the y-coordinate that defines window position
width	Defines the width of the window
height	Defines the height of the window
min_width	Specifies the minimum useful width of the window
min_height	Specifies the minimum useful height of the window
max_width	Specifies the maximum useful width of the window
max_height	Specifies the maximum useful height of the window
width_inc	Defines the increments by which the width of the window can be resized
height_inc	Defines the increments by which the height of the window can be resized
min_aspect_x 1	Specifies the minimum aspect ratio of the window when used with the min_aspect y member.
min_aspect_y 1	Specifies the minimum aspect ratio of the window with the min_aspect x member.
max_aspect_x 1	Specifies the maximum aspect ratio of the window with the max_aspect y member.
max_aspect_y 1	Specifies the maximum aspect ratio of the window with the max_aspect_x member.
base_width	Defines the desired width of the window
base_height	Defines the desired height of the window
win_gravity	Defines the region of the window that is to be retained when it is resized

By setting the max_width and max_height members, the client can set a meaningful maximum window size to make the maximize operation useful. If these members are not set, then the default maximum size of the window is the screen size.

12.3.3 Setting Window and Icon Names

Xlib includes routines to enable clients to define properties for communicating with the window manager about window names, icon names, and window classes. Use the SET WM NAME routine to set the WM_NAME property to display the name for a given window. Use the SET WM ICON NAME routine to set the WM_ICON_NAME property to set the name of a given window icon name. Example 12-2 illustrates how to use these routines.

Both the SET WM NAME and SET WM ICON NAME routines are convenience functions that use the text property data structure and call the SET TEXT PROPERTY routine. The following illustrates the text property data structure:

typedef struct{ unsigned char *value; Atom encoding; int format; unsigned long items; }XTextProperty

Table 12-6 describes the members of the data structure.

Table 12-6 Text Property Data Structure Members

Member Name	Contents
value	Character string
encoding	Type of property
format	Number of bits: 8, 16, or 32
nitems	Number of items in value

Xlib provides an additional routine to set a window name. The STORE NAME routine assigns a name to a window and displays it in a prominent place such as in the title bar. Example 1-1 in Chapter 1 uses the STORE NAME routine to define the name of the client's parent window, as follows:

XStoreName(dpy, window1, WindowName);

To define and get the class of a specified window, use the SET CLASS HINT and GET CLASS HINT routines. The routines refer to the class hint data structure. The following illustrates the class hint data structure:

typedef struct { char *res_name; char *res_class; } XClassHint;

Table 12-7 defines the members of the data structure. For more information about a window's class, refer to Chapter 10.

Table 12-7 Class Hint Data Structure Members

Member Name	Contents
res_name	Defines the name of the window
res_class	Defines the class of the window

Note that the name defined in this data structure may differ from the name defined by the XA_WM_NAME property. The XA_WM_NAME property specifies what should be displayed in the title bar. Consequently, it may contain a temporary name, as in the name of a file that a client currently has in a buffer. In contrast to XA_WM_NAME, the res_name member defines the formal window name that clients should use when retrieving resources from the resource database. For more information about using the X resource manager, see Chapter 10.