Elk/Xlib Reference Manual

Oliver Laumann


1.  Introduction  

      This manual lists the functions, special forms, and variables defined by the Xlib extension included in the Elk distribution. Most of the functions are directly equivalent to a function of the Xlib C library, so that the description need not be repeated. In such cases, only the name of the corresponding Xlib function is mentioned. Thus, you should have the Xlib - C Language X Interface manual within reach when using this reference manual.

      The functions listed in this document can be loaded by evaluating the expression

(require 'xlib).
in the interpreter's top level or in a Scheme program.

      The types of arguments of the procedures listed below are not described when they are obvious from the context or from the name. For instance, an argument named window is always of type window, an argument named atom is an object of type atom, etc. Arguments the names of which end in ``?'' are always of type boolean.

      If a function returns several items of the same type (for instance, a list of windows), the return value is a vector of objects of this type. If a function returns a collection of items of different types or of different semantics, the return value is a list of objects (or a pair). In this case, multiple-value-bind can be used to bind variables to the return values.

2.  Display Functions  

(display? x)

Returns #t iff x is an object of type display.

(open-display . name-of-display)

See XOpenDisplay. name-of-display is a string or a symbol. If no name is specified, a NULL name will be passed to XOpenDisplay.

(close-display display)

See XCloseDisplay. Finalizes all objects associated with the display, then closes the display.

(display-default-root-window display)
(display-root-window display)

See XDefaultRootWindow.

(display-default-colormap display)
(display-colormap display)

See XDefaultColormap. Returns the default colormap of the display's default screen.

(display-default-gcontext display)

See XDefaultGC. Returns the default graphics context of the display's default screen.

(display-default-depth display)

See XDefaultDepth. Returns the default depth of the display's default screen.

(display-default-screen-number display)

See XDefaultScreen. Returns an integer.

(display-cells display screen-number)

See XDisplayCells. Returns an integer.

(display-planes display screen-number)

See XDisplayPlanes. Returns an integer.

(display-string display)

See XDisplayString. Returns a string.

(display-vendor display)

See XServerVendor, XVendorRelease. Returns a pair; the car is a string (the vendor identification), and the cdr is an integer (the vendor release number).

(display-protocol-version display)

See XProtocolVersion, XProtocolRevision. Returns a pair of integers (the X protocol's major and minor version numbers).

(display-screen-count display)

See XScreenCount. Returns an integer.

(display-image-byte-order display)

See XImageByteOrder. Returns a symbol (lsb-first or msb-first).

(display-bitmap-unit display)

See XBitmapUnit. Returns an integer.

(display-bitmap-bit-order display)

See XBitmapBitOrder. Returns a symbol (lsb-first or msb-first).

(display-bitmap-pad display)

See XBitmapPad. Returns an integer.

(display-width display)
(display-height display)

See XDisplayWidth, XDisplayHeight. Returns the width/height of the display's default screen.

(display-width-mm display)
(display-height-mm display)

See XDisplayWidthMM, XDisplayHeightMM. Returns the width/height of the display's default screen in millimeters.

(display-motion-buffer-size display)

See XDisplayMotionBufferSize. Returns an integer.

(display-flush-output display)

See XFlush.

(display-wait-output display discard-events?)

See XSync.

(no-op display)

See XNoOp.

(list-depths display screen-number)

See XListDepths. Returns a vector of integers.

(list-pixmap-formats display)

See XListPixmapFormats. Returns a vector of lists of three integers (depth, bits per pixel, and scanline pad).

(set-after-function! display procedure)

See XSetAfterFunction. Returns the old after function. If procedure is #f, the current after function is disassociated from the display.

(after-function display)

Returns the after function currently associated with the given display (#f if there is none).

(synchronize display)

Sets the display's after function to display-wait-output.

3.  Window Functions  

(window? x)

Returns #t iff x is an object of type window.

(drawable? x)

Returns #t iff x is a ``drawable'' (window or pixmap).

(window-display window)

Returns the display associated with the window.

(create-window . args)

See XCreateWindow. This function is used to create a new window.

The number of arguments must be even. The 1st, 3rd, etc. argument is the name (a symbol) of an attribute to be set when the window is created, the 2nd, 4th, etc. argument is the corresponding value. The attributes can be specified in any order.

Attributes are x, y, width, height, border (each of which has an integer value), parent (the parent window), and all attributes that can be set by means of the set-window-attribute! functions below except sibling and stack-mode. The attributes parent, width, and height are mandatory. The default for x and y is 0, the default for border is 2.

(set-window-x! window value)
(set-window-y! window value)
(set-window-width! window value)
(set-window-height! window value)
(set-window-border-width! window value)
(set-window-sibling! window value)
(set-window-stack-mode! window value)
(set-window-background-pixmap! window value)
(set-window-background-pixel! window value)
(set-window-border-pixmap! window value)
(set-window-border-pixel! window value)
(set-window-bit-gravity! window value)
(set-window-gravity! window value)
(set-window-backing-store! window value)
(set-window-backing-planes! window value)
(set-window-backing-pixel! window value)
(set-window-save-under! window value)
(set-window-event-mask! window value)
(set-window-do-not-propagate-mask! window value)
(set-window-override-redirect! window value)
(set-window-colormap! window value)
(set-window-cursor! window value)

See XConfigureWindow, XChangeWindowAttributes. Set the sibling window, stacking mode, background pixmap, background pixel, border pixel, cursor, and other attributes (see the window- functions below) of the specified window.

The stacking mode is a symbol (above, below, top-if, bottom-if, opposite). The value argument to set-window-sibling! must be a window, set-window-background-pixmap! expects a pixmap, set-window-background-pixel! and set-window-border-pixel! expect a pixel, and set-window-cursor! expects a cursor argument. For the types of the value argument of the other functions see the return values of the window- functions below.

(window-x window)
(window-y window)
(window-width window)
(window-height window)
(window-border-width window)
(window-depth window)
(window-visual window)
(window-root window)
(window-class window)
(window-bit-gravity window)
(window-gravity window)
(window-backing-store window)
(window-backing-planes window)
(window-backing-pixel window)
(window-save-under window)
(window-colormap window)
(window-map-installed window)
(window-map-state window)
(window-all-event-masks window)
(window-your-event-mask window)
(window-do-not-propagate-mask window)
(window-override-redirect window)
(window-screen window)

See XGetWindowAttributes. Returns the x and y coordinates, width, height, border width, depth, visual, root window, class, bit gravity, window gravity, backing store availability, backing planes, backing pixel, save under availability, colormap, colormap installation information, map state, global event mask, local event mask, ``do-not-propagate'' mask, override redirect attribute, and screen of the specified window.

window-visual and window-screen always return the empty list in the current release of the software. window-root returns a window. window-class returns a symbol (input-output, input-only). window-bit-gravity returns a symbol (forget, north-west, north, north-east, west, center, east, south-west, south, south-east, static). window-gravity returns a symbol (same as window-bit-gravity with unmap instead of forget). window-backing-store returns a symbol (not-useful, when-mapped, always). window-backing-planes and window-backing-pixel return a pixel. window-save-under, window-map-installed and window-override-redirect return #t or #f. window-colormap returns a colormap. window-map-state returns a symbol (unmapped, unviewable, viewable). window-all-event-masks, window-your-event-mask, and window-do-not-propagate-mask return a list of symbols (event mask names such as enter-window, pointer-motion, etc.). All other functions return an integer.

(drawable-root drawable)
(drawable-x drawable)
(drawable-y drawable)
(drawable-width drawable)
(drawable-height drawable)
(drawable-border-width drawable)
(drawable-depth drawable)

See XGetGeometry. Returns the root window, x and y coordinates, width, height, border width, and depth of the specified drawable. drawable-root returns a window, all other functions return an integer.

(map-window window)

See XMapWindow.

(unmap-window window)

See XUnmapWindow.

(destroy-window window)

See XDestroyWindow.

(destroy-subwindows window)

See XDestroySubwindows.

(map-subwindows window)

See XMapSubwindows.

(unmap-subwindows window)

See XUnmapSubwindows.

(circulate-subwindows window direction)

See XCirculateSubwindows. direction is a symbol (raise-lowest or lower-highest).

(clear-window window)

Performs a clear-area on the entire window.

(raise-window window)

See XRaiseWindow.

(lower-window window)

See XLowerWindow.

(restack-windows list-of-windows)

See XRestackWindows.

(query-tree window)

See XQueryTree. Returns a list of three elements: root window, parent window, and children (a vector of windows).

(translate-coordinates src-window x y dst-window)

See XTranslateCoordinates. Returns a list of three elements: destination x and y, and child window.

(query-pointer window)

See XQueryPointer. Returns a list of eight elements: x and y, a boolean indicating whether the pointer is on the same screen as the specified window, the root window, the root window's x and y coordinates, the child window, and a list of modifier names (see grab-button below).

4.  Window Property and Selection Functions  

(atom? x)

Returns #t iff x is an object of type atom.

(make-atom value)

Returns an atom with the given value. value is an integer.

(intern-atom display name)

See XInternAtom. name is a string or a symbol. The atom is created if it does not yet exist.

(find-atom display name)

See XInternAtom. name is a string or a symbol. If the atom does not exist, the symbol none is returned.

(atom-name display atom)

See XGetAtomName. Returns a string.

(list-properties window)

See XListProperties. Returns a vector of atoms.

(get-property window property request-type offset length delete?)

See XGetWindowProperty. property is an object of type atom. request-type is an atom or #f in which case AnyPropertyType will be used. offset and length are integers. An error is signaled if XGetWindowProperty fails.

get-property returns a list of four items: the ``actual type'' (an atom), the format (an integer), the data (if any, the empty list otherwise), and the number of bytes left (an integer).

The data returned is either a string (if the format indicates 8-bit data) or a vector of integers.

(change-property window property type format mode data)

See XChangeProperty. property and type are atoms. format is an integer (8, 16, or 32). If format is 8 data must be a string, otherwise a vector of integers of the appropriate size. An error is signaled if the value of format is invalid or if data holds an integer that exceeds the size indicated by format. mode is a symbol (replace, prepend, or append).

(delete-property window property)

See XDeleteProperty.

(rotate-properties window vector-of-atoms delta)

See XRotateWindowProperties. delta is the amount to rotate (an integer).

(set-selection-owner! display selection owner time)

See XSetSelectionOwner. selection is an atom; owner is a window; time is an integer or the symbol now (for CurrentTime).

(selection-owner display selection)

See XGetSelectionOwner.

(convert-selection selection target property requestor-window time)

See XConvertSelection. selection and target are atoms; property is an atom or the symbol none.

5.  Colormap Functions  

(color? x)

Returns #t iff x is an object of type color.

(make-color r g b)

Returns an object of type color with the specified RGB components. r, g, and b are reals in the range 0.0 to 1.0.

(color-rgb-values color)

Returns a list of three elements, the RGB components of the given color (see make-color above).

(query-color colormap pixel)

See XQueryColor.

(query-colors colormap pixels)

See XQueryColors. pixels is a vector of pixels. Returns a vector of colors of the same size as pixels.

(lookup-color colormap color-name)

See XLookupColor. color-name is a string or a symbol. Returns a pair of colors.

(alloc-color colormap color)

See XAllocColor. Returns a pixel (or #f in case of an error).

(alloc-named-color colormap color-name)

See AllocNamedColor. color-name is a string or a symbol. Returns a list of three elements: a pixel, and two colors (the closest color and the exact color); or #f in case of an error.

(colormap? x)

Returns #t iff x is an object of type colormap.

(colormap-display colormap)

Returns the display associated with the given colormap.

(free-colormap colormap)

See XFreeColormap.

6.  Pixel Functions  

(pixel? x)

Returns #t iff x is an object of type pixel.

(pixel-value pixel)

Returns the value of the pixel as an unsigned integer.

(black-pixel display)
(white-pixel display)

See XBlackPixel, XWhitePixel. Returns the black/white pixel of the display's default screen.

7.  Pixmap Functions  

(pixmap? x)

Returns #t iff x is an object of type pixmap.

(pixmap-display pixmap)

Returns the display associated with the pixmap.

(free-pixmap pixmap)

See XFreePixmap.

(create-pixmap drawable width height depth)

See XCreatePixmap.

(create-bitmap-from-data window data width height)

See XCreateBitmapFromData. data is a string. (* width height) must not exceed the number of bits in string.

(create-pixmap-from-bitmap-data win data width height foregrnd backgrnd depth)

See XCreatePixmapFromBitmapData. data is a string. (* width height) must not exceed the number of bits in string.

(read-bitmap-file drawable filename)

See XReadBitmapFile. filename is a string or a symbol. If XReadBitmapFile signals an error, read-bitmap-file returns a symbol (open-failed, file-invalid, or no-memory). If it succeeds, read-bitmap-file returns a list of five elements: the bitmap (an object of type pixmap), the width and height of the bitmap, and the x and y coordinates of the hotspot.

(write-bitmap-file filename pixmap width height x-hot y-hot)

See XWriteBitmapFile. filename is a string or a symbol. x-hot and y-hot are optional (-1 is used if they are omitted), but either both or none of them must be given. write-bitmap-file returns a symbol (success, open-failed, file-invalid, or no-memory).

8.  Graphics Context Functions  

(gcontext? x)

Returns #t iff x is an object of type gcontext.

(gcontext-display gcontext)

Returns the display associated with the given GC.

(create-gcontext . args)

See XCreateGC. This function is used to create a new GC.

The number of arguments must be even. The 1st, 3rd, etc. argument is the name (a symbol) of an attribute to be set when the graphics context is created, the 2nd, 4th, etc. argument is the corresponding value. The attributes can be specified in any order.

Attributes are window (a drawable; mandatory) and all the attributes that can be set by the set-gcontext-attribute! functions below.

(copy-gcontext gcontext drawable)

See XCopyGC. Returns a copy of gcontext (associated with the specified drawable).

(free-gcontext gcontext)

See XFreeGC.

(query-best-size display width height shape)

See XQueryBestSize. shape is a symbol (cursor, tile, or stipple). Returns a pair of integers (result width and result height).

(query-best-cursor display width height)
(query-best-tile display width height)
(query-best-stipple display width height)

See XQueryBestSize. Invokes query-best-size with the given arguments and a shape of cursor, tile, or stipple, respectively.

(gcontext-function gcontext)
(gcontext-plane-mask gcontext)
(gcontext-foreground gcontext)
(gcontext-background gcontext)
(gcontext-line-width gcontext)
(gcontext-line-style gcontext)
(gcontext-cap-style gcontext)
(gcontext-join-style gcontext)
(gcontext-fill-style gcontext)
(gcontext-fill-rule gcontext)
(gcontext-arc-mode gcontext)
(gcontext-tile gcontext)
(gcontext-stipple gcontext)
(gcontext-ts-x gcontext)
(gcontext-ts-y gcontext)
(gcontext-subwindow-mode gcontext)
(gcontext-exposures gcontext)
(gcontext-clip-x gcontext)
(gcontext-clip-y gcontext)
(gcontext-dash-offset gcontext)

See XGetGCValues. Returns the logical operation, plane mask, foreground and background pixel value, line width and style, cap and join style, fill style and rule, arc mode, tiling and stippling pixmap, tiling x- and y-origin, subwindow mode, clipping x- and y-origin, and dashed line information of the specified graphics context.

gcontext-function returns a symbol (clear, and, and-reverse, copy, and-inverted, no-op, xor, or, nor, equiv, invert, or-reverse, copy-inverted, nand, or set). gcontext-plane-mask, gcontext-foreground, and gcontext-background return a pixel. gcontext-tile and gcontext-stipple return a pixmap. The line style is a symbol (solid, dash, double-dash); the cap style is a symbol (not-last, butt, round, projecting); the join style is a symbol (miter, round, bevel); the fill style is a symbol (solid, tiled, stippled, opaque-stippled); the fill rule is a symbol (even-odd, winding); the arc mode is a symbol (chord, pie-slice); the subwindow-mode is a symbol (clip-by-children, include-inferiors). gcontext-exposures returns a boolean. All other functions return an integer.

(set-gcontext-function! gcontext value)
(set-gcontext-plane-mask! gcontext value)
(set-gcontext-foreground! gcontext value)
(set-gcontext-background! gcontext value)
(set-gcontext-line-width! gcontext value)
(set-gcontext-line-style! gcontext value)
(set-gcontext-cap-style! gcontext value)
(set-gcontext-join-style! gcontext value)
(set-gcontext-fill-style! gcontext value)
(set-gcontext-fill-rule! gcontext value)
(set-gcontext-arc-mode! gcontext value)
(set-gcontext-tile! gcontext value)
(set-gcontext-stipple! gcontext value)
(set-gcontext-ts-x! gcontext value)
(set-gcontext-ts-y! gcontext value)
(set-gcontext-font! gcontext value)
(set-gcontext-subwindow-mode! gcontext value)
(set-gcontext-exposures! gcontext value)
(set-gcontext-clip-x! gcontext value)
(set-gcontext-clip-y! gcontext value)
(set-gcontext-clip-mask! gcontext value)
(set-gcontext-dash-offset! gcontext value)

See XChangeGC. Sets the logical operation, plane mask, foreground and background pixel value, line width and style, cap and join style, fill style and rule, arc mode, tiling and stippling pixmap, tiling x- and y-origin, font, subwindow mode, clipping x- and y-origin, clipping bitmap, and dashed line information for the specified graphics context.

The value argument to set-gcontext-font! is a font, and the value argument to set-gcontext-clip-mask! is a pixmap. For the types of the value argument of the other functions see the return values of the gcontext- functions above.

(set-gcontext-clip-rectangles! gcontext x y rectangles ordering)

See XSetClipRectangles. x and y are integers (the coordinates of the clip-mask origin). rectangles is a vector of lists of four integers (x, y, width, and height of each rectangle). ordering is a symbol (unsorted, y-sorted, yx-sorted, or yx-banded).

(set-gcontext-dashlist! gcontext dash-offset dash-list)

See XSetDashes. dash-offset is an integer. dash-list is a vector of integers between 0 and 255.

9.  Graphics Functions  

(clear-area window x y width height exposures?)

See XClearArea.

(copy-area src-drawable gcontext src-x src-y width height dst-drawable dst-x dst-y)

See XCopyArea.

(copy-plane src-drawable gcontext plane src-x src-y width height dst-drawable dst-x dst-y)

See XCopyPlane. plane is an integer. An error is signaled unless exactly one bit is set in plane.

(draw-point drawable gcontext x y)

See XDrawPoint.

(draw-points drawable gcontext vector-of-points relative?)

See XDrawPoints. vector-of-points is a vector of pairs consisting of two integers (the x and y coordinates). If relative? is #t, CoordModePrevious is passed to XDrawPoints, otherwise CoordModeOrigin is used.

(draw-line drawable gcontext x1 y1 x2 y2)

See XDrawLine.

(draw-lines drawable gcontext vector-of-points relative?)

See XDrawLines. See draw-points above.

(draw-segments drawable gcontext vector-of-points)

See XDrawSegments. vector-of-points is a vector of lists of four integers (x1, y1, x2, and y2).

(draw-rectangle drawable gcontext x y width height)

See XDrawRectangle.

(fill-rectangle drawable gcontext x y width height)

See XFillRectangle.

(draw-rectangles drawable gcontext vector-of-rectangles)

See XDrawRectangles. vector-of-rectangles is a vector of lists of four integers (x, y, width, and height of each rectangle).

(fill-rectangles drawable gcontext vector-of-rectangles)

See XFillRectangles. See draw-rectangles above.

(draw-arc drawable gcontext x y width height angle1 angle2)

See XDrawArc.

(fill-arc drawable gcontext x y width height angle1 angle2)

See XFillArc.

(draw-arcs drawable gcontext vector-of-data)

See XDrawArcs. vector-of-data is a vector of lists of six integers (x, y, width, height, angle1, and angle2).

(fill-arcs drawable gcontext vector-of-data)

See XFillArcs. See draw-arcs above.

(fill-polygon drawable gcontext vector-of-points relative? shape)

See XFillPolygon. See draw-points above. shape is a symbol (complex, non-convex, or convex).

10.  Font Functions  

(font? x)

Returns #t iff x is an object of type font.

(font-display)

Returns the display associated with the given font.

(open-font display font-name)

See XLoadQueryFont. font-name is a string or a symbol.

(close-font font)

See XUnloadFont.

(font-name font)

Returns the name of the specified font (a string) or #f if the name could not be determined (e.g. when the font has been obtained by a call to gcontext-font).

(gcontext-font gcontext)

Calls XQueryFont with the GC obtained by XGContextFromGC. Only a limited number of functions can be applied to a font returned by gcontext-font, since it has neither a name nor a font-ID.

(list-font-names display pattern)

See XListFonts. pattern is a string or a symbol. Returns a vector of font names (strings).

(list-fonts display pattern)

See XListFontsWithInfo. pattern is a string or a symbol. Returns a vector of fonts. These fonts are ``pseudo fonts'' which do not have a font-ID. A pseudo font is loaded automatically and turned into a ``real'' font the first time it is passed to a function that makes use of the font-ID.

(font-direction font)
(font-min-byte2 font)
(font-max-byte2 font)
(font-min-byte1 font)
(font-max-byte1 font)
(font-all-chars-exist? font)
(font-default-char font)
(font-ascent font)
(font-descent font)

These functions return the font direction as a symbol (left-to-right or right-to-left), the first and last character (as an integer), the first and last row (integer), an indication whether all characters have non-zero size (boolean), the default character (integer), and the ascent and descent (integer) of the specified font.

(char-rbearing font index)
(char-lbearing font index)
(char-width font index)
(char-ascent font index)
(char-descent font index)

These functions return the metrics of the character specified by the integer index of the given font. Each function returns an integer. font can be a 1-byte as well as a 2-byte font.

(max-char-lbearing font)
(max-char-rbearing font)
(max-char-width font)
(max-char-ascent font)
(max-char-descent font)

These functions return the maximum metrics over all characters in the specified font. Each function returns an integer.

(min-char-lbearing font)
(min-char-rbearing font)
(min-char-width font)
(min-char-ascent font)
(min-char-descent font)

These functions return the minimum metrics over all characters in the specified font. Each function returns an integer.

(font-properties font)

Returns a vector of font properties; each element of the vector is a pair consisting of the property name (an atom) and an unsigned integer (the value of the property).

(font-property font property-name)

Returns the value of the specified property associated with the specified font. property-name is a string or a symbol.

(font-path display)

See XGetFontPath. Returns the current font path as a vector of strings.

(set-font-path! display path)

See XSetFontPath. path is a list; each element is a string or a symbol.

11.  Text Metrics and Text Drawing Functions  

(text-width font text format)

See XTextWidth, XTextWidth16. format indicates whether 8-bit or 16-bit text is used; it is either the symbol 1-byte or the symbol 2-byte. text is a vector of integers; the integers must not exceed the size indicated by the format.

(extents-lbearing font text format)
(extents-rbearing font text format)
(extents-width font text format)
(extents-ascent font text format)
(extents-descent font text format)

See XTextExtents, XTextExtents16. These functions are used to compute the overall metrics of an 8-bit or 16-bit character string. Each function returns an integer. For the format of text and format see text-width above.

(draw-image-text drawable gcontext x y text format)

See XDrawImageString, XDrawImageString16. See text-width above.

(draw-poly-text drawable gcontext x y text format)

See XDrawText, XDrawText16. See text-width above. text is a vector of integers with intermixed objects of type font.

(translate-text string)

Converts the string into a representation suitable as an argument to text-width, draw-image-text, or draw-poly-text (a vector of integers obtained by applying char->integer to the characters of the string argument).

12.  Cursor Functions  

(cursor? x)

Returns #t iff x is an object of type cursor.

(cursor-display cursor)

Returns the display associated with the given cursor.

(free-cursor)

See XFreeCursor.

(create-cursor src mask x y foreground background)

See XCreatePixmapCursor. src and mask are pixmaps. mask can be the symbol none.

(create-glyph-cursor src src-char mask mask-char foreground background)

See XCreateGlyphCursor. src and mask are fonts. mask can be the symbol none. The display is obtained from src. src-char and mask-char are integers.

(create-font-cursor display src-char)

See XCreateGlyphCursor. Calls create-glyph-cursor with the font named ``cursor'', the specified src-char, a mask-char of (1+ src-char), black foreground, and white background.

(recolor-cursor cursor foreground background)

See XRecolorCursor

(define-cursor window cursor)

Synonym for (set-window-cursor! window cursor).

(undefine-cursor window)

Synonym for (set-window-cursor! window 'none).

13.  Grab Functions  

(grab-pointer window owner? events ptr-sync? kbd-sync? confine-to cursor time)

See XGrabPointer. window and confine-to are windows. events is a list of symbols (event mask names, such as enter-window, pointer-motion, etc.). ptr-sync? and kbd-sync? determine whether synchronous or asynchronous grab mode is to be used. time is an integer or the symbol now (for CurrentTime). grab-pointer returns a symbol (success, not-viewable, already-grabbed, frozen, or invalid-time).

(ungrab-pointer display time)

See XUngrabPointer.

(grab-button win button mod owner? events ptr-sync? kbd-sync? confine-to cursor)

See XGrabButton. button is a symbol (button1 ... button5, or any-button). mod (modifiers) is a list of symbols (shift, lock, control, mod1 ... mod5, button1 ... button5, or any-modifier). For the other arguments see grab-pointer above.

(ungrab-button window button modifiers)

See XUngrabButton. See grab-button above.

(change-active-pointer-grab display events cursor time)

See XChangeActivePointerGrab. events is a list of symbols (event mask names, such as enter-window, pointer-motion, etc.).

(grab-keyboard window owner? pointer-sync? keyboard-sync? time)

See XGrabKeyboard. For a description of the arguments and the return value see grab-pointer above.

(ungrab-keyboard display time)

See XUngrabKeyboard.

(grab-key window key modifiers owner? pointer-sync? keyboard-sync?)

See XGrabKey. key is a keycode (an integer) or the symbol any. For the other arguments see grab-pointer above.

(ungrab-key window key modifiers)

See XUngrabKey. See grab-key above.

(allow-events display mode time)

See XAllowEvents. mode is a symbol (async-pointer, sync-pointer, replay-pointer, async-keyboard, sync-keyboard, replay-keyboard, async-both, or sync-both).

(grab-server display)

See XGrabServer.

(ungrab-server display)

See XUngrabServer.

(with-server-grabbed display . body-forms)

This macro performs a grab-server on the specified display, evaluates the body-forms in order, and then ungrabs the server. The macro body is guarded by a dynamic-wind to ensure that the ungrab-server is performed when a body-form calls a continuation created outside the macro, and that it is grabbed again when the body is re-entered at a later point in time. with-server-grabbed returns the value of the last body-form.

14.  Window Manager Functions  

(reparent-window window parent-window x y)

See XReparentWindow.

(install-colormap colormap)

See XInstallColormap.

(uninstall-colormap colormap)

See XUninstallColormap.

(list-installed-colormaps window)

See XListInstalledColormaps. Returns a vector of colormaps.

(set-input-focus display window revert-to time)

See XSetInputFocus. window can be the symbol pointer-root. revert-to is a symbol (none, pointer-root, or parent). time is an integer or the symbol now.

(input-focus display)

See XGetInputFocus. Returns a pair the car of which is a window, and the cdr is a symbol (none, pointer-root, or parent).

(general-warp-pointer display dst-win dst-x dst-y src-win src-x src-y src-width src-height)

See XWarpPointer.

(warp-pointer dst-window dst-x dst-y)

See XWarpPointer. Invokes general-warp-pointer with the display associated with the dst-window, the dst-window, dst-x, dst-y, a src-window of none, and zero source coordinates and dimensions.

(warp-pointer-relative display x-offset y-offset)

See XWarpPointer. Invokes general-warp-pointer with the specified display, a dst-window of none, x-offset, y-offset, a src-window of none, and zero source coordinates and dimensions.

(bell display . percent)

See XBell. percent is an integer between -100 and 100. If percent is omitted, 0 is used.

(set-access-control display enable?)

See XSetAccessControl.

(change-save-set window mode)

See XChangeSaveSet. mode is a symbol (insert or delete).

(set-close-down-mode display mode)

See XSetCloseDownMode. mode is a symbol (destroy-all, retain-permanent, or retain-temporary).

(get-pointer-mapping display)

See XGetPointerMapping. Returns a vector of 256 integers.

(set-pointer-mapping display mapping)

See XSetPointerMapping. mapping is a vector of integers. Returns #t if XSetPointerMapping succeeds, #f otherwise.

15.  Event Handling Functions  

(event-listen display wait?)

See XPending, XPeekEvent. Returns the size of the display's event queue. If wait? is true and the event queue is empty, event-listen flushes the output buffer and blocks until an event is received from the server.

(get-motion-events window from-time to-time)

See XGetMotionEvents. from-time and to-time are integers or the symbol now. get-motion-events returns a vector of lists of three elements: a time stamp (an integer or the symbol now), and the x and y coordinates (integers).

(handle-events display discard? peek? . clauses)

See XNextEvent, XPeekEvent, XIfEvent, XPeekIfEvent. handle-events is a special form. Each clause is of the form (guard function); guard is either an event name (a symbol, e.g. key-press or exposure), a list of event names, or the symbol else. handle-events gets the next event from the specified display. Then the event type is matched against each event name in each guard in order. When a match occurs, the corresponding function is invoked with the name of the event being dispatched (a symbol) and other, event specific arguments (see below). When no clause matches and an else clause is present, the function from this clause is invoked. handle-events loops until a function returns a value not equal to #f in which case handle-events returns this value.

If discard? is true, unprocessed events (i.e. events for which no matching clause has been found) are removed from the event queue, otherwise they are left in place. If peek? is true, processed events are not removed from the event queue.

The following list gives all event specific arguments for each event type. The first argument is always the event type (a symbol).

In the following list, arguments with names of the form something-window (or simply window) are always of type window; arguments with names of the form something-atom (or simply atom) are always of type atom. time is an integer or the symbol now. x, y, width, height, border-width, x-root, y-root, count, major-code, minor-code, and keycode are integers. state is a list of symbols (shift, lock, control, mod1 ... mod5, button1 ... button5). button is one of the symbols button1 ... button5, button-mask is a list of one or more of these symbols. cross-mode is a symbol (normal, grab, ungrab). place is a symbol (top or bottom).

key-press, key-release:
window, root-window, sub-window, time, x, y, x-root, y-root, state, keycode, same-screen?.
button-press, button-release:
window, root-window, sub-window, time, x, y, x-root, y-root, state, button, same-screen?.
motion-notify:
window, root-window, sub-window, time, x, y, x-root, y-root, state, is-hint?, same-screen?.
enter-notify, leave-notify:
window, root-window, sub-window, time, x, y, x-root, y-root, cross-mode, cross-detail (one of the symbols ancestor, virtual, inferior, nonlinear, nonlinear-virtual), same-screen?, focus?, button-mask.
focus-in, focus-out:
window, cross-mode, focus-detail (one of the symbols ancestor, virtual, inferior, nonlinear, nonlinear-virtual, pointer, pointer-root, none).
keymap-notify:
window, keymap (a string of length 32).
expose:
window, x, y, width, height, count.
graphics-expose:
window, x, y, width, height, count, major-code, minor-code.
no-expose:
window, major-code, minor-code.
visibility-notify:
window, visibility-state (one of the symbols unobscured, partially-obscured, fully-obscured).
create-notify:
parent-window, window, x, y, width, height, border-width, override-redirect?.
destroy-notify:
event-window, window.
unmap-notify:
event-window, window, from-configure.
map-notify:
event-window, window, override-redirect.
map-request:
parent-window, window.
reparent-notify:
event-window, parent-window, window, x, y, override-redirect.
configure-notify:
event-window, window, x, y, width, height, border-width, above-window, override-redirect?.
configure-request:
parent-window, window, x, y, width, height, border-width, above-window, stack-mode (see set-window-stack-mode! above), value-mask (an integer).
gravity-notify:
event-window, window, x, y.
resize-request:
window, width, height.
circulate-notify:
event-window, window, place.
circulate-request:
parent-window, window, place.
property-notify:
window, atom, time, property-state (one of the symbols new-value, deleted).
selection-clear:
window, selection-atom, time.
selection-request:
owner-window, requestor-window, selection-atom, target-atom, property-atom, time.
selection-notify:
requestor-window, selection-atom, target-atom, property-atom, time.
colormap-notify:
window, colormap, new?, colormap-installed?.
client-message:
window, message type (an atom), message data (a string of length 20, or a vector of 10 or 5 integer numbers, or, if the format field of the event is wrong, the format as a number).
mapping-notify:
window, request (one of the symbols modifier, keyboard, pointer), keycode, count.

16.  Inter-Client Communication Functions  

(iconify-window window screen-number)

See XIconifyWindow.

(withdraw-window window screen-number)

See XWithdrawWindow.

(reconfigure-wm-window . args)

See XReconfigureWMWindow.

For the format of the arguments see create-window above. Mandatory attributes are window and screen-number (an integer). Optional attributes are x, y, width, height border-width (integers), sibling (a window), and stack-mode (a symbol; one of above, below, top-if, bottom-if, opposite).

(get-text-property window atom)

See XGetTextProperty. Returns a text property as a list of strings or #f if the specified property does not exist.

(set-text-property! window value atom)

See XSetTextProperty. value is a list holding the items of the text property (strings or symbols).

(wm-protocols window)

See XGetWMProtocols. Returns a vector of atoms.

(set-wm-protocols! window protocols)

See XSetWMProtocols. protocols is a vector of atoms.

(wm-name window)

See XGetTextProperty. Returns the WM_NAME property as a list of strings or #f if it does not exist.

(set-wm-name! window name)

See XSetTextProperty. name is a list of strings or symbols.

(wm-icon-name window)

See XGetTextProperty. Returns the WM_ICON_NAME property as a list of strings or #f if it does not exist.

(set-wm-icon-name! window name)

See XSetTextProperty. name is a list of strings or symbols.

(wm-client-machine window)

See XGetTextProperty, XGetWMClientMachine. Returns the WM_CLIENT_MACHINE property as a list of strings or #f if it does not exist.

(set-wm-client-machine! window value)

See XSetTextProperty, XSetWMClientMachine. value is a list of strings or symbols.

(wm-class window)

See XGetClassHint. Returns a pair (name and class) each component of which is either a string or #f.

(set-wm-class! window name class)

See XSetClassHint. name and class are strings or symbols.

(wm-command window)

See XGetCommand (in X11 Release 4 or newer releases). Returns the value of the WM_COMMAND property of the given window as a list of strings.

(set-wm-command! window command)

See XSetCommand. command is a list; each element is either a string or a symbol.

(transient-for window)

See XGetTransientForHint. Returns a window.

(set-transient-for! window property-window)

See XSetTransientForHint.

(wm-normal-hints window)

See XGetWMSizeHints. Returns a list of hints. Each element is set to the empty list if the corresponding hint has not been set for the specified window.

The elements of the list correspond to the following hints (in this order): x, y, width, and height (program specified); x, y, width and height (user specified); min-width and min-height; max-width and max-height; width-inc and height-inc; min-aspect-x, min-aspect-y, max-aspect-x and max-aspect-y; base-width and base-height; and gravity. All elements are integers except for the value of gravity which is a symbol (see the window-gravity procedure above).

(set-wm-normal-hints! . args)

See XSetWMSizeHints. For the format of the arguments see create-window above. Attributes are window (mandatory) and the names of the hints listed under wm-normal-hints above.

(wm-hints window)

See XGetWMHints. Returns a list of hints. Each element is set to the empty list if the corresponding hint has not been set for the specified window.

The elements of the list correspond to the following hints (in this order): input?, initial-state, icon-pixmap, icon-window, icon-x, icon-y, icon-mask, and window-group. The value of input? is a boolean. initial-state is a symbol (dont-care, normal, zoom, iconic, inactive). The values of icon-pixmap and icon-mask are pixmaps. icon-window and window-group are windows. icon-x and icon-y are integers.

(set-wm-hints! . args)

See XSetWMHints. For the format of the arguments see create-window above. Attributes are window (mandatory) and the names of the hints listed under wm-hints above.

(icon-sizes window)

See XGetIconSizes. Returns a vector of lists of six integers (min-width, min-height, max-width, max-height, width-inc, and height-inc).

(set-icon-sizes! window icon-sizes)

See XSetIconSizes. icon-sizes is a vector of lists of six integers (see icon-sizes above).

17.  Keyboard Utility Functions  

(display-min-keycode display)
(display-max-keycode display)

Returns the minimum/maximum keycode (an integer) for the given display.

(display-keysyms-per-keycode display) Returns the number of keysyms per keycode for the given display.

(string->keysym string)

See XStringToKeysym. string is a string or a symbol. Returns an integer if XStringToKeysym succeeds, #f otherwise.

(keysym->string keysym)

See XKeysymToString. keysym is an integer. Returns #f if XKeysymToString fails.

(keycode->keysym display keycode index)

See XKeycodeToKeysym. keycode and index are integers.

(keysym->keycode display keysym)

See XKeysymToKeycode. keysym is an integer.

(lookup-string display keycode mask)

See XLookupString. keycode is an integer. mask is a list of symbols (shift, lock, control, mod1 ... mod5, button1 ... button5, or any-modifier).

(rebind-keysym display keysym modifiers string)

See XRebindKeysym. keysym is an integer. modifiers is a vector of integers.

(refresh-keyboard-mapping window type)

See XRefreshKeyboardMapping. type is a symbol (modifier, keyboard, or pointer). Invokes XRefreshKeyboardMapping with a faked event structure holding the specified window and request type.

18.  Other Utility Functions  

(xlib-release-4-or-later?)

Returns always #t.

(xlib-release-5-or-later?)

Returns #t iff the Xlib extension is linked together with the X11 Release 5 Xlib or later versions of the Xlib.

(xlib-release-6-or-later?)

Returns #t iff the Xlib extension is linked together with the X11 Release 6 Xlib or later versions of the Xlib.

(get-default display program option)

See XGetDefault. program and option are strings or symbols. Returns a string of #f if the option does not exist for the specified program.

(resource-manager-string display)

See XResourceManagerString. Returns a string or #f if the RESOURCE_MANAGER property does not exist on the root window.

(parse-geometry string)

See XParseGeometry. Returns a list of six elements: two booleans indicating whether x or or y are negative and four integers (x, y, width, and height). Each of the elements can be #f to indicate that the respective value was not found in the string.

(parse-color colormap string)

See XParseColor. Returns an object of type color or #f if XParseColor fails.

(store-buffer display bytes buffer)

See XStoreBuffer. bytes is a string; buffer is an integer between 0 and 7.

(store-bytes display bytes)

See XStoreBytes. bytes is a string.

(fetch-buffer display buffer)

See XFetchBuffer. buffer is an integer between 0 and 7. Returns a string.

(fetch-bytes display)

See XFetchBytes. Returns a string.

(rotate-buffers display delta)

See XRotateBuffers. delta is an integer (the amount to rotate the buffers).

(with object . body-forms)

with is a macro. object must be a drawable, a graphics context, or a font. The body-forms are evaluated in order; with returns the value of the last body-form.

Within the scope of the with, the first call to an accessor function accessing object (such as window-attribute or font-attribute) causes the result of the corresponding Xlib function to be retained in a cache; subsequent calls just return the value from the cache. Likewise, calls to Xlib functions for mutator functions modifying object (such as set-window-attribute!) are delayed until exit of the with body or until an accessor function is called and the cached data for this accessor function has been invalidated by the call to a mutator function.

19.  Server Extension Functions  

(list-extensions display)

See XListExtensions. Returns a vector of strings.

(query-extension display name)

See XQueryExtension. name is a string or a symbol. Returns a list of three elements: the major opcode (an integer) or #f if the extension has no major opcode, the base event type code (an integer) of #f if the extension has no additional event types, and the base error code (an integer) of #f if the extension has no additional error codes. query-extension returns #f if the specified extension is not present.

20.  Error Handling  

x-error-handler

See XSetErrorHandler. If an error event is received and the global variable x-error-handler is bound to a compound procedure, this procedure is invoked with the following arguments: a display, the serial number of the failed request (an integer), the error code (either an integer or one of the symbols bad-request, bad-value, bad-window, bad-pixmap, bad-atom, bad-cursor, bad-font, bad-match, bad-drawable, bad-access, bad-alloc, bad-color, bad-gcontext, bad-id-choice, bad-name, bad-length, or bad-implementation), the major and minor op-code of the failed request (integers), and a resource-ID (an integer).

If an error event is received and this variable is not bound to a compound procedure, the Xlib default error handler is invoked. The initial value of this variable is the empty list.

x-fatal-error-handler

See XSetIOErrorHandler. If a fatal I/O error occurs and the global variable x-fatal-error-handler is bound to a compound procedure, this procedure is invoked with a display as argument. The procedure must invoke exit. If a fatal error occurs and this variable is not bound to a compound procedure, or if the procedure returns, the Xlib default fatal error handler is invoked and the interpreter terminates with an exit code of 1. The initial value of this variable is the empty list.

21.  Interaction with the Garbage Collector  

      The Scheme garbage collector destroys objects of type colormap, cursor, display, font, gcontext, pixmap, or window that are not longer accessible from within the Scheme program. This is done by invoking the function free-colormap, free-cursor, close-display, close-font, free-gcontext, free-pixmap, or destroy-window, respectively, with the object to be destroyed as an argument.

      The garbage collector only destroys objects that have been created from with the Scheme program (by functions like create-pixmap or open-display). Objects that have been obtained from the Xlib through functions like display-default-colormap (and are owned by the Xlib internals), are ignored by the garbage collector.

      Programmers must make sure that an object is accessible during the object's entire lifetime, otherwise future runs of the garbage collector can result in undesired termination of the object. One must be especially careful when results of functions that create new objects (such as create-window) are ignored or assigned to local variables as in

(define dpy (open-display))
(define root (display-root-window dpy))
(do ((x 0 (+ x 10)) (y 0 (+ y 10))) ((= x 50))
  (let ((win
          (create-window 'parent root 'x x 'y y 'width 20 'height 20)))
    (manage-window win)))

      In this example, after termination of the do-loop, the garbage collector will destroy the newly created windows, as they are not accessible from within the program. If this is not desired, the windows could be put into a variable (for instance, be consed into a list) that is defined outside of the body of the loop.

Table of Contents

Introduction
Display Functions
Window Functions
Window Property and Selection Functions
Colormap Functions
Pixel Functions
Pixmap Functions
Graphics Context Functions
Graphics Functions
Font Functions
Text Metrics and Text Drawing Functions
Cursor Functions
Grab Functions
Window Manager Functions
Event Handling Functions
Inter-Client Communication Functions
Keyboard Utility Functions
Other Utility Functions
Server Extension Functions
Error Handling
Interaction with the Garbage Collector


Markup created by unroff 1.0,    September 24, 1996,    net@informatik.uni-bremen.de