diff options
Diffstat (limited to 'Xlibscm.texi')
| -rw-r--r-- | Xlibscm.texi | 1955 |
1 files changed, 1955 insertions, 0 deletions
diff --git a/Xlibscm.texi b/Xlibscm.texi new file mode 100644 index 0000000..59e6c3c --- /dev/null +++ b/Xlibscm.texi @@ -0,0 +1,1955 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename Xlibscm.info +@settitle Xlibscm +@include version.txi +@setchapternewpage on +@c Choices for setchapternewpage are {on,off,odd}. +@paragraphindent 0 +@defcodeindex ft +@syncodeindex ft cp +@c %**end of header + +@dircategory The Algorithmic Language Scheme +@direntry +* Xlibscm: (Xlibscm). SCM Language X Interface. +@end direntry + +@iftex +@finalout +@c DL: lose the egregious vertical whitespace, esp. around examples +@c but paras in @defun-like things don't have parindent +@parskip 4pt plus 1pt +@end iftex + +@titlepage +@title Xlibscm +@subtitle SCM Language X Interface +@subtitle Version @value{SCMVERSION} +@author by Aubrey Jaffer + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1990-1999 Free Software Foundation + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the author. +@end titlepage + +@node Top, Xlibscm, (dir), (dir) + + +@ifinfo +This manual documents the X - SCM Language X Interface. The most recent +information about SCM can be found on SCM's @dfn{WWW} home page: + +@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html} + + +Copyright (C) 1990-1999 Free Software Foundation + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the author. +@end ifinfo + +@menu +* Xlibscm:: +* Display:: +* Screen:: +* Window:: +* Window Visibility:: +* Graphics Context:: +* Cursor:: +* Colormap:: +* Rendering:: +* Event:: +* Index:: +@end menu + +@node Xlibscm, Display, Top, Top +@chapter Xlibscm + +@dfn{Xlibscm} is a SCM interface to @dfn{X}. +@cindex X +The +@ifset html +<A HREF="http://www.x.org/"> +@end ifset +X Window System +@ifset html +</A> +@end ifset +is a network-transparent window system that was +designed at MIT. +@ifset html +<A HREF="scm_toc.html"> +@end ifset +SCM +@ifset html +</A> +@end ifset +is a portable Scheme implementation written in C. +The interface can be compiled into SCM or, on those platforms supporting +dynamic linking, compiled separately and loaded with @code{(require +'Xlib)}. +@ftindex Xlib + +@iftex +@noindent +The most recent information about SCM can be found on SCM's @dfn{WWW} +home page: +@center @url{http://swissnet.ai.mit.edu/~jaffer/SCM.html} +@end iftex + +Much of this X documentation is dervied from: + +@center Xlib - C Language X Interface +@center X Consortium Standard +@center X Version 11, Release 6.3 + +The X Window System is a trademark of X Consortium, Inc. + +TekHVC is a trademark of Tektronix, Inc. + + + +Copyright (C) 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 (C) 1985, 1986, 1987, 1988, 1989, 1990, 1991 by +Digital Equipment Corporation + +Portions Copyright (C) 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. + + +@node Display, Screen, Xlibscm, Top +@chapter Display + +@defun x:open-display display-name +@var{display-name} Specifies the hardware display name, which determines +the display and communications domain to be used. On a POSIX-conformant +system, if the display-name is #f, it defaults to the value of the +@var{DISPLAY} environment variable. + +The encoding and interpretation of @var{display-name} is +implementation-dependent. On POSIX-conformant systems, the +@var{display-name} or @var{DISPLAY} environment variable can be a string +in the format: + +@defspec hostname:number.screen-number + +@var{hostname} specifies the name of the host machine on which the +display is physically attached. Follow the @var{hostname} with either a +single colon (:) or a double colon (::). + +@var{number} specifies the number of the display server on that host +machine. You may optionally follow this display number with a period +(.). A single CPU can have more than one display. Multiple displays +are usually numbered starting with zero. + +@var{screen-number} specifies the screen to be used on that server. +Multiple screens can be controlled by a single X server. The +@var{screen-number} sets an internal variable that can be accessed by +using the x:default-screen procedure. +@end defspec +@end defun + +@defun x:close display +@var{display} specifies the connection to the X server. + +The @code{x:close} function closes the connection to the X server for +the @var{display} specified and destroys all windows, resource IDs +(Window, Font, Pixmap, Colormap, Cursor, and GContext), or other +resources that the client has created on this display, unless the +close-down mode of the resource has been changed (see +@code{x:set-close-down-mode}). Therefore, these windows, resource IDs, +and other resources should not be used again or an error will be +generated. Before exiting, you should call @var{x:close-display} or +@var{x:flush} explicitly so that any pending errors are reported. +@end defun + +@defun x:protocol-version display +Returns cons of the major version number (11) of the X protocol +associated with the connected @var{display} and the minor protocol +revision number of the X server. +@end defun + +@defun x:server-vendor display +Returns a string that provides some identification of the owner of the X +server implementation. The contents of the string are +implementation-dependent. +@end defun + +@defun x:vendor-release display +Returns a number related to a vendor's release of the X server. +@end defun + + +@node Screen, Window, Display, Top +@chapter Screen + +A display consists of one or more @dfn{Screen}s. Each screen has a +@dfn{root-window}, @dfn{default-graphics-context}, @dfn{default-visual}, +and @dfn{colormap}. + +@defun x:screen-count display +Returns the number of available screens. +@end defun + +@defun x:default-screen display +Returns the default screen number specified by the @code{x:open-display} +function. Use this screen number in applications which will use only a +single screen. +@end defun + +@defun x:root-window display screen-number +@defunx x:root-window display +@var{screen-number}, if givien, specifies the appropriate screen number +on the host server. Otherwise the default-screen for @var{display} is +used. + +Returns the root window for the specified @var{screen-number}. Use +@code{x:root-window} for functions that need a drawable of a particular +screen or for creating top-level windows. + +@defunx x:root-window window +Returns the root window for the specified @var{window}'s screen. +@end defun + +@defun x:default-colormap display screen-number +@defunx x:default-colormap display +@defunx x:default-colormap window +Returns the default colormap of the specified screen. +@end defun + +@defun x:default-gc display screen-number +@defunx x:default-gc display +@defunx x:default-gc window +Returns the default graphics-context of the specified screen. +@end defun + +@defun x:default-depths display screen-number +@defunx x:default-depths display +@defunx x:default-depths window +Returns a vector of depths supported by the specified screen. +@end defun + +The @dfn{Visual} type describes possible colormap depths and +arrangements. + +@defun x:default-visual display screen-number +@defunx x:default-visual display +@defunx x:default-visual window +Returns the default Visual type for the specified screen. + +@cindex visual +@cindex Visual +@end defun + +@defun x:make-visual display depth class +@defunx x:make-visual window depth class + +The integer @var{depth} specifies the number of bits per pixel. +The @var{class} argument specifies one of the possible +visual classes for a screen: +@itemize @bullet +@item x:Static-Gray +@item x:Static-Color +@item x:True-Color +@item x:Gray-Scale +@item x:Pseudo-Color +@item x:Direct-Color +@end itemize + +@code{X:make-visual} returns a visual type for the screen specified by +@var{display} or @var{window} if successful; #f if not. + +@end defun + +@defun x:screen-cells display screen-number +@defunx x:screen-cells display +@defunx x:screen-cells window +Returns the number of entries in the default colormap. +@end defun + +@defun x:screen-depth display screen-number +@defunx x:screen-depth display +@defunx x:screen-depth window +Returns the depth of the root window of the specified screen. + +@cindex depth +The @dfn{depth} of a window or pixmap is the number of bits per pixel it has. +The @dfn{depth} of a graphics context is the depth of the drawables it can be +used in conjunction with graphics output. +@end defun + +@defun x:screen-size display screen-number +@defunx x:screen-size display +@defunx x:screen-size window +Returns a list of integer height and width of the screen in pixels. +@end defun + +@defun x:screen-dimensions display screen-number +@defunx x:screen-dimensions display +@defunx x:screen-dimensions window +Returns a list of integer height and width of the screen in millimeters. +@end defun + +@defun x:screen-white display screen-number +@defunx x:screen-white display +@defunx x:screen-white window +Returns the white pixel value of the specified screen. +@end defun + +@defun x:screen-black display screen-number +@defunx x:screen-black display +@defunx x:screen-black window +Returns the black pixel value of the specified screen. +@end defun + + +@node Window, Window Visibility, Screen, Top +@chapter Window + +@cindex Drawable +@cindex drawable +A @dfn{Drawable} is either a window or pixmap. + +@defun x:create-window window position size border-width depth class visual field-name value @dots{} +Creates and returns an unmapped Input-Output subwindow for a specified +parent @var{window} and causes the X server to generate a 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 @var{window} is clipped. The @var{border-width} for an +x:Input-Only window must be zero. + +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. + +@var{Class} can be x:Input-Output, x:Input-Only, or x:Copy-From-Parent. +For class x:Input-Output, the @var{visual} type and @var{depth} must be +a combination supported for the screen. The @var{depth} need not be the +same as the parent, but the parent must not be a window of class +x:Input-Only. For an x:Input-Only window, the @var{depth} must be zero, +and the @var{visual} must be one supported by the screen. + +The returned window will have the attributes specified by +@var{field-name}s and @var{value}. + +@defunx x:create-window window position size border-width border background +The returned window inherits its depth, class, and visual from its +parent. All other window attributes, except @var{background} and +@var{border}, have their default values. +@end defun + +@defun x:create-pixmap drawable size depth +@defunx x:create-pixmap display size depth + +@var{size} is a list, vector, or pair of nonzero integers specifying the width +and height desired in the new pixmap. + +@var{x:create-pixmap} returns a new pixmap of the width, height, and +@var{depth} specified. It is valid to pass an x:Input-Only window to the +drawable argument. The @var{depth} argument must be one of the depths +supported by the screen of the specified @var{drawable}. +@end defun + +@defun x:close window +Destroys the specified @var{window} as well as all of its subwindows and +causes the X server to generate a DestroyNotify event for each window. +The window should not be used again. If the window specified by the +@var{window} argument is mapped, it is unmapped automatically. The +ordering of the DestroyNotify events is such that for any given window +being destroyed, 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 +@var{window} you specified is a root window, an error is signaled. +Destroying a mapped @var{window} will generate x:Expose events on other +windows that were obscured by the window being destroyed. +@end defun + +@defun x:close pixmap +Deletes the association between the @var{pixmap} and its storage. The X +server frees the pixmap storage when there are no references to it. +@end defun + +@defun x:window-geometry drawable +Returns a list of: + +@table @asis +@item coordinates +@code{cons} of x and y coordinates that define the location of the +@var{drawable}. For a window, these coordinates specify the upper-left +outer corner relative to its parent's origin. For pixmaps, these +coordinates are always zero. +@item size +@code{cons} of the @var{drawable}'s dimensions (width and height). For +a window, these dimensions specify the inside size, not including the +border. +@item border-width +The border width in pixels. If the @var{drawable} is a pixmap, this is +zero. +@item depth +The depth of the @var{drawable} (bits per pixel for the object). +@end table +@end defun + +@defun x:window-set! window field-name value @dots{} +Changes the components specified by @var{field-name}s for the specified +@var{window}. The restrictions are the same as for +@code{x:create-window}. The order in which components are verified and +altered is server dependent. If an error occurs, a subset of the +components may have been altered. +@end defun + +@heading Window Attributes + +@noindent +The @code{x:create-window} and @code{x:window-set!} procedures take five +and one argument (respectively) followed by pairs of arguments, where +the first is one of the property-name symbols (or its top-level value) +listed below; and the second is the value to associate with that +property. + +@defvr Attribute x:CW-Back-Pixmap +Sets the background pixmap of the @var{window} to the specified pixmap. +The background pixmap can immediately be freed if no further explicit +references to it are to be made. If x:Parent-Relative is specified, the +background pixmap of the window's parent is used, or on the root window, +the default background is restored. It is an error to perform this +operation on an x:Input-Only window. If the background is set to #f or +None, the window has no defined background. +@end defvr + +@defvr Attribute x:CW-Back-Pixel +Sets the background of the @var{window} to the specified pixel value. +Changing the background does not cause the @var{window} contents to be +changed. It is an error to perform this operation on an x:Input-Only +window. +@end defvr + +@defvr Attribute x:CW-Border-Pixmap +Sets the border pixmap of the @var{window} to the pixmap you specify. +The border pixmap can be freed if no further explicit references to it +are to be made. If you specify x:Copy-From-Parent, a copy of the parent +window's border pixmap is used. It is an error to perform this +operation on an x:Input-Only @var{window}. +@end defvr + +@defvr Attribute x:CW-Border-Pixel +Sets the border of the @var{window} to the pixel @var{value}. It is an +error to perform this operation on an x:Input-Only window. +@end defvr + +@defvr Attribute x:CW-Bit-Gravity +@defvrx Attribute x:CW-Win-Gravity +The bit gravity of a window defines which region of the window should be +retained when an x:Input-Output window is resized. The default value +for the bit-gravity attribute is x:Forget-Gravity. The window gravity +of a window allows you to define how the x:Input-Output or x:Input-Only +window should be repositioned if its parent is resized. The default +value for the win-gravity attribute is x:North-West-Gravity. + +If the inside width or height of a window is not changed and if the +window is moved or its border is changed, then the contents of the +window are not lost but move with the window. Changing the inside width +or height of the window causes its contents to be moved or lost +(depending on the bit-gravity of the window) and causes children to be +reconfigured (depending on their win-gravity). For a change of width +and height, the (x, y) pairs are defined: + +@multitable @columnfractions .5 .5 +@item Gravity Direction +@tab Coordinates +@item x:North-West-Gravity +@tab (0, 0) +@item x:North-Gravity +@tab (Width/2, 0) +@item x:North-East-Gravity +@tab (Width, 0) +@item x:West-Gravity +@tab (0, Height/2) +@item x:Center-Gravity +@tab (Width/2, Height/2) +@item x:East-Gravity +@tab (Width, Height/2) +@item x:South-West-Gravity +@tab (0, Height) +@item x:South-Gravity +@tab (Width/2, Height) +@item x:South-East-Gravity +@tab (Width, Height) +@end multitable + +When a window with one of these bit-gravity values is resized, the +corresponding pair defines the change in position of each pixel in the +window. When a window with one of these win-gravities has its parent +window resized, the corresponding pair defines the change in position of +the window within the parent. When a window is so repositioned, a +x:Gravity-Notify event is generated (see section 10.10.5). + +A bit-gravity of x:Static-Gravity indicates that the contents or origin +should not move relative to the origin of the root window. If the +change in size of the window is coupled with a change in position (x, +y), then for bit-gravity the change in position of each pixel is (-x, +-y), and for win-gravity the change in position of a child when its +parent is so resized is (-x, -y). Note that x:Static-Gravity still only +takes effect when the width or height of the window is changed, not when +the window is moved. + +A bit-gravity of x:Forget-Gravity indicates that the window's contents +are always discarded after a size change, even if a backing store or +save under has been requested. The window is tiled with its background +and zero or more x:Expose events are generated. If no background is +defined, the existing screen contents are not altered. Some X servers +may also ignore the specified bit-gravity and always generate x:Expose +events. + +The contents and borders of inferiors are not affected by their parent's +bit-gravity. A server is permitted to ignore the specified bit-gravity +and use x:Forget-Gravity instead. + +A win-gravity of x:Unmap-Gravity is like x:North-West-Gravity (the +window is not moved), except the child is also unmapped when the parent +is resized, and an x:Unmap-Notify event is generated. +@end defvr + +@defvr Attribute x:CW-Backing-Store +Some implementations of the X server may choose to maintain the contents +of x:Input-Output windows. If the X server maintains the contents of a +window, the off-screen saved pixels are known as backing store. The +backing store advises the X server on what to do with the contents of a +window. The backing-store attribute can be set to x:Not-Useful +(default), x:When-Mapped, or x:Always. A backing-store attribute of +x:Not-Useful advises the X server that maintaining contents is +unnecessary, although some X implementations may still choose to +maintain contents and, therefore, not generate x:Expose events. A +backing-store attribute of x:When-Mapped advises the X server that +maintaining contents of obscured regions when the window is mapped would +be beneficial. In this case, the server may generate an x:Expose event +when the window is created. A backing-store attribute of x:Always +advises the X server that maintaining contents even when the window is +unmapped would be beneficial. Even if the window is larger than its +parent, this is a request to the X server to maintain complete contents, +not just the region within the parent window boundaries. While the X +server maintains the window's contents, x:Expose events normally are not +generated, but the X server may stop maintaining contents at any time. + +When the contents of obscured regions of a window are being maintained, +regions obscured by noninferior windows are included in the destination +of graphics requests (and source, when the window is the source). +However, regions obscured by inferior windows are not included. +@end defvr + +@defvr Attribute x:CW-Backing-Planes +@defvrx Attribute x:CW-Backing-Pixel +You can set backing planes to indicate (with bits set to 1) which bit +planes of an x:Input-Output window hold dynamic data that must be +preserved in backing store and during save unders. The default value +for the backing-planes attribute is all bits set to 1. You can set +backing pixel to specify what bits to use in planes not covered by +backing planes. The default value for the backing-pixel attribute is +all bits set to 0. The X server is free to save only the specified bit +planes in the backing store or the save under and is free to regenerate +the remaining planes with the specified pixel value. Any extraneous +bits in these values (that is, those bits beyond the specified depth of +the window) may be simply ignored. If you request backing store or save +unders, you should use these members to minimize the amount of +off-screen memory required to store your window. +@end defvr + +@defvr Attribute x:CW-Override-Redirect +To control window placement or to add decoration, a window manager often +needs to intercept (redirect) any map or configure request. Pop-up +windows, however, often need to be mapped without a window manager +getting in the way. To control whether an x:Input-Output or +x:Input-Only window is to ignore these structure control facilities, use +the override-redirect flag. + +The override-redirect flag specifies whether map and configure requests +on this window should override a x:Substructure-Redirect-Mask on the +parent. You can set the override-redirect flag to #t or #f (default). +Window managers use this information to avoid tampering with pop-up +windows. +@end defvr + +@defvr Attribute x:CW-Save-Under +Some server implementations may preserve contents of x:Input-Output windows +under other x:Input-Output windows. This is not the same as preserving the +contents of a window for you. You may get better visual appeal if +transient windows (for example, pop-up menus) request that the system +preserve the screen contents under them, so the temporarily obscured +applications do not have to repaint. + +You can set the save-under flag to True or False (default). If +save-under is True, the X server is advised that, when this window is +mapped, saving the contents of windows it obscures would be beneficial. +@end defvr + +@defvr Attribute x:CW-Event-Mask +The event mask defines which events the client is interested in for this +x:Input-Output or x:Input-Only window (or, for some event types, +inferiors of this window). The event mask is the bitwise inclusive OR +of zero or more of the valid event mask bits. You can specify that no +maskable events are reported by setting x:No-Event-Mask (default). + +The following table lists the event mask constants you can pass to the +event-mask argument and the circumstances in which you would want to +specify the event mask: + +@multitable @columnfractions .45 .55 +@item Event Mask +@tab Circumstances +@item x:No-Event-Mask +@tab No events wanted +@item x:Key-Press-Mask +@tab Keyboard down events wanted +@item x:Key-Release-Mask +@tab Keyboard up events wanted +@item x:Button-Press-Mask +@tab Pointer button down events wanted +@item x:Button-Release-Mask +@tab Pointer button up events wanted +@item x:Enter-Window-Mask +@tab Pointer window entry events wanted +@item x:Leave-Window-Mask +@tab Pointer window leave events wanted +@item x:Pointer-Motion-Mask +@tab Pointer motion events wanted +@item x:Pointer-Motion-Hint-Mask +@tab +If x:Pointer-Motion-Hint-Mask is selected in combination with one or +more motion-masks, the X server is free to send only one x:Motion-Notify +event (with the is_hint member of the X:Pointer-Moved-Event structure +set to x:Notify-Hint) to the client for the event window, until either +the key or button state changes, the pointer leaves the event window, or +the client calls X:Query-Pointer or X:Get-Motion-Events. The server +still may send x:Motion-Notify events without is_hint set to +x:Notify-Hint. +@item x:Button1-Motion-Mask +@tab Pointer motion while button 1 down +@item x:Button2-Motion-Mask +@tab Pointer motion while button 2 down +@item x:Button3-Motion-Mask +@tab Pointer motion while button 3 down +@item x:Button4-Motion-Mask +@tab Pointer motion while button 4 down +@item x:Button5-Motion-Mask +@tab Pointer motion while button 5 down +@item x:Button-Motion-Mask +@tab Pointer motion while any button down +@item x:Keymap-State-Mask +@tab Keyboard state wanted at window entry and focus in +@item x:Exposure-Mask +@tab Any exposure wanted +@item x:Visibility-Change-Mask +@tab Any change in visibility wanted +@item x:Structure-Notify-Mask +@tab Any change in window structure wanted +@item x:Resize-Redirect-Mask +@tab Redirect resize of this window +@item x:Substructure-Notify-Mask +@tab Substructure notification wanted +@item x:Substructure-Redirect-Mask +@tab Redirect structure requests on children +@item x:Focus-Change-Mask +@tab Any change in input focus wanted +@item x:Property-Change-Mask +@tab Any change in property wanted +@item x:Colormap-Change--Mask +@tab Any change in colormap wanted +@item x:Owner-Grab-Button--Mask +@tab Automatic grabs should activate with owner_events set to True +@end multitable + +@end defvr + +@defvr Attribute x:CW-Dont-Propagate +The do-not-propagate-mask attribute defines which events should not be +propagated to ancestor windows when no client has the event type +selected in this x:Input-Output or x:Input-Only window. The +do-not-propagate-mask is the bitwise inclusive OR of zero or more of the +following masks: x:Key-Press, x:Key-Release, x:Button-Press, +x:Button-Release, x:Pointer-Motion, x:Button1Motion, x:Button2Motion, +x:Button3Motion, x:Button4Motion, x:Button5Motion, and x:Button-Motion. +You can specify that all events are propagated by setting +x:No-Event-Mask (default). +@end defvr + +@defvr Attribute x:CW-Colormap +The colormap attribute specifies which colormap best reflects the true +colors of the x:Input-Output window. The colormap must have the same +visual type as the window. X servers capable of supporting multiple +hardware colormaps can use this information, and window managers can use +it for calls to X:Install-Colormap. You can set the colormap attribute +to a colormap or to x:Copy-From-Parent (default). + +If you set the colormap to x:Copy-From-Parent, the parent window's +colormap is copied and used by its child. However, the child window +must have the same visual type as the parent. The parent window must +not have a colormap of x:None. The colormap is copied by sharing the +colormap object between the child and parent, not by making a complete +copy of the colormap contents. Subsequent changes to the parent +window's colormap attribute do not affect the child window. +@end defvr + +@defvr Attribute x:CW-Cursor +The cursor attribute specifies which cursor is to be used when the +pointer is in the x:Input-Output or x:Input-Only window. You can set +the cursor to a cursor or x:None (default). + +If you set the cursor to x:None, the parent's cursor is used when the +pointer is in the x:Input-Output or x:Input-Only window, and any change +in the parent's cursor will cause an immediate change in the displayed +cursor. On the root window, the default cursor is restored. +@end defvr + + +@node Window Visibility, Graphics Context, Window, Top +@chapter Window Visibility + +@noindent +In X parlance, a window which is hidden even when not obscured by other +windows is @dfn{unmapped}; one which +@cindex map +@cindex unmap +@cindex mapped +@cindex unmapped +shows is @dfn{mapped}. It is an unfortunate name-collision with Scheme, +and is ingrained in the attribute names. + +@defun x:map-window window +Maps the @var{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 @var{window} is already mapped. + +If the override-redirect of the window is False and if some other client +has selected x:Substructure-Redirect-Mask on the parent window, then the X +server generates a MapRequest event, and the @code{x:map-window} +function does not map the @var{window}. Otherwise, the @var{window} is +mapped, and the X server generates a MapNotify event. + +If the @var{window} becomes viewable and no earlier contents for it are +remembered, the X server tiles the @var{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 x:Expose events. If +backing-store was maintained while the @var{window} was unmapped, no +x: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. + +If the window is an Input-Output window, @code{x:map-window} generates +x:Expose events on each Input-Output 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 x:Expose events and then map the window, so the client processes +input events as usual. The event list will include x:Expose for each +window that has appeared on the screen. The client's normal response to +an x:Expose event should be to repaint the window. This method usually +leads to simpler programs and to proper interaction with window +managers. +@end defun + +@defun x:map-raised window +This procedure is similar to @code{x:map-window} in that it maps the +@var{window} and all of its subwindows that have had map requests. +However, it also raises the specified @var{window} to the top of the +stack. +@end defun + +@defun x:map-subwindows window +Maps all subwindows of a specified @var{window} in top-to-bottom +stacking order. The X server generates x: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. +@end defun + +@defun x:unmap-window window +Unmaps the specified @var{window} and causes the X server to generate an +UnmapNotify event. If the specified @var{window} is already unmapped, +@code{x:unmap-window} 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 @var{window} will generate x:Expose events +on windows that were formerly obscured by it. +@end defun + +@defun x:unmap-subwindows window +Unmaps all subwindows for the specified @var{window} in bottom-to-top +stacking order. It causes the X server to generate an UnmapNotify event +on each subwindow and x:Expose events on formerly obscured windows. 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. +@end defun + +@node Graphics Context, Cursor, Window Visibility, Top +@chapter Graphics Context + +@noindent +Most attributes of graphics operations are stored in @dfn{GC}s. These +include line width, line style, plane mask, foreground, background, +tile, stipple, clipping region, end style, join style, and so on. +Graphics operations (for example, drawing lines) use these values to +determine the actual drawing operation. + +@defun x:create-gc drawable field-name value @dots{} +Creates and returns graphics context. The graphics context can be used +with any destination drawable having the same root and depth as the +specified @var{drawable}. +@end defun + +@defun x:gc-set! graphics-context field-name value @dots{} +Changes the components specified by @var{field-name}s for the specified +@var{graphics-context}. The restrictions are the same as for +@code{x:create-gc}. The order in which components are verified and +altered is server dependent. If an error occurs, a subset of the +components may have been altered. +@end defun + +@defun x:copy-gc-fields! gcontext-src gcontext-dst field-name @dots{} +Copies the components specified by @var{field-name}s from +@var{gcontext-src} to @var{gcontext-dst}. @var{Gcontext-src} and +@var{gcontext-dst} must have the same root and depth. +@end defun + +@defun x:gc-ref graphics-context field-name @dots{} +Returns a list of the components specified by @var{field-name}s @dots{} +from the specified @var{graphics-context}. +@end defun + +@heading GC Attributes + +@noindent +Both @code{x:create-gc} and @code{x:change-gc} take one argument +followed by pairs of arguments, where the first is one of the +property-name symbols (or its top-level value) listed below; and the +second is the value to associate with that property. + +@defvr Attribute x:GC-Function +The function attributes of a GC are used when you update a section of a +drawable (the destination) with bits from somewhere else (the source). +The function in a GC defines how the new destination bits are to be +computed from the source bits and the old destination bits. x:G-Xcopy is +typically the most useful because it will work on a color display, but +special applications may use other functions, particularly in concert +with particular planes of a color display. The 16 functions are: + +@format +@t{ +x:G-Xclear 0 +x:G-Xand (AND src dst) +x:G-Xand-Reverse (AND src (NOT dst)) +x:G-Xcopy src +x:G-Xand-Inverted (AND (NOT src) dst) +x:G-Xnoop dst +x:G-Xxor (XOR src dst) +x:G-Xor (OR src dst) +x:G-Xnor (AND (NOT src) (NOT dst)) +x:G-Xequiv (XOR (NOT src) dst) +x:G-Xinvert (NOT dst) +x:G-Xor-Reverse (OR src (NOT dst)) +x:G-Xcopy-Inverted (NOT src) +x:G-Xor-Inverted (OR (NOT src) dst) +x:G-Xnand (OR (NOT src) (NOT dst)) +x:G-Xset 1} +@end format +@end defvr + +@defvr Attribute x:GC-Plane-Mask + +Many graphics operations depend on either pixel values or planes in a +GC. The planes attribute is an integer which specifies which planes of +the destination are to be modified, one bit per plane. A monochrome +display has only one plane and will be the least significant bit of the +integer. As planes are added to the display hardware, they will occupy +more significant bits in the plane mask. + +In graphics operations, given a source and destination pixel, the result +is computed bitwise on corresponding bits of the pixels. That is, a +Boolean operation is performed in each bit plane. The plane-mask +restricts the operation to a subset of planes. @code{x:All-Planes} can be +used to refer to all planes of the screen simultaneously. The result is +computed by the following: + +@format +(OR (AND (FUNC src dst) plane-mask) (AND dst (NOT plane-mask))) +@end format + +Range checking is not performed on a plane-mask value. It is simply +truncated to the appropriate number of bits. +@end defvr + +@defvr Attribute x:GC-Foreground +@defvrx Attribute x:GC-Background +Range checking is not performed on the values for foreground or +background. They are simply truncated to the appropriate number of +bits. + +Note that foreground and background are not initialized to any values +likely to be useful in a window. +@end defvr + +@defvr Attribute x:GC-Line-Width +The line-width is measured in pixels and either can be greater than or +equal to one (wide line) or can be the special value zero (thin line). + +Thin lines (zero line-width) are one-pixel-wide lines drawn using an +unspecified, device-dependent algorithm. There are only two constraints +on this algorithm. + +@itemize @bullet +@item +If a line is drawn unclipped from [x1,y1] to [x2,y2] and if another line +is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], a point [x,y] is +touched by drawing the first line if and only if the point [x+dx,y+dy] +is touched by drawing the second line. + +@item +The effective set of points comprising a line cannot be affected by +clipping. That is, a point is touched in a clipped line if and only if +the point lies inside the clipping region and the point would be touched +by the line when drawn unclipped. +@end itemize + +A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels +as a wide line drawn from [x2,y2] to [x1,y1], not counting cap-style and +join-style. It is recommended that this property be true for thin +lines, but this is not required. A line-width of zero may differ from a +line-width of one in which pixels are drawn. This permits the use of +many manufacturers' line drawing hardware, which may run many times +faster than the more precisely specified wide lines. + +In general, drawing a thin line will be faster than drawing a wide line +of width one. However, because of their different drawing algorithms, +thin lines may not mix well aesthetically with wide lines. If it is +desirable to obtain precise and uniform results across all displays, a +client should always use a line-width of one rather than a linewidth of +zero. +@end defvr + +@defvr Attribute x:GC-Line-Style +The line-style defines which sections of a line are drawn: + +@table @t +@item x:Line-Solid +The full path of the line is drawn. +@item x:Line-Double-Dash +The full path of the line is drawn, but the even dashes are filled +differently from the odd dashes (see fill-style) with x:Cap-Butt style used +where even and odd dashes meet. +@item x:Line-On-Off-Dash +Only the even dashes are drawn, and cap-style applies to all internal +ends of the individual dashes, except x:Cap-Not-Last is treated as x:Cap-Butt. +@end table +@end defvr + +@defvr Attribute x:GC-Cap-Style + +The cap-style defines how the endpoints of a path are drawn: + +@table @t +@item x:Cap-Not-Last +This is equivalent to x:Cap-Butt except that for a line-width of zero the +final endpoint is not drawn. +@item x:Cap-Butt +The line is square at the endpoint (perpendicular to the slope of the +line) with no projection beyond. +@item x:Cap-Round +The line has a circular arc with the diameter equal to the line-width, +centered on the endpoint. (This is equivalent to x:Cap-Butt for line-width +of zero). +@item x:Cap-Projecting +The line is square at the end, but the path continues beyond the +endpoint for a distance equal to half the line-width. (This is +equivalent to x:Cap-Butt for line-width of zero). +@end table +@end defvr + +@defvr Attribute x:GC-Join-Style + +The join-style defines how corners are drawn for wide lines: + +@table @t +@item x:Join-Miter +The outer edges of two lines extend to meet at an angle. However, if +the angle is less than 11 degrees, then a x:Join-Bevel join-style is used +instead. +@item x:Join-Round +The corner is a circular arc with the diameter equal to the +line-width, centered on the x:Join-point. +@item x:Join-Bevel +The corner has x:Cap-Butt endpoint styles with the triangular notch filled. +@end table +@end defvr + +@defvr Attribute x:GC-Fill-Style + +The fill-style defines the contents of the source for line, text, and +fill requests. For all text and fill requests (for example, +X:Draw-Text, X:Fill-Rectangle, X:Fill-Polygon, and X:Fill-Arc); for line +requests with linestyle x:Line-Solid (for example, X:Draw-Line, +X:Draw-Segments, X:Draw-Rectangle, X:Draw-Arc); and for the even dashes +for line requests with line-style x:Line-On-Off-Dash or +x:Line-Double-Dash, the following apply: + +@table @t +@item x:Fill-Solid +Foreground +@item x:Fill-Tiled +Tile +@item x:Fill-Opaque-Stippled +A tile with the same width and height as stipple, but with background +everywhere stipple has a zero and with foreground everywhere stipple has +a one +@item x:Fill-Stippled +Foreground masked by stipple +@end table + +When drawing lines with line-style x:Line-Double-Dash, the odd dashes +are controlled by the fill-style in the following manner: + +@table @t +@item x:Fill-Solid +Background +@item x:Fill-Tiled +Same as for even dashes +@item x:Fill-Opaque-Stippled +Same as for even dashes +@item x:Fill-Stippled +Background masked by stipple +@end table +@end defvr + +@defvr Attribute x:GC-Fill-Rule +The fill-rule defines what pixels are inside (drawn) for paths given in +X:Fill-Polygon requests and can be set to x:Even-Odd-Rule or +x:Winding-Rule. + +@table @t +@item x:Even-Odd-Rule +A point is inside if an infinite ray with the point as +origin crosses the path an odd number of times. +@item x:Winding-Rule +A point is inside if an infinite ray with the point as origin crosses an +unequal number of clockwise and counterclockwise directed path segments. +@end table + +A clockwise directed path segment is one that crosses the ray from left +to right as observed from the point. A counterclockwise segment is one +that crosses the ray from right to left as observed from the point. The +case where a directed line segment is coincident with the ray is +uninteresting because you can simply choose a different ray that is not +coincident with a segment. + +For both x:Even-Odd-Rule and x:Winding-Rule, a point is infinitely +small, and the path is an infinitely thin line. A pixel is inside if +the center point of the pixel is inside and the center point is not on +the boundary. If the center point is on the boundary, the pixel is +inside if and only if the polygon interior is immediately to its right +(x increasing direction). Pixels with centers on a horizontal edge are +a special case and are inside if and only if the polygon interior is +immediately below (y increasing direction). +@end defvr + +@defvr Attribute x:GC-Tile +@defvrx Attribute x:GC-Stipple +The tile/stipple represents an infinite two-dimensional plane, with the +tile/stipple replicated in all dimensions. + +The tile pixmap must have the same root and depth as the GC, or an error +results. The stipple pixmap must have depth one and must have the same +root as the GC, or an error results. For stipple operations where the +fill-style is x:Fill-Stippled but not x:Fill-Opaque-Stippled, the +stipple pattern is tiled in a single plane and acts as an additional +clip mask to be ANDed with the clip-mask. Although some sizes may be +faster to use than others, any size pixmap can be used for tiling or +stippling. +@end defvr + +@defvr Attribute x:GC-Tile-Stip-X-Origin +@defvrx Attribute x:GC-Tile-Stip-Y-Origin +When the tile/stipple plane is superimposed on a drawable for use in a +graphics operation, the upper-left corner of some instance of the +tile/stipple is at the coordinates within the drawable specified by the +tile/stipple origin. The tile/stipple origin is interpreted relative to +the origin of whatever destination drawable is specified in a graphics +request. +@end defvr + +@defvr Attribute x:GC-Font +The font to be used for drawing text. +@end defvr + +@defvr Attribute x:GC-Subwindow-Mode +You can set the subwindow-mode to x:Clip-By-Children or +x:Include-Inferiors. +@table @t +@item x:Clip-By-Children +Both source and destination windows are additionally clipped by all +viewable Input-Output children. +@item x:Include-Inferiors +Neither source nor destination window is clipped by inferiors. This +will result in including subwindow contents in the source and drawing +through subwindow boundaries of the destination. The use of +@code{x:Include-Inferiors} on a window of one depth with mapped +inferiors of differing depth is not illegal, but the semantics are +undefined by the core protocol. +@end table +@end defvr + +@defvr Attribute x:GC-Graphics-Exposures +The graphics-exposure flag controls x:Graphics-Expose event generation +for X:Copy-Area and X:Copy-Plane requests (and any similar requests +defined by extensions). +@end defvr + +@defvr Attribute x:GC-Clip-X-Origin +@defvrx Attribute x:GC-Clip-Y-Origin +The clip-mask origin is interpreted relative to the origin of whatever +destination drawable is specified in a graphics request. +@end defvr + +@defvr Attribute x:GC-Clip-Mask +The clip-mask restricts writes to the destination drawable. If the +clip-mask is set to a pixmap, it must have depth one and have the same +root as the GC, or an error results. If clip-mask is set to +@cindex x:None +@cindex none +@dfn{x:None}, the pixels are always drawn regardless of the clip origin. +The clip-mask also can be set by calling @code{X:Set-Region}. Only +pixels where the clip-mask has a bit set to 1 are drawn. Pixels are not +drawn outside the area covered by the clip-mask or where the clip-mask +has a bit set to 0. The clip-mask affects all graphics requests. The +clip-mask does not clip sources. The clip-mask origin is interpreted +relative to the origin of whatever destination drawable is specified in +a graphics request. +@end defvr + +@defvr Attribute x:GC-Dash-Offset +Defines the phase of the pattern, specifying how many pixels into the +dash-list the pattern should actually begin in any single graphics +request. Dashing is continuous through path elements combined with a +join-style but is reset to the dash-offset between each sequence of +joined lines. + +The unit of measure for dashes is the same for the ordinary +coordinate system. Ideally, a dash length is measured along +the slope of the line, but implementations are only required +to match this ideal for horizontal and vertical lines. +Failing the ideal semantics, it is suggested that the length +be measured along the major axis of the line. The major +axis is defined as the x axis for lines drawn at an angle of +between -45 and +45 degrees or between 135 and 225 degrees +from the x axis. For all other lines, the major axis is the +y axis. +@end defvr + +@defvr Attribute x:GC-Dash-List +There must be at least one element in the specified @var{dash-list}. +The initial and alternating elements (second, fourth, and so on) of the +@var{dash-list} are the even dashes, and the others are the odd dashes. +Each element specifies a dash length in pixels. All of the elements +must be nonzero. Specifying an odd-length list is equivalent to +specifying the same list concatenated with itself to produce an +even-length list. +@end defvr + +@defvr Attribute x:GC-Arc-Mode +The arc-mode controls filling in the X:Fill-Arcs function and can be set +to x:Arc-Pie-Slice or x:Arc-Chord. +@table @t +@item x:Arc-Pie-Slice +The arcs are pie-slice filled. +@item x:Arc-Chord +The arcs are chord filled. +@end table +@end defvr + + +@node Cursor, Colormap, Graphics Context, Top +@chapter Cursor + +@defun x:create-cursor display shape +X provides a set of standard cursor shapes in a special font named +@cindex cursor +@dfn{cursor}. Applications are encouraged to use this interface for +their cursors because the font can be customized for the individual +display type. The @var{shape} argument specifies which glyph of the standard +fonts to use. + +The hotspot comes from the information stored in the cursor font. The +initial colors of a cursor are a black foreground and a white background +(see X:Recolor-Cursor). The names of all cursor shapes are defined with +the prefix XC: in @file{x11.scm}. + +@defunx x:create-cursor source-font source-char mask-font mask-char fgc bgc +Creates a cursor from the source and mask bitmaps obtained from the +specified font glyphs. The integer @var{source-char} must be a defined +glyph in @var{source-font}. The integer @var{mask-char} must be a +defined glyph in @var{mask-font}. The origins of the @var{source-char} +and @var{mask-char} glyphs are positioned coincidently and define the +hotspot. The @var{source-char} and @var{mask-char} need not have the +same bounding box metrics, and there is no restriction on the placement +of the hotspot relative to the bounding boxes. + +@defunx x:create-cursor source-font source-char #f #f fgc bgc +If @var{mask-font} and @var{mask-char} are #f, all pixels of the source +are displayed. + +@defunx x:create-cursor source-pixmap mask-pixmap fgc bgc origin +@var{mask-pixmap} must be the same size as the pixmap defined by the +@var{source-pixmap} argument. The foreground and background RGB values +must be specified using @var{foreground-color} and +@var{background-color}, even if the X server only has a x:Static-Gray or +x:Gray-Scale screen. The hotspot must be a point within the +@var{source-pixmap}. + +@code{X:Create-Cursor} creates and returns a cursor. The +@var{foreground-color} is used for the pixels set to 1 in the source, +and the @var{background-color} is used for the pixels set to 0. Both +source and mask must have depth one but can have any root. The +@var{mask-pixmap} defines the shape of the cursor. The pixels set to 1 +in @var{mask-pixmap} define which source pixels are displayed, and the +pixels set to 0 define which pixels are ignored. + +@defunx x:create-cursor source-pixmap #f fgc bgc origin +If @var{mask-pixmap} is #f, all pixels of the source are displayed. +@end defun + +@node Colormap, Rendering, Cursor, Top +@chapter Colormap + +@cindex colormap +@cindex RGB +A @dfn{colormap} maps pixel values to @dfn{RGB} color space values. + +@defun x:create-colormap window visual alloc-policy +@var{window} specifies the window on whose screen you want to create a +colormap. @var{visual} specifies a visual type supported on the screen. +@var{alloc-policy} Specifies the colormap entries to be allocated. You +can pass @code{X:Alloc-None} or @code{X:Alloc-All}. + +The @code{X:Create-Colormap} function creates and returns a colormap of +the specified @var{visual} type for the screen on which @var{window} +resides. Note that @var{window} is used only to determine the screen. + +@table @samp +@item X:Gray-Scale +@itemx X:Pseudo-Color +@itemx X:Direct-Color +The initial values of the colormap entries are undefined. + +@item X:Static-Gray +@itemx X:Static-Color +@itemx X:True-Color +The entries have defined values, but those values are specific to +@var{visual} and are not defined by X. The @var{alloc-policy} must be +@samp{X:Alloc-None}. + +@end table + +For the other visual classes, if @var{alloc-policy} is +@samp{X:Alloc-None}, the colormap initially has no allocated entries, +and clients can allocate them. + +If @var{alloc-policy} is @samp{X:Alloc-All}, the entire colormap is +allocated writable. The initial values of all allocated entries are +undefined. + +@table @samp +@item X:Gray-Scale +@itemx X:Pseudo-Color +The effect is as if an @code{XAllocColorCells} call returned all pixel +values from zero to N - 1, where N is the colormap entries value in +@var{visual}. + +@item X:Direct-Color +The effect is as if an @code{XAllocColorPlanes} call returned a pixel +value of zero and red_mask, green_mask, and blue_mask values containing +the same bits as the corresponding masks in the specified visual. +@end table + +@end defun + + +To create a new colormap when the allocation out of a previously +shared colormap has failed because of resource exhaustion, use: + +@defun x:copy-colormap-and-free colormap + +Creates and returns a colormap of the same visual type and for the same +screen as the specified @var{colormap}. It also moves all of the +client's existing allocation from the specified @var{colormap} to the +new colormap with their color values intact and their read-only or +writable characteristics intact and frees those entries in the specified +colormap. Color values in other entries in the new colormap are +undefined. If the specified colormap was created by the client with +alloc set to @samp{X:Alloc-All}, the new colormap is also created with +@samp{X:Alloc-All}, all color values for all entries are copied from the +specified @var{colormap}, and then all entries in the specified +@var{colormap} are freed. If the specified @var{colormap} was not +created by the client with @samp{X:Alloc-All}, the allocations to be moved +are all those pixels and planes that have been allocated by the client +and that have not been freed since they were allocated. + +@end defun + +A @dfn{colormap} maps pixel values to elements of the @dfn{RGB} +datatype. An @var{RGB} is a list or vector of 3 integers, describing +the red, green, and blue intensities respectively. The integers are in +the range 0 - 65535. + +@defun x:alloc-colormap-cells colormap ncolors nplanes +@defunx x:alloc-colormap-cells colormap ncolors nplanes contiguous? + +The @code{X:Alloc-Color-Cells} function allocates read/write color +cells. The number of colors, @var{ncolors} must be positive and the +number of planes, @var{nplanes} nonnegative. If @var{ncolors} and +nplanes are requested, then @var{ncolors} pixels and nplane plane masks +are returned. No mask will have any bits set to 1 in common with any +other mask or with any of the pixels. By ORing together each pixel with +zero or more masks, @var{ncolors} * 2^@var{nplanes} distinct pixels can +be produced. All of these are allocated writable by the request. + +@table @samp +@item x:Gray-Scale +@itemx x:Pseudo-Color +Each mask has exactly one bit set to 1. If @var{contiguous?} is +non-false and if all masks are ORed together, a single contiguous set of +bits set to 1 is formed. +@item x:Direct-Color +Each mask has exactly three bits set to 1. If @var{contiguous?} is +non-false and if all masks are ORed together, three contiguous sets of +bits set to 1 (one within each pixel subfield) is formed. +@end table + +The RGB values of the allocated entries are undefined. +@code{X:Alloc-Color-Cells} returns a list of two uniform arrays if it +succeeded or #f if it failed. The first array has the pixels allocated +and the second has the plane-masks. + + +@defunx x:alloc-colormap-cells colormap ncolors rgb +@defunx x:alloc-colormap-cells colormap ncolors rgb contiguous? + +The specified @var{ncolors} must be positive; and @var{rgb} a list or +vector of 3 nonnegative integers. If @var{ncolors} colors, @var{nreds} +reds, @var{ngreens} greens, and @var{nblues} blues are requested, +@var{ncolors} pixels are returned; and the masks have @var{nreds}, +@var{ngreens}, and @var{nblues} bits set to 1, respectively. If +@var{contiguous?} is non-false, each mask will have a contiguous set of +bits set to 1. No mask will have any bits set to 1 in common with any +other mask or with any of the pixels. + +Each mask will lie within the corresponding pixel subfield. By ORing +together subsets of masks with each pixel value, @var{ncolors} * +2(@var{nreds}+@var{ngreens}+@var{nblues}) distinct pixel values can be +produced. All of these are allocated by the request. However, in the +colormap, there are only @var{ncolors} * 2^@var{nreds} independent red +entries, @var{ncolors} * 2^@var{ngreens} independent green entries, and +@var{ncolors} * 2^@var{nblues} independent blue entries. + +@code{X:Alloc-Color-Cells} returns a list if it succeeded or #f if it +failed. The first element of the list has an array of the pixels +allocated. The second, third, and fourth elements are the red, green, +and blue plane-masks. +@end defun + +@defun x:free-colormap-cells colormap pixels planes +@defunx x:free-colormap-cells colormap pixels + +Frees the cells represented by pixels whose values are in the +@var{pixels} unsigned-integer uniform-vector. The @var{planes} argument +should not have any bits set to 1 in common with any of the pixels. The +set of all pixels is produced by ORing together subsets of the +@var{planes} argument with the pixels. The request frees all of these +pixels that were allocated by the client. Note that freeing an +individual pixel obtained from @code{X:Alloc-Colormap-Cells} with a +planes argument may not actually allow it to be reused until all of its +related pixels are also freed. Similarly, a read-only entry is not +actually freed until it has been freed by all clients, and if a client +allocates the same read-only entry multiple times, it must free the +entry that many times before the entry is actually freed. + +All specified pixels that are allocated by the client in the +@var{colormap} are freed, even if one or more pixels produce an error. +It is an error if a specified pixel is not allocated by the client (that +is, is unallocated or is only allocated by another client) or if the +colormap was created with all entries writable (by passing +@samp{x:Alloc-All} to @code{X:Create-Colormap}). If more than one pixel +is in error, the one that gets reported is arbitrary. +@end defun + +@defun x:colormap-find-color colormap rgb + +@var{rgb} is a list or vector of 3 integers, describing the red, green, +and blue intensities respectively; or an integer @samp{#x@i{rrggbb}}, +packing red, green and blue intensities in the range 0 - 255. + +@defunx x:colormap-find-color colormap color-name + +The case-insensitive string @var{color_name} specifies the name of a +color (for example, @file{red}) + +@code{X:Colormap-Find-Color} allocates a read-only colormap entry +corresponding to the closest RGB value supported by the hardware. +@code{X:Colormap-Find-Color} returns the pixel value of the color +closest to the specified @var{RGB} or @var{color_name} elements +supported by the hardware, if successful; otherwise +@code{X:Colormap-Find-Color} returns #f. + +Multiple clients that request the same effective RGB value can +be assigned the same read-only entry, thus allowing entries to be +shared. When the last client deallocates a shared cell, it is +deallocated. + +@end defun + +@defun x:color-ref colormap pixel + +Returns a list of 3 integers, describing the red, green, +and blue intensities respectively of the @var{colormap} entry of the +cell indexed by @var{pixel}. + +The integer @var{pixel} must be a valid index into @var{colormap}. +@end defun + +@defun X:Color-Set! colormap pixel rgb + +@var{rgb} is a list or vector of 3 integers, describing the red, green, +and blue intensities respectively; or an integer @samp{#x@i{rrggbb}}, +packing red, green and blue intensities in the range 0 - 255. + +@defunx X:Color-Set! colormap pixel color-name + +The case-insensitive string @var{color_name} specifies the name of a +color (for example, @file{red}) + +The integer @var{pixel} must be a valid index into @var{colormap}. + +@code{X:Color-Set!} changes the @var{colormap} entry of the read/write +cell indexed by @var{pixel}. If the @var{colormap} is an installed map +for its screen, the changes are visible immediately. + +@end defun + +@defun x:install-colormap colormap + +Installs the specified @var{colormap} for its associated screen. All +windows associated with @var{colormap} immediately display with true +colors. A colormap is associated with a window when the window is +created or its attributes changed. + +If the specified colormap is not already an installed colormap, the X +server generates a ColormapNotify event on each window that has that +colormap. + +@end defun + + +@node Rendering, Event, Colormap, Top +@chapter Rendering + +@defun x:flush display +@defunx x:flush window +Flushes the output buffer. Some client applications need not use this +function because the output buffer is automatically flushed as needed by +calls to X:Pending, X:Next-Event, and X:Window-Event. Events generated +by the server may be enqueued into the library's event queue. + +@defunx x:flush gc +Forces sending of GC component changes. + +Xlib usually defers sending changes to the components of a GC to the +server until a graphics function is actually called with that GC. This +permits batching of component changes into a single server request. In +some circumstances, however, it may be necessary for the client to +explicitly force sending the changes to the server. An example might be +when a protocol extension uses the GC indirectly, in such a way that the +extension interface cannot know what GC will be used. +@end defun + +@defun x:clear-area window (x-pos y-pos) (width height) expose? +Paints a rectangular area in the specified @var{window} according to the +specified dimensions with the @var{window}'s background pixel or pixmap. +The subwindow-mode effectively is @samp{x:Clip-By-Children}. If width +is zero, it is replaced with the current width of the @var{window} minus +x. If height is zero, it is replaced with the current height of the +@var{window} minus y. If the @var{window} has a defined background +tile, the rectangle clipped by any children is filled with this tile. +If the @var{window} has background x:None, the contents of the +@var{window} are not changed. In either case, if @var{expose?} is True, +one or more x:Expose events are generated for regions of the rectangle +that are either visible or are being retained in a backing store. If +you specify a @var{window} whose class is x:Input-Only, an error +results. +@end defun + +@defun x:fill-rectangle window gcontext position size + +@end defun + +@heading Draw Strings + +@defun x:draw-string drawable gc position string +@var{Position} specifies coordinates relative to the origin of +@var{drawable} of the origin of the first character to be drawn. + +@code{x:draw-string} draws the characters of @var{string}, starting at +@var{position}. +@end defun + +@defun x:image-string drawable gc position string +@var{Position} specifies coordinates relative to the origin of +@var{drawable} of the origin of the first character to be drawn. + +@code{x:image-string} draws the characters @emph{and background} of +@var{string}, starting at @var{position}. +@end defun + +@heading Draw Shapes + +@defun x:draw-points drawable gc position @dots{} +@var{Position} @dots{} specifies coordinates of the point to be drawn. + +@defunx x:draw-points drawable gc x y @dots{} +(@var{x}, @var{y}) @dots{} specifies coordinates of the point to be +drawn. + +@defunx x:draw-points drawable gc point-array +@var{point-array} is a uniform short array of rank 2, whose rightmost +index spans a range of 2. + +The @code{X:Draw-Points} procedure uses the foreground pixel and +function components of the @var{gc} to draw points into @var{drawable} +at the positions (relative to the origin of @var{drawable}) specified. + +@code{X:Draw-Points} uses these @var{gc} components: function, +planemask, foreground, subwindow-mode, clip-x-origin, clip-y-origin, and +clip-mask. +@end defun + + +@defun x:draw-segments drawable gc pos1 pos2 @dots{} +@var{Pos1}, @var{pos2}, @dots{} specify coordinates to be connected by +segments. + +@defunx x:draw-segments drawable gc x1 y1 x2 y2 @dots{} +(@var{x1}, @var{y1}), (@var{x2}, @var{y2}) @dots{} specify coordinates +to be connected by segments. + +@defunx x:draw-segments drawable gc point-array +@var{point-array} is a uniform short array of rank 2, whose rightmost +index spans a range of 2. + +The @code{X:Draw-Segments} procedure uses the components of the +specified @var{gc} to draw multiple unconnected lines between disjoint +adjacent pair of points passed as arguments. It draws the segments in +order and does not perform joining at coincident endpoints. For any +given line, @code{X:Draw-Segments} does not draw a pixel more than once. +If thin (zero line-width) segments intersect, the intersecting pixels +are drawn multiple times. If wide segments intersect, the intersecting +pixels are drawn only once, as though the entire PolyLine protocol +request were a single, filled shape. @code{X:Draw-Segments} treats all +coordinates as relative to the origin of @var{drawable}. + +@code{X:Draw-Segments} uses these @var{gc} components: function, +plane-mask, line-width, line-style, cap-style, fill-style, +subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask, join-style. +It also use these @var{gc} mode-dependent components: foreground, +background, tile, stipple, tilestipple-x-origin, tile-stipple-y-origin, +dash-offset, and dash-list. +@end defun + +@defun x:draw-lines drawable gc pos1 pos2 @dots{} +@var{Pos1}, @var{pos2}, @dots{} specify coordinates to be connected by +lines. + +@defunx x:draw-lines drawable gc x1 y1 x2 y2 @dots{} +(@var{x1}, @var{y1}), (@var{x2}, @var{y2}) @dots{} specify coordinates +to be connected by lines. + +@defunx x:draw-lines drawable gc point-array +@var{point-array} is a uniform short array of rank 2, whose rightmost +index spans a range of 2. + +The @code{X:Draw-Lines} procedure uses the components of the specified +@var{gc} to draw lines between each adjacent pair of points passed as +arguments. It draws the lines in order. The lines join correctly at +all intermediate points, and if the first and last points coincide, the +first and last lines also join correctly. For any given line, +@code{X:Draw-Lines} does not draw a pixel more than once. If thin (zero +line-width) lines intersect, the intersecting pixels are drawn multiple +times. If wide lines intersect, the intersecting pixels are drawn only +once, as though the entire PolyLine protocol request were a single, +filled shape. @code{X:Draw-Lines} treats all coordinates as relative to +the origin of @var{drawable}. + +@code{X:Draw-Lines} uses these @var{gc} components: function, +plane-mask, line-width, line-style, cap-style, fill-style, +subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask, join-style. +It also use these @var{gc} mode-dependent components: foreground, +background, tile, stipple, tilestipple-x-origin, tile-stipple-y-origin, +dash-offset, and dash-list. +@end defun + +@defun x:fill-polygon drawable gc pos1 pos2 @dots{} +@var{Pos1}, @var{pos2}, @dots{} specify coordinates of the border path. + +@defunx x:fill-polygon drawable gc x1 y1 x2 y2 @dots{} +(@var{x1}, @var{y1}), (@var{x2}, @var{y2}) @dots{} specify coordinates +of the border path. + +@defunx x:fill-polygon drawable gc point-array +@var{point-array} is a uniform short array of rank 2, whose rightmost +index spans a range of 2. + +The path is closed automatically if the last point in the list or +@var{point-array} does not coincide with the first point. + +The @code{X:Fill-Polygon} procedure uses the components of the specified +@var{gc} to fill the region closed by the specified path. +@code{X:Fill-Polygon} does not draw a pixel of the region more than +once. @code{X:Fill-Polygon} treats all coordinates as relative to the +origin of @var{drawable}. + +@code{X:Fill-Polygon} uses these @var{gc} components: function, +planemask, fill-style, fill-rule, subwindow-mode, clip-x-origin, +clip-y-origin, and clip-mask. It also use these @var{gc} mode-dependent +components: foreground, background, tile, stipple, +tile-stipple-x-origin, and tile-stipple-y-origin. +@end defun + +@node Event, Index, Rendering, Top +@chapter Event + +@noindent +These three status routines always return immediately if there are +events already in the queue. + +@defun x:q-length display +Returns the length of the event queue for the connected @var{display}. +Note that there may be more events that have not been read into the +queue yet (see X:Events-Queued). +@end defun + +@defun x:pending display +Returns the number of events that have been received from the X server +but have not been removed from the event queue. +@end defun + +@defun x:events-queued display +Returns the number of events already in the queue if the number is +nonzero. If there are no events in the queue, @code{X:Events-Queued} +attempts to read more events out of the application's connection without +flushing the output buffer and returns the number read. +@end defun + +@noindent +Both of these routines return an object of type @dfn{event}. + +@defun x:next-event display +Removes and returns the first event from the event queue. If the event +queue is empty, @code{X:Next-Event} flushes the output buffer and blocks +until an event is received. +@end defun + +@defun x:peek-event display +Returns the first event from the event queue, but it does not remove the +event from the queue. If the queue is empty, @code{X:Peek-Event} +flushes the output buffer and blocks until an event is received. +@end defun + +@noindent +Each event object has fields dependent on its sub-type. + +@defun x:event-ref event field-name +@multitable @columnfractions .40 .60 +@item window +@tab +The window on which @var{event} was generated and is referred to as the +event window. +@item root +@tab +is the event window's root window. +@item subwindow +@tab +If the source window is an inferior of the event window, the +@var{subwindow} is the child of the event window that is the source +window or the child of the event window that is an ancestor of the +source window. Otherwise, @samp{None}. +@item X-event:type +@tab +An integer: @var{x:Key-Press}, @var{x:Key-Release}, +@var{x:Button-Press}, @var{x:Button-Release}, @var{x:Motion-Notify}, +@var{x:Enter-Notify}, @var{x:Leave-Notify}, @var{x:Focus-In}, +@var{x:Focus-Out}, @var{x:Keymap-Notify}, @var{x:Expose}, +@var{x:Graphics-Expose}, @var{x:No-Expose}, @var{x:Visibility-Notify}, +@var{x:Create-Notify}, @var{x:Destroy-Notify}, @var{x:Unmap-Notify}, +@var{x:Map-Notify}, @var{x:Map-Request}, @var{x:Reparent-Notify}, +@var{x:Configure-Notify}, @var{x:Configure-Request}, +@var{x:Gravity-Notify}, @var{x:Resize-Request}, +@var{x:Circulate-Notify}, @var{x:Circulate-Request}, +@var{x:Property-Notify}, @var{x:Selection-Clear}, +@var{x:Selection-Request}, @var{x:Selection-Notify}, +@var{x:Colormap-Notify}, @var{x:Client-Message}, or +@var{x:Mapping-Notify}. +@item X-event:serial +@tab +The serial number of the protocol request that generated the @var{event}. +@item X-event:send-event +@tab +Boolean that indicates whether the event was sent by a different client. +@item X-event:time +@tab +The time when the @var{event} was generated expressed in milliseconds. +@item X-event:x +@item X-event:y +@tab +For window entry/exit events the @var{x} and @var{y} members are set to +the coordinates of the pointer position in the event window. This +position is always the pointer's final position, not its initial +position. If the event window is on the same screen as the root window, +@var{x} and @var{y} are the pointer coordinates relative to the event +window's origin. Otherwise, @var{x} and @var{y} are set to zero. + +For expose events The @var{x} and @var{y} members are set to the +coordinates relative to the drawable's origin and indicate the +upper-left corner of the rectangle. + +For configure, create, gravity, and reparent events the @var{x} and +@var{y} members are set to the window's coordinates relative to the +parent window's origin and indicate the position of the upper-left +outside corner of the created window. +@item X-event:x-root +@itemx X-event:y-root +@tab +The pointer's coordinates relative to the root window's origin at the +time of the @var{event}. +@item X-event:state +@tab +For keyboard, pointer and window entry/exit events, the state member is +set to indicate the logical state of the pointer buttons and modifier +keys just prior to the @var{event}, which is the bitwise inclusive OR of +one or more of the button or modifier key masks: @var{x:Button1-Mask}, +@var{x:Button2-Mask}, @var{x:Button3-Mask}, @var{x:Button4-Mask}, +@var{x:Button5-Mask}, @var{x:Shift-Mask}, @var{x:Lock-Mask}, +@var{x:Control-Mask}, @var{x:Mod1-Mask}, @var{x:Mod2-Mask}, +@var{x:Mod3-Mask}, @var{x:Mod4-Mask}, and @var{x:Mod5-Mask}. + +For visibility events, the state of the window's visibility: +@var{x:Visibility-Unobscured}, @var{x:Visibility-Partially-Obscured}, or +@var{x:Visibility-Fully-Obscured}. + +For colormap events, indicates whether the colormap is installed or +uninstalled: x:Colormap-Installed or x:Colormap-Uninstalled. + +For property events, indicates whether the property was changed to a new +value or deleted: x:Property-New-Value or x:Property-Delete. +@item X-event:keycode +@tab +An integer that represents a physical key on the keyboard. +@item X-event:same-screen +@tab +Indicates whether the event window is on the same screen as the root +window. If #t, the event and root windows are on the same screen. If +#f, the event and root windows are not on the same screen. +@item X-event:button +@tab +The pointer button that changed state; can be the @var{x:Button1}, +@var{x:Button2}, @var{x:Button3}, @var{x:Button4}, or @var{x:Button5} +value. +@item X-event:is-hint +@tab +Detail of motion-notify events: @var{x:Notify-Normal} or +@var{x:Notify-Hint}. +@item X-event:mode +@tab +Indicates whether the @var{event} is a normal event, pseudo-motion event +when a grab activates, or a pseudo-motion event when a grab deactivates: +@var{x:Notify-Normal}, @var{x:Notify-Grab}, or @var{x:Notify-Ungrab}. +@item X-event:detail +@tab +Indicates the notification detail: @var{x:Notify-Ancestor}, +@var{x:Notify-Virtual}, @var{x:Notify-Inferior}, +@var{x:Notify-Nonlinear}, or @var{x:Notify-Nonlinear-Virtual}. +@item X-event:focus +@tab +If the event window is the focus window or an inferior of the focus +window, #t; otherwise #f. +@item X-event:width +@itemx X-event:height +@tab +The size (extent) of the rectangle. +@item X-event:count +@tab +For mapping events is the number of keycodes altered. + +For expose events Is the number of Expose or GraphicsExpose events that +are to follow. If count is zero, no more Expose events follow for this +window. However, if count is nonzero, at least that number of Expose +events (and possibly more) follow for this window. Simple applications +that do not want to optimize redisplay by distinguishing between +subareas of its window can just ignore all Expose events with nonzero +counts and perform full redisplays on events with zero counts. +@item X-event:major-code +@tab +The major_code member is set to the graphics request initiated by the +client and can be either X_CopyArea or X_CopyPlane. If it is +X_CopyArea, a call to XCopyArea initiated the request. If it is +X_CopyPlane, a call to XCopyPlane initiated the request. +@item X-event:minor-code +@tab +Not currently used. +@item X-event:border-width +@tab +For configure events, the width of the window's border, in pixels. +@item X-event:override-redirect +@tab +The override-redirect attribute of the window. Window manager clients +normally should ignore this window if it is #t. +@item X-event:from-configure +@tab +True if the event was generated as a result of a resizing of the +window's parent when the window itself had a win-gravity of +x:Unmap-Gravity. +@item X-event:value-mask +@tab +Indicates which components were specified in the ConfigureWindow +protocol request. The corresponding values are reported as given in the +request. The remaining values are filled in from the current geometry +of the window, except in the case of above (sibling) and detail +(stack-mode), which are reported as None and Above, respectively, if +they are not given in the request. +@item X-event:place +@tab +The window's position after the restack occurs and is either +x:Place-On-Top or x:Place-On-Bottom. If it is x:Place-On-Top, the +window is now on top of all siblings. If it is x:Place-On-Bottom, the +window is now below all siblings. +@item X-event:new +@tab +indicate whether the colormap for the specified window was changed or +installed or uninstalled and can be True or False. If it is True, the +colormap was changed. If it is False, the colormap was installed or +uninstalled. +@item X-event:format +@tab +Is 8, 16, or 32 and specifies whether the data should be viewed as a +list of bytes, shorts, or longs +@item X-event:request +@tab +Indicates the kind of mapping change that occurred and can be +@var{x:Mapping-Modifier}, @var{x:Mapping-Keyboard}, or +@var{x:Mapping-Pointer}. If it is @var{x:Mapping-Modifier}, the +modifier mapping was changed. If it is @var{x:Mapping-Keyboard}, the +keyboard mapping was changed. If it is @var{x:Mapping-Pointer}, the +pointer button mapping was changed. +@item X-event:first-keycode +@tab +The X-event:first-keycode is set only if the X-event:request was set to +@var{x:Mapping-Keyboard}. The number in X-event:first-keycode +represents the first number in the range of the altered mapping, and +X-event:count represents the number of keycodes altered. +@end multitable +@end defun + +@node Index, , Event, Top +@c @node Procedure and Macro Index, Variable Index, The Implementation, Top +@unnumbered Procedure and Macro Index + +This is an alphabetical list of all the procedures and macros in Xlibscm. + +@printindex fn + +@c @node Variable Index, Type Index, Procedure and Macro Index, Top +@unnumbered Variable Index + +This is an alphabetical list of all the global variables in Xlibscm. + +@printindex vr + +This is an alphabetical list of concepts introduced in this manual. + +@unnumbered Concept Index +@printindex cp + +@contents +@bye |