Next: , Previous: , Up: Windows and Pixmaps   [Contents][Index]


5.3 Window Attributes

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.

Function: drawable-border-width drawable
drawable

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.

border-width

Type card16.

Function: drawable-depth drawable
drawable

A drawable object.

Returns the depth of the specified drawable (bits per pixel).

depth

Type card8.

Function: drawable-height drawable
inside-height

Type card16.

Function: drawable-width drawable
drawable

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.

inside-width

Type card16.

Function: drawable-x drawable
outside-left

Type int16.

Function: drawable-y drawable
drawable

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.

outside-top

Type int16.

Function: window-all-event-masks window
window

A window.

Returns the inclusive-or of the event masks selected on the specified window by all clients.

all-event-masks

Type mask32.

Function: setf (window-background) window background
window

A window.

background

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.

background

Either a pixel, a pixmap, :none, or :parent-relative.

Function: window-backing-pixel window
window

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.

backing-pixel

Type pixel.

Function: window-backing-planes window
window

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.

backing-planes

Type pixel.

Function: window-backing-store window
window

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.

backing-store-type

One of :always, :not-useful, or :when-mapped.

Function: window-bit-gravity window
window

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.

:centerW/2H/2
:eastWH/2
:northW/20
:north-eastW0
:north-west00
:southW/2H
:south-eastWH
:south-west0H
:west0H/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.

bit-gravity

Type bit-gravity.

Function: setf (window-border) window border
window

A window.

border

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.

border

Either a pixel, a pixmap, or :copy.

Function: window-class window
window

A window.

Returns the class of the specified window.

class

Either :input-output or :input-only.

Function: window-colormap window
window

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.

colormap

Type colormap or null.

Function: window-colormap-installed-p window
window

A window.

Returns non-nil if the colormap associated with this window is installed. Otherwise, this function returns nil.

colormap-installed-p

Type boolean.

Function: setf (window-cursor) window cursor
window

A window.

cursor

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.

cursor

Type cursor or :none.

Function: window-display window
window

A window.

Returns the display object associated with the specified window.

display

Type display.

Function: window-do-not-propagate-mask window
window

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.

do-not-propagate-mask

Type mask32.

Function: window-equal window-1 window-2
window-1
window-2

The windows to compare for equality.

Returns non-nil if the two arguments are the same window, and nil if they are not.

equal-p

Type boolean.

Function: window-event-mask window
window

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.

event-mask

Type mask32.

Function: window-gravity window
window

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.

:centerW/2H/2
:eastWH/2
:northW/20
:north-eastW0
:north-west00
:southW/2H
:south-eastWH
:south-west0H
:west0H/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.

gravity

Type win-gravity.

Function: window-id window
window

A window.

Returns the unique ID assigned to window.

id

Type resource-id.

Function: window-map-state window
window

A window.

Returns the map state of window. A window is :unviewable if it is mapped but some ancestor is unmapped.

map-state

One of :unmapped, :unviewable, or :viewable.

Function: window-override-redirect window
window

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.

override-redirect

Either :on or :off.

Function: window-p object
window-p

Type boolean.

Returns non-nil if the object argument is a window; otherwise, it returns nil.

Function: window-plist window
window

A window.

Returns and (with setf) sets the property list for the specified window. This function provides a hook where extensions can hang data.

plist

A property list.

Function: setf (window-priority window) (&optional sibling) mode
window

A window.

sibling

An optional argument specifying that window is to be restacked relative to this sibling window.

mode

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.

mode

One of :above, :below, :bottom-if, :opposite, or :top-if.

Function: window-save-under window
window

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.

save-under

Either :on or :off.

Function: window-visual window
window

A window.

Returns the visual-type associated with the specified window.

visual-type

Type card29.

Macro: with-state drawable &body body

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 Attributeswindow-all-event-maskswindow-background
window-backing-pixelwindow-backing-pixel
window-backing-planeswindow-backing-planes
window-backing-storewindow-backing-store
window-bit-gravitywindow-bit-gravity
window-classwindow-border
window-colormapwindow-colormap
window-colormap-installed-pwindow-cursor
window-do-not-propagate-maskwindow-do-not-propagate-mask
window-event-maskwindow-event-mask
window-gravitywindow-gravity
window-map-state
window-override-redirectwindow-override-redirect
window-save-underwindow-save-under
window-visual
Drawable Geometrydrawable-border-widthdrawable-border-width
drawable-depthdrawable-height
drawable-heightdrawable-width
drawable-rootdrawable-x
drawable-widthdrawable-y
drawable-xwindow-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.

drawable

A display.

body

The forms in which attributes accesses are batched.


Next: , Previous: , Up: Windows and Pixmaps   [Contents][Index]