diff options
Diffstat (limited to 'libX11/specs/libX11/CH03')
| -rw-r--r-- | libX11/specs/libX11/CH03 | 3121 |
1 files changed, 0 insertions, 3121 deletions
diff --git a/libX11/specs/libX11/CH03 b/libX11/specs/libX11/CH03 deleted file mode 100644 index f7eb2d4c0..000000000 --- a/libX11/specs/libX11/CH03 +++ /dev/null @@ -1,3121 +0,0 @@ -.\" 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 |