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.

Table 3-5 Routines for Managing Properties

Routine	Description
LIST PROPERTIES	Returns a list of properties defined for a specified window.
ROTATE WINDOW PROPERTIES	Rotates the properties of a specified window and generates a property notify event. For more information about property notify events, see Chapter 9.
DELETE PROPERTY	Deletes a specified property.

3.6 Exchanging Properties Between Clients

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.

Table 3-6 Window Changes Data Structure Members

Member Name	Contents
x	Defines, with the y member, the new location of the window relative to the origin of its parent.
y	Defines, with the x member, the new location of the window relative to the origin of its parent.
width	Defines the new width of the window, excluding the border.
height	Defines the new height of the window, excluding the border.
border_width	Specifies the new window border in pixels.
sibling	Specifies the sibling window for stacking order.
stack_mode	Defines how the window is restacked. Table 3-7 lists constants and definitions for restacking windows.

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.

Table 3-7 Stacking Values

Constants	Relative to All Windows	Relative to Siblings
Above	Top of stack.	Just above the sibling.
Below	Bottom of stack.	Just below the sibling.
TopIf	If any sibling obscures a window, the server places the obscured window on top of the stack.	If the specified sibling obscures a window, the server places the obscured window at the top of the stack.
BottomIf	If a window obscures any sibling, the server places the obscuring window at the bottom of the stack.	If a window obscures the specified sibling, the server places the obscuring window at the bottom of the stack.
Opposite	If any sibling obscures a window, the server places the obscured window on top of the stack. If a window obscures any window, the server places the obscuring window at the bottom of the stack.	If the specified sibling obscures a window, the server places the obscuring window on top of the stack. If a window obscures the specified sibling, the server places the obscuring window on the bottom of the stack.

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

Table 3-8 Window Changes Data Structure Flags

Flag Name	Window Changes Member
CWX	x
CWY	y
CWWidth	width
CWHeight	height
CWBorderWidth	border_width
CWSibling	sibling
CWStackMode	stack_mode

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

Example 3-5 Reconfiguring a Window Using the CONFIGURE WINDOW Routine

/* 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.

Table 3-9 Window Configuration Routines

Routine	Description
MOVE WINDOW	Moves a window without changing its size.
RESIZE WINDOW	Changes the size of a window without moving it. The upper left window coordinate does not change after resizing.
MOVE RESIZE WINDOW	Moves and changes the size of a window.
SET WINDOW BORDER WIDTH	Changes the border width of a window.

3.7.2 Effects of Reconfiguring Windows

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.

Table 3-10 Gravity Definitions

Constant Name	Movement of Window Contents and Subwindows
ForgetGravity	The server always discards window contents and tiles the window with its selected background. If the client has not specified a background, existing screen contents remain the same.
NorthWestGravity	Not moved.
NorthGravity	Moved to the right half of the window width.
NorthEastGravity	Moved to the right, the distance of the window width.
WestGravity	Moved down half the window height.
CenterGravity	Moved to the right half of the window width and down half of the window height.
EastGravity	Moved to the right, the distance of the window width and down half the window height.
SouthWestGravity	Moved down the distance of the window height.
SouthGravity	Moved to the right half of the window width and down the distance of the window height.
SouthEastGravity	Moved to the right, the distance of the window width and down the distance of the window height.
StaticGravity	Contents or origin not moved relative to the origin of the root window. Static gravity only takes effect with a change in window width and height.
UnmapGravity	Window should not be moved; the child should be unmapped when the parent is resized.

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.

Table 3-11 Routines for Changing Window Attributes

Routine	Description
SET WINDOW BACKGROUND	Sets the background pixel
SET WINDOW BACKGROUND PIXMAP	Sets the background pixmap
SET WINDOW BORDER	Sets the window border to a specified pixel
SET WINDOW BORDER PIXMAP	Sets the window border to a specified pixmap

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.

Example 3-6 Changing Window Attributes

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.

Table 3-12 Window Information Routines

Routine	Description
QUERY TREE	Returns information about the window tree
GET GEOMETRY	Returns information about the root window identifier, coordinates, width and height, border width, and depth
QUERY POINTER	Returns the root window that the pointer is currently on and the pointer coordinates relative to the root window origin
GET WINDOW ATTRIBUTES	Returns information from the window attributes data structure

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.