diff options
Diffstat (limited to 'libX11/specs/libX11/CH03')
| -rw-r--r-- | libX11/specs/libX11/CH03 | 3121 |
1 files changed, 3121 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH03 b/libX11/specs/libX11/CH03 new file mode 100644 index 000000000..f7eb2d4c0 --- /dev/null +++ b/libX11/specs/libX11/CH03 @@ -0,0 +1,3121 @@ +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software is furnished to do so, subject to +.\" the following conditions: +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from the X Consortium. +.\" +.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +.\" Digital Equipment Corporation +.\" +.\" Portions Copyright \(co 1990, 1991 by +.\" Tektronix, Inc. +.\" +.\" Permission to use, copy, modify and distribute this documentation for +.\" any purpose and without fee is hereby granted, provided that the above +.\" copyright notice appears in all copies and that both that copyright notice +.\" and this permission notice appear in all copies, and that the names of +.\" Digital and Tektronix not be used in in advertising or publicity pertaining +.\" to this documentation without specific, written prior permission. +.\" Digital and Tektronix makes no representations about the suitability +.\" of this documentation for any purpose. +.\" It is provided ``as is'' without express or implied warranty. +.\" +\& +.sp 1 +.ce 3 +\s+1\fBChapter 3\fP\s-1 + +\s+1\fBWindow Functions\fP\s-1 +.sp 2 +.nr H1 3 +.nr H2 0 +.nr H3 0 +.nr H4 0 +.nr H5 0 +.na +.LP +.XS +Chapter 3: Window Functions +.XE +In the X Window System, +a window is a rectangular area on the screen that lets you +view graphic output. +Client applications +can display overlapping and nested windows on one or more +screens that are driven by X servers on one or more machines. +Clients who want to create windows must first +connect their program to the X server +by calling +.PN XOpenDisplay . +This chapter begins with a discussion of +visual types and window attributes. +The chapter continues with a discussion of the Xlib functions you can use to: +.IP \(bu 5 +Create windows +.IP \(bu 5 +Destroy windows +.IP \(bu 5 +Map windows +.IP \(bu 5 +Unmap windows +.IP \(bu 5 +Configure windows +.IP \(bu 5 +Change window stacking order +.IP \(bu 5 +Change window attributes +.LP +This chapter also identifies the window actions that may generate events. +.LP +Note that it is vital that your application conform to the +established conventions for communicating with window managers +for it to work well with the various window managers in use (see section 14.1). +Toolkits generally adhere to these conventions for you, +relieving you of the burden. +Toolkits also often supersede many functions in this chapter +with versions of their own. +For more information, +refer to the documentation for the toolkit that you are using. +.NH 2 +Visual Types +.XS +\*(SN Visual Types +.XE +.LP +.IN "Visual Type" "" "@DEF@" +On some display hardware, +it may be possible to deal with color resources in more than one way. +For example, you may be able to deal with a screen of either 12-bit depth +with arbitrary mapping of pixel to color (pseudo-color) or 24-bit depth +with 8 bits of the pixel dedicated to each of red, green, and blue. +These different ways of dealing with the visual aspects of the screen +are called visuals. +For each screen of the display, there may be a list of valid visual types +supported at different depths of the screen. +Because default windows and visual types are defined for each screen, +most simple applications need not deal with this complexity. +Xlib provides macros and functions that return the default root window, +the default depth of the default root window, and the default visual type +(see sections 2.2.1 and 16.7). +.LP +Xlib uses an opaque +.PN Visual +.IN "Visual" "" "@DEF@" +structure that contains information about the possible color mapping. +The visual utility functions (see section 16.7) use an +.PN XVisualInfo +structure to return this information to an application. +The members of this structure pertinent to this discussion are class, red_mask, +green_mask, blue_mask, bits_per_rgb, and colormap_size. +The class member specifies one of the possible visual classes of the screen +and can be +.IN "Visual Classes" "StaticGray" +.IN "Visual Classes" "StaticColor" +.IN "Visual Classes" "TrueColor" +.IN "Visual Classes" "StaticColor" +.IN "Visual Classes" "GrayScale" +.IN "Visual Classes" "PseudoColor" +.PN StaticGray , +.PN StaticColor , +.PN TrueColor , +.PN GrayScale , +.PN PseudoColor , +or +.PN DirectColor . +.LP +The following concepts may serve to make the explanation of +visual types clearer. +The screen can be color or grayscale, +can have a colormap that is writable or read-only, +and can also have a colormap whose indices are decomposed into separate +RGB pieces, provided one is not on a grayscale screen. +This leads to the following diagram: +.LP +.DS +.TS +center; + c c s c s + c c c c c +| c | c | c | c | c |. + Color Gray-scale + R/O R/W R/O R/W +_ +Undecomposed Static Pseudo Static Gray +Colormap Color Color Gray Scale +_ +.T& +| c | c | c |. +Decomposed True Direct +Colormap Color Color +_ _ _ +.TE +.DE +.LP +Conceptually, +as each pixel is read out of video memory for display on the screen, +it goes through a look-up stage by indexing into a colormap. +Colormaps can be manipulated arbitrarily on some hardware, +in limited ways on other hardware, and not at all on other hardware. +The visual types affect the colormap and +the RGB values in the following ways: +.LP +.IP \(bu 5 +For +.PN PseudoColor , +a pixel value indexes a colormap to produce +independent RGB values, and the RGB values can be changed dynamically. +.IP \(bu 5 +.PN GrayScale +is treated the same way as +.PN PseudoColor +except that the primary that drives the screen is undefined. +Thus, the client should always store the +same value for red, green, and blue in the colormaps. +.IP \(bu 5 +For +.PN DirectColor , +a pixel value is decomposed into separate RGB subfields, and each +subfield separately indexes the colormap for the corresponding value. +The RGB values can be changed dynamically. +.IP \(bu 5 +.PN TrueColor +is treated the same way as +.PN DirectColor +except that the colormap has predefined, read-only RGB values. +These RGB values are server dependent but provide linear or near-linear +ramps in each primary. +.IP \(bu 5 +.PN StaticColor +is treated the same way as +.PN PseudoColor +except that the colormap has predefined, +read-only, server-dependent RGB values. +.IP \(bu 5 +.PN StaticGray +is treated the same way as +.PN StaticColor +except that the RGB values are equal for any single pixel +value, thus resulting in shades of gray. +.PN StaticGray +with a two-entry +colormap can be thought of as monochrome. +.LP +The red_mask, green_mask, and blue_mask members are only defined for +.PN DirectColor +and +.PN TrueColor . +Each has one contiguous set of bits with no +intersections. +The bits_per_rgb member specifies the log base 2 of the +number of distinct color values (individually) of red, green, and blue. +Actual RGB values are unsigned 16-bit numbers. +The colormap_size member defines the number of available colormap entries +in a newly created colormap. +For +.PN DirectColor +and +.PN TrueColor , +this is the size of an individual pixel subfield. +.sp +.LP +To obtain the visual ID from a +.PN Visual , +use +.PN XVisualIDFromVisual . +.IN "XVisualIDFromVisual" "" "@DEF@" +.sM +.FD 0 +VisualID XVisualIDFromVisual\^(\^\fIvisual\fP\^) +.br + Visual *\^\fIvisual\fP\^; +.FN +.IP \fIvisual\fP 1i +Specifies the visual type. +.LP +.eM +The +.PN XVisualIDFromVisual +function returns the visual ID for the specified visual type. +.NH 2 +Window Attributes +.XS +\*(SN Window Attributes +.XE +.LP +.IN "Window" +.IN "Window" "attributes" +All +.PN InputOutput +windows have a border width of zero or more pixels, an optional background, +an event suppression mask (which suppresses propagation of events from +children), and a property list (see section 4.3). +The window border and background can be a solid color or a pattern, called +a tile. +All windows except the root have a parent and are clipped by their parent. +If a window is stacked on top of another window, it obscures that other +window for the purpose of input. +If a window has a background (almost all do), it obscures the other +window for purposes of output. +Attempts to output to the obscured area do nothing, +and no input events (for example, pointer motion) are generated for the +obscured area. +.LP +Windows also have associated property lists (see section 4.3). +.LP +Both +.PN InputOutput +and +.PN InputOnly +windows have the following common attributes, +which are the only attributes of an +.PN InputOnly +window: +.IP \(bu 5 +win-gravity +.IP \(bu 5 +event-mask +.IP \(bu 5 +do-not-propagate-mask +.IP \(bu 5 +override-redirect +.IP \(bu 5 +cursor +.LP +If you specify any other attributes for an +.PN InputOnly +window, +a +.PN BadMatch +error results. +.LP +.PN InputOnly +windows are used for controlling input events in situations where +.PN InputOutput +windows are unnecessary. +.PN InputOnly +windows are invisible; can only be used to control such things as +cursors, input event generation, and grabbing; +and cannot be used in any graphics requests. +Note that +.PN InputOnly +windows cannot have +.PN InputOutput +windows as inferiors. +.LP +Windows have borders of a programmable width and pattern +as well as a background pattern or tile. +.IN "Tile" "pixmaps" +Pixel values can be used for solid colors. +.IN "Resource IDs" "freeing" +.IN "Freeing" "resources" +The background and border pixmaps can be destroyed immediately after +creating the window if no further explicit references to them +are to be made. +.IN "Tile" "mode" +The pattern can either be relative to the parent +or absolute. +If +.PN ParentRelative , +the parent's background is used. +.LP +When windows are first created, +they are not visible (not mapped) on the screen. +Any output to a window that is not visible on the screen +and that does not have backing store will be discarded. +.IN "Window" "mapping" +An application may wish to create a window long before it is +mapped to the screen. +When a window is eventually mapped to the screen +(using +.PN XMapWindow ), +.IN "XMapWindow" +the X server generates an +.PN Expose +event for the window if backing store has not been maintained. +.LP +A window manager can override your choice of size, +border width, and position for a top-level window. +Your program must be prepared to use the actual size and position +of the top window. +It is not acceptable for a client application to resize itself +unless in direct response to a human command to do so. +Instead, either your program should use the space given to it, +or if the space is too small for any useful work, your program +might ask the user to resize the window. +The border of your top-level window is considered fair game +for window managers. +.LP +To set an attribute of a window, +set the appropriate member of the +.PN XSetWindowAttributes +structure and OR in the corresponding value bitmask in your subsequent calls to +.PN XCreateWindow +and +.PN XChangeWindowAttributes , +or use one of the other convenience functions that set the appropriate +attribute. +The symbols for the value mask bits and the +.PN XSetWindowAttributes +structure are: +.sM +.LP +/* Window attribute value mask bits */ +.TS +lw(.5i) lw(2.5i) lw(.8i). +T{ +#define +T} T{ +.PN CWBackPixmap +T} T{ +(1L<<0) +T} +T{ +#define +T} T{ +.PN CWBackPixel +T} T{ +(1L<<1) +T} +T{ +#define +T} T{ +.PN CWBorderPixmap +T} T{ +(1L<<2) +T} +T{ +#define +T} T{ +.PN CWBorderPixel +T} T{ +(1L<<3) +T} +T{ +#define +T} T{ +.PN CWBitGravity +T} T{ +(1L<<4) +T} +T{ +#define +T} T{ +.PN CWWinGravity +T} T{ +(1L<<5) +T} +T{ +#define +T} T{ +.PN CWBackingStore +T} T{ +(1L<<6) +T} +T{ +#define +T} T{ +.PN CWBackingPlanes +T} T{ +(1L<<7) +T} +T{ +#define +T} T{ +.PN CWBackingPixel +T} T{ +(1L<<8) +T} +T{ +#define +T} T{ +.PN CWOverrideRedirect +T} T{ +(1L<<9) +T} +T{ +#define +T} T{ +.PN CWSaveUnder +T} T{ +(1L<<10) +T} +T{ +#define +T} T{ +.PN CWEventMask +T} T{ +(1L<<11) +T} +T{ +#define +T} T{ +.PN CWDontPropagate +T} T{ +(1L<<12) +T} +T{ +#define +T} T{ +.PN CWColormap +T} T{ +(1L<<13) +T} +T{ +#define +T} T{ +.PN CWCursor +T} T{ +(1L<<14) +T} +.TE +.IN "XSetWindowAttributes" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +/* Values */ + +typedef struct { + Pixmap background_pixmap; /* background, None, or ParentRelative */ + unsigned long background_pixel; /* background pixel */ + Pixmap border_pixmap; /* border of the window or CopyFromParent */ + unsigned long border_pixel; /* border pixel value */ + int bit_gravity; /* one of bit gravity values */ + int win_gravity; /* one of the window gravity values */ + int backing_store; /* NotUseful, WhenMapped, Always */ + unsigned long backing_planes; /* planes to be preserved if possible */ + unsigned long backing_pixel; /* value to use in restoring planes */ + Bool save_under; /* should bits under be saved? (popups) */ + long event_mask; /* set of events that should be saved */ + long do_not_propagate_mask; /* set of events that should not propagate */ + Bool override_redirect; /* boolean value for override_redirect */ + Colormap colormap; /* color map to be associated with window */ + Cursor cursor; /* cursor to be displayed (or None) */ +} XSetWindowAttributes; +.De +.LP +.eM +The following lists the defaults for each window attribute and indicates +whether the attribute is applicable to +.PN InputOutput +and +.PN InputOnly +windows: +.TS H +l l l l +lw(1.4i) lw(1.3i) cw(.9i) cw(.8i). +_ +.sp 6p +T{ +.B Attribute +T} T{ +.B Default +T} T{ +.PN InputOutput +T} T{ +.PN InputOnly +T} +.sp 6p +_ +.sp 6p +.TH +.R +T{ +background-pixmap +T} T{ +.PN None +T} T{ +Yes +T} T{ +No +T} +background-pixel Undefined Yes No +T{ +border-pixmap +T} T{ +.PN CopyFromParent +T} T{ +Yes +T} T{ +No +T} +border-pixel Undefined Yes No +T{ +bit-gravity +T} T{ +.PN ForgetGravity +T} T{ +Yes +T} T{ +No +T} +T{ +win-gravity +T} T{ +.PN NorthWestGravity +T} T{ +Yes +T} T{ +Yes +T} +T{ +backing-store +T} T{ +.PN NotUseful +T} T{ +Yes +T} T{ +No +T} +backing-planes All ones Yes No +backing-pixel zero Yes No +T{ +save-under +T} T{ +.PN False +T} T{ +Yes +T} T{ +No +T} +event-mask empty set Yes Yes +do-not-propagate-mask empty set Yes Yes +T{ +override-redirect +T} T{ +.PN False +T} T{ +Yes +T} T{ +Yes +T} +T{ +colormap +T} T{ +.PN CopyFromParent +T} T{ +Yes +T} T{ +No +T} +T{ +cursor +T} T{ +.PN None +T} T{ +Yes +T} T{ +Yes +T} +_ +.TE +.NH 3 +Background Attribute +.XS +\*(SN Background Attribute +.XE +.LP +Only +.PN InputOutput +windows can have a background. +You can set the background of an +.PN InputOutput +window by using a pixel or a pixmap. +.LP +The background-pixmap attribute of a window specifies the pixmap to be used for +a window's background. +This pixmap can be of any size, although some sizes may be faster than others. +The background-pixel attribute of a window specifies a pixel value used to paint +a window's background in a single color. +.LP +You can set the background-pixmap to a pixmap, +.PN None +(default), or +.PN ParentRelative . +You can set the background-pixel of a window to any pixel value (no default). +If you specify a background-pixel, +it overrides either the default background-pixmap +or any value you may have set in the background-pixmap. +A pixmap of an undefined size that is filled with the background-pixel is used +for the background. +Range checking is not performed on the background pixel; +it simply is truncated to the appropriate number of bits. +.LP +If you set the background-pixmap, +it overrides the default. +The background-pixmap and the window must have the same depth, +or a +.PN BadMatch +error results. +If you set background-pixmap to +.PN None , +the window has no defined background. +If you set the background-pixmap to +.PN ParentRelative : +.IP \(bu 5 +The parent window's background-pixmap is used. +The child window, however, must have the same depth as +its parent, +or a +.PN BadMatch +error results. +.IP \(bu 5 +If the parent window has a background-pixmap of +.PN None , +the window also has a background-pixmap of +.PN None . +.IP \(bu 5 +A copy of the parent window's background-pixmap is not made. +The parent's background-pixmap is examined each time the child window's +background-pixmap is required. +.IP \(bu 5 +The background tile origin always aligns with the parent window's +background tile origin. +If the background-pixmap is not +.PN ParentRelative , +the background tile origin is the child window's origin. +.LP +Setting a new background, whether by setting background-pixmap or +background-pixel, overrides any previous background. +The background-pixmap can be freed immediately if no further explicit reference +is made to it (the X server will keep a copy to use when needed). +If you later draw into the pixmap used for the background, +what happens is undefined because the +X implementation is free to make a copy of the pixmap or +to use the same pixmap. +.LP +When no valid contents are available for regions of a window +and either the regions are visible or the server is maintaining backing store, +the server automatically tiles the regions with the window's background +unless the window has a background of +.PN None . +If the background is +.PN None , +the previous screen contents from other windows of the same depth as the window +are simply left in place as long as the contents come from the parent of the +window or an inferior of the parent. +Otherwise, the initial contents of the exposed regions are undefined. +.PN Expose +events are then generated for the regions, even if the background-pixmap +is +.PN None +(see section 10.9). +.NH 3 +Border Attribute +.XS +\*(SN Border Attribute +.XE +.LP +Only +.PN InputOutput +windows can have a border. +You can set the border of an +.PN InputOutput +window by using a pixel or a pixmap. +.LP +The border-pixmap attribute of a window specifies the pixmap to be used +for a window's border. +The border-pixel attribute of a window specifies a pixmap of undefined size +filled with that pixel be used for a window's border. +Range checking is not performed on the background pixel; +it simply is truncated to the appropriate number of bits. +The border tile origin is always the same as the background tile origin. +.LP +You can also set the border-pixmap to a pixmap of any size (some may be faster +than others) or to +.PN CopyFromParent +(default). +You can set the border-pixel to any pixel value (no default). +.LP +If you set a border-pixmap, +it overrides the default. +The border-pixmap and the window must have the same depth, +or a +.PN BadMatch +error results. +If you set the border-pixmap to +.PN CopyFromParent , +the parent window's border-pixmap is copied. +Subsequent changes to the parent window's border attribute do not affect +the child window. +However, the child window must have the same depth as the parent window, +or a +.PN BadMatch +error results. +.LP +The border-pixmap can be freed immediately if no further explicit reference +is made to it. +If you later draw into the pixmap used for the border, +what happens is undefined because the +X implementation is free either to make a copy of the pixmap or +to use the same pixmap. +If you specify a border-pixel, +it overrides either the default border-pixmap +or any value you may have set in the border-pixmap. +All pixels in the window's border will be set to the border-pixel. +Setting a new border, whether by setting border-pixel or by setting +border-pixmap, overrides any previous border. +.LP +Output to a window is always clipped to the inside of the window. +Therefore, graphics operations never affect the window border. +.NH 3 +Gravity Attributes +.XS +\*(SN Gravity Attributes +.XE +.LP +The bit gravity of a window defines which region of the window should be +retained when an +.PN InputOutput +window is resized. +The default value for the bit-gravity attribute is +.PN ForgetGravity . +The window gravity of a window allows you to define how the +.PN InputOutput +or +.PN InputOnly +window should be repositioned if its parent is resized. +The default value for the win-gravity attribute is +.PN NorthWestGravity . +.LP +If the inside width or height of a window is not changed +and if the window is moved or its border is changed, +then the contents of the window are not lost but move with the window. +Changing the inside width or height of the window causes its contents to be +moved or lost (depending on the bit-gravity of the window) and causes +children to be reconfigured (depending on their win-gravity). +For a +change of width and height, the (x, y) pairs are defined: +.LP +.TS +l l +l l. +_ +.sp 6p +.B +Gravity Direction Coordinates +.sp 6p +_ +.sp 6p +.R +T{ +.PN NorthWestGravity +T} T{ +(0, 0) +T} +T{ +.PN NorthGravity +T} T{ +(Width/2, 0) +T} +T{ +.PN NorthEastGravity +T} T{ +(Width, 0) +T} +T{ +.PN WestGravity +T} T{ +(0, Height/2) +T} +T{ +.PN CenterGravity +T} T{ +(Width/2, Height/2) +T} +T{ +.PN EastGravity +T} T{ +(Width, Height/2) +T} +T{ +.PN SouthWestGravity +T} T{ +(0, Height) +T} +T{ +.PN SouthGravity +T} T{ +(Width/2, Height) +T} +T{ +.PN SouthEastGravity +T} T{ +(Width, Height) +T} +.sp 6p +_ +.TE +.LP +When a window with one of these bit-gravity values is resized, +the corresponding pair +defines the change in position of each pixel in the window. +When a window with one of these win-gravities has its parent window resized, +the corresponding pair defines the change in position of the window +within the parent. +When a window is so repositioned, a +.PN GravityNotify +event is generated (see section 10.10.5). +.LP +A bit-gravity of +.PN StaticGravity +indicates that the contents or origin should not move relative to the +origin of the root window. +If the change in size of the window is coupled with a change in position (x, y), +then for bit-gravity the change in position of each pixel is (\-x, \-y), and for +win-gravity the change in position of a child when its parent is so resized is +(\-x, \-y). +Note that +.PN StaticGravity +still only takes effect when the width or height of the window is changed, +not when the window is moved. +.LP +A bit-gravity of +.PN ForgetGravity +indicates that the window's contents are always discarded after a size change, +even if a backing store or save under has been requested. +The window is tiled with its background +and zero or more +.PN Expose +events are generated. +If no background is defined, the existing screen contents are not +altered. +Some X servers may also ignore the specified bit-gravity and +always generate +.PN Expose +events. +.LP +The contents and borders of inferiors are not affected by their parent's +bit-gravity. +A server is permitted to ignore the specified bit-gravity and use +.PN Forget +instead. +.LP +A win-gravity of +.PN UnmapGravity +is like +.PN NorthWestGravity +(the window is not moved), +except the child is also +unmapped when the parent is resized, +and an +.PN UnmapNotify +event is +generated. +.NH 3 +Backing Store Attribute +.XS +\*(SN Backing Store Attribute +.XE +.LP +Some implementations of the X server may choose to maintain the contents of +.PN InputOutput +windows. +If the X server maintains the contents of a window, +the off-screen saved pixels +are known as backing store. +The backing store advises the X server on what to do +with the contents of a window. +The backing-store attribute can be set to +.PN NotUseful +(default), +.PN WhenMapped , +or +.PN Always . +.LP +A backing-store attribute of +.PN NotUseful +advises the X server that +maintaining contents is unnecessary, +although some X implementations may +still choose to maintain contents and, therefore, not generate +.PN Expose +events. +A backing-store attribute of +.PN WhenMapped +advises the X server that maintaining contents of +obscured regions when the window is mapped would be beneficial. +In this case, +the server may generate an +.PN Expose +event when the window is created. +A backing-store attribute of +.PN Always +advises the X server that maintaining contents even when +the window is unmapped would be beneficial. +Even if the window is larger than its parent, +this is a request to the X server to maintain complete contents, +not just the region within the parent window boundaries. +While the X server maintains the window's contents, +.PN Expose +events normally are not generated, +but the X server may stop maintaining +contents at any time. +.LP +When the contents of obscured regions of a window are being maintained, +regions obscured by noninferior windows are included in the destination +of graphics requests (and source, when the window is the source). +However, regions obscured by inferior windows are not included. +.NH 3 +Save Under Flag +.XS +\*(SN Save Under Flag +.XE +.IN "Save Unders" +.LP +Some server implementations may preserve contents of +.PN InputOutput +windows under other +.PN InputOutput +windows. +This is not the same as preserving the contents of a window for you. +You may get better visual +appeal if transient windows (for example, pop-up menus) request that the system +preserve the screen contents under them, +so the temporarily obscured applications do not have to repaint. +.LP +You can set the save-under flag to +.PN True +or +.PN False +(default). +If save-under is +.PN True , +the X server is advised that, when this window is mapped, +saving the contents of windows it obscures would be beneficial. +.NH 3 +Backing Planes and Backing Pixel Attributes +.XS +\*(SN Backing Planes and Backing Pixel Attributes +.XE +.LP +You can set backing planes to indicate (with bits set to 1) +which bit planes of an +.PN InputOutput +window hold dynamic data that must be preserved in backing store +and during save unders. +The default value for the backing-planes attribute is all bits set to 1. +You can set backing pixel to specify what bits to use in planes not +covered by backing planes. +The default value for the backing-pixel attribute is all bits set to 0. +The X server is free to save only the specified bit planes in the backing store +or the save under and is free to regenerate the remaining planes with +the specified pixel value. +Any extraneous bits in these values (that is, those bits beyond +the specified depth of the window) may be simply ignored. +If you request backing store or save unders, +you should use these members to minimize the amount of off-screen memory +required to store your window. +.NH 3 +Event Mask and Do Not Propagate Mask Attributes +.XS +\*(SN Event Mask and Do Not Propagate Mask Attributes +.XE +.LP +The event mask defines which events the client is interested in for this +.PN InputOutput +or +.PN InputOnly +window (or, for some event types, inferiors of this window). +The event mask is the bitwise inclusive OR of zero or more of the +valid event mask bits. +You can specify that no maskable events are reported by setting +.PN NoEventMask +(default). +.LP +The do-not-propagate-mask attribute +defines which events should not be propagated to +ancestor windows when no client has the event type selected in this +.PN InputOutput +or +.PN InputOnly +window. +The do-not-propagate-mask is the bitwise inclusive OR of zero or more +of the following masks: +.PN KeyPress , +.PN KeyRelease , +.PN ButtonPress , +.PN ButtonRelease , +.PN PointerMotion , +.PN Button1Motion , +.PN Button2Motion , +.PN Button3Motion , +.PN Button4Motion , +.PN Button5Motion , +and +.PN ButtonMotion . +You can specify that all events are propagated by setting +.PN NoEventMask +(default). +.NH 3 +Override Redirect Flag +.XS +\*(SN Override Redirect Flag +.XE +.LP +To control window placement or to add decoration, +a window manager often needs to intercept (redirect) any map or configure +request. +Pop-up windows, however, often need to be mapped without a window manager +getting in the way. +To control whether an +.PN InputOutput +or +.PN InputOnly +window is to ignore these structure control facilities, +use the override-redirect flag. +.LP +The override-redirect flag specifies whether map and configure requests +on this window should override a +.PN SubstructureRedirectMask +on the parent. +You can set the override-redirect flag to +.PN True +or +.PN False +(default). +Window managers use this information to avoid tampering with pop-up windows +(see also chapter 14). +.NH 3 +Colormap Attribute +.XS +\*(SN Colormap Attribute +.XE +.LP +The colormap attribute specifies which colormap best reflects the true +colors of the +.PN InputOutput +window. +The colormap must have the same visual type as the window, +or a +.PN BadMatch +error results. +X servers capable of supporting multiple +hardware colormaps can use this information, +and window managers can use it for calls to +.PN XInstallColormap . +You can set the colormap attribute to a colormap or to +.PN CopyFromParent +(default). +.LP +If you set the colormap to +.PN CopyFromParent , +the parent window's colormap is copied and used by its child. +However, the child window must have the same visual type as the parent, +or a +.PN BadMatch +error results. +The parent window must not have a colormap of +.PN None , +or a +.PN BadMatch +error results. +The colormap is copied by sharing the colormap object between the child +and parent, not by making a complete copy of the colormap contents. +Subsequent changes to the parent window's colormap attribute do +not affect the child window. +.NH 3 +Cursor Attribute +.XS +\*(SN Cursor Attribute +.XE +.LP +The cursor attribute specifies which cursor is to be used when the pointer is +in the +.PN InputOutput +or +.PN InputOnly +window. +You can set the cursor to a cursor or +.PN None +(default). +.LP +If you set the cursor to +.PN None , +the parent's cursor is used when the +pointer is in the +.PN InputOutput +or +.PN InputOnly +window, and any change in the parent's cursor will cause an +immediate change in the displayed cursor. +By calling +.PN XFreeCursor , +the cursor can be freed immediately as long as no further explicit reference +to it is made. +.NH 2 +Creating Windows +.XS +\*(SN Creating Windows +.XE +.LP +Xlib provides basic ways for creating windows, +and toolkits often supply higher-level functions specifically for +creating and placing top-level windows, +which are discussed in the appropriate toolkit documentation. +If you do not use a toolkit, however, +you must provide some standard information or hints for the window +manager by using the Xlib inter-client communication functions +(see chapter 14). +.LP +If you use Xlib to create your own top-level windows +(direct children of the root window), +you must observe the following rules so that all applications interact +reasonably across the different styles of window management: +.IP \(bu 5 +You must never fight with the window manager for the size or +placement of your top-level window. +.IP \(bu 5 +You must be able to deal with whatever size window you get, +even if this means that your application just prints a message +like ``Please make me bigger'' in its window. +.IP \(bu 5 +You should only attempt to resize or move top-level windows in +direct response to a user request. +If a request to change the size of a top-level window fails, +you must be prepared to live with what you get. +You are free to resize or move the children of top-level +windows as necessary. +(Toolkits often have facilities for automatic relayout.) +.IP \(bu 5 +If you do not use a toolkit that automatically sets standard window properties, +you should set these properties for top-level windows before mapping them. +.LP +For further information, +see chapter 14 and the \fIInter-Client Communication Conventions Manual\fP. +.LP +.PN XCreateWindow +is the more general function that allows you to set specific window attributes +when you create a window. +.PN XCreateSimpleWindow +creates a window that inherits its attributes from its parent window. +.LP +.IN "Window" "InputOnly" +The X server acts as if +.PN InputOnly +windows do not exist for +the purposes of graphics requests, exposure processing, and +.PN VisibilityNotify +events. +An +.PN InputOnly +window cannot be used as a +drawable (that is, as a source or destination for graphics requests). +.PN InputOnly +and +.PN InputOutput +windows act identically in other respects (properties, +grabs, input control, and so on). +Extension packages can define other classes of windows. +.LP +To create an unmapped window and set its window attributes, use +.PN XCreateWindow . +.IN "XCreateWindow" "" "@DEF@" +.sM +.FD 0 +Window XCreateWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, \fIdepth\fP\^, +.br + \fIclass\fP\^, \fIvisual\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIparent\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + unsigned int \fIborder_width\fP\^; +.br + int \fIdepth\fP\^; +.br + unsigned int \fIclass\fP\^; +.br + Visual *\fIvisual\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XSetWindowAttributes *\fIattributes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIparent\fP 1i +Specifies the parent window. +.ds Xy , which are the top-left outside corner of the created window's \ +borders and are relative to the inside of the parent window's borders +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which are the created window's inside dimensions \ +and do not include the created window's borders +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +The dimensions must be nonzero, +or a +.PN BadValue +error results. +.IP \fIborder_width\fP 1i +Specifies the width of the created window's border in pixels. +.IP \fIdepth\fP 1i +Specifies the window's depth. +A depth of +.PN CopyFromParent +means the depth is taken from the parent. +.IP \fIclass\fP 1i +Specifies the created window's class. +You can pass +.PN InputOutput , +.PN InputOnly , +or +.PN CopyFromParent . +A class of +.PN CopyFromParent +means the class +is taken from the parent. +.IP \fIvisual\fP 1i +Specifies the visual type. +A visual of +.PN CopyFromParent +means the visual type is taken from the +parent. +.IP \fIvaluemask\fP 1i +Specifies which window attributes are defined in the attributes +argument. +This mask is the bitwise inclusive OR of the valid attribute mask bits. +If valuemask is zero, +the attributes are ignored and are not referenced. +.IP \fIattributes\fP 1i +Specifies the structure from which the values (as specified by the value mask) +are to be taken. +The value mask should have the appropriate bits +set to indicate which attributes have been set in the structure. +.LP +.eM +The +.PN XCreateWindow +function creates an unmapped subwindow for a specified parent window, +returns the window ID of the created window, +and causes the X server to generate a +.PN CreateNotify +event. +The created window is placed on top in the stacking order +with respect to siblings. +.LP +The coordinate system has the X axis horizontal and the Y axis vertical +with the origin [0, 0] at the upper-left corner. +Coordinates are integral, +in terms of pixels, +and coincide with pixel centers. +Each window and pixmap has its own coordinate system. +For a window, +the origin is inside the border at the inside, upper-left corner. +.LP +The border_width for an +.PN InputOnly +window must be zero, or a +.PN BadMatch +error results. +For class +.PN InputOutput , +the visual type and depth must be a combination supported for the screen, +or a +.PN BadMatch +error results. +The depth need not be the same as the parent, +but the parent must not be a window of class +.PN InputOnly , +or a +.PN BadMatch +error results. +For an +.PN InputOnly +window, +the depth must be zero, and the visual must be one supported by the screen. +If either condition is not met, +a +.PN BadMatch +error results. +The parent window, however, may have any depth and class. +If you specify any invalid window attribute for a window, a +.PN BadMatch +error results. +.LP +The created window is not yet displayed (mapped) on the user's display. +To display the window, call +.PN XMapWindow . +The new window initially uses the same cursor as +its parent. +A new cursor can be defined for the new window by calling +.PN XDefineCursor . +.IN "Cursor" "Initial State" +.IN "XDefineCursor" +The window will not be visible on the screen unless it and all of its +ancestors are mapped and it is not obscured by any of its ancestors. +.LP +.PN XCreateWindow +can generate +.PN BadAlloc , +.PN BadColor , +.PN BadCursor , +.PN BadMatch , +.PN BadPixmap , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To create an unmapped +.PN InputOutput +subwindow of a given parent window, use +.PN XCreateSimpleWindow . +.IN "XCreateSimpleWindow" "" "@DEF@" +.sM +.FD 0 +Window XCreateSimpleWindow\^(\^\fIdisplay\fP, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^, \fIborder_width\fP\^, +.br + \fIborder\fP\^, \fIbackground\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIparent\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.br + unsigned int \fIborder_width\fP\^; +.br + unsigned long \fIborder\fP\^; +.br + unsigned long \fIbackground\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIparent\fP 1i +Specifies the parent window. +.ds Xy , which are the top-left outside corner of the new window's borders \ +and are relative to the inside of the parent window's borders +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which are the created window's inside dimensions \ +and do not include the created window's borders +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +The dimensions must be nonzero, +or a +.PN BadValue +error results. +.IP \fIborder_width\fP 1i +Specifies the width of the created window's border in pixels. +.IP \fIborder\fP 1i +Specifies the border pixel value of the window. +.IP \fIbackground\fP 1i +Specifies the background pixel value of the window. + +.LP +.eM +The +.PN XCreateSimpleWindow +function creates an unmapped +.PN InputOutput +subwindow for a specified parent window, returns the +window ID of the created window, and causes the X server to generate a +.PN CreateNotify +event. +The created window is placed on top in the stacking order with respect to +siblings. +Any part of the window that extends outside its parent window is clipped. +The border_width for an +.PN InputOnly +window must be zero, or a +.PN BadMatch +error results. +.PN XCreateSimpleWindow +inherits its depth, class, and visual from its parent. +All other window attributes, except background and border, +have their default values. +.LP +.PN XCreateSimpleWindow +can generate +.PN BadAlloc , +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.NH 2 +Destroying Windows +.XS +\*(SN Destroying Windows +.XE +.LP +Xlib provides functions that you can use to destroy a window or destroy all +subwindows of a window. +.LP +.sp +To destroy a window and all of its subwindows, use +.PN XDestroyWindow . +.IN "XDestroyWindow" "" "@DEF@" +.sM +.FD 0 +XDestroyWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XDestroyWindow +function destroys the specified window as well as all of its subwindows and causes +the X server to generate a +.PN DestroyNotify +event for each window. +The window should never be referenced again. +If the window specified by the w argument is mapped, +it is unmapped automatically. +The ordering of the +.PN DestroyNotify +events is such that for any given window being destroyed, +.PN DestroyNotify +is generated on any inferiors of the window before being generated on +the window itself. +The ordering among siblings and across subhierarchies is not otherwise +constrained. +If the window you specified is a root window, no windows are destroyed. +Destroying a mapped window will generate +.PN Expose +events on other windows that were obscured by the window being destroyed. +.LP +.PN XDestroyWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To destroy all subwindows of a specified window, use +.PN XDestroySubwindows . +.IN "XDestroySubwindows" "" "@DEF@" +.sM +.FD 0 +XDestroySubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XDestroySubwindows +function destroys all inferior windows of the specified window, +in bottom-to-top stacking order. +It causes the X server to generate a +.PN DestroyNotify +event for each window. +If any mapped +subwindows were actually destroyed, +.PN XDestroySubwindows +causes the X server to generate +.PN Expose +events on the specified window. +This is much more efficient than deleting many windows +one at a time because much of the work need be performed only once for all +of the windows, rather than for each window. +The subwindows should never be referenced again. +.LP +.PN XDestroySubwindows +can generate a +.PN BadWindow +error. +.NH 2 +Mapping Windows +.XS +\*(SN Mapping Windows +.XE +.LP +A window is considered mapped if an +.PN XMapWindow +call has been made on it. +It may not be visible on the screen for one of the following reasons: +.IP \(bu 5 +It is obscured by another opaque window. +.IP \(bu 5 +One of its ancestors is not mapped. +.IP \(bu 5 +It is entirely clipped by an ancestor. +.LP +.PN Expose +events are generated for the window when part or all of +it becomes visible on the screen. +A client receives the +.PN Expose +events only if it has asked for them. +Windows retain their position in the stacking order when they are unmapped. +.LP +A window manager may want to control the placement of subwindows. +If +.PN SubstructureRedirectMask +has been selected by a window manager +on a parent window (usually a root window), +a map request initiated by other clients on a child window is not performed, +and the window manager is sent a +.PN MapRequest +event. +However, if the override-redirect flag on the child had been set to +.PN True +(usually only on pop-up menus), +the map request is performed. +.LP +A tiling window manager might decide to reposition and resize other clients' +windows and then decide to map the window to its final location. +A window manager that wants to provide decoration might +reparent the child into a frame first. +For further information, +see sections 3.2.8 and 10.10. +Only a single client at a time can select for +.PN SubstructureRedirectMask . +.LP +Similarly, a single client can select for +.PN ResizeRedirectMask +on a parent window. +Then, any attempt to resize the window by another client is suppressed, and +the client receives a +.PN ResizeRequest +event. +.LP +.sp +To map a given window, use +.PN XMapWindow . +.IN "XMapWindow" "" "@DEF@" +.sM +.FD 0 +XMapWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XMapWindow +function +maps the window and all of its +subwindows that have had map requests. +Mapping a window that has an unmapped ancestor does not display the +window but marks it as eligible for display when the ancestor becomes +mapped. +Such a window is called unviewable. +When all its ancestors are mapped, +the window becomes viewable +and will be visible on the screen if it is not obscured by another window. +This function has no effect if the window is already mapped. +.LP +If the override-redirect of the window is +.PN False +and if some other client has selected +.PN SubstructureRedirectMask +on the parent window, then the X server generates a +.PN MapRequest +event, and the +.PN XMapWindow +function does not map the window. +Otherwise, the window is mapped, and the X server generates a +.PN MapNotify +event. +.LP +If the window becomes viewable and no earlier contents for it are remembered, +the X server tiles the window with its background. +If the window's background is undefined, +the existing screen contents are not +altered, and the X server generates zero or more +.PN Expose +events. +If backing-store was maintained while the window was unmapped, no +.PN Expose +events +are generated. +If backing-store will now be maintained, +a full-window exposure is always generated. +Otherwise, only visible regions may be reported. +Similar tiling and exposure take place for any newly viewable inferiors. +.LP +.IN "XMapWindow" +If the window is an +.PN InputOutput +window, +.PN XMapWindow +generates +.PN Expose +events on each +.PN InputOutput +window that it causes to be displayed. +If the client maps and paints the window +and if the client begins processing events, +the window is painted twice. +To avoid this, +first ask for +.PN Expose +events and then map the window, +so the client processes input events as usual. +The event list will include +.PN Expose +for each +window that has appeared on the screen. +The client's normal response to +an +.PN Expose +event should be to repaint the window. +This method usually leads to simpler programs and to proper interaction +with window managers. +.LP +.PN XMapWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To map and raise a window, use +.PN XMapRaised . +.IN "XMapRaised" "" "@DEF@" +.sM +.FD 0 +XMapRaised\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XMapRaised +function +essentially is similar to +.PN XMapWindow +in that it maps the window and all of its +subwindows that have had map requests. +However, it also raises the specified window to the top of the stack. +For additional information, +see +.PN XMapWindow . +.LP +.PN XMapRaised +can generate multiple +.PN BadWindow +errors. +.LP +.sp +To map all subwindows for a specified window, use +.PN XMapSubwindows . +.IN "XMapSubwindows" "" "@DEF@" +.sM +.FD 0 +XMapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XMapSubwindows +.IN "XMapSubwindows" +function maps all subwindows for a specified window in top-to-bottom stacking +order. +The X server generates +.PN Expose +events on each newly displayed window. +This may be much more efficient than mapping many windows +one at a time because the server needs to perform much of the work +only once, for all of the windows, rather than for each window. +.LP +.PN XMapSubwindows +can generate a +.PN BadWindow +error. +.NH 2 +Unmapping Windows +.XS +\*(SN Unmapping Windows +.XE +.LP +Xlib provides functions that you can use to unmap a window or all subwindows. +.LP +.sp +To unmap a window, use +.PN XUnmapWindow . +.IN "XUnmapWindow" "" "@DEF@" +.sM +.FD 0 +XUnmapWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XUnmapWindow +function unmaps the specified window and causes the X server to generate an +.PN UnmapNotify +.IN "UnmapNotify Event" +.IN "XUnmapWindow" +event. +If the specified window is already unmapped, +.PN XUnmapWindow +has no effect. +Normal exposure processing on formerly obscured windows is performed. +Any child window will no longer be visible until another map call is +made on the parent. +In other words, the subwindows are still mapped but are not visible +until the parent is mapped. +Unmapping a window will generate +.PN Expose +events on windows that were formerly obscured by it. +.LP +.PN XUnmapWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To unmap all subwindows for a specified window, use +.PN XUnmapSubwindows . +.IN "XUnmapSubwindows" "" "@DEF@" +.sM +.FD 0 +XUnmapSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XUnmapSubwindows +function unmaps all subwindows for the specified window in bottom-to-top +stacking order. +It causes the X server to generate an +.PN UnmapNotify +event on each subwindow and +.PN Expose +events on formerly obscured windows. +.IN "UnmapNotify Event" +Using this function is much more efficient than unmapping multiple windows +one at a time because the server needs to perform much of the work +only once, for all of the windows, rather than for each window. +.LP +.PN XUnmapSubwindows +can generate a +.PN BadWindow +error. +.NH 2 +Configuring Windows +.XS +\*(SN Configuring Windows +.XE +.LP +.LP +Xlib provides functions that you can use to +move a window, resize a window, move and resize a window, or +change a window's border width. +To change one of these parameters, +set the appropriate member of the +.PN XWindowChanges +structure and OR in the corresponding value mask in subsequent calls to +.PN XConfigureWindow . +The symbols for the value mask bits and the +.PN XWindowChanges +structure are: +.sM +.LP +/* Configure window value mask bits */ +.TS +lw(.5i) lw(2.5i) lw(.8i). +T{ +#define +T} T{ +.PN CWX +T} T{ +(1<<0) +T} +T{ +#define +T} T{ +.PN CWY +T} T{ +(1<<1) +T} +T{ +#define +T} T{ +.PN CWWidth +T} T{ +(1<<2) +T} +T{ +#define +T} T{ +.PN CWHeight +T} T{ +(1<<3) +T} +T{ +#define +T} T{ +.PN CWBorderWidth +T} T{ +(1<<4) +T} +T{ +#define +T} T{ +.PN CWSibling +T} T{ +(1<<5) +T} +T{ +#define +T} T{ +.PN CWStackMode +T} T{ +(1<<6) +T} +.TE +.IN "XWindowChanges" "" "@DEF@" +.Ds 0 +.TA .5i 3i +.ta .5i 3i +/* Values */ + +typedef struct { + int x, y; + int width, height; + int border_width; + Window sibling; + int stack_mode; +} XWindowChanges; +.De +.LP +.eM +The x and y members are used to set the window's x and y coordinates, +which are relative to the parent's origin +and indicate the position of the upper-left outer corner of the window. +The width and height members are used to set the inside size of the window, +not including the border, and must be nonzero, or a +.PN BadValue +error results. +Attempts to configure a root window have no effect. +.LP +The border_width member is used to set the width of the border in pixels. +Note that setting just the border width leaves the outer-left corner of the window +in a fixed position but moves the absolute position of the window's origin. +If you attempt to set the border-width attribute of an +.PN InputOnly +window nonzero, a +.PN BadMatch +error results. +.LP +The sibling member is used to set the sibling window for stacking operations. +The stack_mode member is used to set how the window is to be restacked +and can be set to +.PN Above , +.PN Below , +.PN TopIf , +.PN BottomIf , +or +.PN Opposite . +.LP +If the override-redirect flag of the window is +.PN False +and if some other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no further processing is performed. +Otherwise, +if some other client has selected +.PN ResizeRedirectMask +on the window and the inside +width or height of the window is being changed, +a +.PN ResizeRequest +event is generated, and the current inside width and height are +used instead. +Note that the override-redirect flag of the window has no effect +on +.PN ResizeRedirectMask +and that +.PN SubstructureRedirectMask +on the parent has precedence over +.PN ResizeRedirectMask +on the window. +.LP +When the geometry of the window is changed as specified, +the window is restacked among siblings, and a +.PN ConfigureNotify +event is generated if the state of the window actually changes. +.PN GravityNotify +events are generated after +.PN ConfigureNotify +events. +If the inside width or height of the window has actually changed, +children of the window are affected as specified. +.LP +If a window's size actually changes, +the window's subwindows move according to their window gravity. +Depending on the window's bit gravity, +the contents of the window also may be moved (see section 3.2.3). +.LP +If regions of the window were obscured but now are not, +exposure processing is performed on these formerly obscured windows, +including the window itself and its inferiors. +As a result of increasing the width or height, +exposure processing is also performed on any new regions of the window +and any regions where window contents are lost. +.LP +The restack check (specifically, the computation for +.PN BottomIf , +.PN TopIf , +and +.PN Opposite ) +is performed with respect to the window's final size and position (as +controlled by the other arguments of the request), not its initial position. +If a sibling is specified without a stack_mode, +a +.PN BadMatch +error results. +.LP +If a sibling and a stack_mode are specified, +the window is restacked as follows: +.TS +lw(1i) lw(5i). +T{ +.PN Above +T} T{ +The window is placed just above the sibling. +T} +.sp 6p +T{ +.PN Below +T} T{ +The window is placed just below the sibling. +T} +.sp 6p +T{ +.PN TopIf +T} T{ +If the sibling occludes the window, the window is placed +at the top of the stack. +T} +.sp 6p +T{ +.PN BottomIf +T} T{ +If the window occludes the sibling, the window is +placed at the bottom of the stack. +T} +.sp 6p +T{ +.PN Opposite +T} T{ +If the sibling occludes the window, the window +is placed at the top of the stack. +If the window occludes the sibling, +the window is placed at the bottom of the stack. +T} +.TE +.LP +If a stack_mode is specified but no sibling is specified, +the window is restacked as follows: +.TS +lw(1i) lw(5i). +T{ +.PN Above +T} T{ +The window is placed at the top of the stack. +T} +.sp 6p +T{ +.PN Below +T} T{ +The window is placed at the bottom of the stack. +T} +.sp 6p +T{ +.PN TopIf +T} T{ +If any sibling occludes the window, the window is placed at +the top of the stack. +T} +.sp 6p +T{ +.PN BottomIf +T} T{ +If the window occludes any sibling, the window is placed at +the bottom of the stack. +T} +.sp 6p +T{ +.PN Opposite +T} T{ +If any sibling occludes the window, the window +is placed at the top of the stack. +If the window occludes any sibling, +the window is placed at the bottom of the stack. +T} +.TE +.LP +Attempts to configure a root window have no effect. +.LP +.sp +To configure a window's size, location, stacking, or border, use +.PN XConfigureWindow . +.IN "XConfigureWindow" "" "@DEF@" +.sM +.FD 0 +XConfigureWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvalue_mask\fP\^, \fIvalues\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned int \fIvalue_mask\fP\^; +.br + XWindowChanges *\fIvalues\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi to be reconfigured +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.IP \fIvalue_mask\fP 1i +Specifies which values are to be set using information in +the values structure. +This mask is the bitwise inclusive OR of the valid configure window values bits. +.IP \fIvalues\fP 1i +Specifies the +.PN XWindowChanges +structure. +.LP +.eM +The +.PN XConfigureWindow +function uses the values specified in the +.PN XWindowChanges +structure to reconfigure a window's size, position, border, and stacking order. +Values not specified are taken from the existing geometry of the window. +.LP +If a sibling is specified without a stack_mode or if the window +is not actually a sibling, +a +.PN BadMatch +error results. +Note that the computations for +.PN BottomIf , +.PN TopIf , +and +.PN Opposite +are performed with respect to the window's final geometry (as controlled by the +other arguments passed to +.PN XConfigureWindow ), +not its initial geometry. +Any backing store contents of the window, its +inferiors, and other newly visible windows are either discarded or +changed to reflect the current screen contents +(depending on the implementation). +.LP +.PN XConfigureWindow +can generate +.PN BadMatch , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To move a window without changing its size, use +.PN XMoveWindow . +.IN "XMoveWindow" "" "@DEF@" +.sM +.FD 0 +XMoveWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi to be moved +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.ds Xy , which define the new location of the top-left pixel \ +of the window's border or the window itself if it has no border +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.LP +.eM +The +.PN XMoveWindow +function moves the specified window to the specified x and y coordinates, +but it does not change the window's size, raise the window, or +change the mapping state of the window. +Moving a mapped window may or may not lose the window's contents +depending on if the window is obscured by nonchildren +and if no backing store exists. +If the contents of the window are lost, +the X server generates +.PN Expose +events. +Moving a mapped window generates +.PN Expose +events on any formerly obscured windows. +.LP +If the override-redirect flag of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no further processing is +performed. +Otherwise, the window is moved. +.LP +.PN XMoveWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To change a window's size without changing the upper-left coordinate, use +.PN XResizeWindow . +.IN "XResizeWindow" "" "@DEF@" +.sM +.FD 0 +XResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwidth\fP\^, \fIheight\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.ds Wh , which are the interior dimensions of the window \ +after the call completes +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.LP +.eM +The +.PN XResizeWindow +function changes the inside dimensions of the specified window, not including +its borders. +This function does not change the window's upper-left coordinate or +the origin and does not restack the window. +Changing the size of a mapped window may lose its contents and generate +.PN Expose +events. +If a mapped window is made smaller, +changing its size generates +.PN Expose +events on windows that the mapped window formerly obscured. +.LP +If the override-redirect flag of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no further processing is performed. +If either width or height is zero, +a +.PN BadValue +error results. +.LP +.PN XResizeWindow +can generate +.PN BadValue +and +.PN BadWindow +errors. +.LP +.sp +To change the size and location of a window, use +.PN XMoveResizeWindow . +.IN "XMoveResizeWindow" "" "@DEF@" +.sM +.FD 0 +XMoveResizeWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIx\fP\^, \fIy\fP\^, \fIwidth\fP\^, \fIheight\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIx\fP\^, \fIy\fP\^; +.br + unsigned int \fIwidth\fP\^, \fIheight\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.ds Wi to be reconfigured +.IP \fIw\fP 1i +Specifies the window \*(Wi. +.ds Xy , which define the new position of the window relative to its parent +.IP \fIx\fP 1i +.br +.ns +.IP \fIy\fP 1i +Specify the x and y coordinates\*(Xy. +.ds Wh , which define the interior size of the window +.IP \fIwidth\fP 1i +.br +.ns +.IP \fIheight\fP 1i +Specify the width and height\*(Wh. +.LP +.eM +The +.PN XMoveResizeWindow +function changes the size and location of the specified window +without raising it. +Moving and resizing a mapped window may generate an +.PN Expose +event on the window. +Depending on the new size and location parameters, +moving and resizing a window may generate +.PN Expose +events on windows that the window formerly obscured. +.LP +If the override-redirect flag of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no further processing is performed. +Otherwise, the window size and location are changed. +.LP +.PN XMoveResizeWindow +can generate +.PN BadValue +and +.PN BadWindow +errors. +.LP +.sp +To change the border width of a given window, use +.PN XSetWindowBorderWidth . +.IN "XSetWindowBorderWidth" "" "@DEF@" +.sM +.FD 0 +XSetWindowBorderWidth\^(\^\fIdisplay\fP, \fIw\fP, \fIwidth\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned int \fIwidth\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIwidth\fP 1i +Specifies the width of the window border. +.LP +.eM +The +.PN XSetWindowBorderWidth +function sets the specified window's border width to the specified width. +.LP +.PN XSetWindowBorderWidth +can generate a +.PN BadWindow +error. +.NH 2 +Changing Window Stacking Order +.XS +\*(SN Changing Window Stacking Order +.XE +.LP +.LP +Xlib provides functions that you can use to raise, lower, circulate, +or restack windows. +.LP +.sp +To raise a window so that no sibling window obscures it, use +.PN XRaiseWindow . +.IN "XRaiseWindow" "" "@DEF@" +.sM +.FD 0 +XRaiseWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XRaiseWindow +function +raises the specified window to the top of the stack so that no sibling window +obscures it. +If the windows are regarded as overlapping sheets of paper stacked +on a desk, +then raising a window is analogous to moving the sheet to the top of +the stack but leaving its x and y location on the desk constant. +Raising a mapped window may generate +.PN Expose +events for the window and any mapped subwindows that were formerly obscured. +.LP +If the override-redirect attribute of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no processing is performed. +Otherwise, the window is raised. +.LP +.PN XRaiseWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To lower a window so that it does not obscure any sibling windows, use +.PN XLowerWindow . +.IN "XLowerWindow" "" "@DEF@" +.sM +.FD 0 +XLowerWindow\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XLowerWindow +function lowers the specified window to the bottom of the stack +so that it does not obscure any sibling +windows. +If the windows are regarded as overlapping sheets of paper +stacked on a desk, then lowering a window is analogous to moving the +sheet to the bottom of the stack but leaving its x and y location on +the desk constant. +Lowering a mapped window will generate +.PN Expose +events on any windows it formerly obscured. +.LP +If the override-redirect attribute of the window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates a +.PN ConfigureRequest +event, and no processing is performed. +Otherwise, the window is lowered to the bottom of the +stack. +.LP +.PN XLowerWindow +can generate a +.PN BadWindow +error. +.LP +.sp +To circulate a subwindow up or down, use +.PN XCirculateSubwindows . +.IN "XCirculateSubwindows" "" "@DEF@" +.sM +.FD 0 +XCirculateSubwindows\^(\^\fIdisplay\fP, \fIw\fP\^, \fIdirection\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + int \fIdirection\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIdirection\fP 1i +Specifies the direction (up or down) that you want to circulate +the window. +You can pass +.PN RaiseLowest +or +.PN LowerHighest . +.LP +.eM +The +.PN XCirculateSubwindows +function circulates children of the specified window in the specified +direction. +If you specify +.PN RaiseLowest , +.PN XCirculateSubwindows +raises the lowest mapped child (if any) that is occluded +by another child to the top of the stack. +If you specify +.PN LowerHighest , +.PN XCirculateSubwindows +lowers the highest mapped child (if any) that occludes another child +to the bottom of the stack. +Exposure processing is then performed on formerly obscured windows. +If some other client has selected +.PN SubstructureRedirectMask +on the window, the X server generates a +.PN CirculateRequest +event, and no further processing is performed. +If a child is actually restacked, +the X server generates a +.PN CirculateNotify +event. +.LP +.PN XCirculateSubwindows +can generate +.PN BadValue +and +.PN BadWindow +errors. +.LP +.sp +To raise the lowest mapped child of a window that is partially or completely +occluded by another child, use +.PN XCirculateSubwindowsUp . +.IN "XCirculateSubwindowsUp" "" "@DEF@" +.sM +.FD 0 +XCirculateSubwindowsUp\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XCirculateSubwindowsUp +function raises the lowest mapped child of the specified window that +is partially +or completely +occluded by another child. +Completely unobscured children are not affected. +This is a convenience function equivalent to +.PN XCirculateSubwindows +with +.PN RaiseLowest +specified. +.LP +.PN XCirculateSubwindowsUp +can generate a +.PN BadWindow +error. +.LP +.sp +To lower the highest mapped child of a window that partially or +completely occludes another child, use +.PN XCirculateSubwindowsDown . +.IN "XCirculateSubwindowsDown" "" "@DEF@" +.sM +.FD 0 +XCirculateSubwindowsDown\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XCirculateSubwindowsDown +function lowers the highest mapped child of the specified window that partially +or completely occludes another child. +Completely unobscured children are not affected. +This is a convenience function equivalent to +.PN XCirculateSubwindows +with +.PN LowerHighest +specified. +.LP +.PN XCirculateSubwindowsDown +can generate a +.PN BadWindow +error. +.LP +.sp +To restack a set of windows from top to bottom, use +.PN XRestackWindows . +.IN "XRestackWindows" "" "@DEF@" +.sM +.FD 0 +XRestackWindows\^(\^\fIdisplay\fP, \fIwindows\fP\^, \^\fInwindows\fP\^); +.br + Display *\fIdisplay\fP\^; +.br + Window \fIwindows\fP\^[]; +.br + int \fInwindows\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIwindows\fP 1i +Specifies an array containing the windows to be restacked. +.IP \fInwindows\fP 1i +Specifies the number of windows to be restacked. +.LP +.eM +The +.PN XRestackWindows +function restacks the windows in the order specified, +from top to bottom. +The stacking order of the first window in the windows array is unaffected, +but the other windows in the array are stacked underneath the first window, +in the order of the array. +The stacking order of the other windows is not affected. +For each window in the window array that is not a child of the specified window, +a +.PN BadMatch +error results. +.LP +If the override-redirect attribute of a window is +.PN False +and some +other client has selected +.PN SubstructureRedirectMask +on the parent, the X server generates +.PN ConfigureRequest +events for each window whose override-redirect flag is not set, +and no further processing is performed. +Otherwise, the windows will be restacked in top-to-bottom order. +.LP +.PN XRestackWindows +can generate a +.PN BadWindow +error. +.NH 2 +Changing Window Attributes +.XS +\*(SN Changing Window Attributes +.XE +.LP +.LP +Xlib provides functions that you can use to set window attributes. +.PN XChangeWindowAttributes +is the more general function that allows you to set one or more window +attributes provided by the +.PN XSetWindowAttributes +structure. +The other functions described in this section allow you to set one specific +window attribute, such as a window's background. +.LP +.sp +To change one or more attributes for a given window, use +.PN XChangeWindowAttributes . +.IN "XChangeWindowAttributes" "" "@DEF@" +.sM +.FD 0 +XChangeWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIvaluemask\fP\^, \fIattributes\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned long \fIvaluemask\fP\^; +.br + XSetWindowAttributes *\fIattributes\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIvaluemask\fP 1i +Specifies which window attributes are defined in the attributes +argument. +This mask is the bitwise inclusive OR of the valid attribute mask bits. +If valuemask is zero, +the attributes are ignored and are not referenced. +The values and restrictions are +the same as for +.PN XCreateWindow . +.IP +.IP \fIattributes\fP 1i +Specifies the structure from which the values (as specified by the value mask) +are to be taken. +The value mask should have the appropriate bits +set to indicate which attributes have been set in the structure +(see section 3.2). +.LP +.eM +Depending on the valuemask, +the +.PN XChangeWindowAttributes +function uses the window attributes in the +.PN XSetWindowAttributes +structure to change the specified window attributes. +Changing the background does not cause the window contents to be +changed. +To repaint the window and its background, use +.PN XClearWindow . +Setting the border or changing the background such that the +border tile origin changes causes the border to be repainted. +Changing the background of a root window to +.PN None +or +.PN ParentRelative +restores the default background pixmap. +Changing the border of a root window to +.PN CopyFromParent +restores the default border pixmap. +Changing the win-gravity does not affect the current position of the +window. +Changing the backing-store of an obscured window to +.PN WhenMapped +or +.PN Always , +or changing the backing-planes, backing-pixel, or +save-under of a mapped window may have no immediate effect. +Changing the colormap of a window (that is, defining a new map, not +changing the contents of the existing map) generates a +.PN ColormapNotify +event. +Changing the colormap of a visible window may have no +immediate effect on the screen because the map may not be installed +(see +.PN XInstallColormap ). +Changing the cursor of a root window to +.PN None +restores the default +cursor. +Whenever possible, you are encouraged to share colormaps. +.LP +Multiple clients can select input on the same window. +Their event masks are maintained separately. +When an event is generated, +it is reported to all interested clients. +However, only one client at a time can select for +.PN SubstructureRedirectMask , +.PN ResizeRedirectMask , +and +.PN ButtonPressMask . +If a client attempts to select any of these event masks +and some other client has already selected one, +a +.PN BadAccess +error results. +There is only one do-not-propagate-mask for a window, +not one per client. +.LP +.PN XChangeWindowAttributes +can generate +.PN BadAccess , +.PN BadColor , +.PN BadCursor , +.PN BadMatch , +.PN BadPixmap , +.PN BadValue , +and +.PN BadWindow +errors. +.LP +.sp +To set the background of a window to a given pixel, use +.PN XSetWindowBackground . +.IN "XSetWindowBackground" "" "@DEF@" +.sM +.FD 0 +XSetWindowBackground\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixel\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned long \fIbackground_pixel\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIbackground_pixel\fP 1i +Specifies the pixel that is to be used for the background. +.LP +.eM +The +.PN XSetWindowBackground +function sets the background of the window to the specified pixel value. +Changing the background does not cause the window contents to be changed. +.PN XSetWindowBackground +uses a pixmap of undefined size filled with the pixel value you passed. +If you try to change the background of an +.PN InputOnly +window, a +.PN BadMatch +error results. +.LP +.PN XSetWindowBackground +can generate +.PN BadMatch +and +.PN BadWindow +errors. +.LP +.sp +.LP +To set the background of a window to a given pixmap, use +.PN XSetWindowBackgroundPixmap . +.IN "Window" "background" +.IN "XSetWindowBackgroundPixmap" "" "@DEF@" +.sM +.FD 0 +XSetWindowBackgroundPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIbackground_pixmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Pixmap \fIbackground_pixmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIbackground_pixmap\fP 1i +Specifies the background pixmap, +.PN ParentRelative , +or +.PN None . +.LP +.eM +.IN "Resource IDs" "freeing" +.IN "Freeing" "resources" +The +.PN XSetWindowBackgroundPixmap +function sets the background pixmap of the window to the specified pixmap. +The background pixmap can immediately be freed if no further explicit +references to it are to be made. +If +.PN ParentRelative +is specified, +the background pixmap of the window's parent is used, +or on the root window, the default background is restored. +If you try to change the background of an +.PN InputOnly +window, a +.PN BadMatch +error results. +If the background is set to +.PN None , +the window has no defined background. +.LP +.PN XSetWindowBackgroundPixmap +can generate +.PN BadMatch , +.PN BadPixmap , +and +.PN BadWindow +errors. +.NT Note +.PN XSetWindowBackground +and +.PN XSetWindowBackgroundPixmap +do not change the current contents of the window. +.NE +.LP +.sp +To change and repaint a window's border to a given pixel, use +.PN XSetWindowBorder . +.IN "XSetWindowBorder" "" "@DEF@" +.sM +.FD 0 +XSetWindowBorder\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixel\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + unsigned long \fIborder_pixel\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIborder_pixel\fP 1i +Specifies the entry in the colormap. +.LP +.eM +The +.PN XSetWindowBorder +function sets the border of the window to the pixel value you specify. +If you attempt to perform this on an +.PN InputOnly +window, a +.PN BadMatch +error results. +.LP +.PN XSetWindowBorder +can generate +.PN BadMatch +and +.PN BadWindow +errors. +.LP +.sp +To change and repaint the border tile of a given window, use +.PN XSetWindowBorderPixmap . +.IN "XSetWindowBorderPixmap" "" "@DEF@" +.sM +.FD 0 +XSetWindowBorderPixmap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIborder_pixmap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Pixmap \fIborder_pixmap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIborder_pixmap\fP 1i +Specifies the border pixmap or +.PN CopyFromParent . +.LP +.eM +The +.PN XSetWindowBorderPixmap +function sets the border pixmap of the window to the pixmap you specify. +The border pixmap can be freed immediately if no further explicit +references to it are to be made. +If you specify +.PN CopyFromParent , +a copy of the parent window's border pixmap is used. +If you attempt to perform this on an +.PN InputOnly +window, a +.PN BadMatch +error results. +.IN "Resource IDs" "freeing" +.IN "Freeing" "resources" +.LP +.PN XSetWindowBorderPixmap +can generate +.PN BadMatch , +.PN BadPixmap , +and +.PN BadWindow +errors. +.LP +.sp +To set the colormap of a given window, use +.PN XSetWindowColormap . +.IN "XSetWindowColormap" "" "@DEF@" +.sM +.FD 0 +XSetWindowColormap\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcolormap\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Colormap \fIcolormap\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIcolormap\fP 1i +Specifies the colormap. +.LP +.eM +The +.PN XSetWindowColormap +function sets the specified colormap of the specified window. +The colormap must have the same visual type as the window, +or a +.PN BadMatch +error results. +.LP +.PN XSetWindowColormap +can generate +.PN BadColor , +.PN BadMatch , +and +.PN BadWindow +errors. +.LP +.sp +To define which cursor will be used in a window, use +.PN XDefineCursor . +.IN "Window" "defining the cursor" +.IN "XDefineCursor" "" "@DEF@" +.sM +.FD 0 +XDefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^, \fIcursor\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.br + Cursor \fIcursor\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.IP \fIcursor\fP 1i +Specifies the cursor that is to be displayed or +.PN None . +.LP +.eM +If a cursor is set, it will be used when the pointer is in the window. +If the cursor is +.PN None , +it is equivalent to +.PN XUndefineCursor . +.LP +.PN XDefineCursor +can generate +.PN BadCursor +and +.PN BadWindow +errors. +.LP +.sp +To undefine the cursor in a given window, use +.PN XUndefineCursor . +.IN "Window" "undefining the cursor" +.IN "XUndefineCursor" "" "@DEF@" +.sM +.FD 0 +XUndefineCursor\^(\^\fIdisplay\fP, \fIw\fP\^) +.br + Display *\fIdisplay\fP\^; +.br + Window \fIw\fP\^; +.FN +.IP \fIdisplay\fP 1i +Specifies the connection to the X server. +.IP \fIw\fP 1i +Specifies the window. +.LP +.eM +The +.PN XUndefineCursor +function undoes the effect of a previous +.PN XDefineCursor +for this window. +When the pointer is in the window, +the parent's cursor will now be used. +On the root window, +the default cursor is restored. +.LP +.PN XUndefineCursor +can generate a +.PN BadWindow +error. +.bp |