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 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; see the X protocol
documentation for them.  For example, there are various interactions
among the arguments to CreateWindow requests, few-to-none of which are
documented here.  (I intend to write more extensive documentation for
these; this is a preliminary version.)

A `drawable' means either a window or a pixmap; many requests can
operate on either.

For the routines returning an LX_OP *, see pending-operations 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.)

**** THIS FILE IS STILL BEING WRITTEN ****

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 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, at some popint
after entry to lx_AllocColor and before the returned LX_OP completes.

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<<nplanes) distinct pixels can be produced.  All
these are allocated writable.  For colormaps using a GrayScale or
PseudoColor visual, each plane will have exactly one bit set to 1; for
DirectColor, exactly three bits.  (Presumably these three bits are one
per primary subfield, though this is not stated explicitly in the
protocol document.)  If contig is true, ORing all the planes together
will form a single contiguous set of bits for GrayScale or PseudoColor
or three contiguous sets, one per primary subfield, for DirectColor.
The RGB values in the colormap cells are undefined (until, of course,
they are stored into).

pixp must point to ncols unsigned ints, into which the pixels are
written, or be nil, in which case the returned pixels are not written
anywhere.  planesp must point to nplanes unsigned ints, into which the
planes are written, or be nil, in which case the returned planes, if
any, are not written anywhere.  (It is useless for pixp to be nil; it
is done for consistency rather than utility.  If nplanes is not zero,
it is equally useless for planesp to be nil.)  All writes are done
after entry to lx_AllocColorCells and before the retunred LX_OP
completes.

lx_AllocColorPlanes
-------------------

LX_OP *lx_AllocColorPlanes(LX_CONN *conn, LX_XID cm, int contig,
	int ncol, int nr, int ng, int nb,
	unsigned int *pixp,
	unsigned int *rmp, unsigned int *gmp, unsigned int *bmp)

Issues an AllocColorPlanes request, allocating writable colormap cells
in the colormap cm.  ncol must be positive, and nr, ng, and nb must be
nonnegative.  ncol pixels and three pixel masks are returned; the red,
green, and blue masks have nr, ng, and nb bits set, respectively.  If
contig is true, then each mask's set bits, if any, will be contiguous.
No mask will have anyl bits in cokmmon with any other mask, nor with
any of the pixels.  For DirectColor, each mask will lie within the
correspnoding pixel subfield.

By ORing together one of the pixels with some subset of the masks,
ncol*(1<<(nr+ng+nb)) distinct pixels can be formed; all these are
allocated writable by the request.  Their RGB values are undefined
(until, of course, they are stored into).  In the colormap, there are
only ncol*(1<<nr) independent red entries, ncol*(1<<ng) independent
green entries, and ncol*(1<<nb) independent blue entries, even for
PseudoColor.  When the colormap entry for one of the allocated pixel
values is changed using StoreColors or StoreNamedColor, the pixel value
is decomposed according to the masks and the correspnoding independent
entries are updated.

lx_AllocNamedColor, lx_AllocNamedColor_rgb
------------------  ----------------------

LX_OP *lx_AllocNamedColor(LX_CONN *conn, LX_XID cm,
	const char *name, int namelen,
	unsigned int *pixp,
	unsigned int *xrp, unsigned int *xgp, unsigned int *xbp,
	unsigned int *vrp, unsigned int *vgp, unsigned int *vbp)
LX_OP *lx_AllocNamedColor_rgb(LX_CONN *conn, LX_XID cm,
	const char *name, int namelen,
	unsigned int *pixp,
	LX_RGB *xrgbp, LX_RGB *vrgbp)

Issues an AllocNamedColor request to allocate a colormap cell, as if by
AllocColor (see lx_AllocColor), in cm.  name and namelen are the color
name; as a convenience, if namelen is -1, strlen(name) is used instead.
The resulting pixel value is written through pixp.  For
lx_AllocNamedColor, the exact RGB values resulting from the lookup and
the closest values supported by the visual (the ones actually used in
the colormap allocation) are returned; how they are returned is the
difference between lx_AllocNamedColor and lx_AllocNamedColor_rgb.

For lx_AllocNamedColor, the exact RGB values are written through xrp,
xgp, and xbp, with the values supported by the visual written through
vrp, vgp, and vbp.

For lx_AllocNamedColor_rgb, the exact RGB values are written through
xrgbp and the values supported by the visual are written through vrgbp.

These writes, whichever writes hapepn, happen at some point after entry
to lx_AllocNamedColor or lx_AllocNamedColor_rgb and before the returned
LX_OP completes.

lx_AllowEvents
--------------

void lx_AllowEvents(LX_CONN *conn, LX_ALLOWMODE mode, LX_TIME ts)

Issues an AllowEvents requests, potentially releasing frozen event
processing.  mode specifies how processing is to proceed (one of the
LX_ALLOWMODE_* values) and ts is the timestamp.

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 vlaue 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_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.

lx_ChangeActivePointerGrab
--------------------------

void lx_ChangeActivePointerGrab(LX_CONN *conn, unsigned int em, LX_XID curs, LX_TIME ts)

Issues a ChangeActivePointerGrab request, replacing the event-mask and
cursor for any active grab by this client currently in effect.

lx_ChangeGC_va, lx_ChangeGC_attr
--------------  ----------------

extern void lx_ChangeGC_va(LX_CONN *conn, LX_XID gc, ...);
extern void lx_ChangeGC_attr(LX_CONN *conn, LX_XID gc,
	unsigned int mask, const LX_GC_ATTRIBUTES *attr)

Issues a ChangeGC request, modifying an existing GC.  The variable
arguments, for lx_ChangeGC_va, or the mask and struct, for
lx_ChangeGC_attr, are the same as for lx_CreateGC_*.

lx_ChangeKeyboardMapping
------------------------

void lx_ChangeKeyboardMapping(LX_CONN *conn,
	int fkc, int nkc, int spc, const LX_KEYSYM *syms)

Issues a ChangeKeyboardMapping request, which replaces part or all of
the keyboard mapping.

This replaces the keyboard mappping for nkc keycodes starting with fkc;
that is, for keycodes fkc through fkc+nkc-1 inclusive.  All other
keycodes' mappings are unaffected by this request.

Each affected keycode has spc keysyms specified for it.  The keysyms
for keycode K are syms[(K-fkc)*spc] and the immediately following
entries, for a total of spc keysyms for that keycode.  spc may be
chosen arbitrarily by the client to be large enough to hold all desired
keysyms; LX_KEYSYM_NoSymbol is the appropriate thing to put in trailing
entries for a keycode for which fewer than spc keysyms are of interest.
(It is also legal for NoSymbol to appear in any other position.)

This request generatse a MappingNotify event to all clients.  (There is
no mechanism to express disinterest in MappingNotify; clients that
aren't interested should simply ignore it.)

There is no requirement that the server do anything with the keyboard
mapping beyond storing it for reading and writing by interested clients
(which is, in general, clients that want to handle keyboard input).

The protocol document is silent on what happens if spc is zero.

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).

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
within win; the intersection of this rectangle with the window is
cleared to its background.  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
LX_PIXMAP_None, the window has no defined background; in this case,
existing window contents are not altered by the clear operation.)

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 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.  The first two arguments are the same
for both versions; the difference 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.)

win is the window to be reconfigured.  After that various changes are
specified; how they are specified is how the _va and _attr variants
differ.

lx_ConfigureWindow_va specifies changes with macros forming a variable
argument list.  This is a sequence of one or more of 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 the protocol document for details.
	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.)  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 the protocol document for details.

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.

Note that 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 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 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 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
(window or pixmap) 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 GC, of
the same depth and screen.

lx_CreateWindow_va, lx_CreateWindow_attr
------------------  --------------------

LX_XID lx_CreateWindow_va(
	LX_CONN *conn, LX_XID parent,
	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 parent,
	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.

parent 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 (that is,
the position is specified for the window including its border).  w and
h specify the width and height of the new window's interior (that is,
they are specified not including the border).  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).  After that any
optional attributes are specified; how these are specified is how the
_va and _attr variants differ.

lx_CreateWindow_va specifies optional attributes with macros forming a
variable argument list.  This is a sequence of one or more of 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_BLackPixmap
		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.

There are many interactions among these values; see the protocol
document for details.

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.

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 being drawn, 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_FreeColormap
---------------

void lx_FreeColormap(LX_CONN *conn, LX_XID cm)

Issues a FreeColormap request for colormap cm, destroying it.

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<<nb) colormap cell values
can be produced.  This request frees all of those which were allocated
by the client (using AllocColor, AllocNamedColor, AllocColorCells,
and/or AllocColorPlanes).  Freeing a colormap cell computed from the
values returned by AllocColorPlanes will, in some circumstances, not
actually allow it to be freed for reuse until certain other of its
associated colormap cells are also freed.  Similarly, a cell allocated
read-only is not actually freed for re-use unless no other clients have
it allocated.  Furthermore, if a single client allocates the same
read-only entry multiple times, it must free it that many times in
order for the colormap cell to be freed for reuse.

All of the specified colormap cells which are allocated by the client
in cmap are freed, even if one or more of them produces an error.  It
is a Value error for one of the computed cells to not be a valid cell
index for cmap.  It is an Access error for one of the computed cells to
be not allocated by this client (ie, either unallocated or allocated by
one or more different client(s)).  If more than one of the cells
produces an error, which one is reported is arbitrary.

lx_FreeCursor
-------------

void lx_FreeCursor(LX_CONN *conn, LX_XID curs)

Issues a FreeCursor request, destroying the association between the ID
curs and the cursor.  The cursor's resources will be freed once nothing
refers to it any longer.

lx_FreeGC
---------

void lx_FreeGC(LX_CONN *conn, LX_XID gc)

Issues a FreeGC request for gc, destroying it.

lx_FreePixmap
-------------

void lx_FreePixmap(LX_CONN *conn, LX_XID pm)

Issues a FreePixmap request for pm, destroying it.

lx_GetAtomName
--------------

LX_OP *lx_GetAtomName(LX_CONN *conn, LX_ATOM atom, int *lenp, char **textp)

Issues a GetAtomName request, returning the string for an atom.  The
returned string's length is written through lenp and a pointer to the
string is written through textp at some point after entry to
lx_GetAtomName and before the returned LX_OP completes.

For convenience in the common case of the atom name not containing a
NUL, a NUL is appended to the string returned by the server.  This
added NUL is not included in the length.

The returned string contents are owned by the application and can be
freed with a simple free().

lx_GetFontPath
--------------

LX_OP *lx_GetFontPath(LX_CONN *conn, LX_STRLIST **pathp)

Issues a GetFontPath request, retrieving the server's font path (see
lx_SetFontPath for more).  The path is returned as an LX_STRLIST, which
is written through pathp at some point after entry to lx_GetFontPath
and before the returned LX_OP completes.

lx_GetGeometry
--------------

LX_OP *lx_GetGeometry(LX_CONN *conn, LX_XID d, LX_GET_GEOMETRY *ggp)

Issues a GetGeometry request for drawable d.  The returned values are
written through ggp at some point after entry to lx_GetGeometry and
before the returned LX_OP completes.  x, y, and borderwidth will be
zero for pixmaps.

lx_GetImage
-----------

LX_OP *lx_GetImage(LX_CONN *conn, LX_XID d, LX_IMAGEFORMAT fmt,
	int x, int y, int w, int h, unsigned int planes,
	int *depthp, LX_XID *visp, int *sizep, void **bitsp)

Issues a GetImage request to return a rectangular region of a
drawable's contents.  d is the drawable.  fmt is the desired format and
can be LX_IMAGEFORMAT_XYPixmap or LX_IMAGEFORMAT_ZPixmap.  If XYPixmap,
only the bit-planes specified by planes are returned, with the planes
appearing from most-significant to least-significant in bit order.  If
ZPixmap, the returned data is full depth, with any bit-planes clear in
planes returned as zero.  (planes is not range-checked; extraneous bits
are simply ignored.)  The returned depth, written through depthp, is
the one specified when the drawable was created; this may or may not be
the number of bits returned for each pixel returned.    visp is written
with the window's visual, if d is a window, or with LX_VISUAL_None, if
d is a pixmap.

If d is a pixmap, the whole rectangle must fall within its dimensions;
if d is a window, the whole rectangle both must fall within its outer
dimensions (ie, including its border), the window must be viewable, and
the rectangle must be such that, combined with the window's location,
it falls entirely within the relevant root window.  (Note that the
borders can be read with this request.)

If d is a window, then portions of it which are obscured by
non-inferior windows return data from backing-store, if backing-store
is being maintained, or undefined data, if not.  Regions obscured by
inferior windows return the contents of those inferior windows, when
they are of the same depth as d, or undefined data, when not.

The pointer cursor is never included in the returned data.

The image is returned via *sizep and *bitsp.  The size in bytes is
written through sizep; the bits are copied into newly allocated space,
a pointer to which is returned through bitsp.  The resulting memory is
owned by the application and is allocated such that it can be freed
with free().

lx_GetInputFocus
----------------

LX_OP *lx_GetInputFocus(LX_CONN *conn, LX_XID *focusp, LX_XID *revertp)

Issues a GetInputFocus request, to get the input focus settings.
focusp is written with the focus window, LX_FOCUS_PointerRoot, or
LX_FOCUS_None, and revertp is written with LX_FOCUS_None,
LX_FOCUS_PointerRoot, or LX_FOCUS_Parent.  Each write happen at some
point after entry to lx_GetInputFocus and before the returned LX_OP
completes.

lx_GetKeyboardMapping
---------------------

LX_OP *lx_GetKeyboardMapping(LX_CONN *conn, int mink, int nkc,
	int *spcp, LX_KEYSYM **symsp)

Issues a GetKeyboardMapping request to retrieve part or all of the
keyboard mapping.  Each keycode has a conceptually half-infinite array
of keysyms associated with it, of which only a finite number are other
than NoSymbol.  This request retrieves this mapping for nkc keycodes
beginning at mink (that is, the mappings for keycodes [mink,mink+nkc)
are retrieved).  This range of keycodes must fall into the
[minkeycode,maxkeycode] range returned during connection setup.

The server chooses a keysyms-per-keycode value (here called spc) which
is large enough to report all non-NoSymbol entries for the keycodes in
question.  The returned mapping takes the form of spc, written through
spcp, and a vector of LX_KEYSYMs, a pointer to which is written through
symsp.  Keysym N, for N in [0,spc), for keycode K, for K in
[mink,mink+nkc), is in (*symsp)[((K-mink)*spc)+n].  If (as is usually
the case) there are keycodes which have fewer than spc non-NoSymbol
keysyms, LX_KEYSYM_NoSymbol is used to fill in trailing keysyms for
such keycodes.

The LX_KEYSYMs vector is allocated by liblx and is owned by the
application; it can be freed with free().

lx_GetMotionEvents
------------------

LX_OP *lx_GetMotionEvents(LX_CONN *conn, LX_XID win,
	LX_TIME start, LX_TIME stop, int *nevp, LX_TIMECOORD **evp)

Issues a GetMotionEvents request, fetching pointer motion history.  win
is the window for the request.  start and stop are temporal limits of
the request (events are returned only for times between start and stop,
inclusive).  The number of returned events is written through nevp and
the events themselves, if any, are returned as an array of *nevp
LX_TIMECOORDs, a pointer to which is written through evp.  The block of
LX_TIMECOORDs is owned by the application and is allocated such that it
can be freed with free().

lx_GetProperty
--------------

LX_OP *lx_GetProperty(LX_CONN *conn, LX_XID win, LX_ATOM prop,
	LX_ATOM type, unsigned int offset, unsigned int len,
	int del, int *fmtp, LX_ATOM *typep, unsigned int *afterp,
	int *lenp, void **valuep)

Issues a GetProperty request.  See the protocol document for details.
The output arguments (fmtp through valuep) have the returned values
wsritten through them at some point after entry to lx_GetProperty and
before the returned LX_OP completes.

The memory pointed to by the returned value (the pointer stored through
valuep) is owned by the applicaitnoand is allocated such that it is
freeable with a simple free().

lx_GetSelectionOwner
--------------------

LX_OP *lx_GetSelectionOwner(LX_CONN *conn, LX_ATOM sel, LX_XID *ownp)

Issues a GetSelectionOwner for sel.  The returned owner value is stored
through ownp at some point after entry to lx_GetSelectionOwner and
before the returned LX_OP completes.

lx_GetWindowAttributes
----------------------

LX_OP *lx_GetWindowAttributes(LX_CONN *conn, LX_XID win,
	LX_GET_WINDOW_ATTRIBUTES *gwa)

Issues a GetWindowAttributes request for win.  The returned attributes
are written throuogh gwa at some point after entry to
lx_GetWindowAttributes and before the returned LX_OP completes.

lx_GrabButton
-------------

void lx_GrabButton(LX_CONN *conn, int btn, unsigned int mods,
	LX_XID grabwin, int ownerevents, unsigned int mask,
	LX_GRABMODE ptrmode, LX_GRABMODE kbdmode,
	LX_XID confineto, LX_XID curs)

Issues a GrabButton request, establishing a passive pointer grab.
LX_AnyButton and LX_AnyModifier can be used for btn and mods to
establish a passive grab on, respectively, any button or any
combination of modifiers.  (These names arguably should be something
like LX_BUTTON_Any and LX_EVS_Any.)

lx_GrabKey
----------

void lx_GrabKey(LX_CONN *conn, unsigned int kc, unsigned int mods,
	LX_XID grabwin, int ownerevents,
	LX_GRABMODE ptrmode, LX_GRABMODE kbdmode)

Issues a GrabKey request, establishing a passive keyboard grab.  kc is
the keycode for the key being grabbed, mods is the modifier bits,
grabwin is the grab window, ownerevents controls how events are
reported, and ptrmode and kbdmode control how event processing proceeds
for pointer and keyboard events.  LX_AnyKey and LX_AnyModifier can be
used for kc and mods to establish a passive grab on, respectively, any
key or any combination of modifiers.  (These names arguably should be
something like LX_KEY_Any and LX_EVS_Any.)

lx_GrabKeyboard
---------------

LX_OP *lx_GrabKeyboard(LX_CONN *conn, LX_XID grabwin, int ownerevents,
	LX_GRABMODE ptrmode, LX_GRABMODE kbdmode, LX_TIME ts,
	LX_GRABSTATUS *statp)

Issues a GrabKeyboard request, attempting to actively grab the
keyboard.  grabwin is the grab window.  ownerevents controls how events
are reported.  ptrmode and kbdmode control how event processing
proceeds for pointer and keyboard events.  ts is a timestamp to resolve
races.

A status value indicating the success or failure (and, if failure, some
indication of why it failed) is written through statp at some point
after entry to lx_GrabKeyboard and before the returned LX_OP completes.

lx_GrabPointer
--------------

LX_OP *lx_GrabPointer(LX_CONN *conn, LX_XID grabwin, int ownerevents,
	unsigned int eventmask, LX_GRABMODE ptrmode, LX_GRABMODE kbdmode,
	LX_XID confine, LX_XID curs, LX_TIME ts, LX_GRABSTATUS *statp)

Issues a GrabPointer request, attempting to actively grab the pointer.
grabwin is the grab window.  ownerevents and eventmask control how
events are reported.  ptrmode and kbdmode control how event processing
proceeds for pointer and keyboard events.  confine is the confine-to
window for the grab.  curs is the cursor.  ts is a timestamp used to
resolve races.

A status value indicating the success or failure (and, if failure, some
indication of why it failed) is written through statp at some point
after entry to lx_GrabPointer and before the returned LX_OP completes.

lx_GrabServer
-------------

void lx_GrabServer(LX_CONN *conn)

Issues a GrabServer request, taking exclusive control of the server.
Naturally, this should be done sparingly if at all.

lx_ImageText8
-------------

void lx_ImageText8(LX_CONN *conn, LX_XID d, LX_XID gc,
	int x, int y, const unsigned char *str, int len)

Issues an ImageText8 request, drawing 8-bit characters, including their
background, the in drawable d using gc.  x and y specify the origin
(the intersection of the left margin and the basleine) for the first
character.  str is the string.  len is its length; as a convenience for
some use cases, if len is -1, strlen(str) is used instead.

The text is drawn as if by first filling a rectangle with upper-left
corner at (x,y-asc), where asc is the font's ascent value, width being
the sum of the widths of all the characters, and height being the sum
of the font's ascent and descent values, with gc's background pixel
value, then drawing the glyphs using gc's foreground pixel value, but
ignoring gc's function and fillstyle; the drawing uses function Copy
and fillstyle Solid.  This request uses 8-bit characters; as a result,
only the first 256 glyphs of the font are accessible.

Compare with lx_PolyText8 and lx_ImageText16.

lx_ImageText16
-------------

void lx_ImageText16(LX_CONN *conn, LX_XID d, LX_XID gc,
	int x, int y, const unsigned short int *str, int len)

Issues an ImageText16 request, drawing 16-bit characters, including
their background, the in drawable d using gc.  x and y specify the
origin (the intersection of the left margin and the basleine) for the
first character.  str is the string.  len is its length.

The text is drawn as if by first filling a rectangle with upper-left
corner at (x,y-asc), where asc is the font's ascent value, width being
the sum of the widths of all the characters, and height being the sum
of the font's ascent and descent values, with gc's background pixel
value, then drawing the glyphs using gc's foreground pixel value, but
ignoring gc's function and fillstyle; the drawing uses function Copy
and fillstyle Solid.  This request uses 16-bit characters; as a result,
all 65536 possible glyphs of the font are accessible.

Compare with lx_PolyText16 and lx_ImageText8.

lx_InstallColormap
------------------

void lx_InstallColormap(LX_CONN *conn, LX_XID cm)

Issues an InstallColormap request, installing cm as an installed
colormap for its screen, causing all windows using that colormap to
display with their correct colors.  Depending on the server and
hardware resources available, other colormaps may be implicitly
installed or uninstalled.  Which other colormaps this happens to is
servre-dependent, except that there is a so-called `required' list
which must be installed (see below).

