HP OpenVMS Systems Documentation

1. The client assigns window width and height the value of 600 (pixels) each.
2. The client specifies the position of the window using two display information routines, WIDTH OF SCREEN and HEIGHT OF SCREEN. The x and y coordinates define the top left outside corner of the window borders relative to the inside of the parent border. In this case, the parent is the root window, which does not have a border.
3. The CREATE SIMPLE WINDOW routine call has the following format:

   window_id = XCreateSimpleWindow(display, parent_id, x_coord, y_coord, width, height, border_width, border_id, background_id)

   
   The client specifies a black border ten pixels wide, a white background, and a size of 600 by 600 pixels.
   The window manager overrides border width and color.
   CREATE SIMPLE WINDOW returns a unique identifier, win1, used in subsequent calls related to the window.

To create a window whose attributes are different from the parent window, use the CREATE WINDOW routine. The CREATE WINDOW routine enables clients to specify the following window attributes when creating an input-output window:

• Default contents of an input-output window
• Border of an input-output window
• Treatment of the window when it or its relative is obscured
• Treatment of the window when it or its relative is moved
• Information the window receives about operations associated with other windows
• Color
• Cursor

Clients creating input-only windows can define the following attributes:

• Treatment of the window when it or its relative is moved
• Information the window receives about operations associated with other windows
• Cursor

Specifying other attributes for an input-only window causes the server to generate an error. Input-only windows cannot have input-output windows as children.

Use the following method to define window attributes:

1. Assign values to the relevant members of a set window attributes data structure.
2. Indicate the defined attribute by specifying the appropriate flag in the value_mask argument of the CREATE WINDOW routine. If more than one attribute is to be defined, indicate the attributes by doing a bitwise OR on the appropriate flags.

The following illustrates the set window attributes data structure:

typedef struct {
    Pixmap background_pixmap;
    unsigned long background_pixel;
    Pixmap border_pixmap;
    unsigned long border_pixel;
    int bit_gravity;
    int win_gravity;
    int backing_store;
    unsigned long backing_planes;
    unsigned long backing_pixel;
    Bool save_under;
    long event_mask;
    long do_not_propagate_mask;
    Bool override_redirect;
    Colormap colormap;
    Cursor cursor;
} XSetWindowAttributes;

Table 3-1 describes the members of the data structure.

Table 3-2 lists default values for the set window attributes data structure.

Xlib assigns a flag for each member of the set window attributes data structure to facilitate referring to the members, as listed in Table 3-3.

Example 3-2 illustrates how clients can define window attributes while creating input-output windows with the CREATE WINDOW routine. The program creates a parent window and two children windows. The hierarchy of the subwindows is determined by the order in which the program creates them. In this case, subwin1 is superior to subwin2, which is created last.

Window window, subwindow1,subwindow2;
int n;
                    .
                    .
                    .
static void doCreateWindows( )
{
    int windowW = 600;
    int windowH = 600;
    int windowX = (WidthOfScreen(screen)-windowW)>>1;
    int windowY = (HeightOfScreen(screen)-windowH)>>1;
    int subwindow1X = 150;
    int subwindow1Y = 100;
    int subwindow1W = 300;
    int subwindow1H = 400;
    int subwindow2X = 275;
    int subwindow2Y = 125;
    int subwindow2W =  50;
    int subwindow2H = 150;
(1)  XSetWindowAttributes xswa;
                    .
                    .
                    .

    /* Create the window window */

(2)  xswa.event_mask = ExposureMask | ButtonPressMask;
    xswa.background_pixel = doDefineColor(1);

(3)  window = XCreateWindow(dpy, XRootWindowOfScreen(screen),
        windowX, windowY, windowW, windowH, 0,
        XDefaultDepthOfScreen(screen), InputOutput,
        XDefaultVisualOfScreen(screen), CWEventMask | CWBackPixel, &xswa);

    /* Create the window subwindow1 */

    xswa.background_pixel = doDefineColor(3);

    subwindow1 = XCreateWindow(dpy, window, subwindow1X, subwindow1Y, subwindow1W,
        subwindow1H, 4, XDefaultDepthOfScreen(screen), InputOutput,
        XDefaultVisualOfScreen(screen), CWEventMask | CWBackPixel, &xswa);

    /* Create the window subwindow2 */

    xswa.background_pixel = doDefineColor(3);

    subwindow2 = XCreateWindow(dpy, window, subwindow2X, subwindow2Y, subwindow2W,
        subwindow2H, 4, XDefaultDepthOfScreen(screen), InputOutput,
        XDefaultVisualOfScreen(screen), CWEventMask | CWBackPixel, &xswa);
}
                    .
                    .
                    .
