.\".U7
.\".UT "Glossary"
\&
.XS
Glossary
.XE
.sp 1
.ce 1
\s+1\fBGlossary\fP\s-1
.sp 2
.na
.LP
.KS
.PN "Access control list"
.IP
X maintains a list of hosts from which client programs may be run.  
By default, 
only programs on the local host may use the display, 
plus any hosts specified in an initial list read by the server.  
This ``access control list'' can be changed by clients on the local host.  
Some server implementations may also implement other authorization mechanisms
in addition to or in place of this mechanism.
The action of this mechanism may be conditional based on the authorization protocol name
and data received by the server at connection setup. 
.KE
.LP
.KS
.PN "Active grab"
.IP
A grab is ``active'' when the pointer or keyboard is actually owned by the 
single grabbing client.
.KE
.LP
.KS
.PN Ancestors
.IP
If W is an inferior of A, then A is an ``ancestor'' of W.
.KE
.LP
.KS
.PN Atom
.IP
An ``atom'' is a unique ID corresponding to a string name.
Atoms are used to identify properties, types, and selections.
.KE
.LP
.KS
.PN Background
.IP
An
.PN InputOutput
window can have a ``background,'' defined as a pixmap,
in which case when regions of the window have their contents lost 
or invalidated,
the server automatically tiles those regions with the background.
.KE
.LP
.KS
.PN "Backing store"
.IP
When a server maintains the contents of a window, 
the off-screen saved pixels are known as a ``backing store.''
.KE
.LP
.KS
.PN "Bit gravity"
.IP
When a window is resized, 
the contents of the window are not necessarily discarded.  
It is possible to request the server (though no guarantees are made) 
to relocate the previous contents to some region of the window.  
This attraction of window contents for some location of
a window is known as ``bit gravity.''
.KE
.LP
.KS
.PN "Bit plane"
.IP
When a pixmap or window is thought of as a stack of bitmaps,
each bitmap is called a ``bit plane'' or ``plane.''
.KE
.LP
.KS
.PN Bitmap
.IP
A ``bitmap'' is a pixmap of depth one.
.KE
.LP
.KS
.PN Border
.IP
An
.PN InputOutput
window can have a ``border'',
with equal thickness on all four sides of the window.
The contents of the border are defined by a pixmap,
and the server automatically maintains the contents of the border.
Exposure events are never generated for border regions.
.KE
.LP
.KS
.PN "Button grabbing"
.IP
Buttons on the pointer may be passively ``grabbed'' by a client.
When the button is pressed, 
the pointer is then actively grabbed by the client.
.KE
.LP
.KS
.PN "Byte order"
.IP
For image (pixmap/bitmap) data, 
byte order is defined by the server,
and clients with different native byte ordering must swap bytes as
necessary.  
For all other parts of the protocol, 
the byte order is defined by the client, 
and the server swaps bytes as necessary.
.KE
.LP
.KS
.PN Children
.IP
The ``children'' of a window are its first-level subwindows.
.KE
.LP
.KS
.PN Class
.IP
Windows can be of different types.
See the entries for
.PN InputOnly
and
.PN InputOutput
windows for further information about valid window types.
.KE
.LP
.KS
.PN Client
.IP
An application program connects to the window system server by some
interprocess communication (IPC) path, such as a TCP connection or a
shared memory buffer.  
This program is referred to as a ``client'' of the window system server.  
More precisely, 
the client is the IPC path itself. 
A program with multiple paths open to the server is viewed as
multiple clients by the protocol.  
Resource lifetimes are controlled by
connection lifetimes, not by program lifetimes.
.KE
.LP
.KS
.PN "Clipping region"
.IP
In a graphics context, 
a bitmap or list of rectangles can be specified
to restrict output to a particular region of the window.  
The image defined by the bitmap or rectangles is called a ``clipping region.''
.KE
.LP
.KS
.PN "Color map"
.IP
A ``color map'' consists of a set of entries defining color values.
The color map associated with a window is used to display the contents of
the window; each pixel value indexes the color map to produce RGB values
that drive the guns of a monitor.
Depending on hardware limitations, 
one or more color maps may be installed at one time, 
such that windows associated with those maps display with true colors.
.KE
.LP
.KS
.PN Connection
.IP
The IPC path between the server and client program is known as a
``connection.''
A client program typically (but not necessarily) has one
connection to the server over which requests and events are sent.
.KE
.LP
.KS
.PN Containment
.IP
A window ``contains'' the pointer if the window is viewable and the
hotspot of the cursor is within a visible region of the window or a
visible region of one of its inferiors.  
The border of the window is included as part of the window for containment.  
The pointer is ``in'' a window if the window contains the pointer but no inferior 
contains the pointer.
.KE
.LP
.KS
.PN "Coordinate system"
.IP
The coordinate system has X horizontal and Y vertical, with the origin
[0, 0] at the upper left.  
Coordinates are discrete, and in terms of pixels.  
Each window and pixmap has its own coordinate system.  
For a window, 
the origin is at the inside upper left, inside the border.
.KE
.LP
.KS
.PN Cursor
.IP
A ``cursor'' is the visible shape of the pointer on a screen.  
It consists of a hot spot, a source bitmap, a shape bitmap, and a pair of colors.  
The cursor defined for a window controls the visible
appearance when the pointer is in that window.
.KE
.LP
.KS
.PN Depth
.IP
The ``depth'' of a window or pixmap is the number of bits per pixel it has.
The depth of a graphics context is the depth of the drawables it can be
used in conjunction with for graphics output.
.KE
.LP
.KS
.PN Device
.IP
Keyboards, mice, tablets, track-balls, button boxes, etc. are all
collectively known as input ``devices.''
Pointers can have one or more buttons 
(usually, the most common number is three).
The core protocol only deals with two devices: ``the keyboard'' 
and ``the pointer.''
.KE
.LP
.KS
.PN "Direct color"
.IP
A class of color map in which a pixel value is decomposed into three
separate subfields for indexing.
One subfield indexes an array to produce red intensity values; the second subfield 
indexes a second array to produce blue intensity values; and the third subfield indexes
a third array to produce green intensity values.
The RGB (red, green, and blue) values in the colormap entry can be 
changed dynamically.
.KE
.LP
.KS
.PN Display
.IP
A server, together with its screens and input devices, is called a ``display.''
The Xlib
.PN Display
.IN "Display"
structure contains all information about the particular display and its screens
as well as the state that Xlib needs to communicate with the display over a
particular connection.
.KE
.LP
.KS
.PN Drawable
.IP
Both windows and pixmaps may be used as sources and destinations in graphics operations.  
These are collectively known as ``drawables.''
However, an 
.PN InputOnly 
window cannot be used as a source or destination in a
graphics operation.
.KE
.LP
.KS
.PN Event
.IP
Clients are informed of information asynchronously by means of ``events.''  
These events may be either asynchronously generated from devices, or
generated as side effects of client requests.  
Events are grouped into types. 
Events are never sent to a client by the server unless the
client has specifically asked to be informed of that type of event,
but clients ndow described
can force events to be sent to other clients.  
Events are typically reported relative to a window.
.KE
.LP
.KS
.PN "Event mask"
.IP
Events are requested relative to a window.  
The set of event types a client requests relative to a window is described 
by using an ``event mask.''
.KE
.LP
.KS
.PN "Event synchronization" 
.IP
There are certain race conditions possible when demultiplexing device
events to clients (in particular deciding where pointer and keyboard
events should be sent when in the middle of window management
operations).  
The event synchronization mechanism allows synchronous processing of device events.
.KE
.LP
.KS
.PN "Event propagation"
.IP
Device-related events ``propagate'' from the source window to ancestor
windows until some client has expressed interest in handling that type
of event, or until the event is discarded explicitly.
.KE
.LP
.KS
.PN "Event source"
.IP
The smallest window containing the pointer is the ``source'' of a device
related event.
.KE
.LP
.KS
.PN "Exposure event"
.IP
Servers do not guarantee to preserve the contents of windows when
windows are obscured or reconfigured.  
``Exposure'' events are sent to clients to inform them when contents of regions of 
windows have been lost.
.KE
.LP
.KS
.PN Extension
.IP
Named ``extensions'' to the core protocol can be defined to extend the system.  
Extension to output requests, resources, and event types are all possible, and expected.
.KE
.LP
.KS
.PN Font
.IP
A ``font'' is an array of glyphs (typically characters).  
The protocol does no translation or interpretation of character sets.  
The client simply indicates values used to index the glyph array.  
A font contains additional metric information to determine inter-glyph 
and inter-line spacing.
.KE
.LP
.KS
.PN "Frozen events"
.IP
Clients can ``freeze'' event processing while they change the screen.
.KE
.LP
.KS
.PN GC
.IP
Shorthand for ``graphics context.''
An equivalent shorthand is GContext.
See \fBgraphics context\fP.
.KE
.LP
.KS
.PN Glyph
.IP
A ``glyph'' is an image, typically of a character, in a font.
.KE
.LP
.KS
.PN Grab
.IP
Keyboard keys, the entire keyboard, pointer buttons, the pointer, 
and the server can be ``grabbed'' for exclusive use by a client.  
In general, these facilities are not intended to be used by normal applications, 
but are intended for various input and window managers to implement various
styles of user interfaces.
.KE
.LP
.KS
.PN "Graphics context"
.IP
Various information for graphics output is stored in a ``graphics
context'' (``GC'' or ``GContext''), such as foreground pixel, background
pixel, line width, clipping region, etc.
A graphics context can only
be used with drawables that have the same root and the same depth as
the graphics context. 
.KE
.LP
.KS
.PN Gravity
.IP
The contents of windows, or subwindows themselves, have a ``gravity.''
This determines how they will be moved when a window ID resized.
See ``bit gravity'' and ``window gravity.''
.KE
.LP
.KS
.PN "Gray scale"
.IP
Gray scale can be viewed as a degenerate case of pseudo color, in which
case the red, green, and blue values in any given color map entry are equal,
thus producing shades of gray.
The gray values can be changed dynamically.
.KE
.LP
.KS
.PN Hotspot
.IP
A cursor has an associated ``hot spot'' which defines a point in the
cursor that corresponds to the coordinates reported for the pointer.
.KE
.LP
.KS
.PN Identifier
.IP
Each resource has an ``identifier'', a unique value associated with it
that clients use to name the resource.  
An identifier can be used over any connection to name the resource.
.KE
.LP
.KS
.PN Inferiors
.IP
The ``inferiors'' of a window are all of the subwindows nested below it:
the children, the children's children, etc.
.KE
.LP
.KS
.PN "Input focus"
.IP
The ``input focus'' is where keyboard input goes.
Keyboard events are by default sent to the client expressing interest
on the window the pointer is in.  
This is said to be a ``real estate driven'' input focus.  
It is also possible to attach the keyboard input to a specific window. 
Events will then be sent to the appropriate client independent of the pointer position.
.KE
.LP
.KS
.PN "Input manager"
.IP
Control over keyboard input is typically provided by an ``input manager'' 
client, usually part of a window manager.
.KE
.LP
.KS
.PN "InputOnly window"
.IP
A window that cannot be used for graphics requests.  
.PN InputOnly 
windows are ``invisible'' and can be used to control such things as cursors,
input event generation, and grabbing.
.PN InputOnly 
windows cannot have 
.PN InputOutput 
windows as inferiors.
.KE
.LP
.KS
.PN "InputOutput window"
.IP
The ``normal'' kind of window that is used for both input and output.
It usually has a background.
.PN InputOutput 
windows can have both 
.PN InputOutput 
and 
.PN InputOnly 
windows as inferiors.
.KE
.LP
.KS
.PN "Key grabbing"
.IP
Keys on the keyboard may be passively ``grabbed'' by a client.  
When the key is pressed, 
the keyboard is then actively grabbed by the client.
.KE
.LP
.KS
.PN "Keyboard grabbing" 
.IP
A client can actively ``grab'' control of the keyboard, and key events
will be sent to that client rather than the client the events would
normally have been sent to.
.KE
.LP
.KS
.PN Keysym
.IP
An encoding of a symbol on a keycap on a keyboard.
.KE
.LP
.KS
.PN Mapped
.IP
A window is said to be ``mapped'' if a map call has been performed on it.
Unmapped windows and their inferiors are never viewable or visible.
.KE
.LP
.KS
.PN "Modifier keys"
.IP
Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock,
ShiftLock, and similar keys are called ``modifier'' keys.
.KE
.LP
.KS
.PN Monochrome
.IP
A special case of static gray, in which there are only two color map entries.
.KE
.LP
.KS
.PN Obscure
.IP
A window is ``obscured'' if some other window ``obscures'' it.
A window can be partially obscured and still have visible regions.
.KE
.LP
.KS
.PN Obscures
.IP
Window A ``obscures'' window B if both are viewable InputOutput windows, if A is
higher in the global stacking order, and if the rectangle defined by the outside
edges of A intersects the rectangle defined by the outside edges of B.
Note the (fine) distinction with ``occludes.''
Also note that window borders are included in the calculation.
.KE
.LP
.KS
.PN Occlude
.IP
A window is ``occluded'' if some other window ``occludes'' it.
.KE
.LP
.KS
.PN Occludes
.IP
Window A ``occludes'' window B if both are mapped, 
if A is higher in the global stacking order, 
and if the rectangle defined by the outside edges of A intersects the rectangle defined 
by the outside edges of B.  
Note the (fine) distinction with ``obscures.''
Also note that window borders are included in the calculation.
Note that
.PN InputOnly
windows never obscure other windows but can occludes other windows.
.KE
.LP
.KS
.PN Padding
.IP
Some padding bytes are inserted in the data stream to maintain
alignment of the protocol requests on natural boundaries.  
This increases ease of portability to some machine architectures.
.KE
.LP
.KS
.PN "Parent window"
.IP
If C is a child of P, then P is the ``parent'' of C.
.KE
.LP
.KS
.PN "Passive grab"
.IP
Grabbing a key or button is a ``passive'' grab.  
The grab activates when the key or button is actually pressed.
.KE
.LP
.KS
.PN "Pixel value"
.IP
A ``pixel'' is an N-bit value (at a single point), 
where N is the number of bit planes (that is, the
depth of) used in a particular window or pixmap.  
A pixel in a window indexes a color map to derive an actual color to be 
displayed.
.KE
.LP
.KS
.PN Pixmap
.IP
A ``pixmap'' is a three dimensional array of bits.  
A pixmap is normally thought of as a two dimensional array of pixels, 
where each pixel can be a value from 0 to %2 sup N %\-1, 
where N is the depth (z axis) of the pixmap.  
A pixmap can also be thought of as a stack of N bitmaps.
A pixmap can only be used on the screen that it was created in.
.KE
.LP
.KS
.PN Plane
.IP
When a pixmap or window is thought of as a stack of bitmaps, each
bitmap is called a ``plane'' or ``bit plane.''
.KE
.LP
.KS
.PN "Plane mask"
.IP
Graphics operations can be restricted to only affect a subset of bit
planes of a destination.  
A ``plane mask'' is a bit mask describing which planes are to be modified,
and is stored in a graphics context.
.KE
.LP
.KS
.PN Pointer
.IP
The ``pointer'' is the pointing device currently attached to the cursor,
and tracked on the screens.
.KE
.LP
.KS
.PN "Pointer grabbing"
.IP
A client can actively ``grab'' control of the pointer, and button and
motion events will be sent to that client rather than the client the
events would normally have been sent to.
.KE
.LP
.KS
.PN "Pointing device"
.IP
A ``pointing device'' is typically a mouse or tablet, or some other
device with effective dimensional motion.  
Only one visible cursor is defined by the core protocol, 
and it tracks whatever pointing device is attached as the pointer.
.KE
.LP
.KS
.PN Property
.IP
Windows may have associated ``properties'', consisting of a name, a type,
a data format, and some data.  
The protocol places no interpretation on properties. 
They are intended as a general-purpose naming mechanism for clients.  
For example, clients might share information such as resize
hints, program names, and icon formats with a window manager 
by means of properties.
.KE
.LP
.KS
.PN "Property list"
.IP
The ``property list'' of a window is the list of properties that have
been defined for the window.
.KE
.LP
.KS
.PN "Pseudo color"
.IP
A class of color map in which a pixel value indexes the color map entry to
produce independent red, green, and blue values.
That is, the color map is viewed as an array of triples (RGB values).
The RGB values can be changed dynamically.
.KE
.LP
.KS
.PN Raise
.IP
Changing the stacking order of a window so as to occlude another
window is to ``raise'' that window.
.KE
.LP
.KS
.PN Rectangle
.IP
A ``rectangle'' specified by [x,y,w,h] has an (infinitely thin)
outline path with corners at [x,y], [x+w,y], [x+w,y+h] and [x, y+h].
When a rectangle is filled,
the lower right edges are not drawn.
For example,
if w=h=0,
nothing would be drawn.
For w=h=1,
a single pixel would be drawn.
.KE
.LP
.KS
.PN "Redirecting control"
.IP
Window managers (or client programs) may wish to enforce window layout
policy in various ways.  
When a client attempts to change the size or position of a window, 
the operation may be ``redirected'' to a specified client, 
rather than the operation actually being performed.
.KE
.LP
.KS
.PN Reply
.IP
Information requested by a client program by means of the X protocol 
is sent back to the client with a ``reply.''
Both events and replys are multipexed on the same connection.  
Most requests do not generate replies.
Some requests generate multiple replies.
.KE
.LP
.KS
.PN Request
.IP
A command to the server is called a ``request.''  
It is a single block of data sent over a connection.
.KE
.LP
.KS
.PN Resource
.IP
Windows, pixmaps, cursors, fonts, graphics contexts, and color maps are
known as ``resources.''  
They all have unique identifiers associated with them for naming purposes.  
The lifetime of a resource usually is bounded by the lifetime of the 
connection over which the resource was created.
.KE
.LP
.KS
.PN "RGB values"
.IP
``Red, green, and blue'' intensity values are used to define a color.
These values are always represented as 16 bit unsigned numbers, with zero
the minimum intensity and 65535 the maximum intensity.
The X server scales these values to match the display hardware.
.KE
.LP
.KS
.PN Root
.IP
The ``root'' of a pixmap or graphics context is the same as the root 
of whatever drawable was used when the pixmap or gcontext was created.  
The ``root'' of a window is the root window under which the window was created.
.KE
.LP
.KS
.PN "Root window"
.IP
Each screen has a ``root window'' covering it.  
It cannot be reconfigured or unmapped, but otherwise acts as a full fledged window.
A root window has no parent.
.KE
.LP
.KS
.PN "Save set"
.IP
The ``save set'' of a client is a list of other client's windows which,
if they are inferiors of one of the client's windows at connection
close, should not be destroyed, and which should be remapped if it is unmapped.  
Save sets are typically used by window managers to avoid
lost windows if the manager should terminate abnormally.
.KE
.LP
.KS
.PN Scanline
.IP
A ``scanline'' is a list of pixel or bit values viewed as a horizontal
row (all values having the same y coordinate) of an image, with the
values ordered by increasing x coordinate.
.KE
.LP
.KS
.PN "Scanline order"
.IP
An image represented in ``scanline order'' contains scanlines ordered by
increasing y coordinate.
.KE
.LP
.KS
.PN Screen
.IP
A server may provide several independent ``screens'', which typically
have physically independent monitors.  
This would be the expected configuration when there is only a single keyboard 
and pointer shared among the screens.
A 
.PN Screen 
.IN "Screen" 
structure contains the information about that screen
and is linked to the 
.PN Display
.IN "Display"
structure.
.KE
.LP
.KS
.PN Selection
.IP
A ``selection'' can be thought of as an indirect property with dynamic
type.
That is, rather than having the property stored in the X server,
it is maintained by some client (the ``owner'').
A selection is global
in nature, being thought of as belonging to the user (but maintained by
clients), rather than being private to a particular window subhierarchy
or a particular set of clients.
When a client asks for the contents of
a selection, it specifies a selection ``target type.''
This target type
can be used to control the transmitted representation of the contents.
For example, if the selection is ``the last thing the user clicked on'',
and that is currently an image, then the target type might specify
whether the contents of the image should be sent in XYFormat or
ZFormat.
.IP
The target type can also be used to control the class of
contents transmitted, for example, 
asking for the ``looks'' (fonts, line
spacing, indentation, and so forth) of a paragraph selection, rather than the
text of the paragraph.
The target type can also be used for other
purposes.
The semantics are not constrained by the protocol.
.KE
.LP
.KS
.PN Server
.IP
The ``server'', also referred to as the``X server'', provides the basic 
windowing mechanism.  
It handles IPC connections from clients, demultipexes graphics requests onto the
screens, and multiplexes input back to the appropriate clients.
.KE
.LP
.KS
.PN "Server grabbing"
.IP
The server can be ``grabbed'' by a single client for exclusive use.  
This prevents processing of any requests from other client connections until
the grab is complete.  
This is typically only a transient state for such things as rubber-banding 
and pop-up menus, or to execute requests indivisibly.
.KE
.LP
.KS
.PN Sibling
.IP
Children of the same parent window are known as ``sibling'' windows.
.KE
.LP
.KS
.PN "Stacking order"
.IP
Sibling windows may ``stack'' on top of each other.  
Windows above both obscure and occlude lower windows.  
This is similar to paper on a desk.  
The relationship between sibling windows is known as the ``stacking order.''
.KE
.LP
.KS
.PN "Static color"
.IP
Static color can be viewed as a degenerate case of pseudo color, in
which the RGB values are predefined and read-only.
See \fBpseudo color\fP.
.KE
.LP
.KS
.PN "Static gray"
.IP
Static gray can be viewed as a degenerate case of gray scale, in which
the gray values are predefined and read-only.
The values are typically
(near-)linear increasing ramps.
See \fBgray scale\fP.
.KE
.LP
.KS
.PN Stipple
.IP
A ``stipple pattern'' is a bitmap that is used to tile a region to serve
as an additional clip mask for a fill operation with the foreground
color.
.KE
.LP
.KS
.PN Status
.IP
Many Xlib functions return a success status.
If the function does not succeed,
however, its arguments ar not disturbed.
.KE
.LP
.KS
.PN Tile
.IP
A pixmap can be replicated in two dimensions to ``tile'' a region.  
The pixmap itself is also known as a ``tile.''
.KE
.LP
.KS
.PN Timestamp
.IP
A time value, expressed in milliseconds, typically since the last server reset.
Timestamp values wrap around (after about 49.7 days).
The server, given its current time is represented by timestamp T, always interprets
timestamps from clients by treating half of the timestamp space as being earlier
in time than T, and half of the timestamp space as being later in time than T.
One timestamp value, represented by the constant 
.PN CurrentTime 
is never generated by the server. 
This value is reserved for use in requests to represent the current server time.
.KE
.LP
.KS
.PN "True color"
.IP
True color can be viewed as a degenerate case of direct color, in which the
subfields in the pixel value directly encode the corresponding RGB
values.
That is, the color map has predefined read-only RGB values.
The values are typically (near-)linear increasing ramps.
See \fBdirect color\fP.
.KE
.LP
.KS
.PN Type
.IP
A type is an arbitrary atom used to identify the interpretation of property data.  
Types are completely uninterpreted by the server. 
They are solely for the benefit of clients.
X predefines type atoms for many frequently used types,
and clients also can define new types.
.KE
.LP
.KS
.PN Viewable
.IP
A window is ``viewable'' if it and all of its ancestors are mapped.  
This does not imply that any portion of the window is actually visible.
Graphics requests can be performed on a window when it is not
viewable, but output will not be retained unless the server is maintaining
backing store. 
.KE
.LP
.KS
.PN Visible
.IP
A region of a window is ``visible'' if someone looking at the screen can
actually ``see'' it:  the window is viewable and the region is not occluded
by any other window.
.KE
.LP
.KS
.PN "Window gravity"
.IP
When windows are resized, 
subwindows may be repositioned automatically relative to some position in the 
window.
This attraction of a subwindow to some part of its parent is known 
as ``window gravity.''
.KE
.LP
.KS
.PN "Window manager"
.IP
Manipulation of windows on the screen, and much of the user interface
(policy) is typically provided by a ``window manager'' client.
.KE
.LP
.KS
.PN XYFormat
.IP
The data for a pixmap is said to be in ``XYFormat'' if it is organized as
a set of bitmaps representing individual bit planes.
.KE
.LP
.KS
.PN ZFormat
.IP
The data for a pixmap is said to be in ``ZFormat'' if it is organized as
a set of pixel values in scanline order.
.KE
.bp