If cm is not already an installed map, a ColormapNotify event is
generated on every window whose colormap is cm.  In addition, for every
other colormap which is installed or uninstalled as a result of the
request (if any), a ColormapNotify event is generated on every window
having that other colormap as its colormap.

At any time, for each screen, there is a subset of the installed maps
that are viewed as an ordered list and are called the `required' list.
The length of the required list is at most M, where M is the
min-installed-maps specified for the screen in the connection setup.
When a colormap is an explicit argument to InstallColormap, it is added
to the head of the list; the list is then truncated at the tail, if
necessary, to keep its length to at most M.

When a colormap is an explicit argument to UninstallColormap and it is
in the required list, it is removed from the list.  A colormap is not
added to the required list when it is installed implicitly by the
server - only explicit InstallColormap requests can do that - and the
server is not permitted to implicitly uninstall a colormap that is in
the required list.

Initially, for each screen, its default colormap is installed and its
required list is empty.

lx_InternAtom
-------------

LX_OP *lx_InternAtom(LX_CONN *conn, int oie, const char *name, int len, LX_ATOM *atomp)

Issues an InternAtom request.  name and len are the desired atom name
and its length (except that, for convenience when using NUL-terminated
strings, if len is -1, strlen(name) is used instead).  If oie is zero
and no such atom exists, one is created.  The protocol document's
description of InternAtom is silent on the behaviour if oie is nonzero
and no atom exists; the encoding section does provide for None in the
encoding of the returned atom, and the Xlib document says "[t]herefore,
XInternAtom can return None".  liblx reflects a None return as
LX_ATOM_None.

The protocol document says that the atom name string "should use the
ISO Latin-1 encoding", noting that "[u]ppercase and lowercase matter";
it is silent on what happens if that `should' is violated.

