This file documents the liblx routines for core requests. Most requests have one routine; a few have more (typically because certain information can be provided in more than one way, such as an RGB triple being provided as a struct or as three separate arguments). The first argument to all of these is an LX_CONN *. This is always the connection the request is made on; this is rarely-to-never specifically mentioned. Most of these do not give full details here. I need to write more detailed documentation; in the meantime, see the X protocol documentation for more information. For example, there are various interactions among the arguments to CreateWindow requests, few-to-none of which are currently documented here. A `drawable' means either a window or a pixmap; many requests can operate on either. A window is `viewable' if it and all of its ancestors are mapped. (It is possible that none of a viewable window is visible, if, for example, it is completely obscured by other windows.) For the routines returning an LX_OP *, see pending-operations.txt for more. Routines that return data through pointer arguments accept nil pointers for these arguments; when this is done, the information that would normally be written through that argument is not saved anywhere. (When it would normally be allocated data such as a struct or a data buffer, the memory either is freed within liblx or isn't allocated at all.) When a routine which returns an LX_OP * also has pointer arguments through which values are potentially returned (which is most of the LX_OP-returning routines), writes through the arguments always happen at some point or points in time, indeterminate from the application's point of view, after entry to the API routine and before the returned LX_OP completes. (See pending-operations.txt for more, including what it means for an LX_OP to complete and what relevant facilities are available to the application.) Requests taking an LX_TIME argument, in general, accept LX_TIME_CurrentTime to mean the current server time, as mentioned in types.txt. Exceptions are specifically mentioned. lx_AllocColor ------------- LX_OP *lx_AllocColor(LX_CONN *conn, LX_XID cm, unsigned int r, unsigned int g, unsigned int b, unsigned int *pix, unsigned int *actr, unsigned int *actg, unsigned int *actb) Issues an AllocColor request, allocating a read-only colormap cell in cm, storing into it the closest values to (r,g,b) that the hardware provides. The resulting pixel value is written through pix and the actual RGB values used are written through actr, actg, and actb. lx_AllocColorCells ------------------ LX_OP *lx_AllocColorCells(LX_CONN *conn, LX_XID cm, int contig, int ncols, int nplanes, unsigned int *pixp, unsigned int *planesp) Issues an AllocColorCells request, allocating writable colormap cells in the colormap cm. ncols must be postive and nplanes must be nonnegative. ncols pixels and nplanes planes will be returned; no plane will have any bits in common with any other plane, nor with any of the pixels, so by ORing together one pixel value with some subset of the planes, ncols*(1<flags has the LX_POINTERCONTROL_ACCEL bit set, then cp->numerator and cp->denominator are the numerator and denominator of an acceleration ratio to be set; if the LX_POINTERCONTROL_THRESH bit, cp->threshold is an acceleration threshold to be set. (There is no way to set one of the numerator or denominator without setting the other.) The acceleration ratio is applied when the pointer moves more than the threshold, and only the portion over the threshold has the ratio applied to it. (The protocol document is silent on whether/how these settings affect pointer motion driven by an absolute input device such as as touchscreen, instead of a relative device such as a mouse.) lx_ChangeProperty ----------------- void lx_ChangeProperty(LX_CONN *conn, LX_XID win, LX_ATOM prop, LX_ATOM ptype, int fmt, LX_PROPERTYMODE mode, const void *data, int len) Issues a ChangeProperty request. win is the window whose property list is to be affected. prop is the property name. ptype is the property type. fmt is 8, 16, or 32, as the property value is made up of 8-, 16-, or 32-bit units; this is needed so the server can byteswap between clients using different endiannesses. mode is one of the LX_PROPERTYMODE_* values, specifying whether the value is to be appended to, prepended to, or completely replaced. data and len are the new value; len is in fmt-sized units (which, unless fmt is 8, is not the length in bytes). lx_ChangeSaveSet ---------------- void lx_ChangeSaveSet(LX_CONN *conn, LX_XID win, LX_CHANGESAVESETMODE mode) Issues a ChangeSaveSet request. Depending on mode, this either inserts (LX_CHANGESAVESETMODE_Insert) or deletes (LX_CHANGESAVESETMODE_Delete) the window from this client's save set. It is a Match error for win to have been created by the client issuing the request. lx_ChangeWindowAttributes_va, lx_ChangeWindowAttributes_attr ---------------------------- ------------------------------ void lx_ChangeWindowAttributes_va(LX_CONN *conn, LX_XID win, ...) void lx_ChangeWindowAttributes_attr(LX_CONN *conn, LX_XID win, unsigned int mask, const LX_SET_WINDOW_ATTRIBUTES *attr) Issues a ChangeWindowAttributes request. conn is the connection, win is the win. The rest of the arguments specify the attributes to change; their values are the same as for lx_CreateWindow_* (qv). Setting a new background replaces any previous background, regardless of which kind of background (pixmap or pixel - BackPixmap or BackPixel) the former one was and regardless of which kind of background the new one is. Changing the background does not in itself cause the window contents to be changed (see lx_ClearArea). Setting the border or doing anything which changes the border tile origin causes the border to be repainted. Changing the background of a root window ot None or ParentRelative restores the default background. Changing the border of a root window to CopyFromParent restores the default border (root windows often have border-width zero and thus their border settings have no visible effect). Changing a window's win-gravity does not in itself affect any window's position. Changing the backing-store, backing-planes, backing-pixel or saved-unde may have no immediate effect. In general, multiple clients can select for events on the same window; each client has a separate event-mask for each window (though typically most clients have all-0 event masks for most windows). In most cases, generated events are reported all interested clients. However, a few event types have restrictions: only one client at a time may select for SubstructureReedirect on any given window; only one client at a time may select for ResizeRedirect on any given window; and only one client at a time may select for ButtonPress on any given window. Any Attempt to violate these restrictions is an Access error. However, while each window has one event-mask per client, each window has only one do-not-propagate mask, not one per client. Changing the colormap attribute of a window (which is not the same thing as modifying the colormap referred to by the colormap attribute of a window) generatse a ColormaNotify event. Changing a window's colormap (in either sense, that is, either changing the colormap attribute or modifying colormap cells in the referred-to colormap) may have no immediate visible effect (if the colormap is not installed, or if none of the RGB triples the pixel values present in the visible portions of the window map to change). Changing the cursor of a root window to None restores the default cursor. The order in which attributes are verified and updated is server-dependent. If an error occurs, some server-dependent subset of the attributes may have been altered. lx_CirculateWindow ------------------ void lx_CirculateWindow(LX_CONN *conn, LX_XID win, LX_CIRCULATE op) Issues a CirculateWindow request for win, potentially restacking its child windows. op specifies the request and can be LX_CIRCULATE_RaiseLowest or LX_CIRCULATE_LowerHighest. If some other client has selected SubstructureRedirect on the win, this generates a CirculateRequest event and does nothing else. Otherwise, the win's child windows are restacked as described below and, if the stacking order actually changed, aCirculateNotify event is then generated. For RaiseLowest, this raises the lowest mapped chiled (if any) which is occluded by another child to the top of the stack. For LowerHighest, this lowers the highest mapped child (if any) which occludes another child to the bottom of the stack. Exposure processing is performed as usual on any portions of any windows which were formerly, but no longer, obscured. lx_ClearArea ------------ void lx_ClearArea(LX_CONN *conn, LX_XID win, int x, int y, int w, int h, int exp) Issues a ClearArea request, clearing some portion of a window to its background. win is the window. x, y, w, and h describe a rectangle relative to win's origin; the intersection of this rectangle with the window is cleared to its background. If w is zero, it is replaced with the window's width minus x; if h is zero, it is replaced with the window's height minus y. If exp is zero, nothing further happens; if exp is nonzero, Expose events are then generated for whatever portion of the affected area is either visible or being retained in backing-store. If the window's background pixmap is set to None, the window has no defined background; in this case, existing window contents are not altered by the clear operation. Otherwise, any window portions cleared ar tiled with the window's background, with a plane-mask of all 1s, a function of Copy, and a subwindow-mode of ClipByChildren (see gc.txt for more). lx_CloseFont ------------ void lx_CloseFont(LX_CONN *conn, LX_XID fid) This issues a CloseFont request, breaking the assocation between the resource ID fid and the font backing it. The underlying font is not freed until no other resource IDs (including those associated with other clients) refers to it, and possibly not even then - see lx_SetFontPath. lx_ConfigureWindow_va, lx_ConfigureWindow_attr --------------------- ----------------------- void lx_ConfigureWindow_va(LX_CONN *conn, LX_XID win, ...) void lx_ConfigureWindow_attr(LX_CONN *conn, LX_XID win, unsigned int mask, const LX_CFG_WINDOW_ATTRIBUTES * attr) Issues a ConfigureWindow request. win is the affected window, for either version; the difference between the two versions is how the configuration changes are presented. The _va version uses a varargs list; the _attr version uses a struct, with a mask to specify which of the struct's members are to be used. (Xlib's XConfigureWindow takes the latter approach.) lx_ConfigureWindow_va specifies changes with macros forming a variable argument list. This is a sequence of one or more calls to the LX_CWV_* macros listed below, of which the last must be LX_CWV_END. The possible attributes and their meanings are: LX_CWV_X(x) x is the window's new outside X position. LX_CWV_Y(y) y is the window's new outside Y position. LX_CWV_W(w) w is the window's new interior width. LX_CWV_H(h) h is the window's new interior height. LX_CWV_BorderWidth(bw) bw is the window's new border width. LX_CWV_Sibling(sib) LX_CWV_StackMode(sm) Together, these specify restacking the window among its siblings. See below. LX_CWV_END Marks the end of the arguments. lx_ConfigureWindow_attr specifies changes with a (pointer to a) struct containing all possible attributes and a mask specifying which elements of the struct to use. (If the mask is zero, the pointer does not need to be valid; such a call is close to useless, as its only effect is to error if the window ID is invalid.) The struct members, their mask bit names, and their meanings are: x LX_CONFIGUREREQUEST_X The window's new outside X position. y LX_CONFIGUREREQUEST_Y The window's new outside Y position. w LX_CONFIGUREREQUEST_Width The window's new interior width. h LX_CONFIGUREREQUEST_Height The window's new interior height. border_width LX_CONFIGUREREQUEST_BorderWidth The window's new border width. sibling LX_CONFIGUREREQUEST_Sibling stack_mode LX_CONFIGUREREQUEST_StackMode Together, these specify restacking the window among its siblings. See below. When a window is moved but its size is not changed, the contents of the window move with the window. Changing either the width or height of a window causes its contents to be moved or discarded, depending on its bit-gravity; it also causes each child window to be potentially reconfigured, depending the child's win-gravity. If we define W and H as the change in, respectively, the window's width and height (each one can be positive, negative, or zero), then we can define nine (x,y) pairs for nine of the gravity settings: Setting (x,y) ------- ----- NorthWest (0,0) North (W/2,0) NorthEast (W,0) West (0,H/2) Center (W/2,H/2) East (W,H/2) SouthWest (0,H) South (W/2,H) SouthEast (W,H) When a window with one of those bit-gravities is resized, the corresponding pair describes the change in position of ach pixel of the window. When a window with one of these win-gravities has its parent resized, the corresponding pair describes the change in position of the window within its parent. In the latter case, this repositioning generates a GravityNotify event. GravityNotify events are always generated after the ConfigureNotify event is. A gravity of Static indicates that the window contents (for bit-gravity) or origin (for win-gravity) should not move relative to the root window's origin - but note that Static bit-gravity does not affect what happens when a window is moved without being resized. A bit-gravity of Forget specifies that the window contents are always discarded after a size change, even if backing-store or save-under would otherwise preserve them. The window is tiled with its background (but see lx_CreateWindow_* for what happens if the background is None) and zero or more exposure events are generated. The contents and borders of a window's inferiors are not affected by its bit-gravity. Also, the server is permitted to ignore a window's bit-gravity specification and use Forget instead. A win-gravity of Unmap is like NorthWest, except the child is also unmapped (and an UnmapNotify event generated) when its parent is resized. UnmapNotify events generated this way are generated after the corresponding ConfigureNotify events. The stack-mode, if specified, must be one of the LX_STACKMODE_* values. If a sibling and stack-mode are specified, the window is restacked among its siblings, let W be the window and S be the sibling; if the stack-mode is Above W is placed just above S. Below W is placed just below S. TopIf If S occludes W, then W is placed at the top of the stacking order. BottomIf If W occludes S, then W is placed at the bottom of the stacking order. Opposite If S occludes W, then W is placed at the top of the stacking order; if W occludes S, then W is placed at the bottom of the stacking order. If a stack-mode is specified but no sibling is specified: Above W is placed at the top of the stacking order. Below W is placed at the bottom of the stacking order. TopIf If any sibling occludes W, then W is placed at the top of the stacking order. BottomIf If W occludes any sibling, the W is placed at the bottom of the stacking order. Opposite If any sibling occludes W, then W is placed at the top of the stacking order; otherwise, if W occludes any sibling, the W is placed at the bottom of the stacking order. It is a Match error to specify a sibling without a stack-mode, or if the `sibling' window is not actually a sibling. Occlusion tests for TopIf, BottomIf, and Opposite are performed based on the windows post-reconfiguration geometry. Attempts to configure a root window have no effect. lx_ConvertSelection ------------------- void lx_ConvertSelection(LX_CONN *conn, LX_XID req, LX_ATOM sel, LX_ATOM tgt, LX_ATOM prop, LX_TIME ts) Issues a ConvertSelection request. req is the requestor window, sel is the selection, tgt is the target the selection owner is requested to convert the selection to, prop is the property the owner is to use when returning the value, and ts is the timestamp of the moment at which the selection value is of interest. The protocol document's description of ConvertSelection is slightly self-contradictory (its description of the SelectionNotify event generated if the selection has no owner ("with property None") conflicts with its statement that the arguments are passed on unchanged). Implementors seem to have created interoperable implementations, though. lx_CopyArea ----------- void lx_CopyArea(LX_CONN *conn, LX_XID srcd, LX_XID dstd, LX_XID gc, int sx, int sy, int dx, int dy, int w, int h) Issues a CopyArea request, copying from srcd to dstd (two drawables, which must have the same depth and be on the same screen; they may be identical). Conceptually, a rectangle w by h pixels, with its upper-left corner at (sx,sy) in srcd and (dx,dy) in dstd, is intersected with dstd. The resulting clipped rectangle then defines a portion of srcd which is then combined with the corresponding portion of dstd using the gc (see gc.txt for more). For any portions of the source rectangle which are outside of srcd, or, if srcd is a window, are neither viewable nor being maintained in backing-store, then, for each such portion: 1) If dstd is a window with a background other than None, the corresponding portion of dstd is tiled with dstd's background (using a plane-mask of all ones and function Copy). 2) If gc's graphics-exposures setting is true, one or more GraphicsExposure events are generated, describing the affected portions of dstd. If gc's graphics-exposures setting is true but no GraphicsExposure events were generated, a single NoExposure event is generated. lx_CopyColormapAndFree ---------------------- LX_XID lx_CopyColormapAndFree(LX_CONN *conn, LX_XID oldcm) Issues a CopyColormapAndFree request for oldcm. This creates a new colormap of the same visual type and on the same screen as oldcm. It then moves all this client's allocations from oldcm to the new colormap, with their color values and RO/RW status intact, then frees them in oldcm. Colors in the other cells of the new colormap, if any, are undefined. The new colormap's LX_XID is returned. lx_CopyGC --------- void lx_CopyGC(LX_CONN *conn, LX_XID fgc, LX_XID tgc, unsigned int mask) Issues a CopyGC request, copying zero or more attributes from fgc to tgc. mask specifies which attributes to copy; it uses the same values as the mask argument to LX_CreateGC_attr. lx_CopyPlane ------------ void lx_CopyPlane(LX_CONN *conn, LX_XID srcd, LX_XID dstd, LX_XID gc, int sx, int sy, int dx, int dy, int w, int h, unsigned int bit) This is just like lx_CopyArea, except that it issues a CopyPlane request instead, which is the same as CopyArea, except that it takes an additional argument and forms the effective source region differently. srcd and dstd do not have to have the same depth, and the effective source region is formed not by just taking pixels from srcd. Each pixel of the effective source region is formed by taking the corresponding pixel from srcd and ANDing it with bit (which must have exactly one bit set, which must be within range for srcd's depth). If the result is zero, the effective source pixel is gc's background pixel value; if the result is nonzero, gc's foreground pixel value. (This can also be thought of as using the bit-plane of srcd as a stipple for a rectangle fill using fill-style OpaqueStippled; see gc.txt for more.) It is otherwise just like lx_CopyArea; in particular, the GraphicsExposure and NoExposure semantics are the same. lx_CreateColormap ----------------- LX_XID lx_CreateColormap(LX_CONN *conn, LX_XID vis, LX_XID win, LX_XID alloc) Issues a CreateColormap request, creating a new colormap. The colormap can be used with any window using vis as its visual and on the same screen as win. For static visuals, alloc must be LX_AllocNone. For dynamic visuals, alloc can be LX_AllocNone, in which case the new colormap initially has no allocations, or LX_AllocAll, in which case all of its cells are allocated writable by this client - except that none of these entries can be freed with FreeColors (see lx_FreeColors). The new colormap's LX_XID is returned. lx_CreateCursor --------------- LX_XID lx_CreateCursor(LX_CONN *conn, LX_XID img, LX_XID msk, int fr, int fg, int fb, int br, int bg, int bb, int hotx, int hoty) LX_XID lx_CreateCursor_rgb(LX_CONN *conn, LX_XID img, LX_XID msk, LX_RGB frgb, LX_RGB brgb, int hotx, int hoty) Issues a CreateCursor request, to create a cursor from two pixmaps, two RGB triples, and two integers. (The RGB triples are passed as separate arguments for lx_CreateCursor and as LX_RGB structs for lx_CreateCursor_rgb.) img is the cursor image; it must be a bitmap (a pixmap of depth one). msk is the mask; it can be a bitmap of the same size as img or it can be LX_PIXMAP_None, in which case it is as if it were a bitmap of the same size as msk with all pixels set to 1. Pixels where msk is 0 are not part of the cursor image; the cursor does not obscure whatever else is on the screen there. Pixels where msk is 1 are part of the cursor image; if the corresponding pixel of img is 0, that pixel of the cursor is displayed as (br,bg,bb) or brgb, as applicable, while if the corresponding pixel of img is 1, that pixel of the cursor is displayed as (fr,fg,fb) or frgb, as applicable. (hotx,hoty) are the coordinates of the cursor hotspot, relative to the (0,0) pixel of img. The hotspot does not have to fall within img. When the cursor image is displayed, it is located on the screen such that the (hotx,hoty) location in the cursor image overlaps the pixel the pointer cursor is pointing to (the coordinates that would, for example, be returned by a QueryPointer request). The above is the ideal. However, as the protocol document phrases it, "[t]he components of the cursor may be transformed arbitrarily to meet display limitations". img and (if not LX_PIXMAP_None) msk may be freed immediately if no further explicit references to them are to be made. It is undefined what, if any, effect later drawing into img and/or msk has on the cursor. lx_CreateGC_va, lx_CreateGC_attr -------------- ---------------- LX_XID lx_CreateGC_va(LX_CONN *conn, LX_XID d, ...) LX_XID lx_CreateGC_attr(LX_CONN *conn, LX_XID d, unsigned int mask, const LX_GC_ATTRIBUTES *attr) Issues a CreateGC request, creating a new GC. d is a drawable of the same screen and depth the new GC is to have. All other parameters are optional; lx_CreateGC_va and lx_CreateGC_attr differ in how they are passed: lx_CreateGC_va takes them as one or more calls to the LX_GCV_* macros, whereas lx_CreateGC_attr takes them as a mask-and-struct, where the struct contains the values and the mask specifies which fields of the struct are used. (Xlib's XCreateGC takes the latter approach.) The new GC's LX_XID is returned. See gc.txt for more about GCs and their attributes. For lx_CreateGC_va, the possible attributes and their meanings are: LX_GCV_Function(f) f is the new GC's function. LX_GCV_PlaneMask(pm) pm is the new GC's plane mask. LX_GCV_Foreground(pix) pix is the new GC's foreground pixel value. LX_GCV_Background(pix) pix is the new GC's background pixel value. LX_GCV_LineWidth(w) w is the new GC's line width. LX_GCV_LineStyle(ls) ls is the new GC's line style, one of the LX_GCLINESTYLE_* values. LX_GCV_CapStyle(cs) cs is the new GC's cap style, one of the LX_GCCAPSPTYLE_* values. LX_GCV_JoinStyle(js) js is the new GC's join style, one of the LX_GCJOINSTYLE_* values. LX_GCV_FillStyle(fs) fs is the new GC's fill style, one of the LX_GCFILLSTYLE_* values. LX_GCV_FillRule(fr) fr is the new GC's fill rule, one of the LX_GCFILLRULE_* values. LX_GCV_Tile(pm) pm is the new GC's tile pixmap. LX_GCV_Stipple(pm) pm is the new GC's stipple pixmap. LX_GCV_TileStipXOrigin(xo) xo is the new GC's tile/stipple X origin. LX_GCV_TileStipYOrigin(yo) yo is the new GC's tile/stipple Y origin. LX_GCV_Font(f) f is the new GC's font ID. LX_GCV_SubwindowMode(sm) sm is the new GC's subwindow mode, one of the LX_GCSUBWINDOWMODE_* values. LX_GCV_GraphicsExposures(gx) gx is the new GC's graphics-exposures boolean. LX_GCV_ClipXOrigin(cxo) cxo is the new GC's clip X origin. LX_GCV_ClipYOrigin(cyo) cyo is the new GC's clip Y origin. LX_GCV_ClipMask(pm) pm is the new GC's clip pixmap. LX_GCV_DashOffset(do) do is the new GC's dash offset. LX_GCV_Dashes(dl) dl is the new GC's dash setting. LX_GCV_ArcMode(am) am is the new GC's arc mode, one of the LX_GCARCMODE_* values. LX_GCV_END Marks the end of the arguments. For lx_CreateGC_attr, the struct members, their mask bit names, and their meanings are: function LX_GCM_Function The new GC's function. plane_mask LX_GCM_PlaneMask The new GC's plane mask. foreground LX_GCM_Foreground The new GC's foreground pixel value. background LX_GCM_Background The new GC's background pixel value. line_width LX_GCM_LineWidth The new GC's line width. line_style LX_GCM_LineStyle The new GC's line style, one of the LX_GCLINESTYLE_* values. cap_style LX_GCM_CapStyle The new GC's cap style, one of the LX_GCCAPSPTYLE_* values. join_style LX_GCM_JoinStyle The new GC's join style, one of the LX_GCJOINSTYLE_* values. fill_style LX_GCM_FillStyle The new GC's fill style, one of the LX_GCFILLSTYLE_* values. fill_rule LX_GCM_FillRule The new GC's fill rule, one of the LX_GCFILLRULE_* values. tile LX_GCM_Tile The new GC's tile pixmap. stipple LX_GCM_Stipple The new GC's stipple pixmap. tile_stip_x_origin LX_GCM_TileStipXOrigin The new GC's tile/stipple X origin. tile_stip_y_origin LX_GCM_TileStipYOrigin The new GC's tile/stipple Y origin. font LX_GCM_Font The new GC's font ID. subwindow_mode LX_GCM_SubwindowMode The new GC's subwindow mode, one of the LX_GCSUBWINDOWMODE_* values. graphics_exposures LX_GCM_GraphicsExposures The new GC's graphics-exposures boolean. clip_x_origin LX_GCM_ClipXOrigin The new GC's clip X origin. clip_y_origin LX_GCM_ClipYOrigin The new GC's clip Y origin. clip_mask LX_GCM_ClipMask The new GC's clip pixmap. dash_offset LX_GCM_DashOffset The new GC's dash offset. dashes LX_GCM_Dashes The new GC's dash setting. arc_mode LX_GCM_ArcMode The new GC's arc mode, one of the LX_GCARCMODE_* values. lx_CreateGlyphCursor, lx_CreateGlyphCursor_rgb -------------------- ------------------------ LX_XID lx_CreateGlyphCursor(LX_CONN *conn, LX_XID srcfont, LX_XID mskfont, int srcchar, int mskchar, int fr, int fg, int fb, int br, int bg, int bb) LX_XID lx_CreateGlyphCursor_rgb(LX_CONN *conn, LX_XID srcfont, LX_XID mskfont, int srcchar, int mskchar, LX_RGB frgb, LX_RGB brgb) Issues a CreateGlyphCursor request to create a cursor from font glyphs. This is just like lx_CreateCursor/lx_CreateCursor_rgb except that, instead of two pixmaps, two font glyphs are used instead. The glyph for character srcchar in srcfont provides the image. If mskfont is LX_FONT_None, all pixels of the image are used; otherwise, the glyph for character mskchar in mskfont provides the mask. The hotspot is the srcchar's origin point; when mskfont is not None, it is also mskchar's origin point. There is no particular restriction on the placement of the origin point(s) relative to the bounding box(es). As for lx_CreateCursor/lx_CreateCursor_rgb, the cursor colours are passed as six integers or two LX_RGBs. The fonts may be closed immediately if no further explicit references to them are to be made. lx_CreatePixmap --------------- LX_XID lx_CreatePixmap(LX_CONN *conn, LX_XID d, unsigned int dp, unsigned int w, unsigned int h) Issues a CreatePixmap request, creating a new pximap. d is a drawable which is used to specify the screen for the new pixmap. dp is the new pixmap's depth; w and h are its width and height. Pixmaps are specific to a screen and depth, but they do not have associated visuals; they can be used with any other drawable, or any GC, of the same depth and screen. lx_CreateWindow_va, lx_CreateWindow_attr ------------------ -------------------- LX_XID lx_CreateWindow_va( LX_CONN *conn, LX_XID parentw, int x, int y, unsigned int w, unsigned int h, unsigned int bw, int dp, LX_WINDOW_CLASS cls, LX_XID vis, ... ) LX_XID lx_CreateWindow_attr( LX_CONN *conn, LX_XID parentw, int x, int y, unsigned int w, unsigned int h, unsigned int bw, int dp, LX_WINDOW_CLASS cls, LX_XID vis, unsigned int mask, const LX_SET_WINDOW_ATTRIBUTES * attr ) Issues a CreateWindow request, to create a window. The first ten arguments are the same for both versions; the difference is how optional attributes are presented. The _va version uses a varargs list; the _attr version uses a struct, with a mask to specify which of the struct's members are to be used. (Xlib's XCreateWindow takes the latter approach.) The new window's LX_XID is returned. parentw is the parent window ID. x and y specify the position of the upper left corner of the outside of the new window's border relative to parentw's origin (that is, the position is specified for the window including its border; to put put another way, the new window's origin is at (x+bw,y+bw) relative to parentw's origin). w and h specify the width and height of the new window's interior (that is, they are specified not including the border); each must be nonzero. bw is the new window's border width. dp is its depth, that is, the number of bits per pixel. cls is its class (one of the LX_WCLASS_* values). See below for more on how these values interact and what combinations are permitted. After that any optional attributes are specified; how these are specified is how the _va and _attr variants differ. Only five of these attributes are valid for InputOnly windows: win-gravity, event mask, do-not-propagate mask, override-redirect, and cursor. Specifying any of the others for an InputOnly window produces a Match error. lx_CreateWindow_va specifies optional attributes with macros forming a variable argument list. This is a sequence of one or more of calls to the LX_CWV_* macros listed below, of which the last must be LX_CWV_END. The possible attributes and their meanings are: LX_CWV_BackPixmap(pm) pm is the new window's background pixmap. LX_CWV_BackPixel(pix) pix is the new window's background pixel. LX_CWV_BorderPixmap(pm) pm is the new window's border pixmap. LX_CWV_BorderPixel(pix) pix is the ndw window's border pixel. LX_CWV_BitGravity(g) g is the new window's bit-gravity. LX_CWV_WinGravity(g) g is the new window's win-gravity. LX_CWV_BackingStore(bs) bs is the new window's backing-store hint. LX_CWV_BackingPlanes(bp) bp is the new window's backing-store planes mask. LX_CWV_BackingPixel(bp) bp is the new window's backing-store pixel value. LX_CWV_OverrideRedirect(or) or is the new window's override-redirect setting. LX_CWV_SaveUnder(su) su is the new window's save-under setting. LX_CWV_EventMask(em) em is the new window's event mask for this client. LX_CWV_DontPropagate(dp) dp is the new window's do-not-propagate mask. LX_CWV_Colormap(cmap) cmap is the new window's colormap. LX_CWV_Cursor(curs) curs is the new window's cursor. LX_CWV_END Marks the end of the arguments. lx_CreateWindow_attr specifies optional attributes with a (pointer to a) struct containing all possible attributes and a mask specifying which elements of the struct to use. (If the mask is zero, the pointer does not need to be valid.) The struct members, their mask bit names, and their meanings are: background_pixmap LX_SWM_BackPixmap The new window's background pixmap. background_pixel LX_SWM_BackPixel The new window's background pixel. border_pixmap LX_SWM_BorderPixmap The new window's border pixmap. border_pixel LX_SWM_BorderPixel The ndw window's border pixel. bit_gravity LX_SWM_BitGravity The new window's bit-gravity. win_gravity LX_SWM_WinGravity The new window's win-gravity. backing_store LX_SWM_BackingStore The new window's backing-store hint. backing_planes LX_SWM_BackingPlanes The new window's backing-store planes mask. backing_pixel LX_SWM_BackingPixel The new window's backing-store pixel value. override_redirect LX_SWM_OverrideRedirect The new window's override-redirect setting. save_under LX_SWM_SaveUnder The new window's save-under setting. event_mask LX_SWM_EventMask The new window's event mask for this client. dont_propagate LX_SWM_DontPropagate The new window's do-not-propagate mask. colormap LX_SWM_Colormap The new window's colormap. cursor LX_CWV_Cursor The new window's cursor. If cls is LX_WCLASS_CopyFromParent, the new window's class is the same as parentw's. If dp is zero for a cls other than LX_WCLASS_InputOnly, the depth is copied from parentw's. vis can be LX_VISUAL_CopyFromParent, in which case the window's visual is the same as parentw's. For class InputOutput (whether specified explicitly or via CopyFromParent), the visual and depth comobination must be one supported for the screen. It is not possible for an InputOnly window to have an InputOutput inferior. For class InputOnly, dp and bw must be zero and the visual must be one supported by the screen, but the parent may have any depth and class. InputOnly windows have no effect on the displayed output (except as they affect the pointer cursor); they are ignored for purposes of graphics requests, exposure, and visibility, and they are not usable as drawables. They are, however, fully functional in other respects, such as properties, grabs, input events, etc. Initially, the new window is on top of the stacking order with respect to any siblings it may have and is not mapped. If BackPixmap is specified, the pixmap must be on the same screen as, and have the same depth as, the new window. Any size pixmap may be used, though some sizes may be faster than others. If LX_PIXMAP_None is specified, the window has no defined background, and circumstances that would normally cause some portion of the window to be painted with its background instead do nothing. If LX_PIXMAP_ParentRelative is specified, the new window must have the same depth as parentw, and whenever this window's background is needed, its parent's background is used instead. The background tile origin is normally the window's origin, but for ParentRelative, it is the parent window's origin. The protocol document is silent on whether, if the window is reparented, it is the new parent or the old whose background is used; the lack of an error described for reparenting to a parent of a different depth implies it's the old's, but then there is the question, also not addressed by the protocol document, of whether the background origin is relative to the new parent's origin or the old's. If BackPixel is specified, it overrides BackPixmap if both rae given; the new window's background is effectively a pixmap of indeterminate size filled with the specified pixel value. The value is not range-checked; any extraneous bits are simply ignored. When no contents are available for some region of a window and either the region is visible or the server is maintaining backing-store for it, the server tiles the region with the window's background, unless the window's background is None, in which case screen contents from either this window or an inferior of it with the same depth are left undisturbed; screen contents are otherwise undefined. Exposure events are generated describing the affected regions (even if the background is None). If BorderPixmap is specified, the pixmap must be on the same screen as, and have the same depth as, the new window. Any size pixmap may be used, though some sizes may be faster than others. If the border pixmap is LX_PIXMAP_CopyFromParent, the parent's border pixmap is copied (in contrast to ParentRelative background, later changes to the parent's border setting have no effect on the new child's), but in this case the window and its parent must have the same depth. The border tile origin is always the same as the background tile origin. (The protocol document does not explicitly address whether this is true even when ParentRelative background means the background tile origin is not the window origin.) If BorderPixel is specified, it overrides BorderPixmap if both rae given; the new window's border is effectively a pixmap of indeterminate size filled with the specified pixel value. The value is not range-checked; any extraneous bits are simply ignored. Graphics requests to a window are always clipped to the interior of the window; they never affect its border. (Graphics requests on the parent with a GC whose subwindow-mode is IncludeInferiors may effect the inferior's border, but they are still clipped to the interior of the window the drawing is taking place on.) The bit-gravity defines which region of the window should be retained if the window is resized; the win-gravity defines how the window should be repositioned if its parent is resized. See lx_ConfigureWindow for more. The server may be able to maintain window contents even for non-visible (off-screen or obscured) portions of windows. This is called backing store. The backing-store setting is a hint to the server as to when doing this would be useful. It can be set to LX_BACKINGSTORE_NotUseful, LX_BACKINGSTORE_WhenMapped, or LX_BACKINGSTORE_Always. NotUseful hints that the application would not benefit from backing-store. WhenMapped hints that backing-store would be useful whenever the window is mapped, but not when it's unmapped. Always hints that backing-store would be useful at all times, even when the window is unmapped. The server may ignore the hint, either maintaining backing-store despite a hint implying it's not useful, or not maintaining backing-store despite a hint implying it would be useful. Exposure events normally will not be generated for windows for which the server is maintaining backing-store, but the server may stop maintaining backing-store at any time. The server may be able to maintain the contents of windows obscured by the new window. This is called save-under; it is designed for things such as pop-up menus. The save-under attribute hints to the server whether this would be useful, though the server may ignore the hint, either maintaining obscured contents despiet save-under being false or not doing so despite it being true. The backing-planes attribute indicates which bit-planes of the window hold dynamic data which needs saving for things such as backing-store on the window or save-under on another window obscuring it. Bits which are 1 in backing-planes should be saved; bits which are 0 need not be saved and instead may be copied from the correspnding bits of the backing-pixel value. (If the backing-planes value is all 1s, which is the default, then the backing-pixel value is irrelevant.) These value are not range-checked, extraneous bits are simply ignored. The event-mask specifies which events the client is interested in for the window (for some event types, this can in some circumstances also affect events generated on inferior windows). The do-not-propagate mask specifies which events should not be propagated to ancestor windows even if that means discarding the event; this affects only certain events, such as KeyPress, which can be passed to ancestor windows. Window managers often will reparent and decorate client windows. For some windows, such as pop-up menpus and tooltips, this is inappropriate. The override-redirect attribute specifies whether this window is such a window. If override-redirect is true, SubstructureRedirect on the parent is effectively false for purposes of handling map map requests and configuration changes for this window. The colormap specifies what colormap best reflects the intended colours for this window's pixels. It must have the same visual type as the window. If it is LX_COLORMAP_CopyFromParent, the parent's colormap is copied (later changes to the parent's colormap setting do not affect this child); however, in this case, the window and its parent must use the same visual. Colormap settings are references to shared objects; if two windows use the same colormap (whether via CopyFromParent or by explicit specification), changes to the colormap affect both. The colormap may also be set to LX_COLORMAP_None; see lx_FreeColormap for a description of what this setting means. If a cursor is specified, it is used whenever the pointer's hot-spot is in the window. LX_CURSOR_None specifies that the parent's cursor is to be used (dynamically; changing the parent's cursor cause the child's to change immediately to match). Any background or border pixmaps specified may be freed immediately if no further explicit references to the are to be made. Subsequent drawing into such a pixmap, if it's not freed, has an undefined effect on the window. A successful CreateWindow generates a CreateNotify event on parentw. lx_DeleteProperty ----------------- void lx_DeleteProperty(LX_CONN *conn, LX_XID win, LX_ATOM prop) Issues a DeleteProperty request. win is the window whose property list is to be affected and prop is the property name. lx_DestroySubwindows -------------------- void lx_DestroySubwindows(LX_CONN *conn, LX_XID win) Issues a DestroySubwindows request for win, destroying all its subwindows (if any). lx_DestroyWindow ---------------- void lx_DestroyWindow(LX_CONN *conn, LX_XID win) Issues a DestroyWindow request for win, destroying it. This includes destroying all its subwindows, if any (but see the save-set facilities for an exception). lx_FillPoly ----------- void lx_FillPoly(LX_CONN *conn, LX_XID d, LX_XID gc, LX_SHAPECLASS sc, LX_COORDMODE cm, int npts, const LX_POINT *pts) Issues a FillPoly request to draw a filled polygon in the drawable d using gc. sc specifies the shape's class; it may be any of the LX_SHAPECLASS_* values. Complex is valid for any shape. Nonconvex means the path does not self-intersect, but may not be convex. Convex means the path does not self-intersect and, in addition, is convex. If an sc value is specified that does not actually describe the shape specified, the graphics results are undefined. When accurate, specifying a more restrictive shape class can improve performance as compared to a less restrictive shape class. (Adajcent coincident points do not count as self-intersection.) lx_ForceScreenSaver ------------------- void lx_ForceScreenSaver(LX_CONN *conn, LX_FORCESCREENSAVER fss) Issues a ForceScreenSaver request, activating or deactivating the screensaver. fss can be LX_FORCESCREENSAVER_Reset to deactivate the screensaver or LX_FORCESCREENSAVER_Activate to activate it. The Activate operation activates the screensaver even if it has been disabled by setting its timeout value to zero. The Reset operation deactivates it just as if device input had been received, including resetting the activation timer if the timeout setting is nonzero. lx_FreeColormap --------------- void lx_FreeColormap(LX_CONN *conn, LX_XID cm) Issues a FreeColormap request for colormap cm, destroying it. If the colormap is an installed map for its screen, it is uninstalled (see lx_UninstallColormap). For any window W for which cm is W's colormap, the colormap for the window is changed to None (and a ColormapNotify event is generated). The protocol does not define the colours displayed for a window with a colormap of None. Attempts to free a screen's default colormap have no effect. lx_FreeColors ------------- void lx_FreeColors(LX_CONN *conn, LX_XID cmap, unsigned int planemask, int npix, const unsigned int *pixv) Issues a FreeColors request, freeing colormap cells in cmap. planemask is a bitmask of pixel bits; pixv points to npix pixel values. planemask must have no bits in common with any of the pixels; let nb be the number of bits set in planemask. By ORing together each of the pixels with subsets of the planemask, npix*(1<>3, with a 0 bit corresponding to a released key and a 1 bit corresponding to a pressed key. (Since the minimum keycode is 8, the [0] byte will always be zero.) This fetches the logical state of the keyboard, which may lag the physical state if keyboard event processing is frozen. lx_QueryPointer, lx_QueryPointer_status --------------- ---------------------- extern LX_OP *lx_QueryPointer(LX_CONN *conn, LX_XID win, int *samescreenp, LX_XID *rootp, LX_XID *childp, int *rxp, int *ryp, int *wxp, int *wyp, unsigned int *maskp) extern LX_OP *lx_QueryPointer_status(LX_CONN *conn, LX_XID win, LX_QUERYPOINTER_STATUS *statp) Issues a QueryPointer request, querying the current pointer location. win is the window the query is issued with respect to. For lx_QueryPointer, the returned values are written through the arguments after win; for lx_QueryPointer_status, the returned values are written into the struct pointed to by statp. Eight values are returned. Four of them depend on whether the pointer is logically on the same screen as win. If not, *samescreenp (lx_QueryPointer) or statp->samescreen (lx_QueryPointer_status) is written with zero, *childp/statp->child with LX_WINDOW_None, *wxp/statp->winx and *wyp/statp->winy with zero; if so, *samescreep/statp->samescreen is written with a nonzero value, *chipd/statp->child is the child of win containing the pointer (or LX_WINDOW_None if none), and *wxp/statp->winx and *wyp/statp->winy are the pointer's coordinates relative to win's origin (which may be outside win's bounds). The other four values are always returned. *rootp/statp->root is the root window of the screen the pointer is logically on, *rxp/statp->rootx and *ryp/statp->rooty are its coordinates relative to that root window's origin, and *maskp/statp->mask is the logical state of the modifier keys. This request always queries logical state. Logical state may lag physical state if event processing is frozen. (Pointer event processing, for most of the returned values, but the modifier state depends on keyboard event processing.) lx_QueryTextExtents8, lx_QueryTextExtents16 -------------------- --------------------- LX_OP *lx_QueryTextExtents8(LX_CONN *conn, LX_XID fid, const unsigned char *str, int slen, LX_TEXTDIRECTION *dirp, int *ascp, int *dscp, LX_CHARINFO *overallp) LX_OP *lx_QueryTextExtents16(LX_CONN *conn, LX_XID fid, const unsigned short int *str, int slen, LX_TEXTDIRECTION *dirp, int *ascp, int *dscp, LX_CHARINFO *overallp) Issues a QueryTextExtents request to determine the metrics for a string when drawn in a particular font. fid is the font ID (or a GC ID, in which case the GC's current font is used). str is the string, of length slen; as a convenience, for lx_QueryTextExtents8, if slen is -1, strlen(str) is used in its stead (lx_QueryTextExtents16 has nothing similar). The returned values are written through dirp (the font's draw-direction hint), ascp (the font's ascent value), dscp (the font's descent value), and overallp (the metrics for the string). lx_QueryTextExtents8 is limited to 8-bit characters, with only the low 256 characters in the font accessible. lx_QueryTextExtents16 can access all 65536 possible characters. (X fonts cannot support more than 65536 characters in a font.) For lx_QueryTextExtents16, slen is in characters, not bytes. lx_QueryTree ------------ LX_OP *lx_QueryTree(LX_CONN *conn, LX_XID win, LX_XID *rootp, LX_XID *parentp, LX_XIDLIST **kidsp) Issues a QueryTree request for win. The returned information is written through rootp (the root window of the screen win is on), parentp (win's immediate parent window), and kidsp (a list of its child windows, in bottom-to-top stacking order). See also the lx_XIDlist_* functions. If win is a root window, parentp is written with LX_WINDOW_None. lx_RecolorCursor, lx_RecolorCursor_rgb ---------------- -------------------- void lx_RecolorCursor(LX_CONN *conn, LX_XID curs, int fr, int fg, int fb, int br, int bg, int bb) void lx_RecolorCursor_rgb(LX_CONN *conn, LX_XID curs, LX_RGB frgb, LX_RGB brgb) Issues a RecolorCursor request, which changes curs's colours. The new foreground colour (the one used where the image has 1 bits) is (fr,fg,fb) for lx_RecolorCursor or frgb for lx_RecolorCursor_rgb; similarly, the background (used where image has 0 bits) is (br,bg,bb) or brgb. If the cursor is being displayed on its screen, the change is visible as soon as the request is processed. lx_ReparentWindow ----------------- void lx_ReparentWindow(LX_CONN *conn, LX_XID win, LX_XID newparent, int x, int y) Issues a ReparentWindow request, reparenting win If win is mapped, it is first unmapped. (The protocol document phrases it as "an UnmapWIndow request is performed automatically first"; it is silent on whether this includes the event generation semantics of UnmapWindow.) Then win is removed from its current position in the window hierarchy and inserted as a child of newparent. x and y specify its position in the new parent (given as the upper-left corner of the outside of the window's border, as usual). win is placed on top of the stacking order relative to any new siblings it may have. A ReparentNotify event is then generated. Finally, if the window was originally mapped, it is remapped ("a MapWindow request is perofrmed automatically"; again, the protocol document is silent on whether this includes event generation). Normal exposure processing is performed on any window portions which are newly non-obscured, except that, when win is initial mapped, the server might not generate exposures on window portions exposed by the initial unmap which are immediately obscured by the final map. It is a Match error if any of: - win and parent are on different screens. - parent is, or is an inferior of, win. - win has ParentRelative background and parent's depth is not the same as win's. lx_RotateProperties ------------------- extern void lx_RotateProperties(LX_CONN *conn, LX_XID win, int delta, int nprop, const LX_ATOM *props) Issues a RotateProperties request, changing properties on win. There are nprop properties involved; props points to their names. If any atom appears more than once in the list, or if one of the atoms does not name a property on win, an error is generated and none of the property changes occur. The value associated with property props[x] before the request becomes the value associated with property props[(x+delta) mod nprop] after the request, for each x in [0,nprop), where mod is the mathematical modulus operator (if delta is nonnegative, this is identical to (x+delta)%nprop). The protocol does not explicitly describe what happens if nprop is zero; presumably nothing is changed in that case. (While the (x+delta)%nprop expression is undefined in that case, there are no valid x values, so that expression will not be evaluated.) If delta is not a multiple of nprop, a PropertyNotify event is generated for each property, in the order listed. The protocol document is silent on the question of whether such events are generated if delta is a multiple of nprop. lx_SendEvent ------------ void lx_SendEvent(LX_CONN *conn, LX_XID dst, int prop, unsigned int mask, const LX_EVENT *ev) Issues a SendEvent request. If dst is LX_WINDOW_PointerWindow, it is replaced with the window the pointer is in. If it is LX_WINDOW_InputFocus, it is replaced with the focus window or, if the pointer is in an inferior of the focus window, that inferior. If mask is zero (ie, it is the empty set), the event is sent to the client which created dst; if that client no longer exists, the event is not sent anywhere. Otherwise, If prop (which here stands for "propagate", not "property") is zero, the event is sent to every client which has selected for any of the event types in mask on dst, even if there are zero such clients. Otherwise, dst is replaced with its closest ancestor A for which some client has selected a type in mask and no intervening window blocks that type with its do-not-propagate mask. If no such A exists or if A is an ancestor of the focus window and InputFocus was originally specified for dst, the event is not sent anywhere. Otherwise, the event is reported to every client selecting for any of the event types in event-mask on A. ev is unchanged except for forcing its `generated by SendEvent' value true, byteswapping any multi-byte values, and setting its sequence number appropriately for each client. In order for byteswapping to be possible, the event type must be a core event or an extension event. It is otherwise unchecked and unmodified. Active grabs are ignored for purposes of this request. Since passive grabs activate on device status, not on events, they are also ignored. lx_SetAccessControl ------------------- void lx_SetAccessControl(LX_CONN *conn, LX_ACCESSCONTROL ac) Issues a SetAccessControl request to alter the enable/disable state of host-based access control. ac can be LX_ACCESSCONTROL_Disable or LX_ACCESSCONTROL_Enable. The client must have permission in a server-dependent way to execute this request (typically, it must be on the same host as the server) or an Access error occurs and the request is otherwise ignored. See also lx_ChangeHosts and lx_ListHosts. lx_SetClipRectangles -------------------- void lx_SetClipRectangles(LX_CONN *conn, LX_XID gc, int xo, int yo, int nr, const LX_RECTANGLE *rv, LX_RECTORDER ro) Issues a SetClipRectangles request. This replaces gc's clip-mask, but specifies it as a list of rectangles rather than as a pixmap. See gc.txt for more. (xo,yo) are the clip origin, respecifying what lx_ChangeGC_* and lx_CreateGC_* call ClipXOrigin and ClipYOrigin. nr, rv, and ro describe the list of rectangles which, after conversion into whatever internal form the server uses for clipping regions, replaces the GC's clip-mask. ro is one of the LX_RECTORDER_* values, describing the list of rectangles. UnSorted is valid for any list of rectangles. YSorted specifies that the rectangles have nondecreasing Y origins. YXSorted is like YSorted, but additionally specifying that all rectangles with equal Y origins have nondecreasing X origins. YXBanded is like YXSorted, but additionally specifying that, for every possible scanline, all rectangles including any portion of that scanline have identical Y origins and Y extents. If the list of rectangles does not actually satisfy the ordering specified by ro, the server may (but does not have to) generate a Match error; if it does not, the graphics results are undefined. Specifying a more constraining ordering may improve performance as compared to a less constraining ordering. lx_SetCloseDownMode ------------------- void lx_SetCloseDownMode(LX_CONN *conn, LX_CLOSEDOWNMODE cdm) Issues a SetCloseDownMode request to change this client's close-down mode. cdm can be LX_CLOSEDOWNMODE_Destroy, LX_CLOSEDOWNMODE_RetainPermanent, or LX_CLOSEDOWNMODE_RetainTemporary. The default for a new client connection is Destroy. See closedown.txt for more. lx_SetDashes ------------ void lx_SetDashes(LX_CONN *conn, LX_XID gc, int offset, int ndash, const unsigned char *dashes) Issues a SetDashes request, changing the dash settings for a GC. This is like using lx_ChangeGC_* to modify the dash settings, except it offers more flexibility. See gc.txt's description of dashes for more; offset is what is there called dash-offset, with ndash and dashes being the list of dashes described there. lx_SetFontPath -------------- void lx_SetFontPath(LX_CONN *conn, int nstrs, const char * const *strs) Issues a SetFontPath request, resetting the server's font search path. The font path consists of a sequence of zero or more strings; in this API, they are NUL-terminated strings, passed as an array via strs, with nstrs giving the number of them. (If nstrs is zero, strs is not used.) The interpretation of these strings is server-dependent, but typically they are directories which fonts are sought for in. This API cannot represent a string with an embedded NUL; if there is a need, I can add a variant that does. One side effect of this operation is that the server is required to flush all cached information it may have about fonts which currently have no explicit resource IDs associated with them. The meaning of an error from this request is server-specific. lx_SetInputFocus ---------------- void lx_SetInputFocus(LX_CONN *conn, LX_XID fwin, LX_XID revto, LX_TIME ts) Issues a SetInputFocus request, to set the keyboard focus. fwin is the focus window, LX_FOCUS_PointerRoot, or LX_FOCUS_None; revto is the revert-to setting and can be LX_FOCUS_None, LX_FOCUS_PointerRoot, or LX_FOCUS_Parent. ts is a timestamp, used to resolve races. The server maintains a timestamp, called the last-focus-change time. If ts is earlier than the last-focus-change time, or later than the current server time, nothing happens. Otherwise, the last-focus-change time is set to ts, the focus window is set to fwin, and the focus revert-to is set to revto. If focus is set to None, all keyboard events are discarded (until the focus window is changed to something else). In this case, the revert-to setting is ignored. If the focus is set to a window, it becomes the focus window. If a generated keyboard event would normally be reported to this window or one of its inferiors, the event is reported normally. Otherwise, the event is reported to the focus window. A window must be viewable to be the focus window (trying to set an unviewable window is an error); if the focus window becomes unviewable, what happens depends on the revert-to setting. If revert-to is PointerRoot or None, that is used as the new focus setting; if revert-to is Parent, the focus setting is changed to the closest ancestor of the (previous) focus window which is viewable and the revert-to setting becomes None. This produces FocusIn and FocusOut events as usual for a focus change, but the last-focus-change time is not affected. If the focus is set to PoinerRoot, the focus window is dynamically taken to be the root window of whichever screen the pointer is on at the moment of the relevant keyboard event (in which case the "...one of its inferiors" clause above always applies). In this case, the revert-to setting is ignored. lx_SetModifierMapping --------------------- LX_OP *lx_SetModifierMapping(LX_CONN *conn, int kpm, const LX_KEYCODE *kcv, LX_MAPPINGSTATUS *statp) Issues a SetModifierMapping request, replacing the keyboard modifier mapping. kcv must point to 8*kpm LX_KEYCODEs; they are broken up into eight sets, each containing kpm elements. Keycode i of set s is in kcv[(s*kpm)+i]. The first set contains the keycodes for Shift; the second set, Lock; the third, Control; then Mod1, Mod2, Mdo3, Mod4, and Mod5, in that order. Within each set, only nonzero keycodes are used; zero keycodes, if present, are ignored. If a modifier has no nonzero keycodes assigned, that modifier is effectively disabled and will always be clear in events. Otherwise, a modifier will be set whenever at least one of the keys for its (nonzero) keycodes is logically down. Servers may have restrictions on which modifiers can be assigned to which keys (for example, multiple keys may not be supported for some or all modifiers). If such a restriction is violated, none of the requested changes occur and the returned status is Failed. If the nonzero keycodes for a mondifier differ from those currently defined and any (of either the current or new) keys for that modifier are logically down, none of the requsted changes occur and the returned status is Busy. Otherwise, the modifications occur, a MappingNotify event is generated, and the returned status is Success. The returned status, as an LX_MAPPINGSTATUS value, is written through statp. lx_SetPointerMapping -------------------- LX_OP *lx_SetPointerMapping(LX_CONN *conn, int num, const unsigned char *map, LX_MAPPINGSTATUS *statp) Issues a SetPointerMapping request, to change the pointer mapping. Physical pointer buttons are numbered starting from 1; if we think of map as being subscripted starting from 1 (which is not how C subscripting works), then physical button-press x becomes logical button-press map[x]. If map[x] is zero, physical button x is, effectively, disabled. Nonzero elements of map[] are not restricted by the number of physical buttons; however, it is an error for any two nonzero elements to have the same value. It is an error if num does not equal the length value a GetPointerMapping request (see lx_GetPointerMapping) would return. If any of the buttons to be changed are logically down, the status reply is Busy and the mapping is not altered. Otherwise, the mapping is changed, the status reply is Success, and a MappingNotify event is generated. The status reply, in the form of an LX_MAPPINGSTATUS value, is written through statp. lx_SetScreenSaver ----------------- void lx_SetScreenSaver(LX_CONN *conn, const LX_SCREENSAVER *ss) Issues a SetScreenSaver request, to control screen-saver settings. These consist of two numeric values (timeout and interval) and two booleans, prefer_blanking and allow_exposures. timeout and interval are in seconds and the protocol cannot represent values outside the signed 16-bit range [-32768,32767]. -1 restores the default and the protocol document specifies that other negative values are errors; there is no way to represent a timeout or interval setting over 32767 seconds (a bit over nine hours). The prefer_blanking setting is one of the LX_SSBLANKING_* vlaues; allow_exposures is one of the LX_SSEXPOSURES_* values. If the timeout value is zero, the screen-saver is disabled (but setting a zero timeout value does not deactivate the screen-saver if it is activated). Otherwise, if timeout seconds elapse with no input from the keyboard or pointer, the screen-saver is activated. When the screen-saver is activated, if the blanking is preferred, the screen simply goes blank (typically by disabling video sync). Otherwise, if either exposures are allowed or the screen can be regenerated without sending exposure events to clients, the screen is changed in a server-dependent way intended to avoid burn-in on physical displays. Otherwise, nothing happens and the screen saver is not actually activated. When the screen saver is activated, at the next keyboard or pointer input, or a ForceScreenSaver request with mode Reset, it is deactivated and screen states are restored. When the server-dependent screen-saver method is amenable to periodic change (such as moving a small image on the screen), interval is a hint as to how often changes should be made; a value of zero hints that no such periodic changes should be made. lx_SetSelectionOwner -------------------- void lx_SetSelectionOwner(LX_CONN *conn, LX_ATOM sel, LX_XID win, LX_TIME ts) Issues a SetSelectionOwner request. sel is the selection, win is the new owner window (or LX_WINDOW_None for no owner), and ts is the timestamp (or LX_TIME_CurrentTime). If ts is earlier than the last-change time of the selection named by sel or is laster than the current server time, nothing happens. Otherwise, the last-change time for sel is set to ts and its owner is changed. If win is LX_WINDOW_None, the selection is said to have no owner, or, equivalently, to be owned by None. Otherwise, sel's owner is set to this client, with its owner window set to win. If the new owner (whether this client or None) differs from the former (current before the request) owner, and the former owner is not None, the former owner is sent a SelectionClear event. If the client owning a selection has its connection close down, or if its owner window is destroyed, the owner of the selection is automatically reset to None, but its last-change time is not affected. The selection atom is uninterpreted by the server; it is up to clients to agree on what selection atoms mean what. The owner window is returned by lx_GetSelectionOwner and is reported in SelectionRequest and SelectionClear events. Selections are global to the server. lx_StoreColors -------------- void lx_StoreColors(LX_CONN *conn, LX_XID cmap, int nc, const LX_RGBPF *cv) Issues a StoreColors request to change the RGB entries for colormap cells in cmap. The request attempts to change nc colormap cells, where the cells themselves, and the values to store in them, are pointed to by cv. All the changes requested which do not produce errors take place, even if one or more of the requested changes produces an error. Each change takes the form of an LX_RGBPF, which consists of r, g, and b values (each in the usual 0-65535 range), a pixel value, and flag bits indicating which of the three primaries are to have their values actually changed. The flag bits use the LX_DO_R, LX_DO_G, and LX_DO_B bits; as a convenience, LX_DO_ALL is defined to be all three bits. If the colormap is installed for its screen, the changes take effect as soon as the request is processed by the server. A Value error results if a pixel value is not a valid colormap cell index for cmap. An Access error results from an attempt to modify a colormap cell which is read-only or unallocated. If more than one attempted change produces an error, which one gets reported is arbitrary. lx_StoreNamedColor ------------------ void lx_StoreNamedColor(LX_CONN *conn, LX_XID cmap, unsigned int pix, const char *name, int namelen, unsigned int doflags) Issues a StoreNamedColor request for cmap. This looks up the named color with respect to cmap's screen and then does the equivalent of a StoreColors request on only one colormap cell, storing the resulting values into colormap cell pix with flags doflags. name and namelen are the color name; the protocol document says that this name "should use the ISO Latin-1 encoding, and uppercase and lowercase do not matter", but is silent on what happens if this `should' is violated. A Name error results if the name is not recognized by the server; Access and Value errors can occur as described for StoreColors (see lx_StoreColors) for the effective single-cell store. lx_TranslateCoordinates ----------------------- LX_OP *lx_TranslateCoordinates(LX_CONN *conn, LX_XID srcwin, LX_XID dstwin, int sx, int sy, int *samescreenp, int *dxp, int *dyp, LX_XID *childp) Issues a TranslateCoordinates request, to translate a location (sx,sy) relative to srcwin into a location relative to dstwin. If srcwin and dstwin are on different screens, *samescreenp is written with zero and *dxp, *dup, and *childp may or may not be written through; if they are, the values written are undefined. If srcwin and dstwin are on the same screen, *samescreenp is written with a nonzero value and the coordinates relative to dstwin are written through *dxp and *dyp. If the location is within a mapped child of dstwin, *childp is written with that child; otherwise, it is written with LX_WINDOW_None. lx_UngrabButton --------------- void lx_UngrabButton(LX_CONN *conn, int btn, unsigned int mods, LX_XID grabwin) Issues an UngrabButton request, revoking any passive grab (see lx_GrabButton) by this client with the same button, modifiers, and grab window. LX_AnyButton and LX_AnyModifier work for btn and mods just as they do for lx_GrabButton. lx_UngrabKey ------------ void lx_UngrabKey(LX_CONN *conn, unsigned int kc, unsigned int mods, LX_XID grabwin) Issues an UngrabKey request, revoking any passive grab (see lx_GrabKey) by this client with the same keycode, modifiers, and grab window. LX_AnyKey and LX_AnyModifier work for kc and mods just as they do for lx_GrabButton. lx_UngrabKeyboard ----------------- void lx_UngrabKeyboard(LX_CONN *conn, LX_TIME ts) Issues an UngrabKeyboard request with timestamp ts, releasing any currently active keyboard grab by this client. lx_UngrabPointer ---------------- void lx_UngrabPointer(LX_CONN *conn, LX_TIME ts) Issues an UngrabPointer request with timestamp ts, releasing any currently active pointer grab by this client. lx_UngrabServer --------------- void lx_UngrabServer(LX_CONN *conn) Issues an UngrabServer request, releasing the server after an lx_GrabServer, re-enabling processing of requests and close-downs on other connections. lx_UninstallColormap -------------------- void lx_UninstallColormap(LX_CONN *conn, LX_XID cm) Issues an UninstallColormap request, removing cm from the required list for its screen, if it's there (see lx_InstallColormap for a discussion of the required list). This may lead to various colormaps being installed or uninstalled on the screen; except that the required list must remain installed, which ones get installed or uninstalled is server-dependent. Whenever a colormap actually gets installed or uninstalled, a ColormapNotify event is generated on every window whose colormap it is. lx_UnmapSubwindows ------------------ void lx_UnmapSubwindows(LX_CONN *conn, LX_XID win) Issues an UnmapSubwindows request for win, unmapping all its subwindows. This is (usually) more efficient than unmapping the subwindows individually, because some of the work needs to be done only once, rather than once per subwindow. The unmaps happen in bottom-to-top stacking order. lx_UnmapWindow -------------- void lx_UnmapWindow(LX_CONN *conn, LX_XID win) Issues an UnmapWindow request for win. If win is not mapped, this does nothing. Otherwise, it is unmapped and an UnmapNotify event is generated. If this leads to any regions of any other window being newly visible, or newly maintained in backing-store or save-under space, normal exposure processing happens for those regions. lx_WarpPointer -------------- void lx_WarpPointer(LX_CONN *conn, LX_XID srcwin, LX_XID dstwin, int srcx, int srcy, int srcw, int srch, int dstx, int dsty) Issues a WarpPointer request, to move the pointer. If dstwin is LX_WINDOW_None, the pointer is moved by delta (dstx,dsty) relative to its current position. Otherwise, the pointer is moved to absolute position (dstx,dsty) relative to dstwin's origin. If srcwin is LX_WINDOW_None, the move always happens, if srcwin is not None, it must be a window, and the move happens only if the pointer is within the rectangle defined by srcx, srcy, srcw, and srch relative to srcwin's origin. If srcw is zero, it is replaced with srcwin's width minus srcx; if srch is zero, it is replaced with srcwin's height minus srcy. All effects that confine the pointer (such as active pointer grabs) still apply, and can lead to the pointer moving less than the request would appear to call for. Events are generated as if the user had moved the pointer to its final position in a single step.