static int doDefineColor(n)
{
                    .
                    .
                    .

1. Allocate storage for a set window attributes data structure used to define window attributes.
2. Set the attributes of the parent window. The client indicates an interest in window exposure and button press events. For more information about events, see Chapter 9.
   The client defines the window background by calling the client-defined doDefineColor routine. For more information about defining colors, see Chapter 5.
3. The CREATE WINDOW routine call has the following format:

   window_id_return=XCreateWindow(display, parent_id, x_coord, y_coord, width, height, border_width, depth, class, visual_struc, attributes_mask, attributes)

   
   The depth of a window is its number of bits per pixel. The call passes a display information routine to indicate that the client wants the parent window depth to be identical to the display depth.
   The window class can be either input only or input-output, specified by the following constants:

   • InputOnly
   • InputOutput
   
   If the window is the same class as the parent, pass the constant CopyFromParent.
   The visual type indicates how the window displays color values. For more information about visual types, see Chapter 5.

When a client no longer needs a window, the client should destroy it using either the DESTROY WINDOW or the DESTROY SUBWINDOWS routine. DESTROY WINDOW destroys a specified window and all its subwindows. DESTROY SUBWINDOWS destroys all subwindows of a specified window in bottom-to-top stacking order.

Destroying a window frees all storage allocated for that window. If the window is mapped to the screen, the server notifies all applications that the window has been destroyed.

3.4 Mapping and Unmapping Windows

After creating a window, the client can map it to a screen using the MAP WINDOW or MAP SUBWINDOWS routine. Mapping generally makes a window visible at the location the client specified when creating it. Part or all of the window is not visible when the following conditions occur:

• One or more windows higher in the stacking order obscure it
• One or more window ancestors are not mapped
• The new window extends beyond the boundary of its parent

MAP WINDOW maps a window. If the window is an inferior, and one or more of its ancestors have not been mapped, the server considers the window to be mapped after the call, even though the window is not visible on the screen. The window becomes visible when its ancestors are mapped.

To map all subwindows of a specified window in top-to-bottom order, use MAP SUBWINDOWS. Using the MAP SUBWINDOWS routine to map several windows may be more efficient than calling the MAP WINDOW routine to map each window. The MAP SUBWINDOWS routine enables the server to map all of the windows at one time instead of mapping a single window with the MAP WINDOW routine.

To ensure that the window is completely visible, use the MAP RAISED routine. MAP RAISED reorders the stack with the window on top and then maps the window. Example 3-3 illustrates how a window is mapped and raised to the top of the stack.

Window window,subwindow1,subwindow2;

    /* Create windows in the following order: window, subwindow2, subwindow1 */
                    .
                    .
                    .
static void doMapWindows( )
{
    XMapWindow(dpy, window);
(1)  XMapWindow(dpy, subwindow2);
(2)  XMapRaised(dpy, subwindow1);
}

1. In this example, the client created subwindow1 after subwindow2, putting subwindow1 at the top of the stack.
   Consequently, whether subwindow2 were to be mapped before or after subwindow1, subwindow1 would obscure subwindow2.
   The effect is illustrated in Figure 3-5.
2. Mapping and raising subwindow2 moves it to the top of the stack. It is now visible, as Figure 3-6 illustrates.

When the client no longer needs a window mapped to the screen, call UNMAP WINDOW. If the window is a parent, its children are no longer visible after the call, although they are still mapped. The children become visible when the parent is mapped again.

To unmap all subwindows of a specified window, use UNMAP SUBWINDOWS. UNMAP SUBWINDOWS results in an UNMAP WINDOW call on all subwindows of the parent, from bottom-to-top stacking order.

Figure 3-5 Window Before Restacking

Figure 3-6 Restacked Window

Xlib enables clients to associate data with a window. This data is considered a property of the window. For example, a client could store text as a window property. Although a property must be data of only one type, it can be stored in 8-bit, 16-bit, and 32-bit formats.

Xlib uses atoms to uniquely identify properties. An atom is a string paired with an identifier. For example, a client could use the atom XA_WM_ICON_NAME to name a window icon stored for later use. The atom XA_WM_ICON_NAME pairs the string XA_WM_ICON_NAME with a value, 37, that uniquely identifies a property.

In DECW$INCLUDE:XATOMS.H, VMS DECwindows includes predefined atoms such as XA_WM_ICON_NAME for commonly used properties. Table 3-4 lists by function all predefined atoms except those used to identify font properties and atoms used to communicate with the window manager. See Chapter 12 for a list of atoms related to window management. See Chapter 8 for a list of atoms related to fonts.

In addition to providing predefined atoms, Xlib enables clients to create atom names of their own. To create an atom name, use the INTERN ATOM routine, as in the following example:

               .
               .
               .
    Atom atom_id;
    char *name = "MY_ATOM";
    Bool if_exists;

    atom_id =  XInternAtom(dpy, name, if_exists);
               .
               .
               .

The routine returns an identifier associated with the string MY_ATOM. If the atom does not exist in the atom table, Xlib returns the value none. Note that any atom identifier and its associated name remain defined until the server is reset. Example 3-4 uses the INTERN ATOM routine to exchange properties between two windows.

To get the name of an atom, use the GET ATOM NAME routine, as in the following example:

              .
              .
              .
    char *name;
    Atom atom_id = 39;

    name = XGetAtomName(dpy, atom_id);
              .
              .
              .

The routine returns a string associated with the atom identifier.

Xlib enables clients to change, obtain, update, and interchange properties. Example 3-4 illustrates exchanging properties between two subwindows. The example uses the CHANGE PROPERTY routine to set a property on the parent window and the GET PROPERTY routine to get the data from the parent window. In addition, the example uses the INTERN ATOM routine.

#define windowWidth      600
#define windowHeight     600
#define subwindowWidth   300
#define subwindowHeight  150
#define true 1

display *dpy;
window win, subwin1, sunwin2;
gc gc;
screen *screen;
int n;
atom atom_id;
char *name = "my_atom";
bool if_exists;
                    .
                    .
                    .

static void doCreateWindows( )
{
    int winW = windowWidth;
    int winH = windowHeight;
    int winX = 100;
    int winY = 100;
    int subwindow1X = 150;
    int subwindow1Y = 100;
    int subwindow2X = 150;
    int subwindow2Y = 350;
    XSetWindowAttributes xswa;

    /* Create the win window */

    xswa.event_mask = ExposureMask | ButtonPressMask | PropertyChangeMask;
    xswa.background_pixel = doDefineColor(1);

    win = XCreateWindow(dpy, RootWindowOfScreen(screen),
        winX, winY, winW, winH, 0,
        DefaultDepthOfScreen(screen), InputOutput,
        DefaultVisualOfScreen(screen), CWEventMask | CWBackPixel, &xswa);

    /* Create the subwindows */
    xswa.event_mask = ExposureMask| ButtonPressMask;
    xswa.background_pixel = doDefineColor(2);

    subwin1 = XCreateWindow(dpy, win, subwindow1X, subwindow1Y, subwindowWidth,
        subwindowHeight, 0, DefaultDepthOfScreen(screen), InputOutput,
        DefaultVisualOfScreen(screen), CWEventMask | CWBackPixel, &xswa);
    subwin2 = XCreateWindow(dpy, win, subwindow2X, subwindow2Y, subwindowWidth,
        subwindowHeight, 0, DefaultDepthOfScreen(screen), InputOutput,
        DefaultVisualOfScreen(screen), CWEventMask | CWBackPixel, &xswa);
                    .
                    .
                    .
/***** Handle events ******/
static void doHandleEvents( )
{
    XEvent event;

    for ( ; ; ) {
        XNextEvent(dpy, &event);
        switch (event.type) {
            case Expose:                doExpose(&event); break;
            case ButtonPress:           doButtonPress(&event);break;
            case PropertyNotify:        doPropertyNotify(&event);break;
        }
    }
}
                    .
                    .
                    .
/***** Handle button presses *******/
static void doButtonPress(eventP)
XEvent *eventP;
{
    char *property_data = "You clicked MB1";

    if (eventP->xbutton.button == Button2) sys$exit(1);
    if (eventP->xbutton.window == subwin1 && eventP->xbutton.button == Button1)
(1)      XChangeProperty(dpy, win, atom_id, XA_STRING, 16,
            PropModeReplace, property_data, 15);
    return;
}
/***** Get the property and draw text into the subwindow *******/
static void doPropertyNotify(eventP)
XEvent *eventP;
{
    long offset = 0;
    long length = 1000;
    Atom type_returned;
    int format_returned;
    unsigned long num_items_returned, bytes_remaining;
    unsigned char *property_returned;

    if (eventP->xproperty.atom == atom_id){
(2)      XGetWindowProperty(dpy, win, atom_id, offset, length,
            true, XA_STRING, &type_returned, &format_returned,
            &num_items_returned, &bytes_remaining, &property_returned);

(3)      XDrawString(dpy, subwin2, gc, 75, 75, property_returned,
            num_items_returned);
    }
    return;
}