The returned atom is written through *atomp at some point after entry
to lx_InternAtom and before the returned LX_OP completes.

lx_ListExtensions
-----------------

LX_OP *lx_ListExtensions(LX_CONN *conn, LX_STRLIST **listp)

Issues a ListExtensions request, returning "a list of all extensions
supported by the server".  It is not clear to me whether a server is
permitted to provide a different set of extensions to different
connections, or whether the set of extensions may change during the
life of a connection (for example, enabling certain extensions in
response to the use of a security-authorization extension); the
protocol document is silent on such points.

See lists for what can be done with LX_STRLISTs.

lx_ListFonts
------------

LX_OP *lx_ListFonts(LX_CONN *conn, const char *pat, int maxn, LX_STRLIST **slp)

Issues a ListFonts request to obtain font names matching a pattern.
pat is the (NUL-terminated) pattern string, which "should use the ISO
Latin-1 encoding, and uppercase and lowercase do not matter", in the
words of the protocol document; it is silent on what happens if that
`should' is violated.  Characters ? (0x3f) and * (0x2a) in the pattern
match any single character and any string of zero or more characters,
respectively.  maxn specifies the maximum number of names to return.
The names themselves are returned as an LX_STRLIST, which is written
through slp at some point after entry to lx_ListFonts and before the
returned LX_OP completes.  See lists for more on LX_STRLISTs,
including how to free them.

lx_ListFontsWithInfo
--------------------

LX_OP *lx_ListFontsWithInfo(LX_CONN *conn, const char *pat, int maxn, void (*cb)(char *fn, LX_FONTINFO *fi, void *cbarg), void *cbarg)

This is just like lx_ListFonts (qv), except that instead of returning
just the names, each listed font is returned with its LX_FONTINFO, and
they are returned via a callback instead of a single data structure.

For each returned font, (*cb)() is called, with fn being the font name
string, fi its LX_FONTINFO pointer, and cbarg being
lx_ListFontsWithInfo's cbarg argument.  Ownership of the memory fn and
fi point to is passed to (*cb)(). fn can be free with free(); see
font-info for more on LX_FONTINFOs.  cbarg is opaque to liblx; it is
used only for passing to (*cb)().

The end of the list is indicated by the returned LX_OP completing.

lx_ListInstalledColormaps
-------------------------

LX_OP *lx_ListInstalledColormaps(LX_CONN *conn, LX_XID win, LX_XIDLIST **cmaps)

Issues a ListInstalledColormaps request, returning a list of the
currently installed colormaps for the screen win is on.  The order of
the returned list is meaningless and there is no explicit indication of
the required list (see lx_InstallColormap for a discussion of the
required list).

The list is returned as an LX_XIDLIST, a pointer to which is written
through cmaps at some point after entry to lx_ListInstalledColormaps
and before the returned LX_OP completes.  (See lists for what can be
done with the LX_XIDLIST.)

lx_ListProperties
-----------------

LX_OP *lx_ListProperties(LX_CONN *conn, LX_XID win, LX_XIDLIST **listp)

Issues a ListProperties request.  win is the window whose property list
is being queried.  The resulting property name list is returned as an
LX_XIDLIST (the LX_ATOMs being cast to LX_XIDs for the purpose); see
the lx_XIDlist_* functions, documented in lists, for what cna be done
with the LX_XIDLIST.

lx_LookupColor, lx_LookupColor_rgb
--------------  ------------------

LX_OP *lx_LookupColor(LX_CONN *conn, LX_XID cmap,
	const char *name, int namelen,
	unsigned int *xrp, unsigned int *xgp, unsigned int *xbp,
	unsigned int *vrp, unsigned int *vgp, unsigned int *vbp)
LX_OP *lx_LookupColor_rgb(LX_CONN *conn, LX_XID cmap,
	const char *name, int namelen,
	LX_RGB *xrgbp, LX_RGB *vrgbp)

Issues a LookupColor request to look up a color by name with respect to
cmap's screen.  The lookup returns both the exact RGB values and the
closest values supported for cmap's visual.  The protocol document says
that the name "should use the ISO Latin-1 encoding, and uppercase and
lowercase do not matter", but is silent on what happens if that
`should' is violated.

