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 XOpenDisplay().

  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.

Description
  XSetWindowBackgroundPixmap()	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 background 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  par-
  ent's parent if the parent's background_pixmap attribute is also ParentRelative, 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 background is re-examined each time the window background is  required	(when
  it  needs  to  be redrawn due to mapping or exposure).  The window's contents 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 Also
  XCreateBitmapFromData(), XCreatePixmap(), XCreatePixmapFromBitmapData(), XFreePixmap(), XQueryBestSize(), XQueryBestStipple(),  XQueryBest-
  Tile(), XReadBitmapFile(), XSetTile(), XSetWindowBorderPixmap(), XWriteBitmapFile().

Xlib - Pixmaps and Tiles											      XSetWindowBackgroundPixmap()