% Copyright (C) 1989, Digital Equipment Corporation
% All rights reserved.
% See the file COPYRIGHT for a full description.
%
% Last modified on Tue Dec 15 10:27:54 PST 1992 by kalsow
%      modified on Mon Feb  3 22:02:09 PST 1992 by muller

\newenvironment{interfaces}{\begin{center}\begin{tabular}{p{1.5in}p{4.5in}}}{
        \end{tabular}\end{center}}

\chapter{The libraries}
%======================

\label{libs}

\srcmodula includes a large set of libraries, described in this chapter.
It is intended that the interfaces within the library be complete and
self documenting.

              \index{files!suffixes}
              \index{files!.ix, .mx, .ax@{\tt .ix}, {\tt .mx}, {\tt .ax}}
              \index{.ix, .mx, .ax files@{\tt .ix}, {\tt .mx}, {\tt .ax} files}
The library {\tt foo} is in the files {\tt LIB/libfoo.a} and
{\tt LIB/libfoo.ax}, and the interfaces that are implemented by this
library are in the directory {\tt PUB}; {\tt LIB} and {\tt PUB} depend
on your local configuration, see chapter~\ref{local} for the values of these
parameters (by default, they are {\tt /usr/local/lib/m3} and
{\tt /usr/local/include/m3}).

              \index{compiler!options}
              \index{-l@{\tt -l}}
Normally, the {\tt m3} driver knows the location of the public
interfaces and archives.  You just need to pass the {\tt -lfoo} option
to {\tt m3} to link with the library {\tt foo}.  Also, the driver
automatically links with the {\tt m3} library. 

The key to making \modula successful requires designing, building and
sharing libraries. You are encouraged to send us useful modules or programs
and we will include them in the next release as contributed software.
You can also announce the availability of your work on \newsgroup.

Your system may have additional libraries; see chapter~\ref{local}
or ask your system administrator.

\section{The m3 library}
%--------------------------
               \index{libm3.a@{\tt libm3.a}}
The {\tt m3} library contains some basic interfaces and modules. This
library is always included when linking \modula programs, and its
interfaces are accessible using the default search path.

Conversion of representation:

               \index{I/O!numeric conversion}
               \index{numeric conversion}
\begin{interfaces}
\intf{Fmt}      & Formatting to \verb|Text.T| \\
\intf{Scan}     & Parsing from \verb|Text.T| \\
\intf{Convert}  & Basic binary/ASCII conversion of numbers \\
\intf{CConvert} & Low-level routines for floating-point conversion \\
\end{interfaces}

Input/output is achieved using readers and writers:

               \index{I/O!streams}
\begin{interfaces}
\intf{Rd}           & Basic operations on readers \\
\intf{UnsafeRd}     & Faster version for non-concurrent access \\
\intf{RdClass}      & To implement new classes of readers \\
\intf{Wr}           & Basic operations on writers \\
\intf{UnsafeWr}     & Faster version for non-concurrent access \\
\intf{WrClass}      & To implement new classes of writers \\
\intf{TextRd}       & Readers that are connected to \verb|Text.T|s \\
\intf{TextWr}       & Writers that are connected to \verb|Text.T|s \\
\intf{Stdio}        & Readers and writers for standard files \\
\intf{FileStream}   & Readers and writers connected to named files \\
\intf{UFileRdWr}    & Readers and writers connected to file descriptors \\
\intf{NullRd}       & An empty reader \\
\intf{NullWr}       & A writer that absorbs bytes \\
\intf{UFileRd}      & Readers connected to Unix file descriptors \\
\intf{UFileWr}      & Writers connected to Unix file descriptors \\
\intf{FilterRd}     & A transparent filter \\
\intf{RdUtils}      & Convenience procedures scan readers and format errors\\
\intf{IOFailure}    & Lists the common exceptions raised by readers and writers
\end{interfaces}

Higher-level input/output:

              \index{pickles}
\begin{interfaces}
\intf{AutoFlushWr}   & buffered writers that flush automatically\\
\intf{MsgRd}         & Readers on streams of messages \\
\intf{MsgWr}         & Writers on streams of messages \\
\intf{SeekableRd}    & Seekable readers from unseekable ones \\
\intf{Pkl}           & reading and writing binary data structures
\end{interfaces}

Support for more complex parsing and printing:

            \index{parsing}
            \index{pretty-printing}
\begin{interfaces}
\intf{Formatter}   & Formatting of text, for example for pretty-printers \\
\intf{FWr}         & Writers with embedded formatting commands \\
\intf{FieldList}   & Awk-like field access to input \\
\intf{Lex}         & Simple string scanning \\
\end{interfaces}

There is also a very primitive equivalent of \verb|stdio|, which is
needed by the low-levels of the runtime: \intf{SmallIO}.