name and namelen specify the color name string.  As a convenience for
applications using NUL-terminated strings, if namelen is -1,
strlen(name) is used instead.

For lx_LookupColor, the exact RGB triple is returned through xrp, xgp,
and xbp; the visual's values are retunred through vrp, vgp, and vbp.
For lx_LookupColor_rgb, the exact RGB triple is returned through xrgbp;
the visual's values are returned through vrgbp.  The writes occur at
some point after entry to lx_LookupColor or lx_LookupColor_rgb and
before the returned LX_OP completes.

lx_MapSubwindows
----------------

void lx_MapSubwindows(LX_CONN *conn, LX_XID win)

Issues a MapSubwindows request for win.  This is (usually) more
efficient than mapping the subwindows individually, because some of the
work needs to be done only once.

lx_MapWindow
------------

void lx_MapWindow(LX_CONN *conn, LX_XID win)

Issues a MapWindow request for win.

lx_OpenFont
-----------

LX_XID lx_OpenFont(LX_CONN *conn, const char *fn)

Issues an OpenFont request, returning a resource ID associated with the
specified font, loading the font if necessary.  The font name, fn,
"should use the ISO Latin-1 encoding, and uppercase and lowercase do
not matter", in the words of the protocol document, but it is silent on
what happens if the string is not valid Latin-1 text.  (This API cannot
represent a font name string containing a NULs; while the protocol can,
I do not consider this a significant defect.  If it proves to be so, a
length argument may be added.)  Characters ? (0x3f) and * (0x2a) in the
font string do not have defined interpretation by the core protocol; my
experience is that they are interpreted as wildcards, as for ListFonts
requests (see lx_ListFonts), with the first resulting name used.

