XCreateWindow()XCreateWindow()NameXCreateWindow – create a window and set attributes.
Synopsis
Window XCreateWindow(display, parent, x, y, width, height, bor‐
der_width, depth, class, visual, valuemask, attributes)
Display *display;
Window parent;
int x, y;
unsigned int width, height;
unsigned int border_width;
int depth;
unsigned int class;
Visual *visual
unsigned long valuemask;
XSetWindowAttributes *attributes;
Arguments
display Specifies a connection to an X server; returned from
XOpenDisplay().
parent Specifies the parent window. Parent must be InputOutput if
class of window created is to be InputOutput.
x Specify the x and y coordinates of the upper-left pixel of
y the new window's border relative to the origin of the parent
(upper-left inside the parent's border).
width Specify the width and height, in pixels, of the window.
height These are the new window's inside dimensions. These dimen‐
sions do not include the new window's borders, which are
entirely outside of the window. Must be non-zero, otherwise
the server generates a BadValue error.
border_width
Specifies the width, in pixels, of the new window's border.
Must be 0 for InputOnly windows, otherwise a BadMatch error
is generated.
depth Specifies the depth of the window, which can be different
from the parent's depth. A depth of CopyFromParent means the
depth is taken from the parent. Use XListDepths() if choos‐
ing an unusual depth. The specified depth paired with the
visual argument must be supported on the screen.
class Specifies the new window's class. Pass one of these con‐
stants: InputOutput, InputOnly, or CopyFromParent.
visual Specifies a connection to an visual structure describing the
style of colormap to be used with this window. CopyFromPar‐
ent is valid.
valuemask Specifies which window attributes are defined in the
attributes argument. If valuemask is 0, attributes is not
referenced. This mask is the bitwise OR of the valid
attribute mask bits listed in the Structures section below.
attributes
Attributes of the window to be set at creation time should be
set in this structure. The valuemask should have the appro‐
priate bits set to indicate which attributes have been set in
the structure.
Returns
The window.
Description
To create an unmapped subwindow for a specified parent window use XCre‐
ateWindow() or XCreateSimpleWindow(). XCreateWindow() is a more gen‐
eral function that allows you to set specific window attributes when
you create the window. If you do not want to set specific attributes
when you create a window, use XCreateSimpleWindow(), which creates a
window that inherits its attributes from its parent. XCreateSimpleWin‐
dow() creates only InputOutput windows that use the default depth and
visual.
XCreateWindow() returns the ID of the created window. XCreateWindow()
causes the X server to generate a CreateNotify event. The newly cre‐
ated window is placed on top of its siblings in the stacking order.
Extension packages may define other classes of windows.
The visual should be DefaultVisual() or one returned by XGetVisual‐
Info() or XMatchVisualInfo(). The depth should be DefaultDepth(), 1,
or a depth returned by XListDepths(). In current implementations of
Xlib, if you specify a visual other than the one used by the parent,
you must first find (using XGetRGBColormaps()) or create a colormap
matching this visual and then set the colormap window attribute in the
attributes and valuemask arguments. Otherwise, you will get a BadMatch
error.
The created window is not yet displayed (mapped) on the user's display.
To display the window, call XMapWindow. The new window initially uses
the same cursor as its parent. A new cursor can be defined for the new
window by calling XDefineCursor(). The window will not be visible on
the screen unless it and all of its ancestors are mapped and it is not
obscured by any of its ancestors.
For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadAlloc
BadColor Invalid colormap in attributes.
BadCursor
BadMatch Any invalid setting of a window attribute.
Attribute besides win_gravity, event_mask, do_not_propa‐
gate_mask, override_redirect, or cursor specified for Inpu‐
tOnly window.
depth non-zero for InputOnly.
Parent of InputOutput is InputOnly.
border_width is non-zero for InputOnly, or depth or visual
invalid for screen.
depth not supported on screen for InputOutput.
width or height is 0.
visual not supported on screen.
border_pixel not set when creating window of different depth
than parent.
BadPixmap
BadValue
Structures
/*
* Data structure for setting window attributes.
*/
typedef struct {
Pixmap background_pixmap; /* background or None or ParentRelative */
unsigned long background_pixel; /* background pixel */
Pixmap border_pixmap; /* border of the window */
unsigned long border_pixel; /* border pixel value */
int bit_gravity; /* one of bit gravity values */
int win_gravity; /* one of the window gravity values */
int backing_store; /* NotUseful, WhenMapped, Always */
unsigned long backing_planes; /* planes to be preseved if possible */
unsigned long backing_pixel; /* value to use in restoring planes */
Bool save_under; /* should bits under be saved (popups) */
long event_mask; /* set of events that should be saved */
long do_not_propagate_mask; /* set of events that should not
propagate */
Bool override_redirect; /* boolean value for override-redirect */
Colormap colormap; /* colormap to be associated with window */
Cursor cursor; /* cursor to be displayed (or None) */
} XSetWindowAttributes;
/* Definitions for valuemask argument */
#define CWBackPixmap (1L<<0)
#define CWBackPixel (1L<<1)
#define CWBorderPixmap (1L<<2)
#define CWBorderPixel (1L<<3)
#define CWBitGravity (1L<<4)
#define CWWinGravity (1L<<5)
#define CWBackingStore (1L<<6)
#define CWBackingPlanes (1L<<7)
#define CWBackingPixel (1L<<8)
#define CWOverrideRedirect (1L<<9)
#define CWSaveUnder (1L<<10)
#define CWEventMask (1L<<11)
#define CWDontPropagate (1L<<12)
#define CWColormap (1L<<13)
#define CWCursor (1L<<14)
Errors
BadWindow
See AlsoXCreateSimpleWindow(), XDestroySubwindows(), XDestroyWindow(), XList‐
Depths().
Xlib - Window Existence XCreateWindow()