Fingerprints (64 bits CRC's are built using polynomial arithmetic:

          \index{fingerprints}
\begin{interfaces}
\intf{FPrint}        & Compute the fingerprint of a \verb|Text.T| \\
\intf{PolyBasis}     & support for \intf{FPrint} \\
\intf{Poly}          & support for \intf{FPrint}
\end{interfaces}

There is a set of interfaces to provide standard access to and
operations on basic types: \intf{Char}, \intf{Boolean}, \intf{Cardinal},
\intf{Integer}, \intf{Real}, \intf{LongReal}, \intf{Extended}, \intf{Address}, {\tt
Refany}, \intf{Root}, and \intf{Cast}.

The m3 library has a few basic data structures, lists:

          \index{lists!generic}
\begin{interfaces}
\intf{List}            & Lists of \verb|REFANY|s \\
\intf{GenList.[im]g}   & Generic list interface and implementation \\
\intf{RefanyList}      & Lists of \verb|REFANY|s \\
\intf{TextList}        & Lists of \verb|TEXT|s \\
\end{interfaces}

sets:
           \index{sets}
\begin{interfaces}
\intf{IntegerSet}  & sets of \verb|INTEGER|s \\
\intf{RefanySet}   & sets of \verb|REFANY|s \\
\intf{TextSet}     & sets of \verb|TEXT|s \\
\end{interfaces}

tables:
           \index{tables}
\begin{interfaces}
\intf{IntTable}    & Tables that map \verb|INTEGER|s to \verb|REFANY|s\\
\intf{RefTable}    & Tables that map \verb|REFANY|s to \verb|REFANY|s \\
\intf{IntIntTbl}   & Tables that map \verb|INTEGER|s to \verb|INTEGER|s \\
\intf{IntRefTbl}   & Tables that map \verb|INTEGER|s to \verb|REFANY|s \\
\intf{IntTxtTbl}   & Tables that map \verb|INTEGER|s to \verb|TEXT|s \\
\intf{RefIntTbl}   & Tables that map \verb|REFANY|s to \verb|INTEGER|s \\
\intf{RefRefTbl}   & Tables that map \verb|REFANY|s to \verb|REFANY|s \\
\intf{RefTxtTbl}   & Tables that map \verb|REFANY|s to \verb|TEXT|s \\
\intf{TxtIntTbl}   & Tables that map \verb|TEXT|s to \verb|INTEGER|s \\
\intf{TxtRefTbl}   & Tables that map \verb|TEXT|s to \verb|REFANY|s \\
\intf{TxtTxtTbl}   & Tables that map \verb|TEXT|s to \verb|TEXT|s \\
\intf{IntegerToIntegerTable} & obsolete --- use \verb|IntIntTbl| \\
\intf{IntegerToRefanyTable}  & obsolete --- use \verb|IntRefTbl| \\
\intf{IntegerToTextTable}    & obsolete --- use \verb|IntTxtTbl| \\
\intf{RefanyToIntegerTable}  & obsolete --- use \verb|RefIntTbl| \\
\intf{RefanyToRefanyTable}   & obsolete --- use \verb|RefRefTbl| \\
\intf{RefanyToTextTable}     & obsolete --- use \verb|RefTxtTbl| \\
\intf{TextToIntegerTable}    & obsolete --- use \verb|TxtIntTbl| \\
\intf{TextToRefanyTable}     & obsolete --- use \verb|TxtRefTbl| \\
\intf{TextToTextTable}       & obsolete --- use \verb|TxtTxtTbl| \\
\end{interfaces}

sorted tables:
             \index{sorted tables}
\begin{interfaces}
\intf{STable}      & Sorted tables, implemented by 2-3-4 trees \\
\intf{STableF}     & friends-only interface to sorted tables \\
\intf{SIntTable}   & \intf{STable} applied to \intf{INTEGER} \\
\intf{SIntTableF}  & friends-only interface to sorted integer tables \\
\intf{STextTable}  & \intf{STable} applied to \verb|Text.T| \\
\intf{STextTableF} & friends-only interface to sorted text tables
\end{interfaces}

property lists:
            \index{lists!property}
            \index{property lists}
\begin{interfaces}
\intf{Property}    & simple, unmonitored property lists \\
\intf{PropertyV}   & property sets including NIL \\
\intf{PropertyF}   & friends-only \\
\intf{MProperty}   & monitored property lists \\
\intf{MPropertyF}  & friends-only \\
\end{interfaces}

symbolic expressions:
            \index{symbolic expressions}
\begin{interfaces}
\intf{Atom}        & unique texts \\
\intf{Sx}          & symbolic expressions \\
\intf{SxSymbol}    & ``symbols'' for symbolic expressions \\
\intf{SxSyntax}    & controls for reading and printing symbolic expressions \\
\intf{SxPrivate}   & friends-only private definitions \\
\end{interfaces}

There is a set of interfaces that give access to the ANSI-C libraries. This
collection is under construction and provides only a subset of the ANSI
required functionality.

            \index{C linkage@{\tt C} linkage}
\begin{interfaces}
\intf{M3toC}      & support for \modula/C communication \\
\intf{Ctypes}     & C-like names for types \\
\intf{Cstdarg}    & obsolete \\
\intf{Cstdlib}    & \verb|stdlib.h| \\
\intf{Cstring}    & \verb|string.h| \\
\intf{Cerrno}     & \verb|errno.h|  \\
\intf{Cstddef}    & \verb|stddef.h| \\
\intf{Csetjmp}    & \verb|setjmp.h| \\
\intf{Cstdio}     & \verb|stdio.h|  \\
\end{interfaces}

There is a set of interfaces that give access to the runtime system.
The \intf{Rep} interfaces depend heavily on the runtime implementation;
other interfaces are more likely to be present (at least, similar
functionalities) in other systems.

            \index{runtime!interfaces}
\begin{interfaces}
\intf{RTException}  & exception mechanism \\
\intf{RTMath}       & basic math functions \\
\intf{RTScheduler}  & low-level access to the thread scheduler \\
\intf{RTType}       & type manipulation \\
\intf{RTProc}       & procedure manipulation \\
\intf{RTHeap}       & heap allocation and garbage collection \\
\intf{RTHeapRep}    & additional control over the heap \\
\intf{RTMisc }      & miscellaneous support functions; runtime errors \\
\intf{RTStack }     & low-level thread stack allocation \\
\intf{RTThread }    & low-level thread switching \\
\intf{RT0}          & low-level types used throughout the runtime \\
\intf{RT0u}         & low-level variables initialized by the linker \\
\intf{RTArgs}       & low-level access to the command line and environment \\
\intf{RTTypeFP}     & type fingerprints \\
\intf{RTMain}       & main program control \\
\intf{RTParams}     & runtime parameters \\
\intf{RTutils}      & misc. runtime diagnostics \\
\intf{RTHeapPolicy} & parameters to tune the allocator and collector \\
\intf{RTWeakRef}    & runtime support for \verb|WeakRef| \\
\intf{RTHeapComm}   & \verb|showheap| support \\
\intf{RTHeapEvent}  & \verb|showheap| support \\
\intf{RTLoader}     & dynamic loading support \\
\intf{RTSignal}     & runtime signal handlers \\
\end{interfaces}

There is a set of interfaces giving access to the Unix system.  These
interfaces are machine-dependent, but we tried to use the same names
in all versions to make programs easier to port.  Thus, it should be
no more difficult to port Modula-3 programs that use these interfaces
than it is to port C programs.

In general, an interface regroups the definitions given by a system
include file and the related functions.  Eventually, all of sections 2
and 3 should be available.  Currently, we have pieces of the following
interfaces:

               \index{Unix!interfaces}
\begin{interfaces}
\intf{Utypes}     & Declarations of types name (\verb|sys/types.h|) \\
\intf{Uerror}     & Declarations of error codes (\verb|errno.h|) \\
\intf{Uipc}       & Inter-process communication (\verb|sys/ipc.h|) \\ 
\intf{Umsg}       & Inter-process messages (\verb|sys/msg.h|) \\
\intf{Unetdb}     & Network database manipulation (\verb|netdb.h|) \\
\intf{Uprocess}   & Process ids\\
\intf{Uresource}  & Resources utilization (\verb|sys/resource.h|) \\
\intf{Usem}       & Semaphores (\verb|sys/sem.h|) \\
\intf{Ushm}       & Shared memory (\verb|sys/shm.h|) \\
\intf{Usignal}    & Signals (\verb|signal.h|) \\
\intf{Utime}      & Time manipulation (\verb|sys/time.h|) \\
\intf{Uugid}      & User and group ids\\
\intf{Uutmp}      & Login names (\verb|utmp.h|) \\
\intf{Upwd}       & (\verb|pwd.h|) \\
\intf{Usocket}    & (\verb|socket.h|) \\
\intf{Usyslog}    & (\verb|syslog.h|) \\
\intf{Uuio}       & (\verb|uio.h|) \\
\intf{Udir}       & (\verb|dir.h|) \\
\intf{Uexec}      & (\verb|exec.h|) \\
\intf{Ustat}      & (\verb|stat.h|) \\
\intf{Uin}        & (\verb|in.h|) \\
\intf{Umman}      & memory management (\verb|mman.h|) \\
\intf{Unix}       & Other functions (not yet organized in separate interfaces)\\
\end{interfaces}

Some geometric support:

                \index{geometry}
\begin{interfaces}
\intf{Math}       & sin, cos and friends \\
\intf{Point}      & 2-D integral points \\
\intf{Interval}   & Open integral intervals\\
\intf{Axis}       & horizontal and vertical axes\\
\intf{Rect}       & 2-D integral rectangles\\
\intf{Transform}  & 2-D transformations \\
\intf{Stat}       & simple statistics \\
\intf{Region}     & a set of integer lattice points \\
\intf{Path}       & a sequence of straight and curved line segments \\
\intf{Trapezoid}  & quadrilaterals with horizontal north and south edges \\
\intf{PolyRegion} & a list of regions \\
\intf{PathPrivate}& friends-only representation of paths \\
\intf{RegionRep}  & friends-only representation of regions \\
\intf{Range}      & simple support for computing \verb|start+length| spans\\
\end{interfaces}

Support for manipulating colors:

                \index{colors}
\begin{interfaces}
\intf{Color}           & color values as \verb|REAL| triples\\
\intf{ColorMatch}      & nearest color match from a set \\
\intf{ColorName}       & mapping from color names to RGB triples \\
\intf{ColorNameF}      & friends-only cache of color names\\
\intf{RGB}             & Red-Green-Blue triple \\
\intf{HSV}             & Hue-Saturation-\\
\intf{CIE}             & 1931 Comission Internationale de l'Eclairage colors\\
\intf{LDW}             & a perceptual color model \\
\intf{YPQ}             & another perceptual color model \\
\intf{IntRGB}          & 10-bit, fixed-point RGB triples \\
\intf{ByteRGB}         & [0..255] RGB triples\\
\intf{Intensity}       & light intensities \\
\intf{IntensityScale}  & tables for scaling light intensities \\
\intf{RGBCIE}          & friends-only RGB $\Leftrightarrow$ CIE mapping \\
\intf{RGBDist}         & distances between RGB values \\
\intf{RGBIO}           & I/O of RGB values as symbolic expressions \\
\intf{RGBScale}        & linear scaling of RGB values \\
\intf{RGBSort}         & sorting of RGB arrays \\
\intf{RGBSortPrivate}  & friends-only \\
\end{interfaces}

Interfaces to access and manipulate command line arguments and
environment variables:

                \index{environment variables}
                \index{command line arguments}
                \index{arguments, command line}
\begin{interfaces}
\intf{Env}         & Simple access to environment variables \\
\intf{Params}      & Simple access to command line arguments \\
\intf{ParseParams} & Parsing of UNIX-style command lines \\
\intf{ParseShell}  & Lower level support \\
\end{interfaces}

Interfaces to navigate through the file system:


                 \index{files!interfaces}
                 \index{resources}
                 \index{bundles}
\begin{interfaces}
\intf{Dir}         & directory access \\
\intf{Filename}    & File names manipulation  \\
\intf{File}        & simple file access \\
\intf{Pathname}    & pathname manipulation \\
\intf{Bundle}      & Access to embedded files \\
\intf{BundleRep}   & friends-only interface to embedded files \\
\intf{Rsrc}        & General resource locator \\
\end{interfaces}

Interfaces for manipulating times:

                 \index{time}
\begin{interfaces}
\intf{Time}        & Time manipulation \\
\intf{LongRealTime}& Times as \verb|LONGREAL|s \\
\intf{ETimer}      & Elapsed time counters \\
\end{interfaces}

Interfaces to help build external performance monitoring tools like
\verb|showheap| and \verb|showthreads|:

                \index{performance monitoring}
\begin{interfaces}
\intf{PerfTool}       & start/stop control for external performance tools \\
\intf{LowPerfTool}    & start/stop control for low-level external perf. tools\\
\intf{PerfComm.[im]g} & generic binding for performance tools \\
\end{interfaces}

Finally, various interfaces, including the  mandatory ones.

               \index{required interfaces}
               \index{random numbers}
               \index{unique IDs}
               \index{floating-point!interfaces}
               \index{weak references}
\begin{interfaces}
\intf{Main}        & Main program interface \\
\intf{Text}        & Character strings \\
\intf{TextF}       & Reveals to our friends what a \verb|Text.T| is \\
\intf{Thread}      & Control of concurrency \\
\intf{ThreadF}     & Additional control for our friends \\
\intf{ThreadComm}  & binding layer for \verb|showheap| \\
\intf{ThreadEvent} & data passed to \verb|showheap| \\
\intf{Word}        & Unsigned integer manipulation \\
\intf{Random}      & Random numbers \\
\intf{RandomPerm}  & Random permutations \\
\intf{UID}         & Generate unique identifiers \\
\intf{Float.ig}  & generic properties and functions of floating-point values \\
\intf{RealFloat}   & standard functions on \verb|REAL| values \\
\intf{LongFloat}   & standard functions on \verb|LONGREAL| values \\
\intf{ExtendedFloat}   & standard functions on \verb|EXTENDED| values \\
\intf{FloatMode}   & control for arithmetic exceptions and rounding \\
\intf{FPU}         & hardware floating-point unit description \\
\intf{SRCM3Path}   & Modula-3 file name components \\
\intf{CopyBytes}   & safe!? interface to copy bytes \\
\intf{M3Config}    & Site-specific configuration data \\
\intf{WeakRef}     & weak references (i.e. don't prevent garbage collection) \\
\end{interfaces}

%\section{The Posix library}
%%--------------------------
%
%The library \intf{m3posix} contains umimplemented interfaces that constitute a
%proposal for a \modula binding of Posix. See the \intf{README} file
%for more details.

\section{The data structures library}
%------------------------------------

               \index{libm3data.a@{\tt libm3data.a}}
               \index{-lm3data@{\tt -lm3data}}
The library \verb|m3data| provides generic data structures.  The
interfaces in that library are currently being designed and the
implementations need more testing.  Your comments are welcome.

First, a small collection of interfaces to be used as parameters
to the generic modules below:

\begin{interfaces}
\intf{Int}                & \verb|INTEGER|s  \\
\intf{Reel}               & \verb|REAL|s  \\
\intf{Txt}                & \verb|TEXT|s  \\
\end{interfaces}

In the interfaces that follow, {\em foo}\intf{ADT}, is an interface
that specifies the properties of all {\em foo}s and \intf{foo} is
an interface that provides a reasonable default implementation of
a {\em foo}\intf{ADT}.

generic sets:
                 \index{sets!generic}
\begin{interfaces}
\intf{SetADT.[im]g}       & generic abstract set \\
\intf{Set.[im]g}          & a generic set \\
\intf{IntSetADT}          & an abstract set of \verb|INTEGER|s \\
\intf{IntSet}             & a set of \verb|INTEGER|s \\
\intf{ReelSetADT}         & an abstract set of \verb|REAL|s \\
\intf{ReelSet}            & a set of \verb|REAL|s \\
\intf{TxtSetADT}          & an abstract set of \verb|TEXT|s \\
\intf{TxtSet}             & a set of \verb|TEXT|s \\
\end{interfaces}

generic bags:
                 \index{bags!generic}
\begin{interfaces}
\intf{BagADT.[im]g}       & generic abstract bag \\
\intf{Bag.[im]g}          & a generic bag \\
\intf{IntBagADT}          & an abstract bag of \verb|INTEGER|s \\
\intf{IntBag}             & a bag of \verb|INTEGER|s \\
\intf{ReelBagADT}         & an abstract Bag of \verb|REAL|s \\
\intf{ReelBag}            & a bag of \verb|REAL|s \\
\intf{TxtBagADT}          & an abstract Bag of \verb|TEXT|s \\
\intf{TxtBag}             & a bag of \verb|TEXT|s \\
\end{interfaces}

generic queues:
                 \index{queues!generic}
\begin{interfaces}
\intf{QueueADT.[im]g}     & generic abstract queue \\
\intf{Queue.[im]g}        & a generic queue \\
\intf{IntQueueADT}        & an abstract queue of \verb|INTEGER|s \\
\intf{IntQueue}           & a queue of \verb|INTEGER|s \\
\intf{ReelQueueADT}       & an abstract Queue of \verb|REAL|s \\
\intf{ReelQueue}          & a queue of \verb|REAL|s \\
\intf{TxtQueueADT}        & an abstract Queue of \verb|TEXT|s \\
\intf{TxtQueue}           & a queue of \verb|TEXT|s \\
\end{interfaces}

generic priority queues:
                 \index{priority queues!generic}
\begin{interfaces}
\intf{PQueueADT.[im]g}     & generic abstract priority queue \\
\intf{PQueue.[im]g}        & a generic priority queue \\
\intf{IntPQueueADT}        & an abstract priority queue of \verb|INTEGER|s \\
\intf{IntPQueue}           & a priority queue of \verb|INTEGER|s \\
\intf{ReelPQueueADT}       & an abstract Priority Queue of \verb|REAL|s \\
\intf{ReelPQueue}          & a priority queue of \verb|REAL|s \\
\intf{TxtPQueueADT}        & an abstract Priority Queue of \verb|TEXT|s \\
\intf{TxtPQueue}           & a priority queue of \verb|TEXT|s \\
\end{interfaces}

generic stacks:
                 \index{stacks!generic}
\begin{interfaces}
\intf{StackADT.[im]g}     & generic abstract stack \\
\intf{Stack.[im]g}        & a generic stack \\
\intf{IntStackADT}        & an abstract stack of \verb|INTEGER|s \\
\intf{IntStack}           & a stack of \verb|INTEGER|s \\
\intf{ReelStackADT}       & an abstract Stack of \verb|REAL|s \\
\intf{ReelStack}          & a stack of \verb|REAL|s \\
\intf{TxtStackADT}        & an abstract Stack of \verb|TEXT|s \\
\intf{TxtStack}           & a stack of \verb|TEXT|s \\
\end{interfaces}

\section{The X11R4 library}
%--------------------------

               \index{X library}
               \index{libm3X11R4.a@{\tt libm3X11R4.a}}
               \index{-lm3X11R4@{\tt -lm3X11R4}}
The library \intf{m3X11R4} contains binding interfaces for the X11R4
system.  The interfaces are:

\begin{interfaces}
\intf{X}   & Xlib-level functionalities \\
\intf{Xt}  & X Toolkit Intrinsics \\
\intf{XtC} & X class types \\
\intf{XtE} & X representation types \\
\intf{XtN} & X resource names\\
\intf{XtR} & X representation types \\
\intf{Xrm} & X resources \\
\intf{Xmu} & X misc. utilities \\
\intf{Xct} & X compound text \\
\intf{Xaw} & X Athena Widget set \\
\intf{Xatom} & X atoms \\
\end{interfaces}

\section{The Trestle library}
%----------------------------


               \index{Trestle}
               \index{windows}
               \index{user interface}
               \index{VBT}
               \index{virtual bitmap terminal}
               \index{libm3ui.a@{\tt libm3ui.a}}
               \index{-lm3ui@{\tt -lm3ui}}
The library \intf{m3ui} contains the Trestle toolkit.  It's a
powerful set of tools for building windowing applications.
A full description of Trestle can be found in the ``Trestle
Reference Manual'' \cite{Trestle}.

\begin{interfaces}
\intf{VBT}          & the basic window abstraction: Virtual Bitmap Terminal \\
\intf{Trestle}      & top-level access to the window system \\
\end{interfaces}

interfaces to compose windows:
                  \index{windows!composition}
\begin{interfaces}
\intf{Split}          & the general interface for splitting sub-windows  \\
\intf{ZSplit}         & overlapping windows  \\
\intf{HVSplit}        & tiled windows  \\
\intf{PackSplit}      & multi-row packed windows \\
\intf{TSplit}         & one-at-a-time temporally separated windows  \\
\end{interfaces}

interfaces to modify the painting or keyboard behavior of windows:

                  \index{buttons}
\begin{interfaces}
\intf{Filter}         & a simple pass-thru VBT \\
\intf{BorderedVBT}    & windows with borders \\
\intf{RigidVBT}       & unstrechable windows  \\
\intf{HighlightVBT}   & windows capable of displaying highlighted rectangles \\
\intf{TranslateVBT}   & windows that translate coordinate systems  \\
\intf{ButtonVBT}      & windows that are sensitive to button presses \\
\intf{QuickBtnVBT}    & buttons activated on the down-stroke  \\
\intf{MenuBtnVBT}     & buttons to be embedded in menus  \\
\intf{AnchorBtnVBT}   & buttons that can be used to anchor pull-down menus  \\
\intf{StableVBT}      & a filter with a preferred size  \\
\end{interfaces}

Leaf VBTs:

                  \index{textures}
\begin{interfaces}
\intf{TextVBT}        & window that displays a text string  \\
\intf{TextureVBT}     & window that displays a possibly colored texture \\
\intf{HVBar}          & an adjustable bar for use within \verb|HVSplit|s  \\
\intf{TypeInVBT}      & one line, editable text strings  \\
\end{interfaces}

Low-level, screen-independent window system resources:

                  \index{painting}
                  \index{fonts}
\begin{interfaces}
\intf{PaintOp}        & painting operations  \\
\intf{Cursor}         & cursor shapes  \\
\intf{Pixmap}         & rectangular arrays of pixels  \\
\intf{Font}           & typefaces  \\
\intf{Palette}        & a mechanism for combining screen-dependent functions  \\
\intf{ScreenType}     & a homogeneous class of screens \\
\intf{Gray}           & gray-scale pixmaps  \\
\intf{TwoTone}        & mixes black \& white and color paint ops  \\
\intf{Latin1Key}      & ISO-Latin-1 keyboard symbols  \\
\intf{KeyboardKey}    & common keyboard symbols  \\
\end{interfaces}

Lower-level, screen-dependent operations:

\begin{interfaces}
\intf{ScrnPaintOp}    & painting operations  \\
\intf{ScrnCursor}     & cursor shapes  \\
\intf{ScrnPixmap}     & rectangular arrays of pixels \\
\intf{ScrnFont}       & typefaces  \\
\intf{ScrnColorMap}   & color maps \\
\end{interfaces}

Interfaces and additional information to help build new VBT classes:

\begin{interfaces}
\intf{VBTClass}       & the primary obligations of a class implementor  \\
\intf{VBTRep}         & the internals of a \verb|VBT|  \\
\intf{FilterClass}    & information for subtypes of \verb|FilterVBT|  \\
\intf{ProperSplit}    & information for subtypes of non-filter (ie. split) classes \\
\intf{BdrVBTClass}    & information for subtypes of \verb|BorderVBT|s  \\
\intf{BtnVBTClass}    & information for subtypes of \verb|ButtonVBT|s  \\
\intf{TextVBTClass}   & information for subtypes of \verb|TextVBT|s  \\
\end{interfaces}

Interfaces that provide control of painting operations:

\begin{interfaces}
\intf{Batch}          & a sequence of painting commands  \\
\intf{BatchUtil}      & clipping and translation of batches  \\
\intf{PaintPrivate}   & paint batches  \\
\end{interfaces}

Miscellaneous window system goo:

\begin{interfaces}
\intf{VBTTuning}      & performance adjustment knobs  \\
\intf{TrestleComm}    & failure exceptions  \\
\end{interfaces}

other low-level stuff:

\begin{interfaces}
\intf{BatchRep}       & friends-only representation of batches  \\
\intf{DpyFilter}      & a filter class to catch re-screen events \\
\intf{ETAgent}        & a low-level filter that redirects window I/O methods \\
\intf{MiscDetail}     & a weakref-like facility to encode \verb|REF|s as \verb|INTEGER|s  \\
\intf{MouseSplit}     & mouse click delivery for splits  \\
\intf{PlttFrnds}      & friends-only representation of palettes  \\
\intf{TrestleClass}   & friends-only interface for Trestle bindings  \\
\intf{TrestleOnX}     & low-level Trestle binding to X  \\
\intf{TrestleImpl}    & low-level interface to set the default binding \\
\end{interfaces}


\section{The vbtkit library}
%-----------------------------

               \index{libvbtkit.a@{\tt libvbtkit.a}}
               \index{-lvbtkit@{\tt -lvbtkit}}
The library \intf{vbtkit} adds another layer of window building tools.

Feedback VBTs provide visual feedback based on the ``state'' of their
children:

\begin{interfaces}
\intf{Feedback}          & a multi-filter with visual feedback for the child \\
\intf{FeedbackClass}     & the methods needed to build a Feedback  \\
\intf{FeedbackVBT}       & a no-op Feedback VBT \\
\intf{BiFeedbackVBT}      & for composing feedback VBTs  \\
\intf{MarginFeedbackVBT}  & displays a left margin as a visual feedback  \\
\intf{BorderedFeedbackVBT}& displays a border as visual feedback  \\
\intf{ShadowedFeedbackVBT}& displays a shadow as visual feedback  \\
\end{interfaces}

Filters that modify their children's painting or keyboard response:

\begin{interfaces}
\intf{ChoiceVBT}     & a multi-filter used to build radio-buttons  \\
\intf{ClipboardVBT}  & a filter taht stores a text \\
\intf{FlexVBT}       & VBTs with a natural size, strech and shrink (ala TeX) \\
\intf{GuardedBtnVBT} & a \intf{ButtonVBT} that requires double-clicks  \\
\intf{ReactivityVBT} & makes its child active, passive, dormant or invisible \\
\intf{Scale}         & uses \intf{ScaleFilter} to keep its window filled  \\
\intf{ScaleFilter}   & scales the child's apparent resolution  \\
\intf{ShadowedVBT}   & surrounds its child with a shadow  \\
\intf{SwitchVBT}     & a VBTkit-style button \\
\intf{ViewportVBT} & a multi-filter that displays multiple views of its child\\
\intf{ZBackgroundVBT} & a filter to put around the background of a \intf{ZSplit} \\
\intf{ZChassisVBT} &  a multi-filter that provides a ``chassis'' for \intf{ZSplit} child  \\
\intf{ZChildVBT}   & a typical child of a \intf{ZSplit}  \\
\intf{ZGrowVBT}    & a switch that lifts and reshapes its nearest \intf{ZChildVBT} \\
\intf{ZMoveVBT}    & a switch that moves its nearest \intf{ZChildVBT}  \\
\end{interfaces}

Splits that compose several children:

\begin{interfaces}
\intf{AnchorSplit}  & a multi-split version of \verb|AnchorBtnVBT|  \\
\intf{JoinVBT}      & allows multiple parents to share a child  \\
\intf{ListVBT}      & displays a vertical list of children \\
\intf{Multi}        & a split class that supports ``logical'' children  \\
\intf{MultiClass}   & methods needed to build a \intf{Multi}  \\
\intf{Radio}        & a split that provides mutual exclusion on set of VBTs  \\
\intf{SplitterVBT}  & rows of children with separating bars  \\
\intf{VBTAlbum}     & a photo album of snapshot VBTs  \\
\intf{ZTilps}       & a multi-split like \intf{ZSplit}  \\
\end{interfaces}

Other useful leaf VBT classes:

\begin{interfaces}
\intf{BooleanVBT}       & an on-off interactor \\
\intf{DragSwitchVBT}    & a switch version of a \intf{DragBtnVBT}  \\
\intf{FileBrowserVBT}   & displays the files of a directory  \\
\intf{MenuSwitchVBT}    & a switch version of \intf{MenuBtnVBT}  \\
\intf{NumericScrollerVBT} & a scroller with a bounded integer range  \\
\intf{NumericVBT}       & displays an editable, bounded integer  \\
\intf{PixmapVBT}        & displays a fixed pixmap \\
\intf{QuickSwitchVBT}   & a switch version of a \intf{QuickBtnVBT} \\
\intf{ScrollerVBT}      & vertical and horizontal scroll bars  \\
\intf{ShadowedBarVBT}   & 3-D rectangles  \\
\intf{SourceVBT}        & a button that looks for marked ``targets''  \\
\intf{TextEditVBT}      & a scrollable, editable text window  \\
\intf{TextPort}         & an editable text window  \\
\intf{TrillSwitchVBT}   & a switch that generates repeated events \\
\intf{TypescriptVBT}    & a ``glass teletype'' window \\
\end{interfaces}

miscellaneous other stuff:

\begin{interfaces}
\intf{AnyEvent}        & a holder for any of the Trestle event-time events \\
\intf{AutoRepeat}      & a timer for repetitively calling a procedure  \\
\intf{CursorFromAscii} & converts an ASCII representation to a \verb|Cursor.T|  \\
\intf{EditCmd}         & the low-level key bindings used by \intf{TextPort} \\
\intf{FlexShape}       & flexible sizes used by \intf{FlexVBT}  \\
\intf{Image}           & a screen-independent, colored pixmap  \\
\intf{Key}             & common non-graphic keys  \\
\intf{KeyTrans}        & mapping from keyboard keys to ASCII characters  \\
\intf{MText}           & a mutable sequence of characters   \\
\intf{MTextDebug}      & utilities for debugging \verb|MText|s  \\
\intf{MTextRd}         & a reader on an \verb|MText|  \\
\intf{MTextUnit}       & internals of an MText  \\
\intf{PaintOpCache}    & a cache of recently created paint-ops  \\
\intf{PixmapFromAscii} & converts an ASCII representation to a \verb|Pixmap.T|  \\
\intf{Pts}             & utilities to convert between pixels and points \\
\intf{Shadow}          & Motif-like 3-D-like shadows  \\
\intf{TextPortPrivate} & common definitions for the text editing windows  \\
\intf{UnixUtils}       & temporary - utilities to access a Unix file system \\
\intf{VBTColors}  & associates foreground and background colors with a \intf{VBT}  \\
\intf{VBTSnap}    & captures a screen dependent pixmap ``snapshot'' of window\\
\intf{VTDef}      & low-level definitions used by \intf{VText}  \\
\intf{VText}      & a visible, mutable, multi-line text   \\
\intf{VTextDef}   & more low-level stuff for use by \intf{VText}  \\
\intf{XParam}     & handles X's \verb|display| and \verb|geometry| parameters\\
\intf{XTrestle}  & installs a top-level window using X-style positioning args\\
\intf{ZSplitUtils}     & utility procedures for manipulating \intf{ZSplit}s \\
\end{interfaces}

\section{The FormsVBT library}
%-----------------------------

               \index{FormsVBT}
               \index{libformsvbt.a@{\tt libformsvbt.a}}
               \index{-lformsvbt@{\tt -lformsvbt}}
The library \intf{formsvbt} provides a high-level system for describing
and building user interfaces.
A full description of FormsVBT can be found in ``The FormsVBT Reference
Manual'' \cite{FormsVBT}.

\begin{interfaces}
\intf{FormsVBT}     & the primary interface to the UI builder  \\
\intf{FormsCache}   & an in-memory cache of forms \\
\intf{FVTypes}      & basic types used by \verb|FormsVBT|  \\
\intf{FVRuntime}    & a private interface to the \verb|FormsVBT| runtime \\
\intf{Manpage}      & the \verb|FormsVBT| man page? \\
\end{interfaces}

\section{The codeview library}
%-----------------------------

               \index{libcodeview.a@{\tt libcodeview.a}}
               \index{-lcodeview@{\tt -lcodeview}}
\begin{interfaces}
\intf{CodeView}      & animated source code views  \\
\intf{DataView}      & animated variable views  \\
\end{interfaces}

\section{The mg library}
%-----------------------

               \index{animation}
               \index{libmg.a@{\tt libmg.a}}
               \index{-lmg@{\tt -lmg}}
\begin{interfaces}
\intf{Animate}            &   \\
\intf{MGPublic}           & convenience routines for manipulating \verb|MG| elements  \\
\intf{Appearances}        &   \\
\intf{CirclePixmap}       & builds \verb|Pixmap|s of circles and ovals  \\
\intf{CirclePixmapCache}  & a cache of \verb|CirclePixmap|s  \\
\intf{Fuzzy}              & interval arithmetic  \\
\intf{MG}                 &   \\
\intf{MGPaintOp}          & \verb|PaintOp.T|s with animated colors  \\
\intf{MGV}                &   \\
\intf{Matrix2D}           &   \\
\intf{R2}                 &   \\
\intf{R2Box}              &   \\
\intf{RealPath}           &   \\
\intf{ShapePixmap}        &   \\
\intf{ShapeUtils}         &   \\
\intf{TypeSelector.[im]g} & \\
\intf{TypeSelector.[im]g} & \\
\end{interfaces}

\section{The mgkit library}
%--------------------------

               \index{libmgkit.a@{\tt libmgkit.a}}
               \index{-lmgkit@{\tt -lmgkit}}
\begin{interfaces}
\intf{ChipsVBT}           &   \\
\intf{RectsVBT}           &   \\
\intf{LinearArray}        &   \\
\intf{LinearArraySelector}&   \\
\intf{IntArrayView}       &   \\
\intf{BinaryTree}         &   \\
\intf{GenericSubTree}     &   \\
\intf{GenericSubTreeSelector} &   \\
\intf{GenericTree}        &   \\
\intf{RadialTree}         &   \\
\intf{GraphVBTExtras}     &   \\
\intf{GraphVBT}           &   \\
\intf{AnimationPath}      &   \\
\intf{Grid}               &   \\
\intf{MGRd}               &   \\
\end{interfaces}

\section{The zeus library}
%-------------------------

               \index{Zeus}
               \index{animation}
               \index{libzeus.a@{\tt libzeus.a}}
               \index{-lzeus@{\tt -lzeus}}
\begin{interfaces}
\intf{Algorithm}          &   \\
\intf{AlgorithmClass}     &   \\
\intf{View}               &   \\
\intf{ViewClass}          &   \\
\intf{Zeus}               &   \\
\intf{ZeusClass}          &   \\
\intf{ZeusCodeView}       &   \\
\intf{ZeusDataView}       &   \\
\intf{ZeusPanel}          &   \\
\intf{ZeusUtil}           &   \\
\end{interfaces}

\section{The bicycle library}
%----------------------------


               \index{playing cards}
               \index{libbicycle.a@{\tt libbicycle.a}}
               \index{-lbicycle@{\tt -lbicycle}}
Bitmap images of playing cards:

\begin{interfaces}
\intf{Card}               &   \\
\intf{PixmapFromXData}    &   \\
\end{interfaces}

\section{The dpskit library}
%---------------------------

               \index{PostScript}
               \index{Display PostScript}
               \index{libdpskit.a@{\tt libdpskit.a}}
               \index{-ldpskit@{\tt -ldpskit}}
Access to the display PostScript extensions of an X-server:

\begin{interfaces}
\intf{DPS}                &   \\
\intf{DisplayList}        &   \\
\intf{DisplayListStack}   &   \\
\intf{DPSWindow}          &   \\
\intf{ButtonDLE}          &   \\
\intf{DragButtonDLE}      &   \\
\intf{PopupButtonDLE}     &   \\
\intf{PopupMenuDLE}       &   \\
\intf{SlideLineDLE}       &   \\
\intf{PagerDLE}           &   \\
\intf{OneSlideDLE}        &   \\
\intf{SlideXDLE}          &   \\
\intf{WarpDLE}            &   \\
\intf{TranslateDLE}       &   \\
\intf{TextLineDLE}        &   \\
\intf{SimpleTextDLE}      &   \\
\intf{VContainerDLE}      &   \\
\intf{HContainerDLE}      &   \\
\intf{DLWindow}           &   \\
\intf{ScaledDLWindow}     &   \\
\intf{Fifo}               &   \\
\intf{Linked2Tree}        &   \\
\intf{Unique}             &   \\
\intf{Pile}               &   \\
\end{interfaces}


\section{The TclTk library}
%--------------------------

               \index{Tcl}
               \index{libTclTk.a@{\tt libTclTk.a}}
               \index{-lTclTk@{\tt -lTclTk}}
\intf{Tcl} is an embeddable tool command language. \intf{Tk} is an X11
toolkit based on the \intf{Tcl} language. Both have been developed by
John Ousterhout at UC Berkeley. 

For an introduction to Tcl and Tk you may wish to read two papers:
``Tcl:  An Embeddable Command Language'', in the Proceedings of the
1990 Winter USENIX Conference, and ``An X11 Toolkit Based on the Tcl
Language'', in the Proceedings of the 1991 Winter USENIX Conference.

The library \intf{TclTk} gives access to the \intf{Tcl} and \intf{Tk}
libraries from Modula-3 programs, via the interfaces \intf{TclC} and
\intf{TkC} respectively. 



