BSD 4_3_Tahoe development

Work on file usr/src/new/X/doc/Xlib/ch01a.t
Work on file usr/src/new/X/doc/Xlib/ch02a.t
Work on file usr/src/new/X/doc/Xlib/ch03a.t
Work on file usr/src/new/X/doc/Xlib/ch03b.t

Synthesized-from: CSRG/cd2/4.3tahoe

diff --git a/usr/src/new/X/doc/Xlib/ch01a.t b/usr/src/new/X/doc/Xlib/ch01a.t
new file mode 100644 (file)
index 0000000..2fc355c
--- /dev/null
+++ b/usr/src/new/X/doc/Xlib/ch01a.t
@@ -0,0 +1,129 @@
+.NH
+Introduction
+.XS ii
+Table of Contents
+.XE
+.XS
+Introduction
+.XE
+.PP
+The X window system supports overlapping (sub)windows.
+All the windows in an X server are arranged in a strict hierarchy.  At
+the top of the hierarchy is the `root' window,
+which covers the entire display screen.
+The root window is partially or completely covered by child windows.
+All windows have parents except for the root window.
+There is usually at least one window per application program.
+.IN "Definitions" "Child Window"
+.IN "Definitions" "Parent Window"
+Child windows  may in turn have
+their own children.
+In this way, an application program can create a tree of arbitrary depth.
+.PP
+A child window may be larger than its parent--that is, part or all of
+the child window may extend beyond the boundaries of the parent.
+However, all output to a window is clipped by the boundaries of its
+parent window.
+.PP
+.IN "Definitions" "Stacking order"
+If several children of a window have overlapping locations, then one of
+the children is considered to be `on top of' or `raised over' the
+others, obscuring them.
+Output to areas covered by other windows will be suppressed by the window
+system.
+If a window  is obscured
+by a second window, 
+then the window will obscure only those ancestors of the second window which
+are also ancestors of the window.
+Normally, child windows obscure their parents
+as well (but there are exceptions--see the discussions of
+.IN "XOpenTransparency"
+.IN "XClipMode"
+\fIXOpenTransparency\fP and \fIXClipMode\fP for details).
+.PP
+.IN "Definitions" "Events"
+.IN "Events"
+Input from X takes the form of `events'.
+Events may either be side effects of a command (restacking windows,
+for example, generates exposure events),
+or completely asynchronous (for example, the keyboard).
+A client program asks to be informed of such events;
+X never sends events a program did not ask for.
+.PP
+X does not take responsibility for the contents of windows; when (part or
+all of) a window is hidden and then brought back onto the screen, its
+contents may be lost lost and the client program is notified (by an exposure
+event) that (part or all
+of) the window needs to be repainted.
+Programs should be prepared to regenerate their windows on demand.
+.PP
+.IN "Definitions" "Resource ID"
+Most of the subroutines in Xlib just add requests to an output buffer;
+these requests later execute asynchronously on the X server
+(often referred to as ``display server'' below).
+Subroutines that return values do not return (``block'')
+until an explicit reply is
+received or an error occurs.
+This may be queried information or a ``resource id'' discussed below.
+If such a call results in an error, the error will
+generally not be reported (by a call to an optional error handler)
+until some later, blocking call is made.
+.PP
+.IN "XSync"
+If a
+client does not want a request to execute asynchronously, he can follow
+it with a call to \fIXSync\fP, which will block until all previously buffered
+asynchronous events have been sent and acted on.
+.PP
+As an important side effect, 
+.IN "XPending"
+.IN "XNextEvent"
+.IN "XWindowEvent"
+.IN "XFlush"
+.IN "XSync"
+the output buffer is always flushed by a call to any subroutine
+which returns a value or by calls to \fIXPending\fP,
+\fIXNextEvent\fP, \fIXWindowEvent\fP,
+\fIXFlush\fP or \fIXSync\fP.
+.PP
+.IN "Resource ID" "Window"
+.IN "Resource ID" "Font"
+.IN "Resource ID" "Pixmap"
+.IN "Resource ID" "Bitmap"
+.IN "Resource ID" "Cursor"
+Many subroutines will return an integer resource id.
+These can be of type ``Window'', ``Font'', ``Pixmap'', ``Bitmap'',
+and ``Cursor'',
+.IN "File" "<X/X.h>"
+as defined in \fI<X/X.h>\fP.
+Some subroutines return ``Status'', an integer error indication.
+If the subroutine fails, it will return 0.
+.PP
+.IN "Definitions" "Status"
+Since C does not provide multiple return values, many subroutines return
+their results by writing into client-passed storage.  Any pointer that is
+used to return a value is designated as ``/* RETURN */'' in the procedure
+declarations below.
+All other pointers passed to these subroutines are
+used for reading only.
+If such a procedure returns a status of 0,
+then it has NOT updated the return parameters.
+.IN "Error Handling"
+By default, errors are handled by a standard library subroutine,
+or you can provide your own.
+Subroutines that return pointers to strings will return NULL pointers if
+the string does not exist.
+.PP
+.PP
+Input events (e.g. key pressed, mouse moved) arrive asynchronously from
+the server and are queued until they are requested by a call to
+\fIXNextEvent\fP or \fIXWindowEvent\fP.  In addition, some of the library
+.IN "XChangeWindow"
+.IN "XRaiseWindow"
+subroutines (e.g. \fIXChangeWindow\fP and \fIXRaiseWindow\fP)
+generate ``exposure''
+events--requests to repaint sections of a window that do not have valid
+contents.  These events also arrive asynchronously, but the client may
+.IN "XSync"
+wish to explicitly wait for them by calling \fIXSync\fP after calling a
+subroutine which may generate exposure events.

diff --git a/usr/src/new/X/doc/Xlib/ch02a.t b/usr/src/new/X/doc/Xlib/ch02a.t
new file mode 100644 (file)
index 0000000..43d6e59
--- /dev/null
+++ b/usr/src/new/X/doc/Xlib/ch02a.t
@@ -0,0 +1,23 @@
+.NH
+.IN "Linking Against Xlib"
+Use of Xlib
+.XS
+Linking Against Xlib
+.XE
+.PP
+To use Xlib, an include line of the form
+.IN "File" "<X/Xlib.h>"
+\fI#include <X/Xlib.h>\fP should be put near the top of a file
+using the library.
+This file defines data structures, macros,
+and symbols you will likely need when programming X.
+.IN "File" "<X/X.h>"
+.IN "File" "<sys/types.h>"
+This file also includes \fI<X/X.h>\fP, and \fI<sys/types.h>\fP.
+.IN "Unix Command" "CC(1)"
+To link an application to Xlib,
+add a \fI-lX\fP option to your cc command.
+.PP
+.IN "File" "<X/Xlib.h>"
+The types of most of the functions below are declared in \fIXlib.h\fP, so
+that you do not have to declare their types in your program.

diff --git a/usr/src/new/X/doc/Xlib/ch03a.t b/usr/src/new/X/doc/Xlib/ch03a.t
new file mode 100644 (file)
index 0000000..5a62a66
--- /dev/null
+++ b/usr/src/new/X/doc/Xlib/ch03a.t
@@ -0,0 +1,110 @@
+.EQ
+delim $$
+.EN
+.NH
+Data Representation
+.XS
+Data Representation
+.XE
+.PP
+.IN "Definitions" "Bitmap"
+.IN "Definitions" "Pixmap"
+A Bitmap is a single plane (bit) rectangle.
+A Pixmap is a rectangle of pixels, and is therefore as ``deep'' as the
+display.
+For example, if your color display has four bits/pixel,
+a Pixmap is a rectangle of four bit pixels.
+In this implementation of the underlying protocol,
+the depth of the display is limited to 16 bit planes.
+.IN "Limitations" "Bits per Pixel"
+The subroutine interface, however, is designed to support display hardware of
+up to 32 bits per pixel.
+The ``pixel value'' can range from 0 to $2 sup n$,
+where \fIn\fP is the number of
+bits per pixel.
+.IN "Definitions" "Pixel values"
+.IN "Definitions" "Cursors"
+Cursors are used as mouse pointers and typically track the mouse; a
+cursor is an arbitrary two-color shape with an arbitrary ``hot spot''.
+.PP
+.IN "Definitions" "Locator"
+A Locator is
+an absolute point on the screen, represented as <x,y> with the X-coordinate
+in the most significant 16 bits and the Y-coordinate in the least significant
+16 bits.
+.EQ
+delim off
+.EN
+.PP
+.IN "Definitions" "Bitmap"
+A Bitmap is represented by ((width + 15) / 16) * height * 2 bytes of data.
+Each row is stored starting on a word (16 bit) boundary, and is padded to
+the right to a 16 bit boundary.
+It is stored top line to bottom line in memory.
+It has a size of (width x height) pixels.
+.IN "Macro" "BitmapSize()"
+The macro \fIBitmapSize(width,height)\fP can be used to compute the size in
+bytes of the Bitmap.
+.IN "Definitions" "Bit Order"
+The
+bits are in scanline order, with each scanline padded if necessary to a
+multiple of 16 bits.
+Within a scanline, the bits are represented left to
+right, stored in 16-bit words.
+The least significant bit of a word is the leftmost visible pixel on the 
+display.
+Analysis showed that the bit reversal cpu time incurred on some
+machine architectures was small relative to the
+data transmission time,
+so a fixed client bitmap representation was selected for portability's sake.
+.PP
+.IN "Definitions" "Pixmap"
+.IN "Definitions" "XY-format"
+.IN "Definitions" "Z-format"
+A Pixmap can be represented in either `XY format' or `Z format'.
+In XY format,
+each plane is represented as a Bitmap, and the planes appear from most to least
+significant bit order.
+The total number of bytes is thus
+((width + 15) / 16) * height * 2 * depth.
+.IN "Macro" "XYPixmapSize()"
+The macro \fIXYPixmapSize(width, height, planes)\fP can be used to
+compute the size in bytes of a Pixmap in XY format.
+In Z format, the pixels are in
+scanline order, left to right within a scanline.
+For hardware with 2 to 8
+planes, each pixel value is represented by a single byte;
+the total number of bytes
+is thus width * height.
+For hardware with 9 to 16 planes, each pixel value is
+represented by a 16-bit word; the total number of bytes is thus
+2 * width * height.
+.IN "Macro" "BZPixmapSize()"
+.IN "Macro" "WZPixmapSize()"
+The macros \fIBZPixmapSize(width, height)\fP and 
+\fIWZPixmapSize(width, height)\fP
+can be used to compute the size in bytes of a pixmap in Z format for
+2 to 8 bit planes and 9 to 16 bitplanes respectively.
+.IN "Restrictions" "Z-format"
+Z-format cannot be used on monochrome display hardware.
+.PP
+Background tiling uses Pixmaps to specify the
+pattern.
+Since you may want such patterns either relative to
+.IN "Definitions" "Tile Mode"
+the window or absolute, there is a concept of `tile mode' associated
+with a window, allowing the pattern to be absolutely positioned to the window,
+or relative to the parent window (often the root window).
+This allows alignment of patterns either to the window you are working
+in, or to the parent window.
+Both are useful; icon windows often want relative alignment, while
+normal windows usually want absolute alignment.
+.PP
+.IN "Macro" "BlackPixel"
+.IN "Macro" "WhitePixel"
+The pixel values \fIBlackPixel\fP and \fIWhitePixel\fP (0 and 1) are
+.IN "File" "<X/X.h>
+always defined on every display server, as defined in \fI<X/X.h>\fP.
+These constants are intended for use in monochrome applications.
+On color hardware, the colors of black and white may
+be redefined by the user.

diff --git a/usr/src/new/X/doc/Xlib/ch03b.t b/usr/src/new/X/doc/Xlib/ch03b.t
new file mode 100644 (file)
index 0000000..cc673c8
--- /dev/null
+++ b/usr/src/new/X/doc/Xlib/ch03b.t
@@ -0,0 +1,27 @@
+.NH 2
+Display Coordinate System
+.XS
+Display Coordinate system
+.XE
+.PP
+.IN "Definitions" "Coordinate System"
+.IN "Definitions" "X Axis"
+.IN "Definitions" "Y Axis"
+As with most bitmap display systems, the coordinate system is
+different from a cartesian coordinate system.
+X and y coordinate systems are measured in pixels from
+the UPPER LEFT corner of the screen or window.
+.PP
+This means that while the X coordinate behaves as one might expect,
+the Y coordinate increases DOWN the screen.
+.PP
+.IN "Definitions" "Window Size"
+When you specify the size of a window in X, it is the size of the
+usable pixels inside the border.
+.PP
+X always measures window size in pixels EXCLUSIVE of borders, from the
+upper left hand corner.
+This is the actual usable size of the window.
+.PP
+If you query the root window, you can determine the absolute size of the 
+display.