HP OpenVMS Systems Documentation

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.

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.

#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.

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.

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.

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.

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.

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.

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.