A font may be used as the font value for any GC, regardless of what
screen or depth the GC is associated with.

lx_PolyArc
----------

void lx_PolyArc(LX_CONN *conn, LX_XID d, LX_XID gc, int narc, const LX_ARC *arcs)

Issues a PolyArc request to draw (potentially) multiple arcs in the
drawable d using gc.  See gc for how each arc is specified.  If the
last point of one arc coincides with the first point of the next, gc's
join-style is applied; similarly for the end of the last arc and the
beginning of the first.  For any given arc, no pixel is drawn more than
once.  If two arcs join correctly, gc's line-width is nonzero, and the
arcs intersect, no pixel is drawn more than once.  Otherwise,
overlapping pixels of distinct arcs are drawn multiple times.

Drawing an arc with one endpoint in a clockwise direction draws the
same pixels as drawing with the other endpoint and the same extent
counterclockwise, except as the difference affects joins.

lx_PolyFillArc
--------------

void lx_PolyFillArc(LX_CONN *conn, LX_XID d, LX_XID gc,
	int narc, const LX_ARC *arcs)

Issues a PolyFillArc request, drawing zero or more filled arcs in d
using gc.  Each arc is drawn by filling the region enclosed by the arc
segment and, depending on gc's arc-mode, either the single line segment
joining the ends of the arc (if LX_GCARCMODE_Chord) or the two line
segments joining the ends of the arc to its centre (if
LX_GCARCMODE_PieSlice).  narc arcs are drawn; arcs points to the arcs
(see gc for how an arc is specified).

