Next: Stacking Order, Previous: Creating Windows, Up: Windows and Pixmaps [Contents][Index]
The following paragraphs describe the CLX functions used to return or change window attributes. Using the with-state macro improves the performance of attribute access by batching related accesses in the minimum number of server requests.
A drawable object.
Returns the border-width of the drawable in pixels. It
always returns zero if the drawable is a pixmap or an
:input-only window. Used with setf, this function also
changes the border width of the :input-only window. The default
border width of a new window is zero.
Changing just the border width leaves the outer left corner of a window in a fixed position but moves the absolute position of the window’s origin. It is an error to make the border width of an :input-only window nonzero.
When changing the border-width of a window, if the override-redirect attribute of the window is :off and some other client has selected :substructure-redirect on the parent, a :configure-request event is generated, and no further processing is performed. Otherwise, the border-width is changed.
Type card16.
A drawable object.
Returns the depth of the specified drawable (bits per pixel).
Type card8.
Type card16.
A drawable object.
These functions return the height or width of the
drawable. These coordinates define the inside size of the
drawable, in pixels. Used with setf, these functions also
change the inside height or width of a window. However, the height or
width of a pixmap cannot be changed.
Changing the width and height resizes a window without changing its position or stacking priority.
Changing the size of a mapped window may cause the window to lose its contents and generate an :exposure event. If a mapped window is made smaller, :exposure events are generated on windows that it formerly obscured.
When changing the size of a window, if the override-redirect attribute of the window is :off and some other client has selected :substructure-redirect on the parent, a :configure-request event is generated, and no further processing is performed. Otherwise, if another client has selected :resize-redirect on the window, a :resize-request event is generated, and the current inside width and height are maintained. Note that the override-redirect attribute of the window has no effect on :resize-redirect and that :substructure-redirect on the parent has precedence over :resize-redirect on the window.
When the inside size of the window is changed, the children of the window can move according to their window gravity. Depending on the window’s bit gravity, the contents of the window can also be moved.
Type card16.
Type int16.
A drawable object.
These functions return the x or y coordinate of the specified
drawable. They always return zero if the drawable is a
pixmap. These coordinates define the location of the top left pixel of
the window’s border or of the window, if it has no border. Used with
setf, these functions also change the x or y coordinate of a
window. However, the x or y coordinate of a pixmap cannot be changed.
Changing the x and y coordinates moves a window without changing its size or stacking priority. Moving a mapped window generates :exposure events on any formerly obscured windows.
When changing the position of a window, if the override-redirect attribute of the window is :off and some other client has selected :substructure-redirect on the parent, a :configure-request event is generated, and no further processing is performed. Otherwise, the window is moved.
Type int16.
A window.
Returns the inclusive-or of the event masks selected on the specified window by all clients.
Type mask32.
A window.
Either a pixel, a pixmap, :none, or :parent-relative.
Changes the background attribute of the window to the specified value. This operation is not allowed on an :input-only window. Changing the background does not cause the window contents to be changed. Note that the background of a window cannot be returned from the X server. The default background of a new window is :none.
In general, the server automatically fills in exposed areas of the window when they are first made visible. A background pixmap is tiled to fill each area. However, if the background is :none, the server will not modify exposed areas. If the background is :parent-relative, the window and its parent must have the same depth. In this case, the window shares the same background as its parent. The parent’s background is not copied and is reexamined whenever the window’s background is required. If the background is :parent-relative, the background pixmap tile origin is the same as the parent’s; otherwise, the tile origin is the window origin.
Either a pixel, a pixmap, :none, or :parent-relative.
A window.
Returns and (with setf) changes the value of the backing-pixel
attribute for the specified window. Changing the backing-pixel
attribute of a mapped window may have no immediate effect. The default
backing-pixel of a new window is zero.
Type pixel.
A window.
Returns and (with setf) changes the value of the backing-planes
attribute for the specified window. Changing the backing-planes
attribute of a mapped window may have no immediate effect. The default
backing-planes of a new window is all one’s.
Type pixel.
A window.
Returns and (with setf) changes the value of the backing-store
attribute for the specified window. Changing the backing-store
attribute of an obscured window to :when-mapped or :always
may have no immediate effect. The default backing-store of a new
window is :not-useful.
One of :always, :not-useful, or :when-mapped.
A window.
Returns and (with setf) changes the bit-gravity attribute of the
window. If a window is reconfigured without changing its inside
width or height, the contents of the window move with the window and
are not lost. Otherwise, the contents of the resized window are either
moved or lost, depending on its bit-gravity attribute. The default
bit-gravity of a new window is :forget.
For example, suppose a window’s size is changed by W pixels in width and H pixels in height. The following table shows, for each bit-gravity value, the change in position (relative to the window origin) that results for each pixel of the window contents.
| :center | W/2 | H/2 |
| :east | W | H/2 |
| :north | W/2 | 0 |
| :north-east | W | 0 |
| :north-west | 0 | 0 |
| :south | W/2 | H |
| :south-east | W | H |
| :south-west | 0 | H |
| :west | 0 | H/2 |
A :static bit-gravity indicates the contents or window should not move relative to the origin of the root window.
A server can choose to ignore the specified bit-gravity attribute and use :forget instead. A :forget bit-gravity attribute indicates that the window contents are always discarded after a size change, even if backing-store or save-under attributes are :on. The window’s background is displayed (unless it is :none), and zero or more :exposure events are generated.
Type bit-gravity.
A window.
Either a pixel, a pixmap, or :copy.
Changes the border attribute of the window to the specified value. This operation is not allowed on an :input-only window. Changing the border attribute also causes the window border to be repainted. Note that the border of a window cannot be returned from the X server. The default border of a new window is :copy.
A border pixmap is tiled to fill the border. The border pixmap tile origin is the same as the background tile origin. A border pixmap and the window must have the same root and depth. If the border is :copy, the parent’s border is copied and used; subsequent changes to the parent’s border do not affect the window border.
Either a pixel, a pixmap, or :copy.
A window.
Returns the class of the specified window.
Either :input-output or :input-only.
A window.
Returns and (with setf) changes the value of the colormap
attribute for the specified window. A value of :copy is
never returned, since the parent’s colormap attribute is actually
copied, but the attribute can be set to :copy in a setf
form. Changing the colormap of a window (defining a new map, not
changing the contents of the existing map) generates a
:colormap-notify event. Changing the colormap of a visible
window may have no immediate effect on the screen
(see install-colormap). The default colormap of a new window is
:copy.
Type colormap or null.
A window.
Returns non-nil if the colormap associated with this window is installed. Otherwise, this function returns nil.
Type boolean.
A window.
Either cursor or :none.
Changes the cursor attribute of the window to the specified value. Changing the cursor of a root window to :none restores the default cursor. Note that the cursor of window cannot be returned from the X server. The default cursor of a new window is :none.
Type cursor or :none.
A window.
Returns the display object associated with the specified window.
Type display.
A window.
Returns and (with setf) changes the do-not-propagate-mask
attribute for the window. The default do-not-propagate-mask of a new
window is zero.
If a window receives an event from one of the user input devices, and if no client has selected to receive the event, the event can instead be propagated up the window hierarchy to the first ancestor for which some client has selected it. However, any event type selected by the do-not-propagate-mask is not be propagated. The types of events that can be selected by the do-not-propagate-mask are those of type device-event-mask-class. See Selecting Events.
Type mask32.
The windows to compare for equality.
Returns non-nil if the two arguments are the same window, and nil if they are not.
Type boolean.
A window.
Returns and (with setf) changes the value of the event-mask
attribute for the window. The default event-mask of a new
window is zero.
Type mask32.
A window.
Returns and (with setf) changes the gravity attribute of the
window. If a parent window is reconfigured without changing its
inside width or height, then all child windows move with the parent
and are not changed. Otherwise, each child of the resized parent is
moved, depending on the child’s gravity attribute. The default gravity
of a new window is :north-west.
For example, suppose the size of the window’s parent is changed by W pixels in width and H pixels in height. The following table shows, for each possible gravity value, the resulting change in the window’s position relative to its parent’s origin. When the window is moved, two events are generated–a :configure-notify event followed by a :gravity-notify event.
| :center | W/2 | H/2 |
| :east | W | H/2 |
| :north | W/2 | 0 |
| :north-east | W | 0 |
| :north-west | 0 | 0 |
| :south | W/2 | H |
| :south-east | W | H |
| :south-west | 0 | H |
| :west | 0 | H/2 |
A :static gravity indicates that the position of the window should not move relative to the origin of the root window.
An :unmap gravity is like :north-west, except the window is also unmapped and an :unmap-notify event is generated. This :unmap-notify event is generated after the :configure-notify event is generated for the parent.
Type win-gravity.
A window.
Returns the unique ID assigned to window.
Type resource-id.
A window.
Returns the map state of window. A window is :unviewable if it is mapped but some ancestor is unmapped.
One of :unmapped, :unviewable, or :viewable.
A window.
Returns and (with setf) changes the value of the
override-redirect attribute for window. The default
override-redirect of a new window is :off.
The override-redirect attribute determines whether or not attempts to change window geometry or parent hierarchy can be redirected by a window manager or some other client. The functions that might be affected by the override-redirect attribute are circulate-window-down, circulate-window-up, drawable-border-width, drawable-height, drawable-width, drawable-x, drawable-y, map-window, and window-priority.
Either :on or :off.
Type boolean.
Returns non-nil if the object argument is a window; otherwise, it returns nil.
A window.
Returns and (with setf) sets the property list for the specified
window. This function provides a hook where extensions can hang
data.
A property list.
A window.
An optional argument specifying that window is to be restacked relative to this sibling window.
One of :above, :below, :bottom-if, :opposite, or :top-if.
Changes the stacking priority element of the window to the specified value. It is an error if the sibling argument is specified and is not actually a sibling of the window. Note that the priority of an existing window cannot be returned from the X server.
When changing the priority of a window, if the override-redirect attribute of the window is :off and some other client has selected :substructure-redirect on the parent, a :configure-request event is generated, and no further processing is performed. Otherwise, the priority is changed.
One of :above, :below, :bottom-if, :opposite, or :top-if.
A window.
Returns and (with setf) changes the value of the save-under
attribute for the specified window. Changing the save-under
attribute of a mapped window may have no immediate effect.
Either :on or :off.
A window.
Returns the visual-type associated with the specified window.
Type card29.
Batches successive read and write accesses to window attributes and drawable geometry, in order to minimize the number of requests sent to the server. Batching occurs automatically within the dynamic extent of the body. The body is not executed within a with-display form.
All window attributes can be returned or changed in a single
request. Similarly, all drawable geometry values can be returned or
changed in a single request. with-state combines accesses to
these values into the minimum number of server requests necessary to
guarantee that each read access returns the current server state of
the drawable. The number of server requests sent depends on
the sequence of calls to reader and setf functions within the
dynamic extent of the body. There are two groups of reader and
setf functions–the Window Attributes group and the Drawable
Geometry group–as shown in Table 4-1.
| Window Attributes | window-all-event-masks | window-background |
| window-backing-pixel | window-backing-pixel | |
| window-backing-planes | window-backing-planes | |
| window-backing-store | window-backing-store | |
| window-bit-gravity | window-bit-gravity | |
| window-class | window-border | |
| window-colormap | window-colormap | |
| window-colormap-installed-p | window-cursor | |
| window-do-not-propagate-mask | window-do-not-propagate-mask | |
| window-event-mask | window-event-mask | |
| window-gravity | window-gravity | |
| window-map-state | ||
| window-override-redirect | window-override-redirect | |
| window-save-under | window-save-under | |
| window-visual | ||
| Drawable Geometry | drawable-border-width | drawable-border-width |
| drawable-depth | drawable-height | |
| drawable-height | drawable-width | |
| drawable-root | drawable-x | |
| drawable-width | drawable-y | |
| drawable-x | window-priority | |
| drawable-y |
The results from a sequence of calls to setf functions in a
given group are cached and sent in a single server request, either
upon exit from the body or when a reader function from the
corresponding group is called.
with-state sends a single request to update all its cached
values for the drawable before the first call to a reader
function within the body and also before the first call to a
reader function following a sequence of calls to setf functions
from the corresponding group.
A display.
The forms in which attributes accesses are batched.
Next: Stacking Order, Previous: Creating Windows, Up: Windows and Pixmaps [Contents][Index]