3122 lines
76 KiB
Plaintext
3122 lines
76 KiB
Plaintext
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining
|
|
.\" a copy of this software and associated documentation files (the
|
|
.\" "Software"), to deal in the Software without restriction, including
|
|
.\" without limitation the rights to use, copy, modify, merge, publish,
|
|
.\" distribute, sublicense, and/or sell copies of the Software, and to
|
|
.\" permit persons to whom the Software is furnished to do so, subject to
|
|
.\" the following conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of the X Consortium shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from the X Consortium.
|
|
.\"
|
|
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
|
|
.\" Digital Equipment Corporation
|
|
.\"
|
|
.\" Portions Copyright \(co 1990, 1991 by
|
|
.\" Tektronix, Inc.
|
|
.\"
|
|
.\" Permission to use, copy, modify and distribute this documentation for
|
|
.\" any purpose and without fee is hereby granted, provided that the above
|
|
.\" copyright notice appears in all copies and that both that copyright notice
|
|
.\" and this permission notice appear in all copies, and that the names of
|
|
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
|
|
.\" to this documentation without specific, written prior permission.
|
|
.\" Digital and Tektronix makes no representations about the suitability
|
|
.\" of this documentation for any purpose.
|
|
.\" It is provided ``as is'' without express or implied warranty.
|
|
.\"
|
|
\&
|
|
.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 window stacking order
|
|
.IP \(bu 5
|
|
Change window attributes
|
|
.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.
|
|
For more information,
|
|
refer to the documentation for the toolkit that you are using.
|
|
.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
|
|
.TS
|
|
center;
|
|
c c s c s
|
|
c c c c c
|
|
| c | c | c | c | c |.
|
|
Color Gray-scale
|
|
R/O R/W R/O R/W
|
|
_
|
|
Undecomposed Static Pseudo Static Gray
|
|
Colormap Color Color Gray Scale
|
|
_
|
|
.T&
|
|
| c | c | c |.
|
|
Decomposed True Direct
|
|
Colormap Color Color
|
|
_ _ _
|
|
.TE
|
|
.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@"
|
|
.sM
|
|
.FD 0
|
|
VisualID XVisualIDFromVisual\^(\^\fIvisual\fP\^)
|
|
.br
|
|
Visual *\^\fIvisual\fP\^;
|
|
.FN
|
|
.IP \fIvisual\fP 1i
|
|
Specifies the visual type.
|
|
.LP
|
|
.eM
|
|
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:
|
|
.sM
|
|
.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
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
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
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.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
|
|
.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
|
|
.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.
|
|
.IP \fIborder_width\fP 1i
|
|
Specifies the width of the created window's border in pixels.
|
|
.IP \fIdepth\fP 1i
|
|
Specifies the window's depth.
|
|
A depth of
|
|
.PN CopyFromParent
|
|
means the depth is taken from the parent.
|
|
.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.
|
|
.IP \fIvisual\fP 1i
|
|
Specifies the visual type.
|
|
A visual of
|
|
.PN CopyFromParent
|
|
means the visual type is taken from the
|
|
parent.
|
|
.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.
|
|
.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.
|
|
.LP
|
|
.eM
|
|
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 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.
|
|
.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@"
|
|
.sM
|
|
.FD 0
|
|
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
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.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
|
|
.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
|
|
.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.
|
|
.IP \fIborder_width\fP 1i
|
|
Specifies the width of the created window's border in pixels.
|
|
.IP \fIborder\fP 1i
|
|
Specifies the border pixel value of the window.
|
|
.IP \fIbackground\fP 1i
|
|
Specifies the background pixel value of the window.
|
|
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XDestroyWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XDestroySubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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 sections 3.2.8 and 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@"
|
|
.sM
|
|
.FD 0
|
|
XMapWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XMapRaised\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XMapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XUnmapWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XUnmapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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:
|
|
.sM
|
|
.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
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
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
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.ds Wi to be reconfigured
|
|
.IP \fIw\fP 1i
|
|
Specifies the window \*(Wi.
|
|
.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.
|
|
.IP \fIvalues\fP 1i
|
|
Specifies the
|
|
.PN XWindowChanges
|
|
structure.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XMoveWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
int \fIx\fP\^, \fIy\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.ds Wi to be moved
|
|
.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
|
|
.IP \fIx\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIy\fP 1i
|
|
Specify the x and y coordinates\*(Xy.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
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
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.ds Wh , which are the interior dimensions of the window \
|
|
after the call completes
|
|
.IP \fIwidth\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight\fP 1i
|
|
Specify the width and height\*(Wh.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
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
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.ds Wi to be reconfigured
|
|
.IP \fIw\fP 1i
|
|
Specifies the window \*(Wi.
|
|
.ds Xy , which define the new position of the window relative to its parent
|
|
.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
|
|
.IP \fIwidth\fP 1i
|
|
.br
|
|
.ns
|
|
.IP \fIheight\fP 1i
|
|
Specify the width and height\*(Wh.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XSetWindowBorderWidth\^(\^\fIdisplay\fP, \fIw\fP, \fIwidth\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
unsigned int \fIwidth\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIwidth\fP 1i
|
|
Specifies the width of the window border.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XRaiseWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XLowerWindow\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XCirculateSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^, \fIdirection\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
int \fIdirection\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.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 .
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XCirculateSubwindowsUp\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XCirculateSubwindowsDown\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XRestackWindows\^(\^\fIdisplay\fP, \fIwindows\fP\^, \^\fInwindows\fP\^);
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIwindows\fP\^[];
|
|
.br
|
|
int \fInwindows\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIwindows\fP 1i
|
|
Specifies an array containing the windows to be restacked.
|
|
.IP \fInwindows\fP 1i
|
|
Specifies the number of windows to be restacked.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
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
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.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).
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XSetWindowBackground\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixel\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
unsigned long \fIbackground_pixel\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIbackground_pixel\fP 1i
|
|
Specifies the pixel that is to be used for the background.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XSetWindowBackgroundPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixmap\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
Pixmap \fIbackground_pixmap\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIbackground_pixmap\fP 1i
|
|
Specifies the background pixmap,
|
|
.PN ParentRelative ,
|
|
or
|
|
.PN None .
|
|
.LP
|
|
.eM
|
|
.IN "Resource IDs" "freeing"
|
|
.IN "Freeing" "resources"
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XSetWindowBorder\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixel\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
unsigned long \fIborder_pixel\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIborder_pixel\fP 1i
|
|
Specifies the entry in the colormap.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XSetWindowBorderPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixmap\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
Pixmap \fIborder_pixmap\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIborder_pixmap\fP 1i
|
|
Specifies the border pixmap or
|
|
.PN CopyFromParent .
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XSetWindowColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcolormap\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
Colormap \fIcolormap\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIcolormap\fP 1i
|
|
Specifies the colormap.
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XDefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcursor\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.br
|
|
Cursor \fIcursor\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.IP \fIcursor\fP 1i
|
|
Specifies the cursor that is to be displayed or
|
|
.PN None .
|
|
.LP
|
|
.eM
|
|
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@"
|
|
.sM
|
|
.FD 0
|
|
XUndefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^)
|
|
.br
|
|
Display *\fIdisplay\fP\^;
|
|
.br
|
|
Window \fIw\fP\^;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the connection to the X server.
|
|
.IP \fIw\fP 1i
|
|
Specifies the window.
|
|
.LP
|
|
.eM
|
|
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
|