The arcs are filled in the order given.  For any single arc, no pixel
is drawn more than once.  If the regions for two arcs intersect, the
intersecting pixels are drawn multiple times.

lx_PolyFillRectangle
--------------------

void lx_PolyFillRectangle(LX_CONN *conn, LX_XID d, LX_XID gc,
	int nrect, const LX_RECTANGLE *rects)

Issues a PolyFillRectangle request to draw multiple filled rectangles
in the drawable d using gc.  nrect is the number of rectangles; rects
is the rectangles themselves.

Each rectangle is drawn as if by a four-point FillPoly request (see
lx_FillPoly), with points (x,y), (x+w,h), (x+w,y+h), and (x,y+h).  For
any individual rectangle, no pixel is drawn more than once.  If
rectangles overlap, the overlapping pixels are drawn multiple times.

lx_PolyLine
-----------

void lx_PolyLine(LX_CONN *conn, LX_XID d, LX_XID gc,
	LX_COORDMODE cm, int npts, const LX_POINT *pts)

Issues a PolyLine request to draw (potentially multiple) lines in the
drawable d using gc.  Each line is drawn between pts[i] and pts[i+1];
there are npts in the list.  The lines are drawn in the order given.
gc's join-style is applied at each intermediate point; if the first and
last points coincide, it is also applied there.

The first point's coordinates are always relative to d's origin;
depending on cm, later points either are also relative to d's origin
(LX_COORDMODE_Origin) or to the previous point (LX_COORDMODE_Previous).

For any given line, no pixel is drawn more than once.  If thin lines
(see gc) intersect, intersecting pixels are drawn multiple times.  If
wide lines (see gc) intersect, intersecting pixels are drawn only once,
as if the entire operation were a single filled shape.

The protocol document is silent on what happens if there are fewer than
two points specified.  liblx does not check for this, simply passing
the specified list to the server, even if npts is less than 2.

Compare with lx_PolySegment.

lx_PolyPoint
------------

void lx_PolyPoint(LX_CONN *conn, LX_XID d, LX_XID gc,
	LX_COORDMODE cm, int npts, const LX_POINT *pts)

Issues a PolyPoint request to draw zero or more points in the drawable
d using gc.  The first point's coordinates are always relative to d's
origin; depending on cm, later points either are also relative to d's
origin (LX_COORDMODE_Origin) or to the previous point
(LX_COORDMODE_Previous).  The points are drawn in the order given.
npts points are drawn; the points themselves are pointed to by pts.

lx_PolyRectangle
----------------

void lx_PolyRectangle(LX_CONN *conn, LX_XID d, LX_XID gc,
	 int nrect, const LX_RECTANGLE *rects)

Issues a PolyRectangle request to draw zero or more rectangle outlines
in the drawable d using gc.  Each rectangle is drawn as if by a
five-point PolyLine request (see lx_PolyLine) for points (x,y),
(x+w,y), (x+w,y+h), (x,y+h), and (x,y).  The rectangls are drawn in the
order listed.  The protocol document states that, for any given
rectangle, no pixel is drawn more than once; I do not know whether this
is actually required or whether drawing a rectangle with thin lines and
either width zero or height zero will draw the resulting degenerate
rectangle twice (which is what the PolyLine request would do).  If two
different rectangles intersect, the overlapping pixels are drawn
multiple times.

lx_PolySegment
--------------

void lx_PolySegment(LX_CONN *conn, LX_XID d, LX_XID gc,
	int nsegs, const LX_SEGMENT *segs)

Issues a PolySegment request, drawing multiple line segments in the
drawable d using gc.  No joining is performed, even if endpoints
coincide.  For any given line segment, no pixel is drawn more than
once; if segments overlap, overlapping pixels are drawn multiple times.

Compare with lx_PolyLine.

lx_PolyText8
------------

void lx_PolyText8(LX_CONN *conn, LX_XID d, LX_XID gc,
	int x, int y, int nitems, const LX_TEXTITEM8 *items)

Issues a PolyText8 request, to draw glyphs in d using gc, from 8-bit
text strings.  The initial locatino is (x,y) relative to d's origin.
Each LX_TEXTITEM8 is processed in turn.  First, if its font is not
LX_FONT_None, then the specified font is stored into gc and is used for
further text (note that this change to the gc is not undone at the end
of the request).  Then, the current position is moved by the item's
delta, which must be in the range -128 to 127, in the X direction.
Then the characters from the text item, if any, are drawn, treating
each glyph as an additional mask for a fill operation on d using gc.
After each character is drawn, its width is added to the current
position's X coordinate to get the origin for the next character
(compare lx_ImageText8).  Each glyph is located by using the text byte
as a index, from 0 to 255, into the font; only the first 256 glyphs are
accessible using this request (compare lx_PolyText16).  Each item is
limited to at most 254 characters.

If a Font error is generated, previous items may have been drawn.

lx_PolyText16
-------------

void lx_PolyText16(LX_CONN *conn, LX_XID d, LX_XID gc,
	int x, int y, int nitems, const LX_TEXTITEM16 *items)

