Next: Window Properties and Visibility, Previous: Windows and Pixmaps, Up: Drawables [Contents][Index]
Changes the components specified by field-names for the specified
window. The restrictions are the same as for
x:create-window. The order in which components are verified and
altered is server dependent. If an error occurs, a subset of the
components may have been altered.
The x:create-window and x:window-set! procedures take five
and one argument (respectively) followed by pairs of arguments, where
the first is one of the property-name symbols (or its top-level value)
listed below; and the second is the value to associate with that
property.
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 x:Parent-Relative is specified, the background pixmap of the window’s parent is used, or on the root window, the default background is restored. It is an error to perform this operation on an x:Input-Only window. If the background is set to #f or None, the window has no defined background.
Sets the background of the window to the specified pixel value. Changing the background does not cause the window contents to be changed. It is an error to perform this operation on an x:Input-Only window.
Sets the border pixmap of the window to the pixmap you specify. The border pixmap can be freed if no further explicit references to it are to be made. If you specify x:Copy-From-Parent, a copy of the parent window’s border pixmap is used. It is an error to perform this operation on an x:Input-Only window.
Sets the border of the window to the pixel value. It is an error to perform this operation on an x:Input-Only window.
The bit gravity of a window defines which region of the window should be retained when an x:Input-Output window is resized. The default value for the bit-gravity attribute is x:Forget-Gravity. The window gravity of a window allows you to define how the x:Input-Output or x:Input-Only window should be repositioned if its parent is resized. The default value for the win-gravity attribute is x:North-West-Gravity.
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:
| Gravity Direction | Coordinates |
| x:North-West-Gravity | (0, 0) |
| x:North-Gravity | (Width/2, 0) |
| x:North-East-Gravity | (Width, 0) |
| x:West-Gravity | (0, Height/2) |
| x:Center-Gravity | (Width/2, Height/2) |
| x:East-Gravity | (Width, Height/2) |
| x:South-West-Gravity | (0, Height) |
| x:South-Gravity | (Width/2, Height) |
| x:South-East-Gravity | (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 x:Gravity-Notify event is generated (see section 10.10.5).
A bit-gravity of x:Static-Gravity 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 x:Static-Gravity still only takes effect when the width or height of the window is changed, not when the window is moved.
A bit-gravity of x:Forget-Gravity 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 x: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 x: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 x:Forget-Gravity instead.
A win-gravity of x:Unmap-Gravity is like x:North-West-Gravity (the window is not moved), except the child is also unmapped when the parent is resized, and an x:Unmap-Notify event is generated.
Some implementations of the X server may choose to maintain the contents of x:Input-Output 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 x:Not-Useful (default), x:When-Mapped, or x:Always. A backing-store attribute of x:Not-Useful advises the X server that maintaining contents is unnecessary, although some X implementations may still choose to maintain contents and, therefore, not generate x:Expose events. A backing-store attribute of x:When-Mapped 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 x:Expose event when the window is created. A backing-store attribute of x: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, x: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.
You can set backing planes to indicate (with bits set to 1) which bit planes of an x:Input-Output 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.
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 x:Input-Output or x:Input-Only 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 x:Substructure-Redirect-Mask on the parent. You can set the override-redirect flag to #t or #f (default). Window managers use this information to avoid tampering with pop-up windows.
Some server implementations may preserve contents of x:Input-Output windows under other x:Input-Output 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.
The event mask defines which events the client is interested in for this x:Input-Output or x:Input-Only 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 x:No-Event-Mask (default).
The following table lists the event mask constants you can pass to the event-mask argument and the circumstances in which you would want to specify the event mask:
| Event Mask | Circumstances |
| x:No-Event-Mask | No events wanted |
| x:Key-Press-Mask | Keyboard down events wanted |
| x:Key-Release-Mask | Keyboard up events wanted |
| x:Button-Press-Mask | Pointer button down events wanted |
| x:Button-Release-Mask | Pointer button up events wanted |
| x:Enter-Window-Mask | Pointer window entry events wanted |
| x:Leave-Window-Mask | Pointer window leave events wanted |
| x:Pointer-Motion-Mask | Pointer motion events wanted |
| x:Pointer-Motion-Hint-Mask | If x:Pointer-Motion-Hint-Mask is selected in combination with one or more motion-masks, the X server is free to send only one x:Motion-Notify event (with the is_hint member of the X:Pointer-Moved-Event structure set to x:Notify-Hint) to the client for the event window, until either the key or button state changes, the pointer leaves the event window, or the client calls X:Query-Pointer or X:Get-Motion-Events. The server still may send x:Motion-Notify events without is_hint set to x:Notify-Hint. |
| x:Button1-Motion-Mask | Pointer motion while button 1 down |
| x:Button2-Motion-Mask | Pointer motion while button 2 down |
| x:Button3-Motion-Mask | Pointer motion while button 3 down |
| x:Button4-Motion-Mask | Pointer motion while button 4 down |
| x:Button5-Motion-Mask | Pointer motion while button 5 down |
| x:Button-Motion-Mask | Pointer motion while any button down |
| x:Keymap-State-Mask | Keyboard state wanted at window entry and focus in |
| x:Exposure-Mask | Any exposure wanted |
| x:Visibility-Change-Mask | Any change in visibility wanted |
| x:Structure-Notify-Mask | Any change in window structure wanted |
| x:Resize-Redirect-Mask | Redirect resize of this window |
| x:Substructure-Notify-Mask | Substructure notification wanted |
| x:Substructure-Redirect-Mask | Redirect structure requests on children |
| x:Focus-Change-Mask | Any change in input focus wanted |
| x:Property-Change-Mask | Any change in property wanted |
| x:Colormap-Change–Mask | Any change in colormap wanted |
| x:Owner-Grab-Button–Mask | Automatic grabs should activate with owner_events set to True |
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 x:Input-Output or x:Input-Only window. The do-not-propagate-mask is the bitwise inclusive OR of zero or more of the following masks: x:Key-Press, x:Key-Release, x:Button-Press, x:Button-Release, x:Pointer-Motion, x:Button1Motion, x:Button2Motion, x:Button3Motion, x:Button4Motion, x:Button5Motion, and x:Button-Motion. You can specify that all events are propagated by setting x:No-Event-Mask (default).
The colormap attribute specifies which colormap best reflects the true colors of the x:Input-Output window. The colormap must have the same visual type as the window. X servers capable of supporting multiple hardware colormaps can use this information, and window managers can use it for calls to X:Install-Colormap. You can set the colormap attribute to a colormap or to x:Copy-From-Parent (default).
If you set the colormap to x:Copy-From-Parent, 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. The parent window must not have a colormap of x:None. 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 x:Input-Output or x:Input-Only window. You can set the cursor to a cursor or x:None (default).
If you set the cursor to x:None, the parent’s cursor is used when the pointer is in the x:Input-Output or x:Input-Only window, and any change in the parent’s cursor will cause an immediate change in the displayed cursor. On the root window, the default cursor is restored.
Returns a list of the components specified by field-names for the
specified window. Allowable field-names are a subset of
those for x:window-set!:
Next: Window Properties and Visibility, Previous: Windows and Pixmaps, Up: Drawables [Contents][Index]