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

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

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_Bell
-------

void lx_Bell(LX_CONN *conn, int p)

Issues a Bell request to ring the keyboard bell.  p, comobined with
the keyboard bell base volume setting (see
lx_ChangeKeyboardControl_va), specifies the desired volume.  The
protocol is unable to represent p values outside the signed 8-bit range
[-128,127]; the protocol definition states that values outside the
range [-100,100] are errors.  Let b be the base volume setting.  Then,
if p is nonnegative, the nominal volume for the bell is
b-((b*p)/100)+p; if p is negative, b+((b*p)/100).  To put it another
way, p values from 0 through 100 scale from b to 100; values from 0
through -100 scale from b to 0.

But note that, as noted under lx_ChangeKeyboardControl_va, the server
(and the hardware backing it) may limit the actual volume severely; it
is not uncommon, for example, for the bell hardware to have only two
volumes, `off' and `on'.

Except for very special circumstances, p should be zero; overriding the
user's global setting should be done only with very good reason.

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_ChangeHosts
--------------

void lx_ChangeHosts(LX_CONN *conn, LX_CHANGEHOSTSMODE hm,
	LX_HOSTTYPE ht, int datalen, const void *data)

Issues a ChangeHosts request, modifying the server access control list.
When access control is enabled, a connecting host must be on this list
or the server will refuse the connection.  (Some servers may perform
more detailed access control in some server-dependent way, such as
checking the authorization protocol name and data passed during
connection startup.)  Servers supporting access control typically have
some way to specify an initial list at server startup time.

The client must have permission in a server-dependent way to execute
this request (typically, must be on the same host as the server) or an
Access error occurs and the request is otherwise ignored.

hm can be LX_CHANGEHOSTSMODE_Insert, to isnert a new entry, or
LX_CHANGEHOSTSMODE_Delete, to delete an existing entry.  ht specifies
the type of the host address, with data and datalen being type-specific
data giving the address itself.

