InfoMagic Source Code 1993 July/THE_SOURCE_CODE_CD_ROM.iso/X/mit/doc/Xlib/CH03

Text File | 1991-08-18 | 83.6 KB | 3,214 lines

\&
.sp 1
.ce 3
\s+1\fBChapter 3\fP\s-1

\s+1\fBWindow Functions\fP\s-1
.sp 2
.nr H1 3
.nr H2 0
.nr H3 0
.nr H4 0
.nr H5 0
.na
.LP
.XS
Chapter 3: Window Functions
.XE
In the X Window System,
a window is a rectangular area on the screen that lets you
view graphic output.
Client applications
can display overlapping and nested windows on one or more
screens that are driven by X servers on one or more machines.
Clients who want to create windows must first
connect their program to the X server
by calling
.PN XOpenDisplay .
This chapter begins with a discussion of
visual types and window attributes.
The chapter continues with a discussion of the Xlib functions you can use to:
.IP \(bu 5
Create windows
.IP \(bu 5
Destroy windows
.IP \(bu 5
Map windows
.IP \(bu 5
Unmap windows
.IP \(bu 5
Configure windows
.IP \(bu 5
Change the stacking order
.IP \(bu 5
Change window attributes
.RE
.LP
This chapter also identifies the window actions that may generate events.
.LP
Note that it is vital that your application conform to the
established conventions for communicating with window managers
for it to work well with the various window managers in use (see section 14.1).
Toolkits generally adhere to these conventions for you,
relieving you of the burden.
Toolkits also often supersede many functions in this chapter
with versions of their own.
Refer to the documentation for the toolkit you are using
for more information.
.NH 2
Visual Types
.XS
\*(SN Visual Types
.XE
.LP
.IN "Visual Type" "" "@DEF@"
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).
.LP
Xlib uses an opaque
.PN Visual
.IN "Visual" "" "@DEF@"
structure that contains information about the possible color mapping.
The visual utility functions (see section 16.7) use an
.PN 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
.IN "Visual Classes" "StaticGray"
.IN "Visual Classes" "StaticColor"
.IN "Visual Classes" "TrueColor"
.IN "Visual Classes" "StaticColor"
.IN "Visual Classes" "GrayScale"
.IN "Visual Classes" "PseudoColor"
.PN StaticGray ,
.PN StaticColor ,
.PN TrueColor ,
.PN GrayScale ,
.PN PseudoColor ,
or
.PN DirectColor .
.LP
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:
.LP
.DS 0
.TA 1.1i 1.6i 2.2i 2.7i 3.2i
.ta 1.1i 1.6i 2.2i 2.7i 3.2i
        Color          GrayScale
    \ \ R/O      \ R/W     \ R/O    \ R/W
+-------------------+----------------------------------------+
\|| Undecomposed    |\ Static    |\ Pseudo    |\ Static    |\ Gray    |
\||  Colormap    |\ Color    |\ Color    |\ Gray    |\ Scale    |
+-------------------+----------------------------------------+
\|| Decomposed    |\ True    |\ Direct    |
\||  Colormap    |\ Color    |\ Color    |
+-------------------+--------------------+
.DE
.LP
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:
.LP
.IP \(bu 5
For
.PN PseudoColor ,
a pixel value indexes a colormap to produce
independent RGB values, and the RGB values can be changed dynamically.
.IP \(bu 5
.PN GrayScale
is treated the same way as
.PN 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.
.IP \(bu 5
For
.PN 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.
.IP \(bu 5
.PN TrueColor
is treated the same way as
.PN 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.
.IP \(bu 5
.PN StaticColor
is treated the same way as
.PN PseudoColor
except that the colormap has predefined,
read-only, server-dependent RGB values.
.IP \(bu 5
.PN StaticGray
is treated the same way as
.PN StaticColor
except that the RGB values are equal for any single pixel
value, thus resulting in shades of gray.
.PN StaticGray
with a two-entry
colormap can be thought of as monochrome.
.LP
The red_mask, green_mask, and blue_mask members are only defined for
.PN DirectColor
and
.PN 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
.PN DirectColor
and
.PN TrueColor ,
this is the size of an individual pixel subfield.
.sp
.LP
To obtain the visual ID from a
.PN Visual ,
use
.PN XVisualIDFromVisual .
.IN "XVisualIDFromVisual" "" "@DEF@"
.\" Start marker code here
.FD 0
VisualID XVisualIDFromVisual\^(\^\fIvisual\fP\^)
.br
       Visual *\^\fIvisual\fP\^;
.FN
.\" $Header: visual_gen.a,v 1.1 88/07/10 10:05:08 mento Exp $
.IP \fIvisual\fP 1i
Specifies the visual type.
.\" End marker code here
.LP
The
.PN XVisualIDFromVisual
function returns the visual ID for the specified visual type.
.NH 2
Window Attributes
.XS
\*(SN Window Attributes
.XE
.LP
.IN "Window"
.IN "Window" "attributes"
All
.PN 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.
.LP
Windows also have associated property lists (see section 4.3).
.LP
Both
.PN InputOutput
and
.PN InputOnly
windows have the following common attributes,
which are the only attributes of an
.PN InputOnly
window:
.IP \(bu 5
win-gravity
.IP \(bu 5
event-mask
.IP \(bu 5
do-not-propagate-mask
.IP \(bu 5
override-redirect
.IP \(bu 5
cursor
.LP
If you specify any other attributes for an
.PN InputOnly
window,
a
.PN BadMatch
error results.
.LP
.PN InputOnly
windows are used for controlling input events in situations where
.PN InputOutput
windows are unnecessary.
.PN 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
.PN InputOnly
windows cannot have
.PN InputOutput
windows as inferiors.
.LP
Windows have borders of a programmable width and pattern
as well as a background pattern or tile.
.IN "Tile" "pixmaps"
Pixel values can be used for solid colors.
.IN "Resource IDs" "freeing"
.IN "Freeing" "resources"
The background and border pixmaps can be destroyed immediately after
creating the window if no further explicit references to them
are to be made.
.IN "Tile" "mode"
The pattern can either be relative to the parent
or absolute.
If
.PN ParentRelative ,
the parent's background is used.
.LP
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.
.IN "Window" "mapping"
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
.PN XMapWindow ),
.IN "XMapWindow"
the X server generates an
.PN Expose
event for the window if backing store has not been maintained.
.LP
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.
.LP
To set an attribute of a window,
set the appropriate member of the
.PN XSetWindowAttributes
structure and OR in the corresponding value bitmask in your subsequent calls to
.PN XCreateWindow
and
.PN XChangeWindowAttributes ,
or use one of the other convenience functions that set the appropriate
attribute.
The symbols for the value mask bits and the
.PN XSetWindowAttributes
structure are:
.\" Start marker code here
.LP
/* Window attribute value mask bits */
.TS
lw(.5i) lw(2.5i) lw(.8i).
T{
#define
T}    T{
.PN CWBackPixmap
T}    T{
(1L<<0)
T}
T{
#define
T}    T{
.PN CWBackPixel
T}    T{
(1L<<1)
T}
T{
#define
T}    T{
.PN CWBorderPixmap
T}    T{
(1L<<2)
T}
T{
#define
T}    T{
.PN CWBorderPixel
T}    T{
(1L<<3)
T}
T{
#define
T}    T{
.PN CWBitGravity
T}    T{
(1L<<4)
T}
T{
#define
T}    T{
.PN CWWinGravity
T}    T{
(1L<<5)
T}
T{
#define
T}    T{
.PN CWBackingStore
T}    T{
(1L<<6)
T}
T{
#define
T}    T{
.PN CWBackingPlanes
T}    T{
(1L<<7)
T}
T{
#define
T}    T{
.PN CWBackingPixel
T}    T{
(1L<<8)
T}
T{
#define
T}    T{
.PN CWOverrideRedirect
T}    T{
(1L<<9)
T}
T{
#define
T}    T{
.PN CWSaveUnder
T}    T{
(1L<<10)
T}
T{
#define
T}    T{
.PN CWEventMask
T}    T{
(1L<<11)
T}
T{
#define
T}    T{
.PN CWDontPropagate
T}    T{
(1L<<12)
T}
T{
#define
T}    T{
.PN CWColormap
T}    T{
(1L<<13)
T}
T{
#define
T}    T{
.PN CWCursor
T}    T{
(1L<<14)
T}
.TE
.IN "XSetWindowAttributes" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
/* 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;
.De
.\" End marker code here
.LP
The following lists the defaults for each window attribute and indicates
whether the attribute is applicable to
.PN InputOutput
and
.PN InputOnly
windows:
.TS H
l l l l
lw(1.4i) lw(1.3i) cw(.9i) cw(.8i).
_
.sp 6p
T{
.B Attribute
T}    T{
.B Default
T}    T{
.PN InputOutput
T}    T{
.PN InputOnly
T}
.sp 6p
_
.sp 6p
.TH
.R
T{
background-pixmap
T}    T{
.PN None
T}    T{
Yes
T}    T{
No
T}
background-pixel    Undefined    Yes    No
T{
border-pixmap
T}    T{
.PN CopyFromParent
T}    T{
Yes
T}    T{
No
T}
border-pixel    Undefined    Yes    No
T{
bit-gravity
T}    T{
.PN ForgetGravity
T}    T{
Yes
T}    T{
No
T}
T{
win-gravity
T}    T{
.PN NorthWestGravity
T}    T{
Yes
T}    T{
Yes
T}
T{
backing-store
T}    T{
.PN NotUseful
T}    T{
Yes
T}    T{
No
T}
backing-planes    All ones    Yes    No
backing-pixel    zero    Yes    No
T{
save-under
T}    T{
.PN False
T}    T{
Yes
T}    T{
No
T}
event-mask    empty set    Yes    Yes
do-not-propagate-mask    empty set    Yes    Yes
T{
override-redirect
T}    T{
.PN False
T}    T{
Yes
T}    T{
Yes
T}
T{
colormap
T}    T{
.PN CopyFromParent
T}    T{
Yes
T}    T{
No
T}
T{
cursor
T}    T{
.PN None
T}    T{
Yes
T}    T{
Yes
T}
_
.TE
.NH 3
Background Attribute
.XS
\*(SN Background Attribute
.XE
.LP
Only
.PN InputOutput
windows can have a background.
You can set the background of an
.PN InputOutput
window by using a pixel or a pixmap.
.LP
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.
.LP
You can set the background-pixmap to a pixmap,
.PN None
(default), or
.PN 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.
.LP
If you set the background-pixmap,
it overrides the default.
The background-pixmap and the window must have the same depth,
or a
.PN BadMatch
error results.
If you set background-pixmap to
.PN None ,
the window has no defined background.
If you set the background-pixmap to
.PN ParentRelative :
.IP \(bu 5
The parent window's background-pixmap is used.
The child window, however, must have the same depth as
its parent,
or a
.PN BadMatch
error results.
.IP \(bu 5
If the parent window has a background-pixmap of
.PN None ,
the window also has a background-pixmap of
.PN None .
.IP \(bu 5
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.
.IP \(bu 5
The background tile origin always aligns with the parent window's
background tile origin.
If the background-pixmap is not
.PN ParentRelative ,
the background tile origin is the child window's origin.
.LP
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.
.LP
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
.PN None .
If the background is
.PN 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.
.PN Expose
events are then generated for the regions, even if the background-pixmap
is
.PN None
(see section 10.9).
.NH 3
Border Attribute
.XS
\*(SN Border Attribute
.XE
.LP
Only
.PN InputOutput
windows can have a border.
You can set the border of an
.PN InputOutput
window by using a pixel or a pixmap.
.LP
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.
.LP
You can also set the border-pixmap to a pixmap of any size (some may be faster
than others) or to
.PN CopyFromParent
(default).
You can set the border-pixel to any pixel value (no default).
.LP
If you set a border-pixmap,
it overrides the default.
The border-pixmap and the window must have the same depth,
or a
.PN BadMatch
error results.
If you set the border-pixmap to
.PN 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
.PN BadMatch
error results.
.LP
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.
.LP
Output to a window is always clipped to the inside of the window.
Therefore, graphics operations never affect the window border.
.NH 3
Gravity Attributes
.XS
\*(SN Gravity Attributes
.XE
.LP
The bit gravity of a window defines which region of the window should be
retained when an
.PN InputOutput
window is resized.
The default value for the bit-gravity attribute is
.PN ForgetGravity .
The window gravity of a window allows you to define how the
.PN InputOutput
or
.PN InputOnly
window should be repositioned if its parent is resized.
The default value for the win-gravity attribute is
.PN NorthWestGravity .
.LP
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:
.LP
.TS
l l
l l.
_
.sp 6p
.B
Gravity Direction    Coordinates
.sp 6p
_
.sp 6p
.R
T{
.PN NorthWestGravity
T}    T{
(0, 0)
T}
T{
.PN NorthGravity
T}    T{
(Width/2, 0)
T}
T{
.PN NorthEastGravity
T}    T{
(Width, 0)
T}
T{
.PN WestGravity
T}    T{
(0, Height/2)
T}
T{
.PN CenterGravity
T}    T{
(Width/2, Height/2)
T}
T{
.PN EastGravity
T}    T{
(Width, Height/2)
T}
T{
.PN SouthWestGravity
T}    T{
(0, Height)
T}
T{
.PN SouthGravity
T}    T{
(Width/2, Height)
T}
T{
.PN SouthEastGravity
T}    T{
(Width, Height)
T}
.sp 6p
_
.TE
.LP
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
.PN GravityNotify
event is generated (see section 10.10.5).
.LP
A bit-gravity of
.PN 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
.PN StaticGravity
still only takes effect when the width or height of the window is changed,
not when the window is moved.
.LP
A bit-gravity of
.PN 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
.PN 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
.PN Expose
events.
.LP
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
.PN Forget
instead.
.LP
A win-gravity of
.PN UnmapGravity
is like
.PN NorthWestGravity
(the window is not moved),
except the child is also
unmapped when the parent is resized,
and an
.PN UnmapNotify
event is
generated.
.NH 3
Backing Store Attribute
.XS
\*(SN Backing Store Attribute
.XE
.LP
Some implementations of the X server may choose to maintain the contents of
.PN 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
.PN NotUseful
(default),
.PN WhenMapped ,
or
.PN Always .
.LP
A backing-store attribute of
.PN NotUseful
advises the X server that
maintaining contents is unnecessary,
although some X implementations may
still choose to maintain contents and, therefore, not generate
.PN Expose
events.
A backing-store attribute of
.PN 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
.PN Expose
event when the window is created.
A backing-store attribute of
.PN 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,
.PN Expose
events normally are not generated,
but the X server may stop maintaining
contents at any time.
.LP
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.
.NH 3
Save Under Flag
.XS
\*(SN Save Under Flag
.XE
.IN "Save Unders"
.LP
Some server implementations may preserve contents of
.PN InputOutput
windows under other
.PN 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.
.LP
You can set the save-under flag to
.PN True
or
.PN False
(default).
If save-under is
.PN True ,
the X server is advised that, when this window is mapped,
saving the contents of windows it obscures would be beneficial.
.NH 3
Backing Planes and Backing Pixel Attributes
.XS
\*(SN Backing Planes and Backing Pixel Attributes
.XE
.LP
You can set backing planes to indicate (with bits set to 1)
which bit planes of an
.PN 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.
.NH 3
Event Mask and Do Not Propagate Mask Attributes
.XS
\*(SN Event Mask and Do Not Propagate Mask Attributes
.XE
.LP
The event mask defines which events the client is interested in for this
.PN InputOutput
or
.PN 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
.PN NoEventMask
(default).
.LP
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
.PN InputOutput
or
.PN InputOnly
window.
The do-not-propagate-mask is the bitwise inclusive OR of zero or more
of the following masks:
.PN KeyPress ,
.PN KeyRelease ,
.PN ButtonPress ,
.PN ButtonRelease ,
.PN PointerMotion ,
.PN Button1Motion ,
.PN Button2Motion ,
.PN Button3Motion ,
.PN Button4Motion ,
.PN Button5Motion ,
and
.PN ButtonMotion .
You can specify that all events are propagated by setting
.PN NoEventMask
(default).
.NH 3
Override Redirect Flag
.XS
\*(SN Override Redirect Flag
.XE
.LP
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
.PN InputOutput
or
.PN InputOnly
window is to ignore these structure control facilities,
use the override-redirect flag.
.LP
The override-redirect flag specifies whether map and configure requests
on this window should override a
.PN SubstructureRedirectMask
on the parent.
You can set the override-redirect flag to
.PN True
or
.PN False
(default).
Window managers use this information to avoid tampering with pop-up windows
(see also chapter 14).
.NH 3
Colormap Attribute
.XS
\*(SN Colormap Attribute
.XE
.LP
The colormap attribute specifies which colormap best reflects the true
colors of the
.PN InputOutput
window.
The colormap must have the same visual type as the window,
or a
.PN BadMatch
error results.
X servers capable of supporting multiple
hardware colormaps can use this information,
and window managers can use it for calls to
.PN XInstallColormap .
You can set the colormap attribute to a colormap or to
.PN CopyFromParent
(default).
.LP
If you set the colormap to
.PN 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
.PN BadMatch
error results.
The parent window must not have a colormap of
.PN None ,
or a
.PN 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.
.NH 3
Cursor Attribute
.XS
\*(SN Cursor Attribute
.XE
.LP
The cursor attribute specifies which cursor is to be used when the pointer is
in the
.PN InputOutput
or
.PN InputOnly
window.
You can set the cursor to a cursor or
.PN None
(default).
.LP
If you set the cursor to
.PN None ,
the parent's cursor is used when the
pointer is in the
.PN InputOutput
or
.PN InputOnly
window, and any change in the parent's cursor will cause an
immediate change in the displayed cursor.
By calling
.PN XFreeCursor ,
the cursor can be freed immediately as long as no further explicit reference
to it is made.
.NH 2
Creating Windows
.XS
\*(SN Creating Windows
.XE
.LP
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).
.LP
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:
.IP \(bu 5
You must never fight with the window manager for the size or
placement of your top-level window.
.IP \(bu 5
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.
.IP \(bu 5
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.)
.IP \(bu 5
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.
.LP
For further information,
see chapter 14 and the \fIInter-Client Communication Conventions Manual\fP.
.LP
.PN XCreateWindow
is the more general function that allows you to set specific window attributes
when you create a window.
.PN XCreateSimpleWindow
creates a window that inherits its attributes from its parent window.
.LP
.IN "Window" "InputOnly"
The X server acts as if
.PN InputOnly
windows do not exist for
the purposes of graphics requests, exposure processing, and
.PN VisibilityNotify
events.
An
.PN InputOnly
window cannot be used as a
drawable (that is, as a source or destination for graphics requests).
.PN InputOnly
and
.PN InputOutput
windows act identically in other respects (properties,
grabs, input control, and so on).
Extension packages can define other classes of windows.
.LP
To create an unmapped window and set its window attributes, use
.PN XCreateWindow .
.IN "XCreateWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XWindow.f,v 1.1 88/02/26 10:04:14 mento Exp $
Window XCreateWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, \fIdepth\fP\^,
.br
                       \fIclass\fP\^, \fIvisual\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIparent\fP\^;
.br
      int \fIx\fP\^, \fIy\fP\^;
.br
      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
.br
      unsigned int \fIborder_width\fP\^;
.br
      int \fIdepth\fP\^;
.br
      unsigned int \fIclass\fP\^;
.br
      Visual *\fIvisual\fP\^
.br
      unsigned long \fIvaluemask\fP\^;
.br
      XSetWindowAttributes *\fIattributes\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: parent.a,v 1.2 88/05/07 11:34:55 mento Exp $
.IP \fIparent\fP 1i
Specifies the parent window.
.ds Xy , which are the top-left outside corner of the created window's \
borders and are relative to the inside of the parent window's borders
.\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the x and y coordinates\*(Xy.
.ds Wh , which are the created window's inside dimensions \
and do not include the created window's borders
.\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
.IP \fIwidth\fP 1i
.br
.ns
.IP \fIheight\fP 1i
Specify the width and height\*(Wh.
The dimensions must be nonzero,
or a
.PN BadValue
error results.
.\" $Header: borderwidth.a,v 1.4 88/05/07 11:43:25 mento Exp $
.IP \fIborder_width\fP 1i
Specifies the width of the created window's border in pixels.
.\" $Header: depth.a,v 1.3 88/05/07 11:48:11 mento Exp $
.IP \fIdepth\fP 1i
Specifies the window's depth.
A depth of
.PN CopyFromParent
means the depth is taken from the parent.
.\" $Header: class.a,v 1.2 88/04/04 11:10:33 mento Exp $
.IP \fIclass\fP 1i
Specifies the created window's class.
You can pass
.PN InputOutput ,
.PN InputOnly ,
or
.PN CopyFromParent .
A class of
.PN CopyFromParent
means the class
is taken from the parent.
.\" $Header: visual.a,v 1.1 88/02/26 10:32:16 mento Exp $
.IP \fIvisual\fP 1i
Specifies the visual type.
A visual of
.PN CopyFromParent
means the visual type is taken from the
parent.
.\" $Header: valuemask.a,v 1.1 88/02/26 10:32:07 mento Exp $
.IP \fIvaluemask\fP 1i
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.
.\" $Header: attributes.a,v 1.4 88/05/07 11:49:37 mento Exp $
.IP \fIattributes\fP 1i
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.
.\" End marker code here
.LP
.\" $Header: XWindow.d,v 1.3 88/08/17 08:19:17 mento Exp $
The
.PN 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
.PN CreateNotify
event.
The created window is placed on top in the stacking order
with respect to siblings.
.LP
The coordinate system has the X axis horizontal and the Y axis vertical,
with the origin [0, 0] at the upper left.
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.
.LP
The border_width for an
.PN InputOnly
window must be zero, or a
.PN BadMatch
error results.
For class
.PN InputOutput ,
the visual type and depth must be a combination supported for the screen,
or a
.PN BadMatch
error results.
The depth need not be the same as the parent,
but the parent must not be a window of class
.PN InputOnly ,
or a
.PN BadMatch
error results.
For an
.PN InputOnly
window,
the depth must be zero, and the visual must be one supported by the screen.
If either condition is not met,
a
.PN BadMatch
error results.
The parent window, however, may have any depth and class.
If you specify any invalid window attribute for a window, a
.PN BadMatch
error results.
.LP
The created window is not yet displayed (mapped) on the user's display.
To display the window, call
.PN XMapWindow .
The new window initially uses the same cursor as
its parent.
A new cursor can be defined for the new window by calling
.PN XDefineCursor .
.IN "Cursor" "Initial State"
.IN "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.
.LP
.PN XCreateWindow
can generate
.PN BadAlloc ,
.PN BadColor ,
.PN BadCursor ,
.PN BadMatch ,
.PN BadPixmap ,
.PN BadValue ,
and
.PN BadWindow
errors.
.LP
.sp
To create an unmapped
.PN InputOutput
subwindow of a given parent window, use
.PN XCreateSimpleWindow .
.IN "XCreateSimpleWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XCreWin.f,v 1.2 88/04/05 13:35:18 mento Exp $
Window XCreateSimpleWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^,
.br
                             \fIborder\fP\^, \fIbackground\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIparent\fP\^;
.br
      int \fIx\fP\^, \fIy\fP\^;
.br
      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
.br
      unsigned int \fIborder_width\fP\^;
.br
      unsigned long \fIborder\fP\^;
.br
      unsigned long \fIbackground\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: parent.a,v 1.2 88/05/07 11:34:55 mento Exp $
.IP \fIparent\fP 1i
Specifies the parent window.
.ds Xy , which are the top-left outside corner of the new window's borders \
and are relative to the inside of the parent window's borders
.\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the x and y coordinates\*(Xy.
.ds Wh , which are the created window's inside dimensions \
and do not include the created window's borders
.\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
.IP \fIwidth\fP 1i
.br
.ns
.IP \fIheight\fP 1i
Specify the width and height\*(Wh.
The dimensions must be nonzero,
or a
.PN BadValue
error results.
.\" $Header: borderwidth.a,v 1.4 88/05/07 11:43:25 mento Exp $
.IP \fIborder_width\fP 1i
Specifies the width of the created window's border in pixels.
.\" $Header: border.a,v 1.1 88/02/26 10:05:15 mento Exp $
.IP \fIborder\fP 1i
Specifies the border pixel value of the window.
.\" $Header: backpixel.a,v 1.1 88/02/26 10:05:04 mento Exp $
.IP \fIbackground\fP 1i
Specifies the background pixel value of the window.

.\" End marker code here
.LP
.\" $Header: XCreWin.d,v 1.2 88/06/11 07:49:39 mento Exp $
The
.PN XCreateSimpleWindow
function creates an unmapped
.PN InputOutput
subwindow for a specified parent window, returns the
window ID of the created window, and causes the X server to generate a
.PN 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
.PN InputOnly
window must be zero, or a
.PN BadMatch
error results.
.PN XCreateSimpleWindow
inherits its depth, class, and visual from its parent.
All other window attributes, except background and border,
have their default values.
.LP
.PN XCreateSimpleWindow
can generate
.PN BadAlloc ,
.PN BadMatch ,
.PN BadValue ,
and
.PN BadWindow
errors.
.NH 2
Destroying Windows
.XS
\*(SN Destroying Windows
.XE
.LP
Xlib provides functions that you can use to destroy a window or destroy all
subwindows of a window.
.LP
.sp
To destroy a window and all of its subwindows, use
.PN XDestroyWindow .
.IN "XDestroyWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XDestroyWind.f,v 1.1 88/02/26 09:59:40 mento Exp $
XDestroyWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XDestroyWind.d,v 1.3 88/08/17 08:20:48 mento Exp $
The
.PN XDestroyWindow
function destroys the specified window as well as all of its subwindows and causes
the X server to generate a
.PN 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
.PN DestroyNotify
events is such that for any given window being destroyed,
.PN 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
.PN Expose
events on other windows that were obscured by the window being destroyed.
.LP
.PN XDestroyWindow
can generate a
.PN BadWindow
error.
.LP
.sp
To destroy all subwindows of a specified window, use
.PN XDestroySubwindows .
.IN "XDestroySubwindows" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XDestroySubs.f,v 1.1 88/02/26 09:59:40 mento Exp $
XDestroySubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XDestroySubs.d,v 1.4 88/06/11 07:50:01 mento Exp $
The
.PN XDestroySubwindows
function destroys all inferior windows of the specified window,
in bottom-to-top stacking order.
It causes the X server to generate a
.PN DestroyNotify
event for each window.
If any mapped
subwindows were actually destroyed,
.PN XDestroySubwindows
causes the X server to generate
.PN 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.
.LP
.PN XDestroySubwindows
can generate a
.PN BadWindow
error.
.NH 2
Mapping Windows
.XS
\*(SN Mapping Windows
.XE
.LP
A window is considered mapped if an
.PN XMapWindow
call has been made on it.
It may not be visible on the screen for one of the following reasons:
.IP \(bu 5
It is obscured by another opaque window.
.IP \(bu 5
One of its ancestors is not mapped.
.IP \(bu 5
It is entirely clipped by an ancestor.
.LP
.PN Expose
events are generated for the window when part or all of
it becomes visible on the screen.
A client receives the
.PN Expose
events only if it has asked for them.
Windows retain their position in the stacking order when they are unmapped.
.LP
A window manager may want to control the placement of subwindows.
If
.PN 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
.PN MapRequest
event.
However, if the override-redirect flag on the child had been set to
.PN True
(usually only on pop-up menus),
the map request is performed.
.LP
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 section 3.2.8 and section 10.10.
Only a single client at a time can select for
.PN SubstructureRedirectMask .
.LP
Similarly, a single client can select for
.PN ResizeRedirectMask
on a parent window.
Then, any attempt to resize the window by another client is suppressed, and
the client receives a
.PN ResizeRequest
event.
.LP
.sp
To map a given window, use
.PN XMapWindow .
.IN "XMapWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XMapWindow.f,v 1.1 88/02/26 10:01:30 mento Exp $
XMapWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XMapWindow.d,v 1.3 88/06/11 07:51:58 mento Exp $
The
.PN 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.
.LP
If the override-redirect of the window is
.PN False
and if some other client has selected
.PN SubstructureRedirectMask
on the parent window, then the X server generates a
.PN MapRequest
event, and the
.PN XMapWindow
function does not map the window.
Otherwise, the window is mapped, and the X server generates a
.PN MapNotify
event.
.LP
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
.PN Expose
events.
If backing-store was maintained while the window was unmapped, no
.PN 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.
.LP
.IN "XMapWindow"
If the window is an
.PN InputOutput
window,
.PN XMapWindow
generates
.PN Expose
events on each
.PN 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
.PN Expose
events and then map the window,
so the client processes input events as usual.
The event list will include
.PN Expose
for each
window that has appeared on the screen.
The client's normal response to
an
.PN Expose
event should be to repaint the window.
This method usually leads to simpler programs and to proper interaction
with window managers.
.LP
.PN XMapWindow
can generate a
.PN BadWindow
error.
.LP
.sp
To map and raise a window, use
.PN XMapRaised .
.IN "XMapRaised" "" "@DEF@"
.\" Start marker code here
.FD 0
XMapRaised\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XMapRaised.d,v 1.2 88/05/07 12:22:21 mento Exp $
The
.PN XMapRaised
function
essentially is similar to
.PN 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
.PN XMapWindow .
.LP
.PN XMapRaised
can generate multiple
.PN BadWindow
errors.
.LP
.sp
To map all subwindows for a specified window, use
.PN XMapSubwindows .
.IN "XMapSubwindows" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XMapSubs.f,v 1.1 88/02/26 10:01:30 mento Exp $
XMapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XMapSubs.d,v 1.3 88/06/11 07:51:57 mento Exp $
The
.PN XMapSubwindows
.IN "XMapSubwindows"
function maps all subwindows for a specified window in top-to-bottom stacking
order.
The X server generates
.PN 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.
.LP
.PN XMapSubwindows
can generate a
.PN BadWindow
error.
.NH 2
Unmapping Windows
.XS
\*(SN Unmapping Windows
.XE
.LP
Xlib provides functions that you can use to unmap a window or all subwindows.
.LP
.sp
To unmap a window, use
.PN XUnmapWindow .
.IN "XUnmapWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XUnmapWindow.f,v 1.1 88/02/26 10:04:09 mento Exp $
XUnmapWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XUnmapWindow.d,v 1.2 88/06/11 07:54:34 mento Exp $
The
.PN XUnmapWindow
function unmaps the specified window and causes the X server to generate an
.PN UnmapNotify
.IN "UnmapNotify Event"
.IN "XUnmapWindow"
event.
If the specified window is already unmapped,
.PN 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
.PN Expose
events on windows that were formerly obscured by it.
.LP
.PN XUnmapWindow
can generate a
.PN BadWindow
error.
.LP
.sp
To unmap all subwindows for a specified window, use
.PN XUnmapSubwindows .
.IN "XUnmapSubwindows" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XUnmapSubs.f,v 1.1 88/02/26 10:04:09 mento Exp $
XUnmapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XUnmapSubs.d,v 1.4 88/06/11 07:54:33 mento Exp $
The
.PN XUnmapSubwindows
function unmaps all subwindows for the specified window in bottom-to-top
stacking order.
It causes the X server to generate an
.PN UnmapNotify
event on each subwindow and
.PN Expose
events on formerly obscured windows.
.IN "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.
.LP
.PN XUnmapSubwindows
can generate a
.PN BadWindow
error.
.NH 2
Configuring Windows
.XS
\*(SN Configuring Windows
.XE
.LP
.LP
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
.PN XWindowChanges
structure and OR in the corresponding value mask in subsequent calls to
.PN XConfigureWindow .
The symbols for the value mask bits and the
.PN XWindowChanges
structure are:
.\" Start marker code here
.LP
/* Configure window value mask bits */
.TS
lw(.5i) lw(2.5i) lw(.8i).
T{
#define
T}    T{
.PN CWX
T}    T{
(1<<0)
T}
T{
#define
T}    T{
.PN CWY
T}    T{
(1<<1)
T}
T{
#define
T}    T{
.PN CWWidth
T}    T{
(1<<2)
T}
T{
#define
T}    T{
.PN CWHeight
T}    T{
(1<<3)
T}
T{
#define
T}    T{
.PN CWBorderWidth
T}    T{
(1<<4)
T}
T{
#define
T}    T{
.PN CWSibling
T}    T{
(1<<5)
T}
T{
#define
T}    T{
.PN CWStackMode
T}    T{
(1<<6)
T}
.TE
.IN "XWindowChanges" "" "@DEF@"
.Ds 0
.TA .5i 3i
.ta .5i 3i
/* Values */

typedef struct {
    int x, y;
    int width, height;
    int border_width;
    Window sibling;
    int stack_mode;
} XWindowChanges;
.De
.\" End marker code here
.LP
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
.PN BadValue
error results.
Attempts to configure a root window have no effect.
.LP
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
.PN InputOnly
window nonzero, a
.PN BadMatch
error results.
.LP
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
.PN Above ,
.PN Below ,
.PN TopIf ,
.PN BottomIf ,
or
.PN Opposite .
.LP
If the override-redirect flag of the window is
.PN False
and if some other client has selected
.PN SubstructureRedirectMask
on the parent, the X server generates a
.PN ConfigureRequest
event, and no further processing is performed.
Otherwise,
if some other client has selected
.PN ResizeRedirectMask
on the window and the inside
width or height of the window is being changed,
a
.PN 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
.PN ResizeRedirectMask
and that
.PN SubstructureRedirectMask
on the parent has precedence over
.PN ResizeRedirectMask
on the window.
.LP
When the geometry of the window is changed as specified,
the window is restacked among siblings, and a
.PN ConfigureNotify
event is generated if the state of the window actually changes.
.PN GravityNotify
events are generated after
.PN ConfigureNotify
events.
If the inside width or height of the window has actually changed,
children of the window are affected as specified.
.LP
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).
.LP
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.
.LP
The restack check (specifically, the computation for
.PN BottomIf ,
.PN TopIf ,
and
.PN 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
.PN BadMatch
error results.
.LP
If a sibling and a stack_mode are specified,
the window is restacked as follows:
.TS
lw(1i) lw(5i).
T{
.PN Above
T}    T{
The window is placed just above the sibling.
T}
.sp 6p
T{
.PN Below
T}    T{
The window is placed just below the sibling.
T}
.sp 6p
T{
.PN TopIf
T}    T{
If the sibling occludes the window, the window is placed
at the top of the stack.
T}
.sp 6p
T{
.PN BottomIf
T}    T{
If the window occludes the sibling, the window is
placed at the bottom of the stack.
T}
.sp 6p
T{
.PN Opposite
T}    T{
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.
T}
.TE
.LP
If a stack_mode is specified but no sibling is specified,
the window is restacked as follows:
.TS
lw(1i) lw(5i).
T{
.PN Above
T}    T{
The window is placed at the top of the stack.
T}
.sp 6p
T{
.PN Below
T}    T{
The window is placed at the bottom of the stack.
T}
.sp 6p
T{
.PN TopIf
T}    T{
If any sibling occludes the window, the window is placed at
the top of the stack.
T}
.sp 6p
T{
.PN BottomIf
T}    T{
If the window occludes any sibling, the window is placed at
the bottom of the stack.
T}
.sp 6p
T{
.PN Opposite
T}    T{
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.
T}
.TE
.LP
Attempts to configure a root window have no effect.
.LP
.sp
To configure a window's size, location, stacking, or border, use
.PN XConfigureWindow .
.IN "XConfigureWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XReconfWin.f,v 1.1 88/02/26 10:02:36 mento Exp $
XConfigureWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvalue_mask\fP\^, \fIvalues\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      unsigned int \fIvalue_mask\fP\^;
.br
      XWindowChanges *\fIvalues\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi to be reconfigured
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.\" $Header: value_mask.a,v 1.2 88/05/07 12:39:38 mento Exp $
.IP \fIvalue_mask\fP 1i
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.
.\" $Header: values.a,v 1.2 88/05/07 12:41:05 mento Exp $
.IP \fIvalues\fP 1i
Specifies the
.PN XWindowChanges
structure.
.\" End marker code here
.LP
.\" $Header: XReconfWin.d,v 1.2 88/06/11 07:52:46 mento Exp $
The
.PN XConfigureWindow
function uses the values specified in the
.PN 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.
.LP
If a sibling is specified without a stack_mode or if the window
is not actually a sibling,
a
.PN BadMatch
error results.
Note that the computations for
.PN BottomIf ,
.PN TopIf ,
and
.PN Opposite
are performed with respect to the window's final geometry (as controlled by the
other arguments passed to
.PN 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).
.LP
.PN XConfigureWindow
can generate
.PN BadMatch ,
.PN BadValue ,
and
.PN BadWindow
errors.
.LP
.sp
To move a window without changing its size, use
.PN XMoveWindow .
.IN "XMoveWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XMoveWindow.f,v 1.1 88/02/26 10:01:32 mento Exp $
XMoveWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      int \fIx\fP\^, \fIy\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi to be moved
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.ds Xy , which define the new location of the top-left pixel \
of the window's border or the window itself if it has no border
.\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the x and y coordinates\*(Xy.
.\" End marker code here
.LP
.\" $Header: XMoveWindow.d,v 1.3 88/06/11 07:52:00 mento Exp $
The
.PN 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
.PN Expose
events.
Moving a mapped window generates
.PN Expose
events on any formerly obscured windows.
.LP
If the override-redirect flag of the window is
.PN False
and some
other client has selected
.PN SubstructureRedirectMask
on the parent, the X server generates a
.PN ConfigureRequest
event, and no further processing is
performed.
Otherwise, the window is moved.
.LP
.PN XMoveWindow
can generate a
.PN BadWindow
error.
.LP
.sp
To change a window's size without changing the upper-left coordinate, use
.PN XResizeWindow .
.IN "XResizeWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XChWindow.f,v 1.1 88/02/26 09:58:36 mento Exp $
XResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.ds Wh , which are the interior dimensions of the window \
after the call completes
.\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
.IP \fIwidth\fP 1i
.br
.ns
.IP \fIheight\fP 1i
Specify the width and height\*(Wh.
.\" End marker code here
.LP
.\" $Header: XChWindow.d,v 1.3 88/06/11 07:49:12 mento Exp $
The
.PN 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
.PN Expose
events.
If a mapped window is made smaller,
changing its size generates
.PN Expose
events on windows that the mapped window formerly obscured.
.LP
If the override-redirect flag of the window is
.PN False
and some
other client has selected
.PN SubstructureRedirectMask
on the parent, the X server generates a
.PN ConfigureRequest
event, and no further processing is performed.
If either width or height is zero,
a
.PN BadValue
error results.
.LP
.PN XResizeWindow
can generate
.PN BadValue
and
.PN BadWindow
errors.
.LP
.sp
To change the size and location of a window, use
.PN XMoveResizeWindow .
.IN "XMoveResizeWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XConfWindow.f,v 1.1 88/02/26 09:58:51 mento Exp $
XMoveResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      int \fIx\fP\^, \fIy\fP\^;
.br
      unsigned int \fIwidth\fP\^, \fIheight\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.ds Wi to be reconfigured
.\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
.IP \fIw\fP 1i
Specifies the window \*(Wi.
.ds Xy , which define the new position of the window relative to its parent
.\" $Header: xy_gen.a,v 1.2 88/08/04 11:22:37 mento Exp $
.IP \fIx\fP 1i
.br
.ns
.IP \fIy\fP 1i
Specify the x and y coordinates\*(Xy.
.ds Wh , which define the interior size of the window
.\" $Header: w+h_gen.a,v 1.2 88/08/04 11:21:28 mento Exp $
.IP \fIwidth\fP 1i
.br
.ns
.IP \fIheight\fP 1i
Specify the width and height\*(Wh.
.\" End marker code here
.LP
.\" $Header: XConfWindow.d,v 1.2 88/06/11 07:49:24 mento Exp $
The
.PN XMoveResizeWindow
function changes the size and location of the specified window
without raising it.
Moving and resizing a mapped window may generate an
.PN Expose
event on the window.
Depending on the new size and location parameters,
moving and resizing a window may generate
.PN Expose
events on windows that the window formerly obscured.
.LP
If the override-redirect flag of the window is
.PN False
and some
other client has selected
.PN SubstructureRedirectMask
on the parent, the X server generates a
.PN ConfigureRequest
event, and no further processing is performed.
Otherwise, the window size and location are changed.
.LP
.PN XMoveResizeWindow
can generate
.PN BadValue
and
.PN BadWindow
errors.
.LP
.sp
To change the border width of a given window, use
.PN XSetWindowBorderWidth .
.IN "XSetWindowBorderWidth" "" "@DEF@"
.\" Start marker code here
.FD 0
XSetWindowBorderWidth\^(\^\fIdisplay\fP, \fIw\fP, \fIwidth\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      unsigned int \fIwidth\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.IP \fIwidth\fP 1i
Specifies the width of the window border.
.\" End marker code here
.LP
.\" $Header: XBdrWidth.d,v 1.1 88/02/26 10:41:07 mento Exp $
The
.PN XSetWindowBorderWidth
function sets the specified window's border width to the specified width.
.LP
.PN XSetWindowBorderWidth
can generate a
.PN BadWindow
error.
.NH 2
Changing Window Stacking Order
.XS
\*(SN Changing Window Stacking Order
.XE
.LP
.LP
Xlib provides functions that you can use to raise, lower, circulate,
or restack windows.
.LP
.sp
To raise a window so that no sibling window obscures it, use
.PN XRaiseWindow .
.IN "XRaiseWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XRaiseWindow.f,v 1.1 88/02/26 10:02:34 mento Exp $
XRaiseWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XRaiseWindow.d,v 1.2 88/06/11 07:52:45 mento Exp $
The
.PN 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
.PN Expose
events for the window and any mapped subwindows that were formerly obscured.
.LP
If the override-redirect attribute of the window is
.PN False
and some
other client has selected
.PN SubstructureRedirectMask
on the parent, the X server generates a
.PN ConfigureRequest
event, and no processing is performed.
Otherwise, the window is raised.
.LP
.PN XRaiseWindow
can generate a
.PN BadWindow
error.
.LP
.sp
To lower a window so that it does not obscure any sibling windows, use
.PN XLowerWindow .
.IN "XLowerWindow" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XLowerWindow.f,v 1.1 88/02/26 10:01:27 mento Exp $
XLowerWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XLowerWindow.d,v 1.2 88/06/11 07:51:55 mento Exp $
The
.PN 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
.PN Expose
events on any windows it formerly obscured.
.LP
If the override-redirect attribute of the window is
.PN False
and some
other client has selected
.PN SubstructureRedirectMask
on the parent, the X server generates a
.PN ConfigureRequest
event, and no processing is performed.
Otherwise, the window is lowered to the bottom of the
stack.
.LP
.PN XLowerWindow
can generate a
.PN BadWindow
error.
.LP
.sp
To circulate a subwindow up or down, use
.PN XCirculateSubwindows .
.IN "XCirculateSubwindows" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XCircWindow.f,v 1.1 88/02/26 09:58:44 mento Exp $
XCirculateSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^, \fIdirection\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      int \fIdirection\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: direction.a,v 1.2 88/04/04 11:12:47 mento Exp $
.IP \fIdirection\fP 1i
Specifies the direction (up or down) that you want to circulate
the window.
You can pass
.PN RaiseLowest
or
.PN LowerHighest .
.\" End marker code here
.LP
.\" $Header: XCircWindow.d,v 1.4 88/06/11 07:49:20 mento Exp $
The
.PN XCirculateSubwindows
function circulates children of the specified window in the specified
direction.
If you specify
.PN RaiseLowest ,
.PN XCirculateSubwindows
raises the lowest mapped child (if any) that is occluded
by another child to the top of the stack.
If you specify
.PN LowerHighest ,
.PN 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
.PN SubstructureRedirectMask
on the window, the X server generates a
.PN CirculateRequest
event, and no further processing is performed.
If a child is actually restacked,
the X server generates a
.PN CirculateNotify
event.
.LP
.PN XCirculateSubwindows
can generate
.PN BadValue
and
.PN BadWindow
errors.
.LP
.sp
To raise the lowest mapped child of a window that is partially or completely
occluded by another child, use
.PN XCirculateSubwindowsUp .
.IN "XCirculateSubwindowsUp" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XCircWinUp.f,v 1.1 88/02/26 09:58:43 mento Exp $
XCirculateSubwindowsUp\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XCircWinUp.d,v 1.3 88/08/17 08:27:23 mento Exp $
The
.PN 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
.PN XCirculateSubwindows
with
.PN RaiseLowest
specified.
.LP
.PN XCirculateSubwindowsUp
can generate a
.PN BadWindow
error.
.LP
.sp
To lower the highest mapped child of a window that partially or
completely occludes another child, use
.PN XCirculateSubwindowsDown .
.IN "XCirculateSubwindowsDown" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XCircWinDn.f,v 1.1 88/02/26 09:58:42 mento Exp $
XCirculateSubwindowsDown\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" End marker code here
.LP
.\" $Header: XCircWinDn.d,v 1.3 88/08/17 08:28:27 mento Exp $
The
.PN 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
.PN XCirculateSubwindows
with
.PN LowerHighest
specified.
.LP
.PN XCirculateSubwindowsDown
can generate a
.PN BadWindow
error.
.LP
.sp
To restack a set of windows from top to bottom, use
.PN XRestackWindows .
.IN "XRestackWindows" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XRestackWins.f,v 1.1 88/02/26 10:02:42 mento Exp $
XRestackWindows\^(\^\fIdisplay\fP, \fIwindows\fP\^, \^\fInwindows\fP\^);
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIwindows\fP\^[];
.br
      int \fInwindows\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: windows.a,v 1.2 88/04/05 14:11:11 mento Exp $
.IP \fIwindows\fP 1i
Specifies an array containing the windows to be restacked.
.\" $Header: nwindows.a,v 1.1 88/02/26 10:29:55 mento Exp $
.IP \fInwindows\fP 1i
Specifies the number of windows to be restacked.
.\" End marker code here
.LP
.\" $Header: XRestackWins.d,v 1.4 88/06/11 07:52:50 mento Exp $
The
.PN 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
.PN BadMatch
error results.
.LP
If the override-redirect attribute of a window is
.PN False
and some
other client has selected
.PN SubstructureRedirectMask
on the parent, the X server generates
.PN 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.
.LP
.PN XRestackWindows
can generate a
.PN BadWindow
error.
.NH 2
Changing Window Attributes
.XS
\*(SN Changing Window Attributes
.XE
.LP
.LP
Xlib provides functions that you can use to set window attributes.
.PN XChangeWindowAttributes
is the more general function that allows you to set one or more window
attributes provided by the
.PN XSetWindowAttributes
structure.
The other functions described in this section allow you to set one specific
window attribute, such as a window's background.
.LP
.sp
To change one or more attributes for a given window, use
.PN XChangeWindowAttributes .
.IN "XChangeWindowAttributes" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XChWAttr.f,v 1.1 88/02/26 09:58:34 mento Exp $
XChangeWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      unsigned long \fIvaluemask\fP\^;
.br
      XSetWindowAttributes *\fIattributes\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: valuemask.a,v 1.1 88/02/26 10:32:07 mento Exp $
.IP \fIvaluemask\fP 1i
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
.PN XCreateWindow .
.IP
.IP \fIattributes\fP 1i
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).
.\" End marker code here
.LP
.\" $Header: XChWAttr.d,v 1.2 88/06/11 07:49:11 mento Exp $
Depending on the valuemask,
the
.PN XChangeWindowAttributes
function uses the window attributes in the
.PN 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
.PN 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
.PN None
or
.PN ParentRelative
restores the default background pixmap.
Changing the border of a root window to
.PN 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
.PN WhenMapped
or
.PN 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
.PN 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
.PN XInstallColormap ).
Changing the cursor of a root window to
.PN None
restores the default
cursor.
Whenever possible, you are encouraged to share colormaps.
.LP
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
.PN SubstructureRedirectMask ,
.PN ResizeRedirectMask ,
and
.PN ButtonPressMask .
If a client attempts to select any of these event masks
and some other client has already selected one,
a
.PN BadAccess
error results.
There is only one do-not-propagate-mask for a window,
not one per client.
.LP
.PN XChangeWindowAttributes
can generate
.PN BadAccess ,
.PN BadColor ,
.PN BadCursor ,
.PN BadMatch ,
.PN BadPixmap ,
.PN BadValue ,
and
.PN BadWindow
errors.
.LP
.sp
To set the background of a window to a given pixel, use
.PN XSetWindowBackground .
.IN "XSetWindowBackground" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XBackground.f,v 1.1 88/02/26 09:58:16 mento Exp $
XSetWindowBackground\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixel\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      unsigned long \fIbackground_pixel\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: back_pix.a,v 1.2 88/04/05 14:24:47 mento Exp $
.IP \fIbackground_pixel\fP 1i
Specifies the pixel that is to be used for the background.
.\" End marker code here
.LP
.\" $Header: XBackground.d,v 1.4 88/06/11 07:48:45 mento Exp $
The
.PN 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.
.PN XSetWindowBackground
uses a pixmap of undefined size filled with the pixel value you passed.
If you try to change the background of an
.PN InputOnly
window, a
.PN BadMatch
error results.
.LP
.PN XSetWindowBackground
can generate
.PN BadMatch
and
.PN BadWindow
errors.
.LP
.sp
.LP
To set the background of a window to a given pixmap, use
.PN XSetWindowBackgroundPixmap .
.IN "Window" "background"
.IN "XSetWindowBackgroundPixmap" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XPmapBgnd.f,v 1.1 88/02/26 10:01:52 mento Exp $
XSetWindowBackgroundPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixmap\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Pixmap \fIbackground_pixmap\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: tile.a,v 1.3 88/05/07 13:12:11 mento Exp $
.IP \fIbackground_pixmap\fP 1i
Specifies the background pixmap,
.PN ParentRelative ,
or
.PN None .
.\" End marker code here
.LP
.IN "Resource IDs" "freeing"
.IN "Freeing" "resources"
.\" $Header: XPmapBgnd.d,v 1.3 88/06/11 07:52:14 mento Exp $
The
.PN 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
.PN 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
.PN InputOnly
window, a
.PN BadMatch
error results.
If the background is set to
.PN None ,
the window has no defined background.
.LP
.PN XSetWindowBackgroundPixmap
can generate
.PN BadMatch ,
.PN BadPixmap ,
and
.PN BadWindow
errors.
.NT Note
.PN XSetWindowBackground
and
.PN XSetWindowBackgroundPixmap
do not change the current contents of the window.
.NE
.LP
.sp
To change and repaint a window's border to a given pixel, use
.PN XSetWindowBorder .
.IN "XSetWindowBorder" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XBorder.f,v 1.1 88/02/26 09:58:27 mento Exp $
XSetWindowBorder\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixel\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      unsigned long \fIborder_pixel\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: bord_pix.a,v 1.2 88/05/07 13:15:29 mento Exp $
.IP \fIborder_pixel\fP 1i
Specifies the entry in the colormap.
.\" End marker code here
.LP
.\" $Header: XBorder.d,v 1.3 88/06/11 07:48:47 mento Exp $
The
.PN XSetWindowBorder
function sets the border of the window to the pixel value you specify.
If you attempt to perform this on an
.PN InputOnly
window, a
.PN BadMatch
error results.
.LP
.PN XSetWindowBorder
can generate
.PN BadMatch
and
.PN BadWindow
errors.
.LP
.sp
To change and repaint the border tile of a given window, use
.PN XSetWindowBorderPixmap .
.IN "XSetWindowBorderPixmap" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XPmapBorder.f,v 1.1 88/02/26 10:01:53 mento Exp $
XSetWindowBorderPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixmap\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Pixmap \fIborder_pixmap\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: bord_pixmap.a,v 1.2 88/05/07 13:17:18 mento Exp $
.IP \fIborder_pixmap\fP 1i
Specifies the border pixmap or
.PN CopyFromParent .
.\" End marker code here
.LP
.\" $Header: XPmapBorder.d,v 1.3 88/06/11 07:52:14 mento Exp $
The
.PN 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
.PN CopyFromParent ,
a copy of the parent window's border pixmap is used.
If you attempt to perform this on an
.PN InputOnly
window, a
.PN BadMatch
error results.
.IN "Resource IDs" "freeing"
.IN "Freeing" "resources"
.LP
.PN XSetWindowBorderPixmap
can generate
.PN BadMatch ,
.PN BadPixmap ,
and
.PN BadWindow
errors.
.LP
.sp
To set the colormap of a given window, use
.PN XSetWindowColormap .
.IN "XSetWindowColormap" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XChCmap.f,v 1.2 88/05/09 06:54:34 mento Exp $
XSetWindowColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcolormap\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Colormap \fIcolormap\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: cmap.a,v 1.2 88/05/09 06:39:13 mento Exp $
.IP \fIcolormap\fP 1i
Specifies the colormap.
.\" End marker code here
.LP
.\" $Header: XChCmap.d,v 1.3 88/05/09 06:57:38 mento Exp $
The
.PN XSetWindowColormap
function sets the specified colormap of the specified window.
The colormap must have the same visual type as the window,
or a
.PN BadMatch
error results.
.LP
.PN XSetWindowColormap
can generate
.PN BadColor ,
.PN BadMatch ,
and
.PN BadWindow
errors.
.LP
.sp
To define which cursor will be used in a window, use
.PN XDefineCursor .
.IN "Window" "defining the cursor"
.IN "XDefineCursor" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XDefCursor.f,v 1.1 88/02/26 09:59:31 mento Exp $
XDefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcursor\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.br
      Cursor \fIcursor\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.\" $Header: cursor_def.a,v 1.2 88/05/13 13:12:57 mento Exp $
.IP \fIcursor\fP 1i
Specifies the cursor that is to be displayed or
.PN None .
.\" End marker code here
.LP
.\" $Header: XDefCursor.d,v 1.2 88/06/11 07:49:58 mento Exp $
If a cursor is set, it will be used when the pointer is in the window.
If the cursor is
.PN None ,
it is equivalent to
.PN XUndefineCursor .
.LP
.PN XDefineCursor
can generate
.PN BadCursor
and
.PN BadWindow
errors.
.LP
.sp
To undefine the cursor in a given window, use
.PN XUndefineCursor .
.IN "Window" "undefining the cursor"
.IN "XUndefineCursor" "" "@DEF@"
.\" Start marker code here
.FD 0
.\" $Header: XUndefCursor.f,v 1.1 88/02/26 10:04:03 mento Exp $
XUndefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^)
.br
      Display *\fIdisplay\fP\^;
.br
      Window \fIw\fP\^;
.FN
.\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
.IP \fIdisplay\fP 1i
Specifies the connection to the X server.
.\" End marker code here
.\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
.IP \fIw\fP 1i
Specifies the window.
.LP
.\" $Header: XUndefCursor.d,v 1.2 88/06/11 07:54:20 mento Exp $
The
.PN XUndefineCursor
function undoes the effect of a previous
.PN 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.
.LP
.PN XUndefineCursor
can generate a
.PN BadWindow
error.
.bp