Tips for Programming Overlays

The following information may be useful when deciding which model to use, and how to manage stacking.

Parent-Child Model

It is strongly suggested that all transparency and overlays designs follow the simple underlay-parent overlay-child model. The desired underlay window is created first, and then the overlay is created as a child of the underlay. The overlay window is the only child of the underlay. This eliminates a number of odd cases for the X server, and also helps make sure there are no incidental interfering windows between the underlay and the overlay.

If using Xlib and/or programming your own XCreateWindow for these calls, it is important to understand that the client must provide extra information when creating a window that does not have the same visual as its parent. If the visual is not the default visual, you must provide a colormap or, if the colormaps are equivalent, assign the parent visual's colormap to the child. If the depths are different, you must provide a BorderPixel or BorderPixmap. Failure to do so may cause a BadMatch to return as the result of the create window.

For information about colormap equivalence, see the X Server Device Developer's Guide.

Stacking

When you raise a window, it does not matter if the window is an overlay window or not, it will raise to the top of the stack. If you lower a window, it does not matter if it is an overlay window, it will lower to the bottom of the stack.

This brings up the confusing notion of an overlay window being below an underlay window. This actually happens all the time. This is because the X server is enforcing the simple stacking policy, and it will do whatever is necessary to make that overlay window appear below the other windows, even if it has to software clip it.

Problems are best avoided by using the underlay-parent overlay-child model. That way, an underlay-overlay pair is treated as an entire application from the parent window, and it raises and lowers together.