The protocol document defines three address types (Internet, meaning
IPv4; DECnet; and Chaosnet).  I have seen a fourth in use (IPv6).
Servers need not support any of these and may support others; using an
unsupported host type or an inappropriate address data blobj for the
host type (what `inappropriate' means depend on the host type) results
in an error.

For LX_HOSTTYPE_IPv4, datalen must be 4 and data must point to the
four-byte IPv4 address in network order.

For LX_HOSTTYPE_IPv6, datalen must be 16 and the data must point to the
16-byte IPv6 address in network order.

For LX_HOSTTYPE_DECnet, datalen must be 2 and data must point to the
two-byte address.  The first byte contains the low 8 bits of the node
number; the second byte contains the high 2 bits of the ndoe number in
its low 2 bits and the area number in its high 6 bits.

For LX_HOSTTYPE_Chaos, datalen must be 2 and the data must point to the
two-byte address.  The first byte is the host number and the second
byte is the subnet number.

See also lx_ListHosts and lx_SetAccessControl.

lx_ChangeKeyboardControl_va
---------------------------

void lx_ChangeKeyboardControl_va(LX_CONN *conn, ...)

Issues a ChangeKeyboardControl request to modify the keyboard control
settings.  The changes are described by a variable argument list, which
consist of one or more calls to the LX_KCV_* macros, the last of which
must be LX_KCV_END.  The macros, their arguments, and their meanings
are:

	LX_KCV_KeyClickPercent(p)
		Sets keyclick volume to p.  The protocol restricts p to
		the signed 8-bit range, [-128,127].  -1 restores the
		default and other negative values produce errors.  The
		nominal range is 0 (silent) to 100 (as loud as
		available).
	LX_KCV_BellPercent(p)
		Sets bell volume to p.  The protocol restricts p to the
		signed 8-bit range, [-128,127].  -1 restores the
		default and other negative values produce errors.  The
		nominal range is 0 (silent) to 100 (as loud as
		available).
	LX_KCV_BellPitch(p)
		Sets the bell pitch to p Hz.  The protocol restricts p
		to the signed 16-bit range, [-32768,32767].  -1
		restores the default and other negative values produce
		errors.  There is no way to represent a requested pitch
		above 32767 Hz.
	LX_KCV_BellDuration(d)
		Sets the bell duration to d milliseconds.  The protocol
		restricts d to the signed 16-bit range, [-32768,32767].
		-1 restores the default and other negative values
		produce errors.  There is no way to represent a
		requested duration over 32.767 seconds.
	LX_KCV_LED(n,act)
		Sets LED n according to act.  The protocol restricts n
		to the unsigned 8-bit range [0,255] (but the protocol
		document specifies that at most 32 LEDs, numbered from
		1, are supported; it is silent on what happens if n is
		out of range); act is LX_KBCTLLEDACTION_Off or
		LX_KBCTLLEDACTION_On according as the LED is to be
		turned off or on, respectively.
	LX_KCV_AllLED(act)
		This has the semantics of LX_KCV_LED(n,act) for every
		supported value of n (see the note below).
	LX_KCV_Repeat(kc,act)
		Sets autorepeat for keycode kc according to act.  The
		protocol restricts kc to the unsigned 8-bit range
		[0,255] (but it is silent on what happens if it is not
		a valid keycode).  act is LX_KBCTLREPEATACTION_Off,
		LX_KBCTLREPEATACTION_On, or
		LX_KBCTLREPEATACTION_Default.  See the discussion of
		keyboard autorepeat, below.
	LX_KCV_GlobalRepeat(act)
		Sets the global keyboard autorepeat setting to act.
		act is LX_KBCTLREPEATACTION_Off,
		LX_KBCTLREPEATACTION_On, or
		LX_KBCTLREPEATACTION_Default.  See the discussion of
		keyboard autorepeat, below.
	LX_KCV_END
		Marks the end of the argument list.

At most one call to LX_KCV_LED() and/or LX_KCV_AllLED() may appear;
what happens if either one is called multiple times, or if both are
called, is undefined.  To change multiple LEDs' states in a way that
can't be done with AllLED(), call lx_ChangeKeyboardControl_va multiple
times.

At most one call to LX_KCV_Repeat() and/or LX_KCV_GlobalRepeat() may
appear; what happens if either one is called multiple times, or if both
are called, is undefined.  To effect multiple such changes, call
lx_ChangeKeyboardControl_va multiple times.

Keyboard autorepeat is slightly complicated.  Each key has an
autorepeat on/off setting, and a default value for that setting; there
also is a global autorepeat on/off setting, and a default for it.  The
ideal behaviour (which may not be achievable, depending on the hardware
and in some cases other things) is that, when the global setting is
off, no keys autorepeat; when the global setting is on, keys autorepeat
or not depending on their individual settings.  Setting
LX_KBCTLREPEATACTION_Default is a request to set the relevant setting
to its (server-dependent) default.

A bell generator connected to the console but not directly on the
keyboard is treated as if it were part of the keyboard.

Depending on the hardware and possibly the server, volume and pitch
settings may be limited, in some cases severely.  For example, some
hardware is not capable of software control over keyclick.

If an error is generated, some subset of the controls may have been
altered; the order in which changes are verified and implemented is
server-dependent.  If exact order matters, use multiple
ChangeKeyboardControl requests.

There is no variant of this call which takes a struct instead of a
variable argument list.  I may implement one if there is a need.

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 generates a MappingNotify event to all clients.  (There is
no mechanism to express uninterest 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_ChangePointerControl
-----------------------

void lx_ChangePointerControl(LX_CONN *conn, const LX_POINTERCONTROL *cp)

Issues a ChangePointerControl request, pontentially changing popinter
acceleration settings.  If cp->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.

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

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_GetKeyboardControl
---------------------

LX_OP *lx_GetKeyboardControl(LX_CONN *conn, LX_KEYBOARDCONTROL *kcp)

Issues a GetKeyboardControl request, retrieving the keyboard control
settings (see lx_ChangeKeyboardControl_va).  The settings are written
through kcp at some point after entry to lx_GetKeyboardControl 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_GetModifierMapping
---------------------

LX_OP *lx_GetModifierMapping(LX_CONN *conn, int *kpmp, LX_KEYCODE *kcv)

Issues a GetModifierMapping request, returning the modifier mapping.
This mapping consists of some number, kpm, of keycodes per modifier;
kpm is chosen arbitrarily by the server to be some value large enough
to represent all the keycodes assigned to each modifier.  The resulting
keycodes are written through kcv, which must point to enough
LX_KEYCODEs.  Because the protocol cannot represent a kpm value over
255, 255*8=2040 LX_KEYCODEs are always enough.  kpm is written through
kpmp.  The first kpm keycodes are Shift, the next kpm are for Lock,
followed by Control, Mod1, Mod2, Mod3, Mod4, and Mod5, in that order.
Only nonzero LX_KEYCODEs are meaningful; zero values fill any unused
entries in the array.  The order of keycodes in a modifier's set is
meaningless; it is chosen arbitrarily by the server.

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

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_GetPointerControl
--------------------

LX_OP *lx_GetPointerControl(LX_CONN *conn, LX_POINTERCONTROL *cp)

Issues a GetPointerControl request, retrieving the pointer control
settings (see lx_ChangePointerControl).  The returned settings are
written through cp at some point after entry to lx_GetPointerControl
and before the returned LX_OP completes.

The _ACCEL and _THRESH flag bits (see lx_ChangePointerControl) are
always both set in *cp, so the struct is suitable for passing to
lx_ChangePointerControl to restore the returned settings.

lx_GetPointerMapping
--------------------

LX_OP *lx_GetPointerMapping(LX_CONN *conn, int *nump, unsigned char *mapp)

Issues a GetPointerMapping request, retrieving the pointer button
mapping (see lx_SetPointerMapping).

The returned list length is written through nump, and the mapping is
written through mapp, at some point after entry to lx_GetPointerMapping
and before the returned LX_OP completes.

mapp must point to enough unsigned chars to store the resulting list.
The wire protocol cannot represent a mapping with more than 255
entries, so 255 unsigned chars always suffices.  (It would also suffice
to call lx_GetPointerMapping with nil for mapp, wait for the response,
allocate the array, and call lx_GetPointerMapping again.  That costs a
server round-trip; whether that is better or worse than allocating
enough space for the largest possible array is application-specific.)

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_GetScreenSaver
-----------------

LX_OP *lx_GetScreenSaver(LX_CONN *conn, LX_SCREENSAVER *ss)

Issues a GetScreenSaver request, retrieving the screen saver settings
(see lx_SetScreenSaver).  The returned state is written through ss at
some point after entry to lx_GetScreenSaver and before the returned
LX_OP completes.

The returned LX_SCREENSAVER will never use LX_SSBLANKING_Default or
LX_SSEXPOSURES_Default.

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_KillClient
-------------

void lx_KillClient(LX_CONN *conn, LX_XID id)

Issues a KillClient request.  If id is the ID of a resource created by
a client connection which still exists, that client connection is
forcibly closed, with all the usual consequences of connection closure.
If the client has already terminated with its close-down mode set to
RetainPermanent or RetainTemporary, all that client's resources are
destroyed.  id can also be LX_KILLCIENT_AllTemporary, which destroys
the resources of all clients which have terminated with close-down mode
RetainTemporary.

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_ListHosts
------------

LX_OP *lx_ListHosts(LX_CONN *conn, LX_ACCESSCONTROL *acp, LX_HOSTLIST **hlp)

Issues a ListHosts request, returning the state of access control
(LX_ACCESSCONTROL_Disable or LX_ACCESSCONTROL_Enable) through acp and
the addresses on the access control list, in the form of an
LX_HOSTLIST, through hlp.  See lists for what can be done with the
LX_HOSTLIST.

See also lx_ChangeHosts and lx_SetAccessControl.

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_NoOperation
--------------

void lx_NoOperation(LX_CONN *conn)

Issues a NoOperation request.  This does nothing and is not really
useful; this routine exists for completeness rather than utility.

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

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

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.  (I have not yet
written documentation on connection closedown; see the protocol
document.)

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_SetModifierMapping
---------------------

LX_OP *lx_SetModifierMapping(LX_CONN *conn,
	int kpm, const LX_KEYCODE *kcv, LX_MAPPINGSTATUS *statp)

Issues a SetModifierMapping request, replacing the 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 set, Control; then Mod1, Mod2, Mdo3, Mod4,
and Mod5.  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 at some point after entry ot lx_SetModifierMappign and before the
returned LX_OP completes.

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

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
LS_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; the screen saver is not actually
activated.

When the screen saver is activated, at the next keyboard or pointer
input, or the 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
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).

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.