Issues a PolyText16 request, to draw glyphs in d using gc, from 16-bit
text strings.  The initial locatino is (x,y) relative to d's origin.
Each LX_TEXTITEM16 is processed in turn.  First, if its font is not
LX_FONT_None, then the specified font is stored into gc and is used for
further text (note that this change to the gc is not undone at the end
of the request).  Then, the current position is moved by the item's
delta, which must be in the range -128 to 127, in the X direction.
Then the characters from the text item, if any, are drawn, treating
each glyph as an additional mask for a fill operation on d using gc.
After each character is drawn, its width is added to the current
position's X coordinate to get the origin for the next character
(compare lx_ImageText16).  Each glyph is located by using the text
element as a index into the font; this request supports access to all
65536 possible glyphs (compare lx_PolyText8).  Each item is limited to
at most 254 characters.  The nchars field is, as the name suggests,
measured in characters, not bytes.

If a Font error is generated, previous items may have been drawn.

lx_PutImage
-----------

void lx_PutImage(LX_CONN *conn, LX_XID d, LX_XID gc,
	LX_IMAGEFORMAT fmt, int dp, int w, int h, int dstx, int dsty,
	int leftpad, int datalen, const void *data)

Issues a PutImage request, combining an image specified by the client
with a region of the destination drawable d using gc.

fmt specifies the format of the image; it can be LX_IMAGEFORMAT_Bitmap,
LX_IMAGEFORMAT_XYPixmap, or LX_IMAGEFORMAT_ZPixmap.  For Bitmap, dp
must be 1 and the image must be in XY format; for XYPixmap, the the
iamge must be in XY format; for ZPixmap, the image must be in the Z
format defined for depth dp.  (See image for a description of image
formats.)

For ZPixmap, leftpad must be zero.  For Bitmap and XYPixmap, leftpad
must be less than the bitmap-scanline-pad value received at connection
setup (at this writing there is no call to get this value - I intend to
fix this).  The first leftpad bits in each scanline are ignored; the
image begins that many bits into the data.  w is the width of the image
in pixels, not the width plus leftpad.

lx_QueryBestSize
----------------

LX_OP *lx_QueryBestSize(LX_CONN *conn, LX_XID d, LX_SIZECLASS cls,
	int w, int h, int *rwp, int *rhp)

Issues a QueryBestSize request, to determine the best size closest to
the provided size (the w and h arguments).  cls specifies what kind of
object the query is for: LX_SIZECLASS_Cursor, LX_SIZECLASS_Tile, or
LX_SIZECLASS_Stipple.  The returned size is written through the rwp and
rhp arguments at some point after entry to lx_QueryBestSize and before
the returned LX_OP completes.

What `best' means depends on cls.

For Cursor, it is the largest size which can be fully displayed.  For
Tile, it is the size that can be tiled tastest.  For Stipple, it is the
size that can be stipppled fastest.

The drawwable d indicates the context.  For Cursor, it is any drawable
on the desired screen.  For Tile and Stipple, it is a window on the
desired screen of the desired class and depth.  An InputOnly window is
an error for Tile or Stipple.

Some of the above language is ambiguous.  `Closest' and `largest' are
vague.  For example, is a 10x20 cursor larger than, smaller than, or
the same size as a 40x5 cursor?  Depending on the anticipated cursor
images, any of the three could be the correct answer.  Similarly, on a
display for which any tile X size that's a multiple of 8 will be the
same speed, which of 8x12 or 16x12 is `closer' to 12x12?  The protocol
document is similarly vague.

lx_QueryColors
--------------

LX_OP *lx_QueryColors(LX_CONN *conn, LX_XID cmap,
	int npix, const unsigned int *pixp, LX_RGB *rgbv)

Issues a QueryColors request to return the RGB values actually stored
in cmap in the specified colormap cells.  pixp must point to npix
colormap cells (pixel values); rgbv must point to npix LX_RGBs.  The
(hardawre-dependent) RGB values actually stored in cmap are returned,
stored into rgbv.  A Value error is generated if a pixel value is not a
valid colormap cell index for cmap.  If more than one pixel is in
error, which one is reported is arbitrary.

lx_QueryExtension
-----------------

LX_OP *lx_QueryExtension(LX_CONN *conn, const char *name, int namelen,
	int *presentp, int *majorp, int *evbp int *erbp)

This issues a QueryExtension request to discover information about an
extension.  name and namelen are the extension name; as a convenience
for code using NUL-terminated strings, if namelen is -1, strlen(name)
is used instead.

If the server does not support the extension for this connection:
*presentp is written with zero.  Which (if any) of the other return
values are written, and if so with what values, is undefined.

If the server does support the extension for this connection: *presentp
is written with a nonzero value.  *majorp is written with the
extension's major opcode (the minor opcode format, if any, and request
formats, if any, are extension-specific).  If the extension provides
any additional event types, the base event type is written through
evbp; otherwise, zero is.  If the extension provides any additional
errors, the base error code is written through erbp; otherwise, zero
is.  The details of the extension's events and errors, if any, are
extension-specific.

The protocol document says that the extensino name "should use the ISO
Latin-1 encoding, and uppercase and lowercase matter"; it is silent on
what happens if that `should' is violated.

lx_QueryFont
------------

LX_OP *lx_QueryFont(LX_CONN *conn, LX_XID fid, LX_FONTINFO **fip)

Issues a QueryFont request, requesting font information about fid.  fid
may be a font ID or may be a GC ID; in the case of a GC, its current
font is used.  (The use of a GC is the only way to query the server
default font, except for server-specific methods such as knowing that
the server default font is also available under a particular name.)

The returned info is written through fip at some point after entry to
lx_QueryFont and before the returned LX_OP completes.  See font-info
for more information about LX_FONTINFOs.

lx_QueryKeymap
--------------

LX_OP *lx_QueryKeymap(LX_CONN *conn, unsigned char *statep)

Issues a QueryKeymap request, fetching the state of the keyboard.
statep must point to at least 32 bytes; key N corresponds to bit
1<<(N&7) of byte N>>3, with a 0 bit corresponding to a released key and
a 1 bit corresponding to a pressed key.

This fetches the logical state of the keyboard, which may lag the
physical state if keyboard event processing is frozen.

