HP OpenVMS Systems Documentation

1. When the user clicks MB1 in subwindow subwin1, the client calls the CHANGE PROPERTY routine. CHANGE PROPERTY causes the server to change the property identified by the atom atom_id to the value specified by property_data. The property is associated with the parent window, win.
   When changing properties, clients can specify how the server should treat the property. If the client specifies the constant PropModeReplace, the server discards the previous property. If the client specifies the constant PropModePrepend, the server inserts the new data at the beginning of the existing property data. If the client specifies the constant PropModeAppend, the server inserts the new data at the end of the existing property data.
   Changing the property causes the server to send a property notify event to win. For information about event handling, see Chapter 9.
2. After checking to ensure that the changed property is the one to obtain, the client calls the GET WINDOW PROPERTY routine.
3. After getting the string data from the parent window, the client uses it to write text in subwin2. For information about writing text, see Chapter 8.

In addition to the GET WINDOW PROPERTY routine, Xlib includes the property-management routines described in Table 3-5.

Xlib provides routines that enable clients to exchange properties. The properties, which are global to the server, are called selections. Text cut from one window and pasted into another window exemplifies the global exchange of properties. The text cut in window A is a property owned by client A. Ownership of the property transfers to client B, who then pastes the text into window B.

Properties are exchanged between clients by a series of calls to routines that manage the selected text. When a user drags the pointer cursor, client A responds by calling the SET SELECTION OWNER routine. SET SELECTION OWNER identifies client A as the owner of the selected text. The routine also identifies the window of the selection, associates an atom with the text, and puts a time-stamp on the selection. The atom, XA_PRIMARY, names the selection. The time-stamp enables any clients competing for the selection to determine selection ownership.

Clients can determine the owner of a selection by calling the GET SELECTION OWNER routine. This routine returns the identifier of the window that currently owns the specified selection.

By calling the CONVERT SELECTION routine, clients ask the owner of a selection to convert it to a particular data type. If conversion is possible, the client converting the selection notifies the client requesting the conversion that the selection is available. The property is then exchanged.

For example, when a user decides to paste the selected text in window B, client B, who owns window B, sends client A a selection request. The request identifies the window requesting the cut text and the format in which the client would like the property transferred.

In response to the request, client A first checks to ensure that the time of the request corresponds to the time in which client A owns the selection. If the time coincides and if client A can convert the selection to the data type requested by client B, client A notifies client B that the text is stored and available. Client B then retrieves the data by calling the GET WINDOW PROPERTY routine.

Clients request and notify other clients of selections by using events. For information about using events to request, convert, and notify clients of selections, see Chapter 9. For style guidelines about using selections, see the OSF/Motif Style Guide.

3.7 Changing Window Characteristics

Xlib provides routines that enable clients to change window position, size, border width, stacking order, and attributes.

This section describes how to use Xlib routines to do the following:

• Change multiple window characteristics in one call
• Change position, size, or border width
• Change stacking order
• Change window attributes

Xlib enables clients either to change window characteristics using one call or to use individual routines to reposition, resize, or change border width.

The CONFIGURE WINDOW routine enables clients to change window position, size, border width, and place in the hierarchy. To change these window characteristics in one call, use the CONFIGURE WINDOW routine, as follows:

1. Set values of relevant members of a window changes data structure.
2. Indicate what is to be reconfigured by specifying the appropriate flag in the CONFIGURE WINDOW value_mask argument.

The window changes data structure enables clients to specify one or more values for reconfiguring a window. The following illustrates the window changes data structure:

typedef struct {
    int x, y;
    int width, height;
    int border_width;
    Window sibling;
    int stack_mode;
} XWindowChanges;

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

The client can change the hierarchical position of a window in relation to all windows in the stack or to a specified sibling. If the client changes the size, position, and stacking order of the window by calling CONFIGURE WINDOW, the server restacks the window based on its final, not initial, size and position. Table 3-7 lists constants and definitions for restacking windows.

Xlib assigns a symbol to the flag associated with each member of the data structure (Table 3-8).

Example 3-5 illustrates using CONFIGURE WINDOW to change the position, size, and stacking order of a window when the user presses a button.

    /* This program changes the position, size, and stacking
       order of subwindow1 */

static void doButtonPress(eventP)
XEvent *eventP
{
    XWindowChanges xwc;

(1)  xwc.x = 200;
    xwc.y = 350;
    xwc.width = 200;
    xwc.height = 50;
    xwc.sibling = subwindow2;
    xwc.stack_mode = Above;

(2)  XConfigureWindow(dpy, subwindow1, CWX | CWY | CWWidth | CWHeight | CWSibling
            | CWStackMode, &xwc);
}

