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