Window Functions
Visual Types
Visual Type
On some display hardware,
it may be possible to deal with color resources in more than one way.
For example, you may be able to deal with a screen of either 12-bit depth
with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth
with 8 bits of the pixel dedicated to each of red, green, and blue.
These different ways of dealing with the visual aspects of the screen
are called visuals.
For each screen of the display, there may be a list of valid visual types
supported at different depths of the screen.
Because default windows and visual types are defined for each screen,
most simple applications need not deal with this complexity.
Xlib provides macros and functions that return the default root window,
the default depth of the default root window, and the default visual type
(see sections 2.2.1 and 16.7).
Xlib uses an opaque
Visual
Visual
structure that contains information about the possible color mapping.
The visual utility functions (see section 16.7) use an
XVisualInfo
structure to return this information to an application.
The members of this structure pertinent to this discussion are class, red_mask,
green_mask, blue_mask, bits_per_rgb, and colormap_size.
The class member specifies one of the possible visual classes of the screen
and can be
Visual ClassesStaticGray
Visual ClassesStaticColor
Visual ClassesTrueColor
Visual ClassesStaticColor
Visual ClassesGrayScale
Visual ClassesPseudoColor
StaticGray,
StaticColor,
TrueColor,
GrayScale,
PseudoColor,
or
DirectColor.
The following concepts may serve to make the explanation of
visual types clearer.
The screen can be color or grayscale,
can have a colormap that is writable or read-only,
and can also have a colormap whose indices are decomposed into separate
RGB pieces, provided one is not on a grayscale screen.
This leads to the following diagram:
Color Gray-Scale
R/O R/W R/O R/W
----------------------------------------------
Undecomposed Static Pseudo Static Gray
Colormap Color Color Gray Scale
Decomposed True Direct
Colormap Color Color
----------------------------------------------
Conceptually,
as each pixel is read out of video memory for display on the screen,
it goes through a look-up stage by indexing into a colormap.
Colormaps can be manipulated arbitrarily on some hardware,
in limited ways on other hardware, and not at all on other hardware.
The visual types affect the colormap and
the RGB values in the following ways:
For
PseudoColor,
a pixel value indexes a colormap to produce
independent RGB values, and the RGB values can be changed dynamically.
GrayScale
is treated the same way as
PseudoColor
except that the primary that drives the screen is undefined.
Thus, the client should always store the
same value for red, green, and blue in the colormaps.
For
DirectColor,
a pixel value is decomposed into separate RGB subfields, and each
subfield separately indexes the colormap for the corresponding value.
The RGB values can be changed dynamically.
TrueColor
is treated the same way as
DirectColor
except that the colormap has predefined, read-only RGB values.
These RGB values are server dependent but provide linear or near-linear
ramps in each primary.
StaticColor
is treated the same way as
PseudoColor
except that the colormap has predefined,
read-only, server-dependent RGB values.
StaticGray
is treated the same way as
StaticColor
except that the RGB values are equal for any single pixel
value, thus resulting in shades of gray.
StaticGray
with a two-entry
colormap can be thought of as monochrome.
The red_mask, green_mask, and blue_mask members are only defined for
DirectColor
and
TrueColor.
Each has one contiguous set of bits with no
intersections.
The bits_per_rgb member specifies the log base 2 of the
number of distinct color values (individually) of red, green, and blue.
Actual RGB values are unsigned 16-bit numbers.
The colormap_size member defines the number of available colormap entries
in a newly created colormap.
For
DirectColor
and
TrueColor,
this is the size of an individual pixel subfield.
To obtain the visual ID from a
Visual,
use
XVisualIDFromVisual.
XVisualIDFromVisual
VisualID XVisualIDFromVisual
Visual *visual
visual
Specifies the visual type.
The
XVisualIDFromVisual
function returns the visual ID for the specified visual type.
Window Attributes
Window
Windowattributes
All
InputOutput
windows have a border width of zero or more pixels, an optional background,
an event suppression mask (which suppresses propagation of events from
children), and a property list (see section 4.3).
The window border and background can be a solid color or a pattern, called
a tile.
All windows except the root have a parent and are clipped by their parent.
If a window is stacked on top of another window, it obscures that other
window for the purpose of input.
If a window has a background (almost all do), it obscures the other
window for purposes of output.
Attempts to output to the obscured area do nothing,
and no input events (for example, pointer motion) are generated for the
obscured area.
Windows also have associated property lists (see section 4.3).
Both
InputOutput
and
InputOnly
windows have the following common attributes,
which are the only attributes of an
InputOnly
window:
win-gravity
event-mask
do-not-propagate-mask
override-redirect
cursor
If you specify any other attributes for an
InputOnly
window,
a
BadMatch
error results.
InputOnly
windows are used for controlling input events in situations where
InputOutput
windows are unnecessary.
InputOnly
windows are invisible; can only be used to control such things as
cursors, input event generation, and grabbing;
and cannot be used in any graphics requests.
Note that
InputOnly
windows cannot have
InputOutput
windows as inferiors.
Windows have borders of a programmable width and pattern
as well as a background pattern or tile.
Tilepixmaps
Pixel values can be used for solid colors.
Resource IDsfreeing
Freeingresources
The background and border pixmaps can be destroyed immediately after
creating the window if no further explicit references to them
are to be made.
Tilemode
The pattern can either be relative to the parent
or absolute.
If
ParentRelative,
the parent's background is used.
When windows are first created,
they are not visible (not mapped) on the screen.
Any output to a window that is not visible on the screen
and that does not have backing store will be discarded.
Windowmapping
An application may wish to create a window long before it is
mapped to the screen.
When a window is eventually mapped to the screen
(using
XMapWindow),
XMapWindow
the X server generates an
Expose
event for the window if backing store has not been maintained.
A window manager can override your choice of size,
border width, and position for a top-level window.
Your program must be prepared to use the actual size and position
of the top window.
It is not acceptable for a client application to resize itself
unless in direct response to a human command to do so.
Instead, either your program should use the space given to it,
or if the space is too small for any useful work, your program
might ask the user to resize the window.
The border of your top-level window is considered fair game
for window managers.
To set an attribute of a window,
set the appropriate member of the
XSetWindowAttributes
structure and OR in the corresponding value bitmask in your subsequent calls to
XCreateWindow
and
XChangeWindowAttributes,
or use one of the other convenience functions that set the appropriate
attribute.
The symbols for the value mask bits and the
XSetWindowAttributes
structure are:
/* Window attribute value mask bits */
/* Window attribute value mask bits */
#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)
XSetWindowAttributes
/* Values */
typedef struct {
Pixmap background_pixmap; /* background, None, or ParentRelative */
unsigned long background_pixel; /* background pixel */
Pixmap border_pixmap; /* border of the window or CopyFromParent */
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 preserved 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; /* color map to be associated with window */
Cursor cursor; /* cursor to be displayed (or None) */
} XSetWindowAttributes;
The following lists the defaults for each window attribute and indicates
whether the attribute is applicable to
InputOutput
and
InputOnly
windows:
Attribute
Default
InputOutput
nputOnly
background-pixmap
None
Yes
No
background-pixel
Undefined
Yes
No
border-pixmap
CopyFromParent
Yes
No
border-pixel
Undefined
Yes
No
bit-gravity
ForgetGravity
Yes
No
win-gravity
NorthWestGravity
Yes
Yes
backing-store
NotUseful
Yes
No
backing-planes
All ones
Yes
No
backing-pixel
zero
Yes
No
save-under
False
Yes
No
event-mask
empty set
Yes
Yes
do-not-propagate-mask
empty set
Yes
Yes
override-redirect
False
Yes
Yes
colormap
CopyFromParent
Yes
No
cursor
None
Yes
Yes
Background Attribute
Only
InputOutput
windows can have a background.
You can set the background of an
InputOutput
window by using a pixel or a pixmap.
The background-pixmap attribute of a window specifies the pixmap to be used for
a window's background.
This pixmap can be of any size, although some sizes may be faster than others.
The background-pixel attribute of a window specifies a pixel value used to paint
a window's background in a single color.
You can set the background-pixmap to a pixmap,
None
(default), or
ParentRelative.
You can set the background-pixel of a window to any pixel value (no default).
If you specify a background-pixel,
it overrides either the default background-pixmap
or any value you may have set in the background-pixmap.
A pixmap of an undefined size that is filled with the background-pixel is used
for the background.
Range checking is not performed on the background pixel;
it simply is truncated to the appropriate number of bits.
If you set the background-pixmap,
it overrides the default.
The background-pixmap and the window must have the same depth,
or a
BadMatch
error results.
If you set background-pixmap to
None,
the window has no defined background.
If you set the background-pixmap to
ParentRelative:
The parent window's background-pixmap is used.
The child window, however, must have the same depth as
its parent,
or a
BadMatch
error results.
If the parent window has a background-pixmap of
None,
the window also has a background-pixmap of
None.
A copy of the parent window's background-pixmap is not made.
The parent's background-pixmap is examined each time the child window's
background-pixmap is required.
The background tile origin always aligns with the parent window's
background tile origin.
If the background-pixmap is not
ParentRelative,
the background tile origin is the child window's origin.
Setting a new background, whether by setting background-pixmap or
background-pixel, overrides any previous background.
The background-pixmap can be freed immediately if no further explicit reference
is made to it (the X server will keep a copy to use when needed).
If you later draw into the pixmap used for the background,
what happens is undefined because the
X implementation is free to make a copy of the pixmap or
to use the same pixmap.
When no valid contents are available for regions of a window
and either the regions are visible or the server is maintaining backing store,
the server automatically tiles the regions with the window's background
unless the window has a background of
None.
If the background is
None,
the previous screen contents from other windows of the same depth as the window
are simply left in place as long as the contents come from the parent of the
window or an inferior of the parent.
Otherwise, the initial contents of the exposed regions are undefined.
Expose
events are then generated for the regions, even if the background-pixmap
is
None
(see section 10.9).
Border Attribute
Only
InputOutput
windows can have a border.
You can set the border of an
InputOutput
window by using a pixel or a pixmap.
The border-pixmap attribute of a window specifies the pixmap to be used
for a window's border.
The border-pixel attribute of a window specifies a pixmap of undefined size
filled with that pixel be used for a window's border.
Range checking is not performed on the background pixel;
it simply is truncated to the appropriate number of bits.
The border tile origin is always the same as the background tile origin.
You can also set the border-pixmap to a pixmap of any size (some may be faster
than others) or to
CopyFromParent
(default).
You can set the border-pixel to any pixel value (no default).
If you set a border-pixmap,
it overrides the default.
The border-pixmap and the window must have the same depth,
or a
BadMatch
error results.
If you set the border-pixmap to
CopyFromParent,
the parent window's border-pixmap is copied.
Subsequent changes to the parent window's border attribute do not affect
the child window.
However, the child window must have the same depth as the parent window,
or a
BadMatch
error results.
The border-pixmap can be freed immediately if no further explicit reference
is made to it.
If you later draw into the pixmap used for the border,
what happens is undefined because the
X implementation is free either to make a copy of the pixmap or
to use the same pixmap.
If you specify a border-pixel,
it overrides either the default border-pixmap
or any value you may have set in the border-pixmap.
All pixels in the window's border will be set to the border-pixel.
Setting a new border, whether by setting border-pixel or by setting
border-pixmap, overrides any previous border.
Output to a window is always clipped to the inside of the window.
Therefore, graphics operations never affect the window border.
Gravity Attributes
The bit gravity of a window defines which region of the window should be
retained when an
InputOutput
window is resized.
The default value for the bit-gravity attribute is
ForgetGravity.
The window gravity of a window allows you to define how the
InputOutput
or
InputOnly
window should be repositioned if its parent is resized.
The default value for the win-gravity attribute is
NorthWestGravity.
If the inside width or height of a window is not changed
and if the window is moved or its border is changed,
then the contents of the window are not lost but move with the window.
Changing the inside width or height of the window causes its contents to be
moved or lost (depending on the bit-gravity of the window) and causes
children to be reconfigured (depending on their win-gravity).
For a
change of width and height, the (x, y) pairs are defined:
Gravity Direction
Coordinates
NorthWestGravity
(0, 0)
NorthGravity
(Width/2, 0)
NorthEastGravity
(Width, 0)
WestGravity
(0, Height/2)
CenterGravity
(Width/2, Height/2)
EastGravity
(Width, Height/2)
SouthWestGravity
(0, Height)
SouthGravity
(Width/2, Height)
SouthEastGravity
(Width, Height)
When a window with one of these bit-gravity values is resized,
the corresponding pair
defines the change in position of each pixel in the window.
When a window with one of these win-gravities has its parent window resized,
the corresponding pair defines the change in position of the window
within the parent.
When a window is so repositioned, a
GravityNotify
event is generated (see section 10.10.5).
A bit-gravity of
StaticGravity
indicates that the contents or origin should not move relative to the
origin of the root window.
If the change in size of the window is coupled with a change in position (x, y),
then for bit-gravity the change in position of each pixel is (−x, −y), and for
win-gravity the change in position of a child when its parent is so resized is
(−x, −y).
Note that
StaticGravity
still only takes effect when the width or height of the window is changed,
not when the window is moved.
A bit-gravity of
ForgetGravity
indicates that the window's contents are always discarded after a size change,
even if a backing store or save under has been requested.
The window is tiled with its background
and zero or more
Expose
events are generated.
If no background is defined, the existing screen contents are not
altered.
Some X servers may also ignore the specified bit-gravity and
always generate
Expose
events.
The contents and borders of inferiors are not affected by their parent's
bit-gravity.
A server is permitted to ignore the specified bit-gravity and use
Forget
instead.
A win-gravity of
UnmapGravity
is like
NorthWestGravity
(the window is not moved),
except the child is also
unmapped when the parent is resized,
and an
UnmapNotify
event is
generated.
Backing Store Attribute
Some implementations of the X server may choose to maintain the contents of
InputOutput
windows.
If the X server maintains the contents of a window,
the off-screen saved pixels
are known as backing store.
The backing store advises the X server on what to do
with the contents of a window.
The backing-store attribute can be set to
NotUseful
(default),
WhenMapped,
or
Always.
A backing-store attribute of
NotUseful
advises the X server that
maintaining contents is unnecessary,
although some X implementations may
still choose to maintain contents and, therefore, not generate
Expose
events.
A backing-store attribute of
WhenMapped
advises the X server that maintaining contents of
obscured regions when the window is mapped would be beneficial.
In this case,
the server may generate an
Expose
event when the window is created.
A backing-store attribute of
Always
advises the X server that maintaining contents even when
the window is unmapped would be beneficial.
Even if the window is larger than its parent,
this is a request to the X server to maintain complete contents,
not just the region within the parent window boundaries.
While the X server maintains the window's contents,
Expose
events normally are not generated,
but the X server may stop maintaining
contents at any time.
When the contents of obscured regions of a window are being maintained,
regions obscured by noninferior windows are included in the destination
of graphics requests (and source, when the window is the source).
However, regions obscured by inferior windows are not included.
Save Under Flag
Save Unders
Some server implementations may preserve contents of
InputOutput
windows under other
InputOutput
windows.
This is not the same as preserving the contents of a window for you.
You may get better visual
appeal if transient windows (for example, pop-up menus) request that the system
preserve the screen contents under them,
so the temporarily obscured applications do not have to repaint.
You can set the save-under flag to
True
or
False
(default).
If save-under is
True,
the X server is advised that, when this window is mapped,
saving the contents of windows it obscures would be beneficial.
Backing Planes and Backing Pixel Attributes
You can set backing planes to indicate (with bits set to 1)
which bit planes of an
InputOutput
window hold dynamic data that must be preserved in backing store
and during save unders.
The default value for the backing-planes attribute is all bits set to 1.
You can set backing pixel to specify what bits to use in planes not
covered by backing planes.
The default value for the backing-pixel attribute is all bits set to 0.
The X server is free to save only the specified bit planes in the backing store
or the save under and is free to regenerate the remaining planes with
the specified pixel value.
Any extraneous bits in these values (that is, those bits beyond
the specified depth of the window) may be simply ignored.
If you request backing store or save unders,
you should use these members to minimize the amount of off-screen memory
required to store your window.
Event Mask and Do Not Propagate Mask Attributes
The event mask defines which events the client is interested in for this
InputOutput
or
InputOnly
window (or, for some event types, inferiors of this window).
The event mask is the bitwise inclusive OR of zero or more of the
valid event mask bits.
You can specify that no maskable events are reported by setting
NoEventMask
(default).
The do-not-propagate-mask attribute
defines which events should not be propagated to
ancestor windows when no client has the event type selected in this
InputOutput
or
InputOnly
window.
The do-not-propagate-mask is the bitwise inclusive OR of zero or more
of the following masks:
KeyPress,
KeyRelease,
ButtonPress,
ButtonRelease,
PointerMotion,
Button1Motion,
Button2Motion,
Button3Motion,
Button4Motion,
Button5Motion,
and
ButtonMotion.
You can specify that all events are propagated by setting
NoEventMask
(default).
Override Redirect Flag
To control window placement or to add decoration,
a window manager often needs to intercept (redirect) any map or configure
request.
Pop-up windows, however, often need to be mapped without a window manager
getting in the way.
To control whether an
InputOutput
or
InputOnly
window is to ignore these structure control facilities,
use the override-redirect flag.
The override-redirect flag specifies whether map and configure requests
on this window should override a
SubstructureRedirectMask
on the parent.
You can set the override-redirect flag to
True
or
False
(default).
Window managers use this information to avoid tampering with pop-up windows
(see also chapter 14).
Colormap Attribute
The colormap attribute specifies which colormap best reflects the true
colors of the
InputOutput
window.
The colormap must have the same visual type as the window,
or a
BadMatch
error results.
X servers capable of supporting multiple
hardware colormaps can use this information,
and window managers can use it for calls to
XInstallColormap.
You can set the colormap attribute to a colormap or to
CopyFromParent
(default).
If you set the colormap to
CopyFromParent,
the parent window's colormap is copied and used by its child.
However, the child window must have the same visual type as the parent,
or a
BadMatch
error results.
The parent window must not have a colormap of
None,
or a
BadMatch
error results.
The colormap is copied by sharing the colormap object between the child
and parent, not by making a complete copy of the colormap contents.
Subsequent changes to the parent window's colormap attribute do
not affect the child window.
Cursor Attribute
The cursor attribute specifies which cursor is to be used when the pointer is
in the
InputOutput
or
InputOnly
window.
You can set the cursor to a cursor or
None
(default).
If you set the cursor to
None,
the parent's cursor is used when the
pointer is in the
InputOutput
or
InputOnly
window, and any change in the parent's cursor will cause an
immediate change in the displayed cursor.
By calling
XFreeCursor,
the cursor can be freed immediately as long as no further explicit reference
to it is made.
Creating Windows
Xlib provides basic ways for creating windows,
and toolkits often supply higher-level functions specifically for
creating and placing top-level windows,
which are discussed in the appropriate toolkit documentation.
If you do not use a toolkit, however,
you must provide some standard information or hints for the window
manager by using the Xlib inter-client communication functions
(see chapter 14).
If you use Xlib to create your own top-level windows
(direct children of the root window),
you must observe the following rules so that all applications interact
reasonably across the different styles of window management:
You must never fight with the window manager for the size or
placement of your top-level window.
You must be able to deal with whatever size window you get,
even if this means that your application just prints a message
like ``Please make me bigger'' in its window.
You should only attempt to resize or move top-level windows in
direct response to a user request.
If a request to change the size of a top-level window fails,
you must be prepared to live with what you get.
You are free to resize or move the children of top-level
windows as necessary.
(Toolkits often have facilities for automatic relayout.)
If you do not use a toolkit that automatically sets standard window properties,
you should set these properties for top-level windows before mapping them.
For further information,
see chapter 14 and the Inter-Client Communication Conventions Manual.
XCreateWindow
is the more general function that allows you to set specific window attributes
when you create a window.
XCreateSimpleWindow
creates a window that inherits its attributes from its parent window.
WindowInputOnly
The X server acts as if
InputOnly
windows do not exist for
the purposes of graphics requests, exposure processing, and
VisibilityNotify
events.
An
InputOnly
window cannot be used as a
drawable (that is, as a source or destination for graphics requests).
InputOnly
and
InputOutput
windows act identically in other respects (properties,
grabs, input control, and so on).
Extension packages can define other classes of windows.
To create an unmapped window and set its window attributes, use
XCreateWindow.
XCreateWindow
Window XCreateWindow
Display *display
Window parent
intx, y
unsignedintwidth, height
unsignedint border_width
int depth
unsignedint class
Visual *visual
unsignedlong valuemask
XSetWindowAttributes *attributes
display
Specifies the connection to the X server.
parent
Specifies the parent window.
borders and are relative to the inside of the parent window's borders
x
y
Specify the x and y coordinates(Xy.
and do not include the created window's borders
width
height
Specify the width and height(Wh.
The dimensions must be nonzero,
or a
BadValue
error results.
border_width
Specifies the width of the created window's border in pixels.
depth
Specifies the window's depth.
A depth of
CopyFromParent
means the depth is taken from the parent.
class
Specifies the created window's class.
You can pass
InputOutput,
InputOnly,
or
CopyFromParent.
A class of
CopyFromParent
means the class
is taken from the parent.
visual
Specifies the visual type.
A visual of
CopyFromParent
means the visual type is taken from the
parent.
valuemask
Specifies which window attributes are defined in the attributes
argument.
This mask is the bitwise inclusive OR of the valid attribute mask bits.
If valuemask is zero,
the attributes are ignored and are not referenced.
attributes
Specifies the structure from which the values (as specified by the value mask)
are to be taken.
The value mask should have the appropriate bits
set to indicate which attributes have been set in the structure.
The
XCreateWindow
function creates an unmapped subwindow for a specified parent window,
returns the window ID of the created window,
and causes the X server to generate a
CreateNotify
event.
The created window is placed on top in the stacking order
with respect to siblings.
The coordinate system has the X axis horizontal and the Y axis vertical
with the origin [0, 0] at the upper-left corner.
Coordinates are integral,
in terms of pixels,
and coincide with pixel centers.
Each window and pixmap has its own coordinate system.
For a window,
the origin is inside the border at the inside, upper-left corner.
The border_width for an
InputOnly
window must be zero, or a
BadMatch
error results.
For class
InputOutput,
the visual type and depth must be a combination supported for the screen,
or a
BadMatch
error results.
The depth need not be the same as the parent,
but the parent must not be a window of class
InputOnly,
or a
BadMatch
error results.
For an
InputOnly
window,
the depth must be zero, and the visual must be one supported by the screen.
If either condition is not met,
a
BadMatch
error results.
The parent window, however, may have any depth and class.
If you specify any invalid window attribute for a window, a
BadMatch
error results.
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.
CursorInitial State
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.
XCreateWindow
can generate
BadAlloc,
BadColor,
BadCursor,
BadMatch,
BadPixmap,
BadValue,
and
BadWindow
errors.
To create an unmapped
InputOutput
subwindow of a given parent window, use
XCreateSimpleWindow.
XCreateSimpleWindow
Window XCreateSimpleWindow
Display *display
Window parent
intx, y
unsignedintwidth, height
unsignedint border_width
unsignedlong border
unsignedlong background
display
Specifies the connection to the X server.
parent
Specifies the parent window.
and are relative to the inside of the parent window's borders
x
y
Specify the x and y coordinates(Xy.
and do not include the created window's borders
width
height
Specify the width and height(Wh.
The dimensions must be nonzero,
or a
BadValue
error results.
border_width
Specifies the width of the created window's border in pixels.
border
Specifies the border pixel value of the window.
background
Specifies the background pixel value of the window.
The
XCreateSimpleWindow
function creates an unmapped
InputOutput
subwindow for a specified parent window, returns the
window ID of the created window, and causes the X server to generate a
CreateNotify
event.
The created window is placed on top in the stacking order with respect to
siblings.
Any part of the window that extends outside its parent window is clipped.
The border_width for an
InputOnly
window must be zero, or a
BadMatch
error results.
XCreateSimpleWindow
inherits its depth, class, and visual from its parent.
All other window attributes, except background and border,
have their default values.
XCreateSimpleWindow
can generate
BadAlloc,
BadMatch,
BadValue,
and
BadWindow
errors.
Destroying Windows
Xlib provides functions that you can use to destroy a window or destroy all
subwindows of a window.
To destroy a window and all of its subwindows, use
XDestroyWindow.
XDestroyWindow
XDestroyWindow
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XDestroyWindow
function destroys the specified window as well as all of its subwindows and causes
the X server to generate a
DestroyNotify
event for each window.
The window should never be referenced again.
If the window specified by the w argument is mapped,
it is unmapped automatically.
The ordering of the
DestroyNotify
events is such that for any given window being destroyed,
DestroyNotify
is generated on any inferiors of the window before being generated on
the window itself.
The ordering among siblings and across subhierarchies is not otherwise
constrained.
If the window you specified is a root window, no windows are destroyed.
Destroying a mapped window will generate
Expose
events on other windows that were obscured by the window being destroyed.
XDestroyWindow
can generate a
BadWindow
error.
To destroy all subwindows of a specified window, use
XDestroySubwindows.
XDestroySubwindows
XDestroySubwindows
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XDestroySubwindows
function destroys all inferior windows of the specified window,
in bottom-to-top stacking order.
It causes the X server to generate a
DestroyNotify
event for each window.
If any mapped
subwindows were actually destroyed,
XDestroySubwindows
causes the X server to generate
Expose
events on the specified window.
This is much more efficient than deleting many windows
one at a time because much of the work need be performed only once for all
of the windows, rather than for each window.
The subwindows should never be referenced again.
XDestroySubwindows
can generate a
BadWindow
error.
Mapping Windows
A window is considered mapped if an
XMapWindow
call has been made on it.
It may not be visible on the screen for one of the following reasons:
It is obscured by another opaque window.
One of its ancestors is not mapped.
It is entirely clipped by an ancestor.
Expose
events are generated for the window when part or all of
it becomes visible on the screen.
A client receives the
Expose
events only if it has asked for them.
Windows retain their position in the stacking order when they are unmapped.
A window manager may want to control the placement of subwindows.
If
SubstructureRedirectMask
has been selected by a window manager
on a parent window (usually a root window),
a map request initiated by other clients on a child window is not performed,
and the window manager is sent a
MapRequest
event.
However, if the override-redirect flag on the child had been set to
True
(usually only on pop-up menus),
the map request is performed.
A tiling window manager might decide to reposition and resize other clients'
windows and then decide to map the window to its final location.
A window manager that wants to provide decoration might
reparent the child into a frame first.
For further information,
see sections 3.2.8 and 10.10.
Only a single client at a time can select for
SubstructureRedirectMask.
Similarly, a single client can select for
ResizeRedirectMask
on a parent window.
Then, any attempt to resize the window by another client is suppressed, and
the client receives a
ResizeRequest
event.
To map a given window, use
XMapWindow.
XMapWindow
XMapWindow
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XMapWindow
function
maps the window and all of its
subwindows that have had map requests.
Mapping a window that has an unmapped ancestor does not display the
window but marks it as eligible for display when the ancestor becomes
mapped.
Such a window is called unviewable.
When all its ancestors are mapped,
the window becomes viewable
and will be visible on the screen if it is not obscured by another window.
This function has no effect if the window is already mapped.
If the override-redirect of the window is
False
and if some other client has selected
SubstructureRedirectMask
on the parent window, then the X server generates a
MapRequest
event, and the
XMapWindow
function does not map the window.
Otherwise, the window is mapped, and the X server generates a
MapNotify
event.
If the window becomes viewable and no earlier contents for it are remembered,
the X server tiles the window with its background.
If the window's background is undefined,
the existing screen contents are not
altered, and the X server generates zero or more
Expose
events.
If backing-store was maintained while the window was unmapped, no
Expose
events
are generated.
If backing-store will now be maintained,
a full-window exposure is always generated.
Otherwise, only visible regions may be reported.
Similar tiling and exposure take place for any newly viewable inferiors.
XMapWindow
If the window is an
InputOutput
window,
XMapWindow
generates
Expose
events on each
InputOutput
window that it causes to be displayed.
If the client maps and paints the window
and if the client begins processing events,
the window is painted twice.
To avoid this,
first ask for
Expose
events and then map the window,
so the client processes input events as usual.
The event list will include
Expose
for each
window that has appeared on the screen.
The client's normal response to
an
Expose
event should be to repaint the window.
This method usually leads to simpler programs and to proper interaction
with window managers.
XMapWindow
can generate a
BadWindow
error.
To map and raise a window, use
XMapRaised.
XMapRaised
XMapRaised
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XMapRaised
function
essentially is similar to
XMapWindow
in that it maps the window and all of its
subwindows that have had map requests.
However, it also raises the specified window to the top of the stack.
For additional information,
see
XMapWindow.
XMapRaised
can generate multiple
BadWindow
errors.
To map all subwindows for a specified window, use
XMapSubwindows.
XMapSubwindows
XMapSubwindows
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XMapSubwindows
XMapSubwindows
function maps all subwindows for a specified window in top-to-bottom stacking
order.
The X server generates
Expose
events on each newly displayed window.
This may be much more efficient than mapping many windows
one at a time because the server needs to perform much of the work
only once, for all of the windows, rather than for each window.
XMapSubwindows
can generate a
BadWindow
error.
Unmapping Windows
Xlib provides functions that you can use to unmap a window or all subwindows.
To unmap a window, use
XUnmapWindow.
XUnmapWindow
XUnmapWindow
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XUnmapWindow
function unmaps the specified window and causes the X server to generate an
UnmapNotify
UnmapNotify Event
XUnmapWindow
event.
If the specified window is already unmapped,
XUnmapWindow
has no effect.
Normal exposure processing on formerly obscured windows is performed.
Any child window will no longer be visible until another map call is
made on the parent.
In other words, the subwindows are still mapped but are not visible
until the parent is mapped.
Unmapping a window will generate
Expose
events on windows that were formerly obscured by it.
XUnmapWindow
can generate a
BadWindow
error.
To unmap all subwindows for a specified window, use
XUnmapSubwindows.
XUnmapSubwindows
XUnmapSubwindows
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XUnmapSubwindows
function unmaps all subwindows for the specified window in bottom-to-top
stacking order.
It causes the X server to generate an
UnmapNotify
event on each subwindow and
Expose
events on formerly obscured windows.
UnmapNotify Event
Using this function is much more efficient than unmapping multiple windows
one at a time because the server needs to perform much of the work
only once, for all of the windows, rather than for each window.
XUnmapSubwindows
can generate a
BadWindow
error.
Configuring Windows
Xlib provides functions that you can use to
move a window, resize a window, move and resize a window, or
change a window's border width.
To change one of these parameters,
set the appropriate member of the
XWindowChanges
structure and OR in the corresponding value mask in subsequent calls to
XConfigureWindow.
The symbols for the value mask bits and the
XWindowChanges
structure are:
/* Configure window value mask bits */
#define CWX (1<<0)
#define CWY (1<<1)
#define CWWidth (1<<2)
#define CWHeight (1<<3)
#define CWBorderWidth (1<<4)
#define CWSibling (1<<5)
#define CWStackMode (1<<6)
XWindowChanges
/* Values */
typedef struct {
int x, y;
int width, height;
int border_width;
Window sibling;
int stack_mode;
} XWindowChanges;
The x and y members are used to set the window's x and y coordinates,
which are relative to the parent's origin
and indicate the position of the upper-left outer corner of the window.
The width and height members are used to set the inside size of the window,
not including the border, and must be nonzero, or a
BadValue
error results.
Attempts to configure a root window have no effect.
The border_width member is used to set the width of the border in pixels.
Note that setting just the border width leaves the outer-left corner of the window
in a fixed position but moves the absolute position of the window's origin.
If you attempt to set the border-width attribute of an
InputOnly
window nonzero, a
BadMatch
error results.
The sibling member is used to set the sibling window for stacking operations.
The stack_mode member is used to set how the window is to be restacked
and can be set to
Above,
Below,
TopIf,
BottomIf,
or
Opposite.
If the override-redirect flag of the window is
False
and if some other client has selected
SubstructureRedirectMask
on the parent, the X server generates a
ConfigureRequest
event, and no further processing is performed.
Otherwise,
if some other client has selected
ResizeRedirectMask
on the window and the inside
width or height of the window is being changed,
a
ResizeRequest
event is generated, and the current inside width and height are
used instead.
Note that the override-redirect flag of the window has no effect
on
ResizeRedirectMask
and that
SubstructureRedirectMask
on the parent has precedence over
ResizeRedirectMask
on the window.
When the geometry of the window is changed as specified,
the window is restacked among siblings, and a
ConfigureNotify
event is generated if the state of the window actually changes.
GravityNotify
events are generated after
ConfigureNotify
events.
If the inside width or height of the window has actually changed,
children of the window are affected as specified.
If a window's size actually changes,
the window's subwindows move according to their window gravity.
Depending on the window's bit gravity,
the contents of the window also may be moved (see section 3.2.3).
If regions of the window were obscured but now are not,
exposure processing is performed on these formerly obscured windows,
including the window itself and its inferiors.
As a result of increasing the width or height,
exposure processing is also performed on any new regions of the window
and any regions where window contents are lost.
The restack check (specifically, the computation for
BottomIf,
TopIf,
and
Opposite)
is performed with respect to the window's final size and position (as
controlled by the other arguments of the request), not its initial position.
If a sibling is specified without a stack_mode,
a
BadMatch
error results.
If a sibling and a stack_mode are specified,
the window is restacked as follows:
Above
The window is placed just above the sibling.
Below
The window is placed just below the sibling.
TopIf
If the sibling occludes the window, the window is placed at the top of the stack.
BottomIf
If the window occludes the sibling, the window is placed at the bottom of the stack.
Opposite
If the sibling occludes the window, the window is placed at the top of the stack.
If the window occludes the sibling,
the window is placed at the bottom of the stack.
If a stack_mode is specified but no sibling is specified,
the window is restacked as follows:
Above
The window is placed at the top of the stack.
Below
The window is placed at the bottom of the stack.
TopIf
If any sibling occludes the window, the window is placed at
the top of the stack.
If the window occludes any sibling, the window is placed at
the bottom of the stack.
Opposite
If any sibling occludes the window, the window
is placed at the top of the stack.
If the window occludes any sibling,
the window is placed at the bottom of the stack.
Attempts to configure a root window have no effect.
To configure a window's size, location, stacking, or border, use
XConfigureWindow.
XConfigureWindow
XConfigureWindow
Display *display
Window w
unsignedint value_mask
XWindowChanges *values
display
Specifies the connection to the X server.
w
Specifies the window (Wi.
value_mask
Specifies which values are to be set using information in
the values structure.
This mask is the bitwise inclusive OR of the valid configure window values bits.
values
Specifies the
XWindowChanges
structure.
The
XConfigureWindow
function uses the values specified in the
XWindowChanges
structure to reconfigure a window's size, position, border, and stacking order.
Values not specified are taken from the existing geometry of the window.
If a sibling is specified without a stack_mode or if the window
is not actually a sibling,
a
BadMatch
error results.
Note that the computations for
BottomIf,
TopIf,
and
Opposite
are performed with respect to the window's final geometry (as controlled by the
other arguments passed to
XConfigureWindow),
not its initial geometry.
Any backing store contents of the window, its
inferiors, and other newly visible windows are either discarded or
changed to reflect the current screen contents
(depending on the implementation).
XConfigureWindow
can generate
BadMatch,
BadValue,
and
BadWindow
errors.
To move a window without changing its size, use
XMoveWindow.
XMoveWindow
XMoveWindow
Display *display
Window w
intx, y
display
Specifies the connection to the X server.
w
Specifies the window (Wi.
of the window's border or the window itself if it has no border
x
y
Specify the x and y coordinates(Xy.
The
XMoveWindow
function moves the specified window to the specified x and y coordinates,
but it does not change the window's size, raise the window, or
change the mapping state of the window.
Moving a mapped window may or may not lose the window's contents
depending on if the window is obscured by nonchildren
and if no backing store exists.
If the contents of the window are lost,
the X server generates
Expose
events.
Moving a mapped window generates
Expose
events on any formerly obscured windows.
If the override-redirect flag of the window is
False
and some
other client has selected
SubstructureRedirectMask
on the parent, the X server generates a
ConfigureRequest
event, and no further processing is
performed.
Otherwise, the window is moved.
XMoveWindow
can generate a
BadWindow
error.
To change a window's size without changing the upper-left coordinate, use
XResizeWindow.
XResizeWindow
XResizeWindow
Display *display
Window w
unsignedintwidth, height
display
Specifies the connection to the X server.
w
Specifies the window.
after the call completes
width
height
Specify the width and height(Wh.
The
XResizeWindow
function changes the inside dimensions of the specified window, not including
its borders.
This function does not change the window's upper-left coordinate or
the origin and does not restack the window.
Changing the size of a mapped window may lose its contents and generate
Expose
events.
If a mapped window is made smaller,
changing its size generates
Expose
events on windows that the mapped window formerly obscured.
If the override-redirect flag of the window is
False
and some
other client has selected
SubstructureRedirectMask
on the parent, the X server generates a
ConfigureRequest
event, and no further processing is performed.
If either width or height is zero,
a
BadValue
error results.
XResizeWindow
can generate
BadValue
and
BadWindow
errors.
To change the size and location of a window, use
XMoveResizeWindow.
XMoveResizeWindow
XMoveResizeWindow
Display *display
Window w
intx, y
unsignedintwidth, height
display
Specifies the connection to the X server.
w
Specifies the window (Wi.
x
y
Specify the x and y coordinates(Xy.
width
height
Specify the width and height(Wh.
The
XMoveResizeWindow
function changes the size and location of the specified window
without raising it.
Moving and resizing a mapped window may generate an
Expose
event on the window.
Depending on the new size and location parameters,
moving and resizing a window may generate
Expose
events on windows that the window formerly obscured.
If the override-redirect flag of the window is
False
and some
other client has selected
SubstructureRedirectMask
on the parent, the X server generates a
ConfigureRequest
event, and no further processing is performed.
Otherwise, the window size and location are changed.
XMoveResizeWindow
can generate
BadValue
and
BadWindow
errors.
To change the border width of a given window, use
XSetWindowBorderWidth.
XSetWindowBorderWidth
XSetWindowBorderWidth
Display *display
Window w
unsignedint width
display
Specifies the connection to the X server.
w
Specifies the window.
width
Specifies the width of the window border.
The
XSetWindowBorderWidth
function sets the specified window's border width to the specified width.
XSetWindowBorderWidth
can generate a
BadWindow
error.
Changing Window Stacking Order
Xlib provides functions that you can use to raise, lower, circulate,
or restack windows.
To raise a window so that no sibling window obscures it, use
XRaiseWindow.
XRaiseWindow
XRaiseWindow
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XRaiseWindow
function
raises the specified window to the top of the stack so that no sibling window
obscures it.
If the windows are regarded as overlapping sheets of paper stacked
on a desk,
then raising a window is analogous to moving the sheet to the top of
the stack but leaving its x and y location on the desk constant.
Raising a mapped window may generate
Expose
events for the window and any mapped subwindows that were formerly obscured.
If the override-redirect attribute of the window is
False
and some
other client has selected
SubstructureRedirectMask
on the parent, the X server generates a
ConfigureRequest
event, and no processing is performed.
Otherwise, the window is raised.
XRaiseWindow
can generate a
BadWindow
error.
To lower a window so that it does not obscure any sibling windows, use
XLowerWindow.
XLowerWindow
XLowerWindow
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XLowerWindow
function lowers the specified window to the bottom of the stack
so that it does not obscure any sibling
windows.
If the windows are regarded as overlapping sheets of paper
stacked on a desk, then lowering a window is analogous to moving the
sheet to the bottom of the stack but leaving its x and y location on
the desk constant.
Lowering a mapped window will generate
Expose
events on any windows it formerly obscured.
If the override-redirect attribute of the window is
False
and some
other client has selected
SubstructureRedirectMask
on the parent, the X server generates a
ConfigureRequest
event, and no processing is performed.
Otherwise, the window is lowered to the bottom of the
stack.
XLowerWindow
can generate a
BadWindow
error.
To circulate a subwindow up or down, use
XCirculateSubwindows.
XCirculateSubwindows
XCirculateSubwindows
Display *display
Window w
int direction
display
Specifies the connection to the X server.
w
Specifies the window.
direction
Specifies the direction (up or down) that you want to circulate
the window.
You can pass
RaiseLowest
or
LowerHighest.
The
XCirculateSubwindows
function circulates children of the specified window in the specified
direction.
If you specify
RaiseLowest,
XCirculateSubwindows
raises the lowest mapped child (if any) that is occluded
by another child to the top of the stack.
If you specify
LowerHighest,
XCirculateSubwindows
lowers the highest mapped child (if any) that occludes another child
to the bottom of the stack.
Exposure processing is then performed on formerly obscured windows.
If some other client has selected
SubstructureRedirectMask
on the window, the X server generates a
CirculateRequest
event, and no further processing is performed.
If a child is actually restacked,
the X server generates a
CirculateNotify
event.
XCirculateSubwindows
can generate
BadValue
and
BadWindow
errors.
To raise the lowest mapped child of a window that is partially or completely
occluded by another child, use
XCirculateSubwindowsUp.
XCirculateSubwindowsUp
XCirculateSubwindowsUp
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XCirculateSubwindowsUp
function raises the lowest mapped child of the specified window that
is partially
or completely
occluded by another child.
Completely unobscured children are not affected.
This is a convenience function equivalent to
XCirculateSubwindows
with
RaiseLowest
specified.
XCirculateSubwindowsUp
can generate a
BadWindow
error.
To lower the highest mapped child of a window that partially or
completely occludes another child, use
XCirculateSubwindowsDown.
XCirculateSubwindowsDown
XCirculateSubwindowsDown
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XCirculateSubwindowsDown
function lowers the highest mapped child of the specified window that partially
or completely occludes another child.
Completely unobscured children are not affected.
This is a convenience function equivalent to
XCirculateSubwindows
with
LowerHighest
specified.
XCirculateSubwindowsDown
can generate a
BadWindow
error.
To restack a set of windows from top to bottom, use
XRestackWindows.
XRestackWindows
XRestackWindows
Display *display
Window windows[]
int nwindows
display
Specifies the connection to the X server.
windows
Specifies an array containing the windows to be restacked.
nwindows
Specifies the number of windows to be restacked.
The
XRestackWindows
function restacks the windows in the order specified,
from top to bottom.
The stacking order of the first window in the windows array is unaffected,
but the other windows in the array are stacked underneath the first window,
in the order of the array.
The stacking order of the other windows is not affected.
For each window in the window array that is not a child of the specified window,
a
BadMatch
error results.
If the override-redirect attribute of a window is
False
and some
other client has selected
SubstructureRedirectMask
on the parent, the X server generates
ConfigureRequest
events for each window whose override-redirect flag is not set,
and no further processing is performed.
Otherwise, the windows will be restacked in top-to-bottom order.
XRestackWindows
can generate a
BadWindow
error.
Changing Window Attributes
Xlib provides functions that you can use to set window attributes.
XChangeWindowAttributes
is the more general function that allows you to set one or more window
attributes provided by the
XSetWindowAttributes
structure.
The other functions described in this section allow you to set one specific
window attribute, such as a window's background.
To change one or more attributes for a given window, use
XChangeWindowAttributes.
XChangeWindowAttributes
XChangeWindowAttributes
Display *display
Window w
unsignedlong valuemask
XSetWindowAttributes *attributes
display
Specifies the connection to the X server.
w
Specifies the window.
valuemask
Specifies which window attributes are defined in the attributes
argument.
This mask is the bitwise inclusive OR of the valid attribute mask bits.
If valuemask is zero,
the attributes are ignored and are not referenced.
The values and restrictions are
the same as for
XCreateWindow.
attributes
Specifies the structure from which the values (as specified by the value mask)
are to be taken.
The value mask should have the appropriate bits
set to indicate which attributes have been set in the structure
(see section 3.2).
Depending on the valuemask,
the
XChangeWindowAttributes
function uses the window attributes in the
XSetWindowAttributes
structure to change the specified window attributes.
Changing the background does not cause the window contents to be
changed.
To repaint the window and its background, use
XClearWindow.
Setting the border or changing the background such that the
border tile origin changes causes the border to be repainted.
Changing the background of a root window to
None
or
ParentRelative
restores the default background pixmap.
Changing the border of a root window to
CopyFromParent
restores the default border pixmap.
Changing the win-gravity does not affect the current position of the
window.
Changing the backing-store of an obscured window to
WhenMapped
or
Always,
or changing the backing-planes, backing-pixel, or
save-under of a mapped window may have no immediate effect.
Changing the colormap of a window (that is, defining a new map, not
changing the contents of the existing map) generates a
ColormapNotify
event.
Changing the colormap of a visible window may have no
immediate effect on the screen because the map may not be installed
(see
XInstallColormap).
Changing the cursor of a root window to
None
restores the default
cursor.
Whenever possible, you are encouraged to share colormaps.
Multiple clients can select input on the same window.
Their event masks are maintained separately.
When an event is generated,
it is reported to all interested clients.
However, only one client at a time can select for
SubstructureRedirectMask,
ResizeRedirectMask,
and
ButtonPressMask.
If a client attempts to select any of these event masks
and some other client has already selected one,
a
BadAccess
error results.
There is only one do-not-propagate-mask for a window,
not one per client.
XChangeWindowAttributes
can generate
BadAccess,
BadColor,
BadCursor,
BadMatch,
BadPixmap,
BadValue,
and
BadWindow
errors.
To set the background of a window to a given pixel, use
XSetWindowBackground.
XSetWindowBackground
XSetWindowBackground
Display *display
Window w
unsignedlong background_pixel
display
Specifies the connection to the X server.
w
Specifies the window.
background_pixel
Specifies the pixel that is to be used for the background.
The
XSetWindowBackground
function sets the background of the window to the specified pixel value.
Changing the background does not cause the window contents to be changed.
XSetWindowBackground
uses a pixmap of undefined size filled with the pixel value you passed.
If you try to change the background of an
InputOnly
window, a
BadMatch
error results.
XSetWindowBackground
can generate
BadMatch
and
BadWindow
errors.
To set the background of a window to a given pixmap, use
XSetWindowBackgroundPixmap.
Windowbackground
XSetWindowBackgroundPixmap
XSetWindowBackgroundPixmap
Display *display
Window w
Pixmap background_pixmap
display
Specifies the connection to the X server.
w
Specifies the window.
background_pixmap
Specifies the background pixmap,
ParentRelative,
or
None.
Resource IDsfreeing
Freeingresources
The
XSetWindowBackgroundPixmap
function sets the background pixmap of the window to the specified pixmap.
The background pixmap can immediately be freed if no further explicit
references to it are to be made.
If
ParentRelative
is specified,
the background pixmap of the window's parent is used,
or on the root window, the default background is restored.
If you try to change the background of an
InputOnly
window, a
BadMatch
error results.
If the background is set to
None,
the window has no defined background.
XSetWindowBackgroundPixmap
can generate
BadMatch,
BadPixmap,
and
BadWindow
errors.
XSetWindowBackground
and
XSetWindowBackgroundPixmap
do not change the current contents of the window.
To change and repaint a window's border to a given pixel, use
XSetWindowBorder.
XSetWindowBorder
XSetWindowBorder
Display *display
Window w
unsignedlong border_pixel
display
Specifies the connection to the X server.
w
Specifies the window.
border_pixel
Specifies the entry in the colormap.
The
XSetWindowBorder
function sets the border of the window to the pixel value you specify.
If you attempt to perform this on an
InputOnly
window, a
BadMatch
error results.
XSetWindowBorder
can generate
BadMatch
and
BadWindow
errors.
To change and repaint the border tile of a given window, use
XSetWindowBorderPixmap.
XSetWindowBorderPixmap
XSetWindowBorderPixmap
Display *display
Window w
Pixmap border_pixmap
display
Specifies the connection to the X server.
w
Specifies the window.
border_pixmap
Specifies the border pixmap or
CopyFromParent.
The
XSetWindowBorderPixmap
function sets the border pixmap of the window to the pixmap you specify.
The border pixmap can be freed immediately if no further explicit
references to it are to be made.
If you specify
CopyFromParent,
a copy of the parent window's border pixmap is used.
If you attempt to perform this on an
InputOnly
window, a
BadMatch
error results.
Resource IDsfreeing
Freeingresources
XSetWindowBorderPixmap
can generate
BadMatch,
BadPixmap,
and
BadWindow
errors.
To set the colormap of a given window, use
XSetWindowColormap.
XSetWindowColormap
XSetWindowColormap
Display *display
Window w
Colormap colormap
display
Specifies the connection to the X server.
w
Specifies the window.
colormap
Specifies the colormap.
The
XSetWindowColormap
function sets the specified colormap of the specified window.
The colormap must have the same visual type as the window,
or a
BadMatch
error results.
XSetWindowColormap
can generate
BadColor,
BadMatch,
and
BadWindow
errors.
To define which cursor will be used in a window, use
XDefineCursor.
Windowdefining the cursor
XDefineCursor
XDefineCursor
Display *display
Window w
Cursor cursor
display
Specifies the connection to the X server.
w
Specifies the window.
cursor
Specifies the cursor that is to be displayed or
None.
If a cursor is set, it will be used when the pointer is in the window.
If the cursor is
None,
it is equivalent to
XUndefineCursor.
XDefineCursor
can generate
BadCursor
and
BadWindow
errors.
To undefine the cursor in a given window, use
XUndefineCursor.
Windowundefining the cursor
XUndefineCursor
XUndefineCursor
Display *display
Window w
display
Specifies the connection to the X server.
w
Specifies the window.
The
XUndefineCursor
function undoes the effect of a previous
XDefineCursor
for this window.
When the pointer is in the window,
the parent's cursor will now be used.
On the root window,
the default cursor is restored.
XUndefineCursor
can generate a
BadWindow
error.