1. Assign values to relevant members of the window changes data structure. Because the client identifies a sibling (subwindow1), it must also choose a mode for stacking operations.
2. The call to reconfigure subwindow1. The CONFIGURE WINDOW routine call has the following format:

   XConfigureWindow(display, window_id, change_mask, values)

   
   Create a mask by performing a bitwise OR operation on relevant flags that indicate which members of WINDOW CHANGES the client has defined.

Figure 3-7 illustrates how the windows look after being reconfigured.

Figure 3-7 Reconfigured Window

Table 3-9 lists routines to change individual window characteristics.

It is important to know how reconfiguring windows affects graphics and text drawn in them by the client. (See Chapter 6 for a description of working with graphics and Chapter 8 for a description of writing text.) When a client resizes a window, window contents are either moved or lost, depending on the bit gravity of the window. Bit gravity indicates that a designated region of the window should be relocated when the window is resized. Resizing also causes the server to resize children of the changed window.

To control how the server moves children when a parent is resized, set the window gravity attribute. Table 3-10 lists choices for retaining window contents and controlling how the server relocates children.

The client can change the hierarchical position of a window in relation to either all windows in the stack or to a specified sibling. If the client changes the size, position, and stacking order of the window by calling CONFIGURE WINDOW, the server restacks the window based on its final, not initial, size and position. Table 3-7 lists constants and definitions for restacking windows.

Figure 3-8 illustrates how the server moves the contents of a reconfigured window when the bit gravity is set to the constant EastGravity.

Figure 3-9 illustrates how the server moves a child window if its parent is resized and its window gravity is set to the constant NorthwestGravity.

Figure 3-8 East Bit Gravity

Figure 3-9 Northwest Window Gravity

Xlib provides routines that alter the window stacking order in the following ways:

• A specified window moves to either the top or the bottom of the stack.
• The lowest mapped child obscured by a sibling moves to the top of the stack.
• The highest mapped child that obscures a sibling moves to the bottom of the stack.

Use the RAISE WINDOW and LOWER WINDOW routines to move a specified window to either the top or the bottom of the stack, respectively.

To raise the lowest mapped child of an obscured window to the top of the stack, call CIRCULATE SUBWINDOWS UP. To lower the highest mapped child that obscures another child, call CIRCULATE SUBWINDOWS DOWN. The CIRCULATE SUBWINDOWS routine enables the client to perform these operations by specifying either the constant RaiseLowest or the constant LowerHighest.

To change the order of the window stack, use RESTACK WINDOW, which changes the window stack to a specified order. Reordered windows must have a common parent. If the first window the client specifies has other unspecified siblings, its order relative to those siblings remains unchanged.

3.7.4 Changing Window Attributes

Xlib provides routines that enable clients to change the following:

• 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

Section 3.2.2 includes descriptions of window attributes and their relationship to the set window attributes data structure.

This section describes how to change any attribute using the CHANGE WINDOW ATTRIBUTES routine. In addition to CHANGE WINDOW ATTRIBUTES, Xlib includes routines that enable clients to change background and border attributes. Table 3-11 lists these routines and their functions.

To change any window attribute, use CHANGE WINDOW ATTRIBUTES as follows:

1. Assign a value to the relevant member of a set window attributes data structure.
2. Indicate the attribute to change by specifying the appropriate flag in the CHANGE WINDOW ATTRIBUTES value_mask argument. To define more than one attribute, indicate the attributes by doing a bitwise OR on the appropriate flags.

See Table 3-3 for symbols Xlib assigns to each member to facilitate referring to the attributes.

Example 3-6 illustrates using CHANGE WINDOW ATTRIBUTES to redefine the characteristics of a window.

    XSetWindowAttributes  xswa;

(1)  xswa.background_pixel = BlackPixelOfScreen(dpy);
    xswa.border_pixel = WhitePixelOfScreen(dpy);

(2)  XChangeWindowAttributes(dpy, win, CWBorderPixel | CWBackPixel, &xswa);
                         .
                         .
                         .

1. Assign new values to a set window attributes data structure.
2. Call CHANGE WINDOW ATTRIBUTES to change the window attributes. The CHANGE WINDOWS ATTRIBUTES routine has the following format:

   XChangeWindowAttributes(display, window_id, attributes_mask, attributes)

   
   Specify the attributes to change with a bitwise inclusive OR of the relevant symbols listed in Table 3-3. The values argument passes the address of a set window attributes data structure.

Using Xlib information routines, clients can get information about the parent, children, and number of children in a window tree; window geometry; the root window in which the pointer is currently visible; and window attributes.

Table 3-12 lists and describes Xlib routines that return information about windows.

To get information about window attributes, use the GET WINDOW ATTRIBUTES routine. The client receives requested information in the window attributes data structure. See the X Window System for more information about the window attributes data structure.