The writes happen at some point after entry ot lx_QueryKeymap and
before the returned LX_OP completes.

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.  In either case, these
writes occur at some point after entry to lx_QueryPointer or
lx_QueryPointer_status and before the returned LX_OP completes.

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, if slen is -1 for lx_QueryTextExtents8,
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), at some
point after entry to lx_QueryTextExtents8 or lx_QueryTextExtents16 and
before the returned LX_OP completes.

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, parentp, and/or kidsp at some point after entry
to lx_QueryTree and before the returned LX_OP completes.  See also the
lx_XIDlist_* functions.  Any of rootp, parentp, and/or kidsp may be
nil, in which case the corresponding information is not returned.

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 is (fr,fg,fb) for lx_RecolorCursor or frgb for
lx_RecolorCursor_rgb; similarly, the background 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 handled.

lx_ReparentWindow
-----------------

void lx_ReparentWindow(LX_CONN *conn, LX_XID win, LX_XID newparent, int x, int y)

Issues a ReparentWindow request, reparenting win so its new parent is
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).

lx_SendEvent
------------

void lx_SendEvent(LX_CONN *conn, LX_XID dst, int prop, unsigned int mask, const LX_EVENT *ev)

Issues a SendEvent request.  This causes the server to send the event
on to the client that created dst (or, if dst is
LX_WINDOW_PointerWindow or LX_WINDOW_InputFocus, a window determined
dynamically from the pointer position or the inpout focus).  (prop,
here, stands for `propagate', not `property'.)

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 changes gc's clip-mask, but
specifies it as a list of rectangles rather than as a pixmap.  See gc
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 for more.

lx_SetFontPath
--------------

void lx_SetFontPath(LX_CONN *conn, int nstrs, const char * const *strs)

Issues a SetFontPath request, resetting the 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.

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.

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.

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).

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
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, 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.

The writes happen at some point after entry to lx_TranslateCoordinates
and before the returned LX_OP completes.

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_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_UngrabKeyboard
-----------------

void lx_UngrabKeyboard(LX_CONN *conn, LX_TIME ts)

Issues an UngrabKeyboard request with timestamp ts, releasing any
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
pointer grab by this client.

lx_UngrabServer
---------------

void lx_UngrabServer(LX_CONN *conn)

Issues an UngrabServer request, releasing the server after an
lx_GrabServer.

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.

lx_UnmapWindow
--------------

void lx_UnmapWindow(LX_CONN *conn, LX_XID win)

Issues an UnmapWindow request for win.

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 moves the pointer.  If dstwin is
LX_WINDOW_None, the pointer is moved by deltas (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.

// conn, ...
extern void lx_ChangeKeyboardControl_va(LX_CONN *, ...);
// LED and Repeat depend on LX_KBCTLLEDACTION and LX_KBCTLREPEATACTION
//  being typedeffed the same as LX_XID.
#define LX_KCV_KeyClickPercent(p) LX__KCV_KeyClickPercent, lx__cvt_int((p))
#define LX_KCV_BellPercent(p) LX__KCV_BellPercent, lx__cvt_int((p))
#define LX_KCV_BellPitch(p) LX__KCV_BellPitch, lx__cvt_int((p))
#define LX_KCV_BellDuration(d) LX__KCV_BellDuration, lx__cvt_int((d))
#define LX_KCV_LED(led,action) LX__KCV_LED, lx__cvt_int((led)) lx__LX_XID((action))
#define LX_KCV_AllLED(action) LX__KCV_LED, (-1), lx__LX_XID((action))
#define LX_KCV_Repeat(key,action) LX__KCV_Repeat, lx__cvt_int((key)) lx__LX_XID((action))
#define LX_KCV_GlobalRepeat(action) LX__KCV_Repeat, (-1) lx__LX_XID((action))
#define LX_KCV_END LX__KCV_END
// conn, status
extern LX_OP *lx_GetKeyboardControl(LX_CONN *, LX_KEYBOARDCONTROL *);
// conn, percent
extern void lx_Bell(LX_CONN *, int);
// conn, status
extern void lx_ChangePointerControl(LX_CONN *, const LX_POINTERCONTROL *);
// conn, status
extern LX_OP *lx_GetPointerControl(LX_CONN *, LX_POINTERCONTROL *);
// conn, status
extern void lx_SetScreenSaver(LX_CONN *, const LX_SCREENSAVER *);
// conn, status
extern LX_OP *lx_GetScreenSaver(LX_CONN *, LX_SCREENSAVER *);
// conn, mode, type, datalen, data
extern void lx_ChangeHosts(LX_CONN *, LX_CHANGEHOSTSMODE, LX_HOSTTYPE, int, const void *);
// conn, accctl, list
// See also the lx_hostlist_* functions.
extern LX_OP *lx_ListHosts(LX_CONN *, LX_ACCESSCONTROL *, LX_HOSTLIST **);
// conn, mode
extern void lx_SetAccessControl(LX_CONN *, LX_ACCESSCONTROL);
// conn, mode
extern void lx_SetCloseDownMode(LX_CONN *, LX_CLOSEDOWNMODE);
// conn, resource
extern void lx_KillClient(LX_CONN *, LX_XID);
// conn, window, delta, nprop, props
extern void lx_RotateProperties(LX_CONN *, LX_XID, int, int, const LX_ATOM *);
// conn, mode
extern void lx_ForceScreenSaver(LX_CONN *, LX_FORCESCREENSAVER);
// conn, num, mapping
// mapping must point to num unsigned chars
extern void lx_SetPointerMapping(LX_CONN *, int, const unsigned char *);
// conn, nump, mapping
// mapping must point to enough unsigned chars (255 are always enough)
extern LX_OP *lx_GetPointerMapping(LX_CONN *, int *, unsigned char *);
// conn, num, keycodesp
// keycodesp must point to 8*num LX_KeyCodes
extern void lx_SetModifierMapping(LX_CONN *, int, const LX_KEYCODE *);
// conn, nump, keycodesp
// keycodesp must point to enough space (2048 LX_KEYCODEs is always enough)
extern LX_OP *lx_GetModifierMapping(LX_CONN *, int *, LX_KEYCODE *);
// conn
extern void lx_NoOperation(LX_CONN *);