RFC 1013
X Window System Protocol, version 11: Alpha update April 1987
Pages: 101
Unclassified
Unclassified
Part 3 of 3 – Pages 65 to 101
It is a Match error to use an InputOnly window in this
request.
CopyArea
src-drawable, dst-drawable: DRAWABLE
gc: GCONTEXT
src-x, src-y: INT16
width, height: CARD16
dst-x, dst-y: INT16
Errors: Drawable, GContext, Match
Combines the specified rectangle of src-drawable with the
specified rectangle of dst-drawable. The src-x and src-y
coordinates are relative to src-drawable's origin, dst-x and
dst-y are relative to dst-drawable's origin, each pair
specifying the upper left corner of the rectangle.
Src-drawable must have the same root and the same depth as
dst-drawable (else a Match error).
If regions of the source rectangle are obscured and have not
been retained by the server, or if regions outside the
boundaries of the source drawable are specified, then the
following occurs. If the dst-drawable is a window with a
background of other than None, the corresponding regions of
the destination are tiled (with plane-mask of ones and
alu-function Copy) with that background. Regardless, if
graphics-exposures in gc is True, GraphicsExposure events
for the corresponding desitnation regions are generated.
If graphics-exposures if True but no regions are exposed,
then a NoExposure event is generated.
GC components: alu-function, plane-mask, foreground,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
CopyPlane
scr-drawable, dst-drawable: DRAWABLE
GC:Gcontext
src-x, src-y: INT16
width, height: CARD16
dst-x, dst-y: INT16
bit-plane: CARD32
Errors: Drawable, GContext, Value, Match
Src-drawable must have the same root as dst-srawable (else
a match error), but need not have the same depth.
Bit-plane must have exactly one bit set. Effectively, that
plane of the src-drawable and the fore-ground/background
pixels in gc are combined to form a pixmap of the same
depth as dst-drawable, and the equivalent of a CopyArea is
performed, with all the same exposure semantics.
GC components: alu-function, plan-mask, foreground,
background, subwindow-mode, graphics-exposures,
clip-x-origin, clip-y-origin, clip-mask
PolyPoint
drawable: DRAWABLE
gc: GCONTEXT
coordinate-mode: {Origin, Previous}
points: LISTofPOINT
Errors: Drawable, GContext, Value, Match
Combines the foreground pixel in gc with the pixel at each
point in the drawable. The points are drawn in the order
listed.
The first point is always relative to the drawable's origin;
the rest are relative either to that origin or the previous
point, depending on the coordinate-mode.
GCcomponents: alu-function, plane-mask, foreground,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
PolyLine
drawable: DRAWABLE
gc: GCONTEXT
coordinate-mode: {Origin, Previous}
points: LISTofPOINT
Errors: Drawable, GContext, Value, Match
Draws lines between each pair of points (point[i], point
[i+1]). The lines are drawn in the order listed. The lines
join correctly at all intermediate points, and if the first
and last points coincide, the first and last lines also join
correctly.
For any given line, no pixel is drawn more than once. If
thin (zero line-width) lines intersect, the intersecting
pixels are drawn multiple times. If wide lines intersect,
the intersecting pixels are drawn only once, as though the
entire PolyLine were a single filled shape.
The first point is always relative to the drawable's origin;
the rest are relative either to that origin or the previous
point, depending on the coordinate-mode.
GC components: alu-function, plane-mask, line-width,
line-style, cap-style, join-style, fill-style,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, background, tile,
stipple, tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset,dash-list
PolySegment
drawable: DRAWABLE
gc: GCONTEXT
segments: LISTofSEGMENT
where SEGMENT: [x1, y1, x2, y2: INT16]
Errors: Drawable, GContext, Match
For each segment, draws a line between [x1, y1] and [x2, y2].
The lines are drawn in the order listed. No joining is
performed at coincident end points. For any given line, no
pixel is drawn more than once. If lines intersect, the
intersecting pixels are drawn multiple times.
GC components: alu-function, plane-mask, line-width,
line-style, cap-style, fill-style, subwindow-mode,
clip-x-origin, clip-y-origin,clip-mask
GC mode-dependent components: foreground, background, tile,
stipple,tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset, dash-list
PolyRectangle
drawable: DRAWABLE
gc: GCONTEXT
rectangles: LISTofRECTANGLE
Errors: Drawable, GContext, Match
Draws the outlines of the specified rectangles, as if a
five-point PolyLine were specified for each rectangle. The x
and y coordinates of each rectangle are relative to the
drawable's origin, and define the upper left corner of the
rectangle.
The rectangles are drawn in the order listed. For any given
rectangle, no pixel is drawn more than once. If rectangles
intersect, the intersecting pixels are drawn multiple times.
GC components: alu-function, plane-mask, line-width,
line-style, join-style, fill-style, subwindow-mode,
clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, background, tile,
stipple, tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset, dash-list
PolyArc
drawable: DRAWABLE
gc: GCONTEXT
arcs: LISTofARC
Errors: Drawable, GContext, Match
Draws circular or elliptical arcs. Each arc is specified by
a rectangle and two angles. The x and y coordinates are
relative to the origin of the drawable, and define the upper
left corner of the rectangle. The center of the circle or
ellipse is the center of the rectangle, and the major and
minor axes are specified by the width and height,
respectively. The angles are signed integers in degrees
scaled by 64, with positive indicating counterclockwise
motion and negative indicating clockwise motion. The start
of the arc is specified by angle1 relative to the
three-oclock position from the center, and the path and
extent of the arc is specified by angle2 relative to the
start of the arc. If the magnitude of angle2 is greater
than 360 degrees, it is truncated to 360 degrees.
The arcs are drawn in the order listed. If the last point in
one arc coincides with the first point in the following arc,
the two arcs will join correctly. If the first point in the
first arc coincides with the last point in the last arc, the
two arcs will join correctly. For any given arc, no pixel is
drawn more than once. If two arcs join correctly and the
line-width is greater than zero and the arcs intersect, no
pixel is drawn more than once. Otherwise, the intersecting
pixels of intersecting arcs are drawn multiple times.
Specifying an arc with one endpoint and a clockwise extent
draws the same pixels as specifying the other endpoint and an
equivalent counterclockwise extent, except as it affects
joins.
By specifying one axis to be zero, a horizontal or vertical
line can be drawn.
Angles are computed based solely on the coordinate system,
ignoring the aspect ratio.
GC components: alu-function, plane-mask, line-width,
line-style, cap-style, join-style, fill-style,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, background, tile,
stipple,tile-stipple-x-origin, tile-stipple-y-origin,
dash-offset, dash-list
FillPoly
drawable: DRAWABLE
gc: GCONTEXT
shape: {Complex, Nonconvex, Convex}
coordinate-mode: {Origin, Previous}
points: LISTofPOINT
Errors: Drawable, GContext, Match, Value
Fills the region closed by the specified path. The path is
closed automatically if the last point in the list does not
coincide with the first point. No pixel of the region is
drawn more than once.
The first point is always relative to the drawable's origin;
the rest are relative either to that origin or the previous
point, depending on the coordinate-mode.
The shape parameter may be used by the server to improve
performance. Complex means the path may self-intersect.
Nonconvex means the path does not self-intersect, but the
shape is not wholly convex. If known by the client,
specifying Nonconvex over Complex may improve performance. If
Nonconvex is specified for a self-intersecting path, the
graphics results are undefined.
Convex means the path is wholly convex. If known by the
client, specifying Convex can improve performance. If Convex
is specified for a path that is not convex, the graphics
results are undefined.
GC components: alu-function, plane-mask, fill-style,
fill-rule, subwindow-mode, clip-x-origin, clip-y-origin,
clip-mask
GC mode-dependent components: foreground, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin
PolyFillRectangle
drawable: DRAWABLE
gc: GCONTEXT
rectangles: LISTofRECTANGLE
Errors: Drawable, GContext, Match
Fills the specified rectangles. The x and y coordinates of
each rectangle are relative to the drawable's origin, and
define the upper left corner of the rectangle.
The rectangles are drawn in the order listed. For any given
rectangle, no pixel is drawn more than once. If rectangles
intersect, the intersecting pixels are drawn multiple times.
GC components: alu-function, plane-mask, fill-style,
fill-rule, subwindow-mode, clip-x-origin, clip-y-origin,
clip-mask
GC mode-dependent components: foreground, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin
PolyFillArc
drawable: DRAWABLE
gc: GCONTEXT
arcs: LISTofARC
Errors: Drawable, GContext, Match
For each arc, fills the region closed by the specified arc
and one or two line segments, depending on the arc-mode. For
Chord, the single line segment joining the endpoints of the
arc is used. For PieSlice, the two line segments joining the
endpoints of the arc with the center point are used. The
arcs are as specified in the PolyArc request.
The arcs are filled in the order listed. For any given arc,
no pixel is drawn more than once. If regions intersect, the
intersecting pixels are drawn multiple times.
GC components: alu-function, plane-mask, fill-style,
fill-rule, arc-mode, subwindow-mode, clip-x-origin,
clip-y-origin, clip-mask
GC mode-dependent components: foreground, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin
PutImage
drawable: DRAWABLE
gc: GCONTEXT
depth: CARD8
width, height: CARD16
dst-x, dst-y: INT16
left-pad: CARD8
format: {Bitmap, XYPixmap, ZPixmap}
bits: <bits>
Errors: Drawable, GContext, Match, Value, Alloc
Combines an image with a rectangle of the drawable. The
dst-x and dst-y coordinates are relative to the drawable's
origin.
If Bitmap format is used, then depth must be one (else a
Match error) and the image must be in XYFormat. The
foreground pixel in gc defines the source for one bits in the
image, and the background pixel defines the source for the
zero bits.
For XYPixmap and ZPixmap, depth must match the depth of
drawable (else a Match error). For XYPixmap, the image must
be sent in XYFormat. For ZPixmap, the image must be sent in
the ZFormat defined for the given depth.
The left-pad must be zero for ZPixmap format. For Bitmap and
XYPixmap format, left-pad must be less than
bitmap-format-scanline-pad (as given in the server connection
setup info). The first left-pad bits in every scanline are
to be ignored by the server; the actual image begins that
many bits into the data. The width argument defines the width
of the actual image, and does not include left-pad.
GC components: alu-function, plane-mask, subwindow-mode,
clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, background
GetImage
drawable: DRAWABLE
x, y: INT16
width, height: CARD16
plane-mask: CARD32
format: {XYFormat, ZFormat}
=>
depth: CARD8
visual: VISUALID or None
bits: <bits>
Errors: Drawable, Value, Match
Returns the contents of the given rectangle of the drawable
in the given format. The x and y coordinates are relative to
the drawable's origin, and define the upper left corner of
the rectangle. If XYFormat is specified, only the bit planes
specified in plane-mask are transmitted. If ZFormat is
specified, then bits in all planes not specified in
plane-mask transmitted as zero. The returned depth specifies
the number of bits per pixel of the image. If the drawable
is a window, its visual type is returned; if the drawable
is a pixmap,the visual is None.
If the drawable is a window, the window must be mapped, and
it must be the case that, if there were no inferiors or
overlapping windows, the specified rectangle of the window
would be fully visible on the screen will include any
visible portions of inferiors or overlapping windows
contained in the rectangle, but if these windows are of
different depth than the specified window, the contents
returned for them are not defined by the core protocol.
PolyText8
drawable: DRAWABLE
gc: GCONTEXT
x, y: INT16
items: LISTofTEXTITEM8
where
TEXTITEM8: TEXTELT8 or FONT
TEXTELT8: [delta: INT8
string: STRING8]
Errors: Drawable, GContext, Match, Font
The x and y coordinates are relative to drawable's origin,
and specify the baseline starting position (the initial
character origin). Each text item is processed in turn. A
font item causes the font to be stored in gc, and to be
used for subsequent text; switching among fonts with
differing draw-directions is permitted. A text element
delta specifies an additional change in the position along
the x axis before the string is drawn; the delta is always
added to the character origin (not added or subtracted based
on the draw-direction of the current font). Each character
image, as defined by the a font in gc, is treated as an
additional mask for a fill operation on the drawable.
All contained FONTs are always transmitted most significant
byte first.
If a Font error is generated for an item, the previous items
may have been drawn.
For fonts defined with two-byte matrix indexing, each STRING8
byte is interpreted as a byte2 value of a CHAR2B with a byte1
value of zero.
GC components: alu-function, plane-mask, fill-style, font,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
GC mode-dependent components: foreground, tile, stipple,
tile-stipple-x-origin, tile-stipple-y-origin
PolyText16
drawable: DRAWABLE
gc: GCONTEXT
x, y: INT16
items: LISTofTEXTITEM16
where
TEXTITEM16: TEXTELT16 or FONT
TEXTELT16: [delta-x: INT8
string: STRING16]
Errors: Drawable, GContext, Match, Font
Just like PolyText8, except two-byte (or 16-bit) characters
are used. For fonts defined with linear indexing rather than
two-byte matrix indexing, the server will interpret each
CHAR2B as a 16-bit number that has been transmitted most
significant byte first (i.e., byte1 of the CHAR2B is taken
as the most significant byte).
ImageText8
drawable: DRAWABLE
gc: GCONTEXT
x, y: INT16
string: STRING8
Errors: Drawable, GContext, Match
The x and y coordinates are relative to drawable's origin,
and specify the baseline starting position (the initial
character origin). The effect is to first fill a
destination rectangle with the background pixel defined in
gc, and then paint the text with the foreground pixel.
The upper left corner of the filled rectangle is at
[x + overall-left, y - font-ascent]
the width is
overall-right - overall-left
and the height is
font-ascent + font-descent
where overall-left, overall-right, font-ascent, and
as font-descent are would be returned by a QueryTextExtents
call using gc and string.
The alu-function and fill-style defined in gc are ignored for
this request; the effective alu-function is Copy and the
effective fill-style Solid.
For fonts defined with two-byte matrix indexing, each STRING8
byte is interpreted as a byte2 value of a CHAR2B with a byte1
value of zero.
GC components: plane-mask, foreground, background, font,
subwindow-mode, clip-x-origin, clip-y-origin, clip-mask
ImageText16
drawable: DRAWABLE
gc: GCONTEXT
x, y: INT16
string: STRING16
Errors: Drawable, GContext, Match
Just like ImageText8, except two-byte (or 16-bit) characters
are used. For fonts defined with linear indexing rather than
two-byte matrix indexing, the server will interpret each
CHAR2B as a 16-bit number that has been transmitted most
significant byte first (i.e., byte1 of the CHAR2B is taken as
the most significant byte).
CreateColormap
mid: COLORMAP
visual: VISUALID
window: WINDOW
alloc: {None, All}
Errors: IDChoice, Window, Value, Match, Alloc
Creates a colormap of the specified visual type for the
screen on which the window resides, and associates the
identifier mid with it. The visual type must be one
supported by the screen, and cannot be of class TrueColor
(else a Match error). The initial values of the colormap
entries are undefined for classes GrayScale, PseudoColor,
and DirectColor; for StaticGray, StaticColor, and
TrueColor, the entries will have defined values, but those
values are specific to the visual and are not defined by
the core protocol. For StaticGray, StaticColor, and
TrueColor, alloc must be specified as None (else a Match
error). For the other classes, if alloc is None, the
colormap initially has no allocated entries, and clients
can allocate entries. If alloc is All, then the entire
colormap is "allocated" writable, but entries cannot be
freed with FreeColors, and no relationships among entries
is defined; the client must understand whether the colormap
is GrayScale, PseudoColor, or DirectColor to know how to
store into entries.
FreeColormap
cmap: COLORMAP
Errors: Colormap
Deletes the association between the resource id and the
colormap. If the colormap is an installed map for a screen,
it is uninstalled (see UninstallColormap). If the colormap
is defined as the colormap for a window (via CreateWindow or
ChangeWindowAttributes), the colormap for the window is
changed to None, and a ColormapNotify event is generated.The
colors displayed for a window with a colormap of None are not
defined by the protocol.
Has no effect on a default colormap for a screen.
CopyColormapAndFree
mid, src-cmap: COLORMAP
Errors: Colormap, Alloc
Creates a colormap for the same screen as src-cmap, and
associates identifier mid with it. Moves all of the client's
existing allocations from src-cmap to the new colormap, and
frees those entries in src-cmap. Values in other entries in
the new colormap are undefined.
InstallColormap
cmap: COLORMAP
Errors: Colormap
Makes this colormap an installed map for its screen. All
windows associated with this colormap immediately display
with true colors. As a side-effect, previously installed
colormaps may be uninstalled, and other windows may display
with false colors. Which colormaps get uninstalled is
server dependent, except that it is guaranteed that the
M-1 most recently client-installed colormaps will not be
uninstalled, where M is the min-installed-maps specified
for the screen in the connection setup.
If cmap is not already an installed map, a ColormapNotify
event is generated on every window having cmap as an
attribute. If a colormap is uninstalled as a result of
the install, a ColormapNotify event is generated on every
window having that colormap as an attribute.
Initially only the default colormap for a screen is
installed.
UninstallColormap
cmap: COLORMAP
Errors: Colormap
If cmap is an installed map for its screen, one or more
colormaps are installed in its place; the choice is server
dependent, pexcept that if the screen's default colormap is
not installed and can be installed (without forcing other
colormaps out), then the default colormap is used.
If cmap is an installed map, a ColormapNotify event is
generated on every window having this colormap as an
attribute. If a colormap is installed as a result of the
uninstall, a ColormapNotify event is generated on every
window having that colormap as an attribute.
ListInstalledColormaps
window: WINDOW
=>
cmaps: LISTofCOLORMAP
Errors: Window
Returns a list of the currently installed colormaps for the
screen of the specified window.
AllocColor
cmap: COLORMAP
red, green, blue: CARD16
=>
pixel: CARD32
red, green, blue: CARD16
Errors: Colormap, Alloc
Allocates a read-only colormap entry corresponding to the
closest RGB values provided by the hardware. Returns the
pixel and the RGB values actually used.
AllocNamedColor
cmap: COLORMAP
name: STRING8
=>
pixel: CARD32
exact-red, exact-green, exact-blue: CARD16
screen-red, screen-green, screen-blue: CARD16
Errors: Colormap, Name, Alloc
Looks up the named color with respect to the screen
associated with the colormap, then does an AllocColor on
cmap. The name should use the ASCII encoding, and
upper/lower case does not matter. The exact RGB values
specify the "true" values for the color, and the screen
values specify the values actually used in the colormap.
AllocColorCells
cmap: COLORMAP
colors, planes: CARD16
contiguous: BOOL
=>
pixels, masks: LISTofCARD32
Errors: Colormap, Value, Alloc
The number of colors must be positive, the number of planes
non-negative. If C colors and P planes are requested, then C
pixels and P masks are returned. No mask will have any bits
in common with any other mask, or with any of the pixels. By
ORing together masks and pixels, C*(2^P) distinct pixels can
be produced; all of these are allocated writable by the
request. For GrayScale or PseudoColor, each mask will have
exactly one bit, and for DirectColor each will have exactly
three bits. If contiguous is True, then if all masks are
ORed together, a single contiguous set of bits will be formed
for GrayScale or PseudoColor, and three contiguous sets of
bits (one within each pixel subfield) for DirectColor. The
RGB values of the allocated entries are undefined.
AllocColorPlanes
cmap: COLORMAP
colors, reds, greens, blues: CARD16
contiguous: BOOL
=>
pixels: LISTofCARD32
red-mask, green-mask, blue-mask: CARD32
Errors; Colormap, Value, Alloc
The number of colors must be positive, the reds, greens, and
blues non-negative. If C colors, R reds, G greens, and B
blues are requested, then C pixels are returned, and the
masks have R, G, and B bits set respectively. If contiguous
is True, then each mask will have a contiguous set of bits.
No mask will have any bits in common with any other mask, or
with any of the pixels. For DirectColor, each mask will lie
within the corresponding pixel subfield. By ORing together
subsets of masks with pixels, C*(2^(R+G+B)) distinct pixels
can be produced; all of these are allocated by the request.
The initial RGB values of the allocated entries are
undefined. In the colormap there are only C*(2^R)
independent red entries, C*(2^G) independent green entries,
and C*(2^B) independent blue entries. This is true even for
PseudoColor. When the colormap entry for a pixel value is
changed using StoreColors or StoreNamedColor, the pixel is
decomposed according to the masks and the corresponding
independent entries are updated.
FreeColors
cmap: COLORMAP
pixels: LISTofCARD32
plane-mask: CARD32
Errors: Colormap, Access, Value
The plane-mask should not have any bits in common with any of
the pixels. The set of all pixels is produced by ORing
together subsets of plane-mask with the pixels. The request
frees all of these pixels. Note that freeing an individual
pixel obtained from AllocColorPlanes may not actually allow
it to be reused until all of its "related" pixels are also
freed.
All specified pixels that are allocated by the client in
cmap are freed, even if one or more pixels produce an error.
A Value error is generated if a specified pixel is not a
valid index into cmap, and an Access error is generated if a
specified pixel is not allocated by the client (i.e., is
unallocated or is only allocated by another client). If more
than one pixel is in error, which one is reported is
arbitrary.
StoreColors
cmap: COLORMAP
items: LISTofCOLORITEM
where
COLORITEM: [pixel: CARD32
do-red, do-green, do-blue: BOOL
red, green, blue: CARD16]
Errors: Colormap, Access, Value
Changes the colormap entries of the specified pixels. The
do-red, do-green, and do-blue fields indicate which
components should actually be changed. If the colormap is an
installed map for its screen, the changes are visible
immediately.
All specified pixels that are allocated writable in cmap (by
any client) are changed, even if one or more pixels produce
an error. A Value error is generated if a specified pixel is
not a valid index into cmap, and an Access error is generated
if a specified pixel is unallocated or is allocated
read-only. If more than one pixel is in error, which one is
reported is arbitrary.
StoreNamedColor
cmap: COLORMAP
pixel: CARD32
name: STRING8
do-red, do-green, do-blue: BOOL
Errors: Colormap, Name, Access, Value
Looks up the named color with respect to the screen
associated with cmap, then does a StoreColors in cmap. The
name should use the ASCII encoding, and upper/lower case
does not matter.
QueryColors
cmap: COLORMAP
pixels: LISTofCARD32
=>
colors: LISTofRGB
where
RGB: [red, green, blue: CARD16]
Errors: Colormap, Value
Returns the color values stored in cmap for the specified
pixels. The values returned for an unallocated entry are
undefined. A Value error is generated if a pixel is not a
valid index into cmap. If more than one pixel is in error,
which one is reported is arbitrary.
LookupColor
cmap: COLORMAP
name: STRING8
=>
exact-red, exact-green, exact-blue: CARD16
screen-red, screen-green, screen-blue: CARD16
Errors: Colormap, Name
Looks up the string name of a color with respect to the
screen associated with cmap, and returns both the exact the
color values and the closest values provided by the hardware.
The name should use the ASCII encoding, and upper/lower
case does not matter.
CreateCursor
cid: CURSOR
source: PIXMAP
mask: PIXMAP or None
fore-red, fore-green, fore-blue: CARD16
back-red, back-green, back-blue: CARD16
x, y: CARD16
Errors: IDChoice, Bitmap, Match, Value, Alloc
Creates a cursor and associates identifier cid with it.
Foreground and background RGB values must be specified, even
if the server only has a monochrome screen. The foreground
is used for the one bits in the source, and the background is
used for the zero bits. Both source and mask (if specified)
must have depth one (else a Match error), but can have any
root. The mask pixmap defines the shape of the cursor; that
is, the one bits in the mask define which source pixels will
be displayed. If no mask is given, all pixels of the source
are displayed. The mask, if present, must be the same size
as source (else a Match error). The x and y coordinates
define the hotspot, relative to the source's origin, and must
be a point within the source (else a Match error).
The components of the cursor may be transformed arbitrarily
to meet display limitations.
The pixmaps can be freed immediately if no further explicit
references to them are to be made.
Subsequent drawing in the source or mask pixmap has an
undefined effect on the cursor; the server might or might
not make a copy of the pixmap.
CreateGlyphCursor
cid: CURSOR
source-font: FONT
mask-font: FONT or None
source-char, mask-char: CARD16
fore-red, fore-green, fore-blue: CARD16
back-red, back-green, back-blue: CARD16
Errors: IDChoice, Font, Value, Alloc
Similar to CreateCursor, but the source and mask bitmaps are
obtained from the specified font glyphs. The mask font and
character are optional. The origin of the source glyph
defines the hotspot, and the mask is positioned such that
the origins are coincident. The source and mask need not
have the same bounding box metrics. If no mask is given,
all pixels of the source are displayed. Note that
source-char and mask-char are CARD16 (not CHAR2B); for
two-byte matrix fonts, the 16-bit value should be formed
with byte1 in the most significant byte and byte2 in the
least significant byte.
FreeCursor
cursor: CURSOR
Errors: Cursor
Deletes the association between the resource id and the
cursor. The cursor storage will be freed when no other
resource references it.
RecolorCursor
cursor: CURSOR
fore-red, fore-green, fore-blue: CARD16
back-red, back-green, back-blue: CARD16
Errors: Cursor
Changes the color of a cursor. If the cursor is being
displayed on a screen, the change is visible immediately.
QueryBestSize
class: {Cursor, Tile, Stipple}
drawable: DRAWABLE
width, height: CARD16
=>
width, height: CARD16
Errors: Drawable, Value, Match
Returns the "best" size that is "closest" to the argument
size. For Cursor, this is the largest size that can be
fully displayed. For Tile, this is the size that can be
tiled "fastest". For Stipple, this is the size that can
be stippled "fastest".
For Cursor, the drawable indicates the desired screen. For
Tile and Stipple, the drawable indicates screen, and also
possibly window class and depth; an InputOnly window cannot
be used as the drawable for Tile or Stipple (else a Match
error).
QueryExtension
name: STRING8
=>
present: BOOL
major-opcode: CARD8
first-event: CARD8
first-error: CARD8
Determines if the named extension is present. If so, the
major opcode for the extension is returned, if it has one,
otherwise zero is returned. Any minor opcode and the request
formats are specific to the extension. If the extension
involves additional event types, the base event type code is
returned, otherwise zero is returned. The format of the
events is specific to the extension. If the extension
involves additional error codes, the base error code is
returned, otherwise zero is returned. The format of
additional data in the errors is specific to the extension.
The extension name should be in the ASCII encoding, and
upper/lower case matters.
ListExtensions
=>
names: LISTofSTRING8
Returns a list of all extensions supported by the server.
SetKeyboardMapping
map: LISTofCARD8
=>
status: {Success, Busy}
Errors: Value
Sets the mapping of the keyboard. Elements of the list are
indexed starting from one. The list must be of length 255.
The index is a "core" keycode, and the element of the list
defines the "effective" keycode.
A zero element disables a key, no elements can have values 1
through 7, and no two elements (with index larger than 7) can
have the same non-zero value. If the keyboard does not
really generate a given keycode, specifying a non-zero value
for that core keycode has no effect.
Elements 6 and 7 of the map must always be zero. The first
five elements are special: they specify the keycodes (if
any) that correspond to the Mod1 through Mod5 modifiers.
Setting one of these entries to zero disables use of that
modifier bit. No two of the firstfive elements can have the
same non-zero value.
A server can impose restrictions on how keyboards get
remapped, e.g., if certain keys do not generate up
transitions in hardware.
If any of the keys or modifiers to be altered are currently
in the down state, the status reply is Busy and the mapping
is not changed.
GetKeyboardMapping
=>
map: LISTofCARD8
Errors: Value
Returns the current mapping of the keyboard. Elements of the
list are indexed starting from one. The length of the list
is 255.
The nominal mapping for a keyboard is almost the identity
mapping, except that map[i]=0 for keycodes that have no
corresponding physical key, and the first five entries
indicate the keycodes (if any) corresponding to the Mod1
through Mod5 modifier bits.
ChangeKeyboardControl
value-mask: BITMASK
value-list: LISTofVALUE
Errors: Match Value
Controls various aspects of the keyboard. The value-mask and
value-list specify which controls are to be changed. The
possible values are:
key-click-percent: INT8
bell-percent: INT8
bell-pitch: INT16
bell-duration: INT16
led: CARD8
led-mode: {On, Off}
key: KEYCODE
auto-repeat-mode: {On, Off, Default}
Key-click-percent sets the volume for key clicks between 0
(off) and 100 (loud) inclusive, if possible. Setting to -1
restores the default. Other negative values generate a Value
error.
Bell-percent sets the base volume for the bell between 0
(off) and 100 (loud) inclusive, if possible. Setting to -1
restores the default. Other negative values generate a Value
error.
Bell-pitch sets the pitch (specified in Hz) of the bell, if
possible. Setting to -1 restores the default. Other
negative values generate a Value error.
Bell-duration sets the duration (specified in milliseconds)
of the bell, if possible. Setting to -1 restores the
default. Other negative values generate a Value error.
If both led-mode and led are specified, then the state of
that LED is changed, if possible. If only led-mode is
specified, then the state of all LEDs are changed, if
possible. At most 32 LEDs are supported, numbered from one.
It is a Match error if an led is specified without an
led-mode.
If both auto-repeat-mode and key are specified, then the
auto-repeat mode of that key is changed, if possible. If
only auto-repeat-mode is specified, then the global
auto-repeat mode for the entire keyboard is changed, if
possible, without affecting the per-key settings. It is
a Match error if a key is specified without an
auto-repeat-mode.
A bell generator connected with the console but not directly
on the keyboard is treated as if it were part of the
keyboard.
The order in which controls are verified and altered is
server dependent. If an error is generated, a subset of the
controls may have been altered.
GetKeyboardControl
=>
key-click-percent: CARD8
bell-percent: CARD8
bell-pitch: CARD16
bell-duration: CARD16
led-mask: CARD32
global-auto-repeat: {On, Off}
auto-repeats: LISTofCARD8
Errors: Match
Returns the current control values for the keyboard. For the
LEDs, the least significant bit of led-mask corresponds to
LED one, and each one bit in led-mask indicates an LED that
is lit. Auto-repeats is a bit vector; each one bit indicates
that auto-repeat is enabled for the corresponding key. The
vector is represented as 32 bytes. Byte N (from 0) contains
the bits for keys 8N to 8N+7, with the least significant bit
in the byte representing key 8N.
Bell
percent: INT8
Errors: Match, Value
Rings the bell on the keyboard at the specified volume
relative to the base volume for the keyboard, if possible.
Percent, which can range from -100 to 100 inclusive, is added
to the base volume, and the sum limited to the range 0 to 100
inclusive.
SetPointerMapping
map: LISTofCARD8
=>
status: {Success, Busy}
Errors: Value
Sets the mapping of the pointer. Elements of the list are
indexed starting from one. The length of the list must be
the same as GetPointerMapping would return. The index is a
"core" button number, and the element of the list defines
the "effective" number.
A zero element disables a button, and elements are not
restricted in value by the number of physical buttons, but
no two elements can have the same non-zero value.
If any of the buttons to be altered are currently in the
down state,the status reply is Busy and the mapping is not
changed.
GetPointerMapping
=>
map: LISTofCARD8
Errors: Value
Returns the current mapping of the pointer. Elements of the
list are indexed starting from one. The length of the list
indicates the number of physical buttons.
The nominal mapping for a pointer is the identity mapping;
map[i]=i.
ChangePointerControl
do-acceleration, do-threshold: BOOL
acceleration-numerator, acceleration-denominator: INT16
threshold: INT16
Errors: Match, Value
Defines how the pointer moves. The acceleration is a
multiplier for movement, expressed as a fraction. For
example, specifying 3/1 means the pointer moves three times
as fast as normal. The fraction may be rounded arbitrarily
by the server. Acceleration only takes effect if the
pointer moves more than threshold pixels at once, and only
applies to the amount beyond the threshold. Setting a
value to -1 restores the default. Other negative values
generate a Value error, as does a zero value for
acceleration-denominator.
GetPointerControl
=>
acceleration-numerator, acceleration-denominator: CARD16
threshold: CARD16
Errors: Match
Returns the current acceleration and threshold for the
pointer.
SetScreenSaver
timeout, interval: INT16
prefer-blanking: {Yes, No, Default}
allow-exposures: {Yes, No, Default}
Errors: Value
Timeout and interval are specified in minutes; setting a
value to -1 restores the default. Other negative values
generate a Value error. If the timeout value is zero,
screen-saver is disabled. If the timeout value is
non-zero, screen-saver is enabled. Once screen-saver
is enabled, if no input from the keyboard or pointer is
generated for timeout minutes, screen-saver is activated.
For each screen, if blanking is preferred and the hardware
supports video blanking, the screen will simply go blank.
Otherwise, if either exposures are allowed or the screen
can be regenerated without sending exposure events to
clients, the screen is tiled with the root window
background tile, randomly re-origined each interval
minutes if the interval value is non-zero. Otherwise, the
state of the screen does not change and screen-saver is not
activated. Screen-saver is deactivated, and all screen
states are restored, at the next keyboard or pointer input
or at the next ForceScreenSaver with mode Reset.
GetScreenSaver
=>
timeout, interval: CARD16
prefer-blanking: {Yes, No}
allow-exposures: {Yes, No}
Returns the current screen-saver control values.
ForceScreenSaver
mode: {Activate, Reset}
If the mode is Activate and screen-saver is currently
deactivated, then screen-saver is activated (even if
screen-saver has been disabled with a timeout value of zero).
If the mode is Reset and screen-saver is currently enabled,
then screen-saver is deactivated (if it was activated), and
then the activation timer is reset to its initial state, as
if device input had just been received.
ChangeHosts
mode: {Insert, Delete}
host: HOST
Errors: Access, Value
Adds or removes the specified host from the access control
list. When the access control mechanism is enabled and a
host attempts to establish a connection to the server, the
host must be in this list or the server will refuse the
connection.
The client must reside on the same host as the server, and/or
have been granted permission in the initial authorization at
connection setup.
An initial access control list can be specified, typically
by naming a file that the server reads at startup and reset.
ListHosts
=>
mode: {Enabled, Disabled}
hosts: LISTofHOST
Returns the hosts on the access control list, and whether use
of the list at connection setup is currently enabled or
disabled.
Each HOST is padded to a multiple of four bytes.
ChangeAccessControl
mode: {Enable, Disable}
Errors: Value, Access
Enables or disables the use of the access control list at
connection setups.
The client must reside on the same host as the server, and/or
have been granted permission in the initial authorization at
connection setup.
ChangeCloseDownMode
mode: {Destroy, RetainPermanent, RetainTemporary}
Errors: Value
Defines what will happen to the client's resources at
connection close. A connection starts in Destroy mode. The
meaning of the close-down mode is described in Section 11.
KillClient
resource: CARD32 or AllTemporary
Errors: Value
If a valid resource is specified, forces a close-down of the
client that created the resource. If the client has already
terminated in either RetainPermanent or RetainTemporary mode,
all of the client's resources are destroyed (see Section 11).
If AllTemporary is specified, then the resources of all
clients that have terminated in RetainTemporary are
destroyed.
NoOperation
This request has no arguments and no results, but the request
length field can be non-zero, allowing the request to be any
multiple of 4 bytes in length. The bytes contained in the
request are uninterpreted by the server.
This request can be used in its minimum 4 byte form as
"padding" where necessary by client libraries that find it
convenient to force requests to begin on 64-bit boundaries.
SECTION 11. CONNECTION CLOSE
What happens at connection close:
All event selections made by the client are discarded. If
the client has the pointer actively grabbed, an
UngrabPointer is performed. If the client has the keyboard
actively grabbed, an UngrabKeyboard is performed. All
passive grabs by the client are eleased. If the client has
the server grabbed, and UngrabServer is performed. If
close-down mode (see ChangeCloseDownMode) is
RetainPermanent or RetainTemporary, then all resources
(including colormap entries) allocated by the client are
marked as "permanent" or "temporary", respectively (but
this does not prevent other clients from explicitly
destroying them). If the mode is Destroy, then all of the
client's resources are destroyed as described below.
What happens when a client's resources are destroyed:
For each window in the client's save-set, if the window
created by the client, that save-set window is reparented to
the closest ancestor such that the save-set window is not an
inferior of a window created by the client. If the save-set
window is unmaped, a MapWindow request is performed on it.
After save-set processing, all windows created by the client
are destroyed. For each non-window resource created by the
client, the appropriate Free request is performed. All
colors and colormap entries allocated by the client are
freed.
What happens when the last connection to a server closes:
A server goes through a cycle, of having no connections and
having some connections. At every transition to the state
of having no connections, the server "resets" its state, as
if it had just been started. This starts by destroying all
lingering resources from clients that have terminated in
RetainPermanent or RetainTemporary mode. It additionally
includes deleting all but the predefined atom identifiers,
deleting all properties on all root windows, resetting all
device maps and attributes (key click, bell volume,
acceleration), resetting the access control list, restoring
the standard root tiles and cursors, restoring the default
font path, and restoring the input focus to state
PointerRoot.
SECTION 12. EVENTS
When a button is pressed with the pointer in some window W, and
no active pointer grab is in progress, then the ancestors if W are
searched from the root down, looking for a passive grab to
activate. If no matching passive grab on the button exists, then
an active grab is started automatically for the client receiving
the event, and the last-pointer-grab time is set to the current
server time. The effect is essentially equivalent to a GrabButton
with arguments:
event-window: the event window
event-mask: the client's selected events on the event window
pointer-mode and keyboard-mode: Asynchronous
owner-events: True if the client has OwnerGrabButton selected
on the event window, else False
confine-to: None
cursor: None
The grab is terminated automatically when all buttons are released.
UngrabPointer and ChangeActiveGrab can both be used to modify the
active grab.
KeyPress
and
KeyRelease
and
ButtonPress
and
ButtonRelease
and
MotionNotify
root, event: WINDOW
child: WINDOW or None
same-screen: BOOL
root-x, root-y, event-x, event-y: INT16
detail: <see below>
state: SETofKEYBUTMASK
time: TIMESTAMP
Generated when a key or button changes state, or the pointer
moves. The "source" of the event is the window the pointer
is in. The window with respect to which the event is
normally reported is found by looking up the hierarchy
(starting with the source window) for the first window on
which any client has selected interest in the event,
provided no intervening window prohibits event generation by
including the event type in its do-not-propagate-mask. The
actual window used for reporting can be modified by active
grabs and the focus window. The window the event is reported
with respect to is called the "event" window.
Root is the root window of the "source" window, and root-x
and root-y are the pointer coordinates relative to root's
origin at the time of the event. Event is the "event"
window. If the event window is on the same screen as root,
then event-x and event-y are the pointer coordinates relative
to the event window's origin; otherwise event-x and event-y
are zero. If the source window is an inferior of the event
window, then child is set to the child of the event window
that is an ancestor of the source window. The state
component gives the state of the buttons and modifier keys
just before the event. The detailcomponent varies with
the event type:
KeyPress, KeyRelease: KEYCODE
ButtonPress, ButtonRelease: BUTTON
MotionNotify: {Normal, Hint}
MotionNotify events are only generated when the motion
begins and ends in the window. The granularity of motion
events is not guaranteed, but a client selecting for motion
events is guaranteed to get at least one event when the
pointer moves and comes to rest. Selecting PointerMotion
receives events independent of the state of the pointer
buttons. By selecting some subset of Button[1-5]Motion
instead, MotionNotify events will only be received when one
or more of the specified buttons are pressed. By selecting
ButtonMotion, MotionNotify events will received only when at
least one button is pressed. The events are always of type
MotionNotify, independent of the selection. If
PointerMotionHint is selected, the server is free to send
only one MotionNotify event (with detail Hint) to the client
for the event window, until either the key or button state
changes, or the pointer leaves the event window, or the
client issues a QueryPointer or GetMotionEvents request.
EnterNotify
and
LeaveNotify
root, event: WINDOW
child: WINDOW or None
same-screen: BOOL
root-x, root-y, event-x, event-y: INT16
mode: {Normal, Grab, Ungrab}
detail: {Ancestor, Virtual, Inferior, Nonlinear,
NonlinearVirtual}
focus: BOOL
state: SETofKEYBUTMASK
time: TIMESTAMP
If pointer motion causes the pointer to be in a different
window than before, EnterNotify and LeaveNotify events are
generated instead of a MotionNotify event. Only clients
selecting EnterWindow on a window receive EnterNotify events,
and only clients selection LeaveNotifyreceive LeaveNotify
events. The pointer position reported in the event is always
the "final" position, not the "initial" position of the
pointer. In a LeaveNotify event, if a child of the event
window contains the "initial" position of the pointer, then
the child component is set to that child, otherwise it is
None. For an EnterNotify event, if a child of the event
window contains the "final" pointer position, then the child
component is set to that child, otherwise it is None. If
the the event window is the focus window or an inferior of
the focus window, then focus is True, and otherwisefocus is
False.
Normal pointer motion events have mode Normal; pseudo-motion
events when a grab actives have mode Grab, and pseudo-motion
events when a grab deactivates have mode Ungrab.
Normal events are generated as follows:
When the pointer moves from window A to window B, and A is an
inferior of B:
LeaveNotify with detail Ancestor is generated on A
LeaveNotify with detail Virtual is generated on each window
between A and B exclusive (in that order)
EnterNotify with detail Inferior is generated on B
When the pointer moves from window A to window B, and B is an
inferior of A:
LeaveNotify with detail Inferior is generated on A
EnterNotify with detail Virtual is generated on each window
between A and B exclusive (in that order)
EnterNotify with detail Ancestor is generated on B
When the pointer moves from window A to window B, with window C
being their least common ancestor:
LeaveNotify with detail Nonlinear is generated on A
LeaveNotify with detail NonlinearVirtual is generated on each
window between A and C exclusive (in that order)
EnterNotify with detail NonlinearVirtual is generated on each
window between C and B exclusive (in that order)
EnterNotify with detail Nonlinear is generated on B
When the pointer moves from window A to window B, on different
screens:
LeaveNotify with detail Nonlinear is generated on A
LeaveNotify with detail NonlinearVirtual is generated on each
window above A up to and including its root (in
order)
EnterNotify with detail NonlinearVirtual is generated on each
window
from B's root down to but not including B (in order)
EnterNotify with detail Nonlinear is generated on B
When a pointer grab activates (but after any initial warp into a
confine-to window), with G the grab-window for the grab and P the
window the pointer is in:
EnterNotify and LeaveNotify events with mode Grab are
generated (as for Normal above) as if the pointer were to
suddenly warp from its current position in P to some position
in G.However, the pointer does not warp, and the pointer
position is used as both the "initial"and "final" positions
for the events.
When a pointer grab deactivates, with G the grab-window for the
grab and P the window the pointer is in:
EnterNotify and LeaveNotify events with mode Ungrab are
generated (as for Normal above) as if the pointer were to
suddenly warp from from some position in G to its current
position in P. However, the pointer does not warp, and the
current pointer position is used as both the "initial" and
"final" positions for the events.
FocusIn
and
FocusOut
event: WINDOW
mode: {Normal, WhileGrabbed, Grab, Ungrab}
detail: {Ancestor, Virtual, Inferior, Nonlinear,
NonlinearVirtual, Pointer, PointerRoot, None}
Generated when the input focus changes. Reported to clients
selecting FocusChange on the window. Events generated by
SetInputFocus when the keyboard is not grabbed have mode
Normal; events generated by SetInputFocus when the keyboard
is grabbed have mode WhileGrabbed; events generated when a
keyboard grab actives have mode Grab, and events generated
when a keyboard grab deactivates have mode Ungrab.
Normal and WhileGrabbed events are generated as follows:
When the focus moves from window A to window B, and A is an
inferior of B, with the pointer in window P:
FocusOut with detail Ancestor is generated on A
FocusOut with detail Virtual is generated on each window
between A and B exclusive (in that order)
FocusIn with detail Inferior is generated on B
If P is an inferior of B, but P is not A or an inferior of A
or an ancestor of A, FocusIn with detail Pointer is
generated on each window below B down to and
including P (in order)
When the focus moves from window A to window B, and B is an
inferior of A, with the pointer in window P:
If P is an inferior of A, but P is not A or an inferior of B
or an ancestor of B, FocusOut with detail Pointer is
generated on each window from P up to but not
including A (in order)
FocusOut with detail Inferior is generated on A
FocusIn with detail Virtual is generated on each window
between A and B exclusive (in that order)
FocusIn with detail Ancestor is generated on B
When the focus moves from window A to window B, with window C
being their least common ancestor, and with the pointer in
window P:
If P is an inferior of A, FocusOut with detail Pointer is
generated on each window from P up to but not
including A (in order)
FocusOut with detail Nonlinear is generated on A
FocusOut with detail NonlinearVirtual is generated on each
window between A and C exclusive (in that order)
FocusIn with detail NonlinearVirtual is generated on each
window between C and B exclusive (in that order)
FocusIn with detail Nonlinear is generated on B
If P is an inferior of B, FocusIn with detail Pointer is
generated on each window below B down to and
including P (in order)
When the focus moves from window A to window B, on different
screens, with the pointer in window P:
If P is an inferior of A, FocusOut with detail Pointer is
generated on each window from P up to but not
including A (in order)
FocusOut with detail Nonlinear is generated on A
FocusOut with detail NonlinearVirtual is generated on each
window above A up to and including its root (in
order)
FocusIn with detail NonlinearVirtual is generated on each
window from B's root down to but not including B
(in order)
FocusIn with detail Nonlinear is generated on B
If P is an inferior of B, FocusIn with detail Pointer is
generated on each window below B down to and
including P (in order)
When the focus moves from window A to PointerRoot (or None)
If P is an inferior of A, FocusOut with detail Pointer is
generated on each window from P up to but not
including A (in order)
FocusOut with detail Nonlinear is generated on A
FocusOut with detail NonlinearVirtual is generated on each
window above A up to and including its root (in
order)
FocusIn with detail PointerRoot (or None) is generated on
all root windows
When the focus moves from PointerRoot (or None) to window A:
FocusOut with detail PointerRoot (or None) is generated on
all root windows
FocusIn with detail NonlinearVirtual is generated on each
window from A's root down to but not including A
(in order)
FocusIn with detail Nonlinear is generated on A
If P is an inferior of A, FocusIn with detail Pointer is
generated on each window below A down to and
including P (in order)
When the focus moves from PointerRoot to None (or vice versa):
FocusOut with detail PointerRoot (or None) is generated on
all root windows
FocusIn with detail None (or PointerRoot) is generated on
all root windows
When a keyboard grab activates, with G the grab-window for the
grab and F the current focus:
FocusIn and FocusOut events with mode Grab are generated (as
for Normal above) as if the focus were to change from F to G
When a keyboard grab deactivates, with G the grab-window for the
grab and F the current focus:
FocusIn and FocusOut events with mode Ungrab are generated
(as for Normal above) as if the focus were to change from G
to F
KeymapNotify
keys: LISTofCARD8
The value is a bit vector, as described in QueryKeymap.
Reported to clients selecting KeymapState on a window.
Generated immediately after every EnterNotify and FocusIn.
Expose
window: WINDOW
x, y, width, height: CARD16
last-in-series: BOOL
Reported to clients selecting Exposure on the window.
Possibly generated when a region of the window becomes
viewable, but might only be generated when a region becomes
visible. All of the regions exposed by a given "action" are
guaranteed to be reported contiguously; if last-in-series is
False then another exposure follows.
The x and y coordinates are relative to drawable's origin,
and specify the upper left corner of a rectangule. The
width and height specify the extent of the rectangle.
Expose events are never generated on InputOnly windows.
GraphicsExposure
drawable: DRAWABLE
x, y, width, height: CARD16
last-in-series: BOOL
major-opcode: CARD8
minor-opcode: CARD16
Reported to clients selecting graphics-exposures in a
graphics context. Generated when a destination region could
not be computed due to an obscured or out-of-bounds source
region. All of the regions exposed by a given graphics
request are guaranteed to be reported contiguously; if
last-in-series is False then another exposure follows.
The x and y coordinates are relative to drawable's origin,
and specify the upper left corner of a rectangule. The width
and height specify the extent of the rectangle.
The major and minor opcodes identify the graphics request
used. For the core protocol, major-opcode is always
CopyArea or CopyPlane and minor-opcode is always zero.
NoExposure
drawable: DRAWABLE
major-opcode: CARD8
minor-opcode: CARD16
Reported to clients selecting graphics-exposures in a
graphics context. Generated when a graphics request that
might produce GraphicsExposure events does not produce any.
The drawable specifies the destination used for the
graphics request.
The major and minor opcodes identify the graphics request
used. For the core protocol, major-opcode is always CopyArea
or CopyPlane and minor-opcode is always zero.
VisibilityNotify
window: WINDOW
state: {Unobscured, PartiallyObscured, FullyObscured}
Reported to clients selecting VisibilityChange on the
window. In the following, the state of the window is
calculated ignoring all of the window's subwindows. When
a window changes state from partially or fully obscured or
not viewable to viewable and completely unobscured, an
event with Unobscured is generated. When a window changes
state from a) viewable and completely unobscured or b) not
viewable, to viewable and partially obscured, an event with
PartiallyObscured is generated. When a window changes state
from a) viewable and completely unobscured or b) viewable and
partially obscured or c) not viewable, to viewable and fully
obscured, an event with FullyObscured is generated.
VisibilityNotify events are never generated on InputOnly
windows.
CreateNotify
parent, window: WINDOW
x, y: INT16
width, height, border-width: CARD16
override-redirect: BOOL
Reported to clients selecting SubstructureNotify on the
parent. Generated when the window is created. The arguments
are as in the CreateWindow request.
DestroyNotify
event, window: WINDOW
Reported to clients selecting StructureNotify on the window,
and to clients selecting SubstructureNotify on the parent.
Generated when the window is destroyed. "Event" is the
window on which the event was generated, and "window" is
the window that is destroyed.
UnmapNotify
event, window: WINDOW
from-configure: BOOL
Reported to clients selecting StructureNotify on the window,
and to clients selecting SubstructureNotify on the parent.
Generated when the window changes state from mapped to
unmapped. "Event" is the window on which the event was
generated, and "window" is the window that is unmapped. The
from-configure flag is True if the event was generated as a
result of the window's parent being resized when the window
itself had a win-gravity of Unmap.
MapNotify
event, window: WINDOW
override-redirect: BOOL
Reported to clients selecting StructureNotify on the window,
and to clients selecting SubstructureNotify on the parent.
Generated when the window changes state from unmapped to
mapped. "Event" is the window on which the event was
generated, and "window" is the window that is mapped. The
override-redirect flag is from the window's attribute.
MapRequest
parent, window: WINDOW
Reported to the client selecting SubstructureRedirect on the
parent. Generated when a MapWindow request is issued on an
unmapped window with an override-redirect attribute of False.
ReparentNotify
event, window, parent: WINDOW
x, y: INT16
override-redirect: BOOL
Reported to clients selecting SubstructureNotify on either
the old or the new parent, and to clients selecting
StructureNotify on the window. Generated when the window
is reparented. "Event" is the window on which the event
was generated, "window" is the window that has been
re-rooted, and "parent" specifies the new parent. The x
and y coordinates are relative to the new parent's origin,
and specify the position of the upper left outer corner of
the window. The override-redirect flag is from the
window's attribute.
ConfigureNotify
event, window: WINDOW
x, y: INT16
width, height, border-width: CARD16
above-sibling: WINDOW or None
override-redirect: BOOL
Reported to clients selecting StructureNotify on the window,
and to clients selecting SubstructureNotify on the parent.
Generated when a ConfigureWindow request actually changes the
state of the window. "Event" is the window on which the event
was generated, and "window" is the window that is changed.
If above-sibling is None, then the window is on the bottom of
the stack with respect to siblings; otherwise, the window is
immediately on top of the specified sibling. The
override-redirect flag is from the window's attribute.
GravityNotify
event, window: WINDOW
x, y: INT16
Reported to clients selecting SubstructureNotify on the
parent, and to clients selecting StructureNotify on the
window. Generated when a window is moved because of a
change in size of the parent. "Event" is the window on
which the event was generated, and "window" is the
window that is moved.
ResizeRequest
window: WINDOW
width, height: CARD16
Reported to the client selecting ResizeRedirect on the
window. Generated when a ConfigureWindow request by some
other client on the window attempts to change the size of the
window. The width and height are the inside size, not
including the border.
ConfigureRequest
parent, window: WINDOW
x, y: INT16
width, height, border-width: CARD16
above-sibling: WINDOW or None
Reported to the client selecting SubstructureRedirect on the
parent. Generated when a ConfigureWindow request is issued on
the window by some other client. The geometry is as derived
from the request. The above-sibling is the sibling the
window should be placed directly on top of; if None, then the
window should be placed on the bottom.
CirculateNotify
event, window: WINDOW
place: {Top, Bottom}
Reported to clients selecting StructureNotify on the window,
and to clients selecting SubstructureNotify on the parent.
Generated when the window is actually restacked from a
CirculateWindow request. "Event" is the window on which the
event was generated, and "window" is the window that is
restacked. If place is Top, the window is now on top of all
siblings; otherwise it is below all siblings.
CirculateRequest
parent, window: WINDOW
place: {Top, Bottom}
Reported to the client selecting SubstructureRedirect on the
parent. Generated when a CirculateWindow request is issued on
the parent and a window actually needs to be restacked. The
window specifies the window to be restacked, and place
specifies what the new position in the stacking order should
be.
PropertyNotify
window: WINDOW
atom: ATOM
state: {NewValue, Deleted}
time: TIMESTAMP
Reported to clients selecting PropertyChange on the window.
Generated when a property of the window is changed. The
timestamp indicates the server time when the property was
changed.
SelectionClear
owner: WINDOW
selection: ATOM
time: TIMESTAMP
Reported to the current owner of a selection. Generated on
the window losing ownership when a new owner is being
defined. The timestamp is the last-change time recorded for
the selection.
SelectionRequest
owner: WINDOW
selection: ATOM
target: ATOM
property: ATOM or None
requestor: WINDOW
time: TIMESTAMP or CurrentTime
Reported to the owner of a selection. Generated when a
client issues a ConvertSelection request. The arguments are
as in the request.
The owner should convert the selection based on the specified
target type. If a property is specified, the owner should
store the result as that property on the requestor window,
and then send a SelectionNotify event to the requestor using
SendEvent. If the selection cannot be converted as
requested, the owner should send a SelectionNotify with the
property set to None.
SelectionNotify
requestor: WINDOW
selection, target: ATOM
property: ATOM or None
time: TIMESTAMP or CurrentTime
This event is only generated by clients using SendEvent. The
owner of a selection should send this event to a requestor
when a selection has been converted and stored as a property,
or when a selection conversion could not be performed
(indicated with property None).
ColormapNotify
window: WINDOW
colormap: COLORMAP or None
new: BOOL
state: {Installed, Uninstalled}
Reported to clients selecting ColormapChange on the window.
Generated with value True for new when the colormap attribute
of the window is changed. Generated with value False for new
when the colormap of a window is installed or uninstalled. In
either case, state indicates whether the colormap is
currently installed.
ClientMessage
window: WINDOW
type: ATOM
format: {8, 16, 32}
data: LISTofINT8 or LISTofINT16 or LISTofINT32
This event is only generated by clients using SendEvent. The
type specifies how the data is to be interpreted by the
receiving client; the server places no interpretation on the
type or the data. The format specifies whether the data
should be viewed as a list of 8-bit, 16-bit, or 32-bit
quantities, so that the server can correctly byte-swap as
necessary. The data always consists of either 20 8-bit values
or 10 16-bit values or 5 32-bit values, although particular
message types might not make use of all of these values.
SECTION 13. FLOW CONTROL AND CONCURRENCY
Whenever the server is writing to a given connection, it is
permissible for the server to stop reading from that connection (but
if the writing would block it must continue to service other
connections). The server is not required to buffer more than a
single request per connection at one time. For a given connection
to the server, a client can block while reading from the connection,
but should undertake to read (events and errors) when writing would
block. Failure on the part of a client to obey this rule could
result in a deadlocked connection, although deadlock is probably
unlikely unless the transport layer has very little buffering, or
unless the client attempts to send large numbers of requests without
ever reading replies or checking for errors and events.
If a server is implemented with internal concurrency, the overall
effect must be as if individual requests are executed to completion
in some serial order, and that requests from a given connection are
executed in delivery order (i.e., the total execution order is a
shuffle of the individual streams). The "execution" of a request
includes validating all arguments, collecting all data for any
reply, and generating (and queueing) all required events, but does
not include the actual transmission of the reply and the events.
In addition, the effect of any other "cause" (e.g., activation of
a grab, pointer motion) that can generate multiple events must
effectively generate (and queue) all required events indivisibly
with respect to all other causes and requests.