XLIB Programming Manual, Rel. 5, Third Edition

4.4 Information from the XWindowAttributes Structure

We have been describing the programmable window attributes stored in the XSetWindowAttributes structure. Many of the other window characteristics described in Chapter 2 including the window configuration, are also stored with the window attributes by the server but are not programmable using XChangeWindowAttributes(). For example, depth, class, and visual are assigned at window creation and cannot be changed. The window size, position, and border width are changed with a separate mechanism, because for top-level windows there must be cooperation from the window manager.

The current state of most of the programmable attributes, the read-only attributes, and the window configuration can be read with XGetWindowAttributes(). All this information is returned in an XWindowAttributes structure (not an XSetWindowAttributes structure).

Example 4-4 shows the fields of the XWindowAttributes structure that are not present in XSetWindowAttributes.

Example 4-4. Read-only XWindowAttributes members

typedef struct {
    /* Members writable with XChangeWindowAttributes omitted */
    .
    .
    .
    /* Window geometry -- set by window configuration functions
     * in cooperation with window manager */
    int x, y;             /* Location of window */
    int width, height;    /* Width and height of window */
    int border_width;     /* Border width of window */

    /* This is the event_mask attribute set by XSelectInput */
    long your_event_mask; /* My event mask */

    /* Set when the window is created, not changeable */
    Visual *visual;       /* The associated visual structure */
    int class;            /* InputOutput, InputOnly */
    int depth;            /* Depth of window */
    Screen *screen;       /* Pointer to screen the window is on */

    /* Server sets these members */
    Window root;          /* Root of screen containing window */
    Bool map_installed;   /* Is colormap currently installed */
    int map_state;        /* IsUnmapped, IsUnviewable, or
                           * IsViewable */
    long all_event_masks; /* Events all clients have interest in */
}  XWindowAttributes;

As you can see, the members of XWindowAttributes that cannot be directly written with XChangeWindowAttributes() are separated into four groups.

The first group provides a way to get the window geometry. This information is returned by XGetGeometry(), but it might be useful to use XGetWindowAttributes() instead if you need both the geometry and a few attributes.

The your_event_mask member can be useful if you want to add event mask symbols to those already selected. In a call to XSelectInput(), you must always specify all the desired event masks. If you do not know which event masks are already selected or do not want to bother passing an event_mask argument into one of your routines, you could read the existing event mask here. Then you could OR in any additional event mask symbols before calling XSelectInput() or XChangeWindowAttributes(). See Chapter 8, for more information on the use of event masks.

The depth, class, visual, and screen members are set when the window is created. If the window was created with XCreateSimpleWindow(), they were inherited from the parent. If the window was created with XCreateWindow(), these members were specified as arguments, except screen, which is indirectly specified by the parent argument. The screen member points to a structure that tells you about the screen on which this window was created. This is one of the Screen structures from the list in the Display structure, and therefore, the information it contains can also be gotten from the macros as described in 3.2.3 Display Macros and Appendix C, Macros, of Volume Two, Xlib Reference Manual. Again, these should only be needed for convenience to avoid having to pass around these values as arguments or global variables.

The root member tells you the ID of the root window on the screen on which your window was created. It is usually more convenient to use the RootWindow() macro.

The map_installed member can be monitored to tell your application whether the colormap it has set in its colormap attribute is currently installed. If not, the application may be displayed in false colors. See Chapter 7, for more details.

The map_state member can be monitored by a program and used to turn off processing while a window is unviewable. Some applications that continuously poll for input or draw (such as in action games) can stop doing so and save processor cycles when there is no chance of getting input or no point in drawing.

The all_event_masks member tells you all the event types that are selected by all clients on the window requested. This is the OR of all the event_mask attributes for that window for all clients. By contrast, your_event_mask specifies only the events selected by your client.

Also note that XWindowAttributes is missing a few fields that are present in XSetWindowAttributes. This means that there are some fields that can be set but not queried. These fields are the background and border pixel value and pixmap and the cursor. The designers of X decided to make these fields nonreadable to reduce restrictions on the implementation of backgrounds, borders, and cursors in the server.