XLIB Programming Manual, Rel. 5, Third Edition

4.2 The Window Attribute Structures

There are actually two structures associated with window attributes. XWindowAttributes is a read-only structure that contains all the attributes, while XSetWindowAttributes is a structure that contains only those attributes that a program is allowed to set. We will not show you XWindowAttributes until 4.4 Information from the XWindowAttributes Structure, since it is used in programming only for getting the values of the window attributes.

Example 4-1 shows the structure that is used to set the window attributes.

Example 4-1. The XSetWindowAttributes structure

typedef struct _XSetWindowAttributes {
    Pixmap background_pixmap;       /* Pixmap, None, or ParentRelative */
    long background_pixel;          /* Background pixel value */
    Pixmap border_pixmap;           /* Pixmap, None, or CopyFromParent */
    long border_pixel;              /* Border pixel value */
    int bit_gravity;                /* One of the bit gravity symbols */
    int win_gravity;                /* One of the window gravity symbols */
    int backing_store;              /* NotUseful, WhenMapped, or Always */
    long backing_bitplanes;         /* Planes to be preserved, if possible */
    long backing_pixel;             /* Value to use in restoring planes */
    Bool save_under;                /* Should bits under window be saved */
    long event_mask;                /* Events that should be queued */
    long do_not_propagate_mask;     /* Events that shouldn't propagate */
    Bool override_redirect;         /* Override redirected configuration
                                     * requests */
    Colormap colormap;              /* Colormap associated with window */
    Cursor cursor;                  /* Cursor to be displayed or None */
} XSetWindowAttributes;

To set the window attributes, you need to set the elements of the XSetWindowAttributes structure to the desired values and then set a valuemask argument that represents which members are to be changed in the server’s internal structure. A symbol specifying each member to be changed is combined with the bitwise OR operator (|). These symbols are shown in Table 4-1. They begin with the letters CW (“Create Window” or “Change Window”) because the routines they are used in have those capital letters in their names.

Table 4-1. Window Attribute Mask Symbols

Member	Flag	Bit
background_pixmap	CWBackPixmap	0
background_pixel	CWBackPixel	1
border_pixmap	CWBorderPixmap	2
border_pixel	CWBorderPixel	3
bit_gravity	CWBitGravity	4
win_gravity	CWWinGravity	5
backing_store	CWBackingStore	6
backing_planes	CWBackingPlanes	7
backing_pixel	CWBackingPixel	8
override_redirect	CWOverrideRedirect	9
save_under	CWSaveUnder	10
event_mask	CWEventMask	11
do_not_propagate_mask	CWDontPropagate	12
colormap	CWColormap	13
cursor	CWCursor	14

For example, if you want to set the initial values of the background and border pixel values, you would follow the procedure shown in Example 4-2.

Example 4-2. Setting window attributes while creating a window

Display *display;
Window parent, window;
int x, y;
unsigned int width, height, border_width;
int depth;
int screen_num;
Visual *visual;
unsigned int class;
XSetWindowAttributes setwinattr;
unsigned long valuemask;

/* (Must open display) */

screen_num = DefaultScreen(display);
valuemask = CWBackPixel | CWBorderPixel;
setwinattr.background_pixel = WhitePixel(display, screen_num);
setwinattr.border_pixel = BlackPixel(display, screen_num);
window = XCreateWindow(display, parent, x, y, width, height,
    border_width, depth, class, visual, valuemask, &setwinattr);

If the window already exists, you can change those same attributes with the procedure shown in Example 4-3.

Example 4-3. Changing window attributes of existing window

Display *display;
Window window;
XSetWindowAttributes setwinattr;
unsigned long valuemask;

/* (Must open display, create window) */

valuemask = CWBackPixel | CWBorderPixel;
setwinattr.background_pixel = WhitePixel(display, screen_num);
setwinattr.border_pixel = BlackPixel(display, screen_num);
XChangeWindowAttributes(display, window, valuemask, &setwinattr);

You can also use separate calls to XSetWindowBackground() and XSetWindowBorder() to set these particular attributes. These and a few other attributes have routines for setting them individually. (These routines are referred to as convenience routines. They are provided for the attributes that most often need to be set without modifying any other attributes.) Table 4-2 lists the attributes that can be set individually and the routines that set them. But it is important to realize that each of these routines would generate a separate protocol request to the server, so if more than one attribute is to be set, it is more efficient to use the procedures shown above in Example 4-2 and Example 4-3.

Table 4-2. Attributes that can be Set Individually

Attribute	Routine for Setting It
background_pixmap	XSetWindowBackgroundPixmap()
background_pixel	XSetWindowBackground()
border_pixmap	XSetWindowBorderPixmap()
border_pixel	XSetWindowBorder()
event_mask	XSelectInput()
colormap	XSetWindowColormap()
cursor	XDefineCursor() or XUndefineCursor()

4.3 Settable Attributes describes all of the attributes and the routines for setting them.