XSetWindowBackgroundPixmap()XSetWindowBackgroundPixmap()Name
XSetWindowBackgroundPixmap – change the background tile attribute of a
window.
Synopsis
XSetWindowBackgroundPixmap(display, w, background_pixmap)
Display *display;
Window w;
Pixmap background_pixmap;
Arguments
display Specifies a connection to an X server; returned from XOpenDis‐
play().
w Specifies the window ID. Must be an InputOutput class window.
background_pixmap
Specifies a pixmap ID, None or ParentRelative, to be used as a
background.
DescriptionXSetWindowBackgroundPixmap() sets the background_pixmap attribute of a
window. This overrides any previous background_pixel or back‐
ground_pixmap attribute setting set with XSetWindowBackgroundPixmap(),
XSetWindowBackground(), or XChangeWindowAttributes(). Drawing into the
pixmap that was set as the background pixmap attribute has an undefined
effect on the window background. The server may or may not make a copy
of the pixmap.
If the background is set to a pixmap, the background is tiled with the
pixmap. If the pixmap is not explicitly referenced again, it can be
freed, since a copy is maintained in the server. The background of the
window will not be redrawn with the new tile until the next Expose
event or XClearWindow() call.
If the background is set to None, the window background initially will
be invisible and will share the bits of its parent, but only if the
background_pixel attribute is not set. When anything is drawn by any
client into the area enclosed by the window, the contents will remain
until the area is explicitly cleared with XClearWindow(). The back‐
ground is not automatically refreshed after exposure.
If the background is set to ParentRelative, the parent's background is
used, and the origin for tiling is the parent's origin (or the parent's
parent if the parent's background_pixmap attribute is also ParentRela‐
tive, and so on). The difference between setting ParentRelative and
explicitly setting the same pixmap as the parent is the origin of the
tiling. The difference between ParentRelative and None is that for
ParentRelative the background is automatically repainted on exposure.
For ParentRelative, the window must have the same depth as the parent,
or a BadMatch error will occur. If the parent has background None,
then the window will also have background None. The parent's back‐
ground is re-examined each time the window background is required (when
it needs to be redrawn due to mapping or exposure). The window's con‐
tents will be lost when the window is moved relative to its parent, and
the contents will have to be redrawn.
Changing the background_pixmap attribute of the root window to None or
ParentRelative restores the default.
XSetWindowBackgroundPixmap() can only be performed on an InputOutput
window. A BadMatch error will result otherwise.
XSetWindowBackground() may be used if a solid color instead of a tile
is desired.
For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadMatch
BadPixmap
BadWindow
See AlsoXCreateBitmapFromData(), XCreatePixmap(), XCreatePixmapFromBitmap‐
Data(), XFreePixmap(), XQueryBestSize(), XQueryBestStipple(),
XQueryBestTile(), XReadBitmapFile(), XSetTile(), XSetWindowBorder‐
Pixmap(), XWriteBitmapFile().
Xlib - Pixmaps and Tiles XSetWindowBackgroundPixmap()
