% dwdoc.tex          Gordon S. Novak Jr.
% 08 Oct 92; 08 Oct 93; 16 Nov 94; 05 Jan 95; 25 Jan 06; 26 Jan 06; 08 Dec 08

\documentstyle[12pt]{article}
\setlength{\oddsidemargin}{0 in}
\setlength{\textwidth}{6.5 in}
\setlength{\textheight}{9.0 in}
\setlength{\parskip}{0.1 in}
\setlength{\parindent}{0.0 in}
\setlength{\topmargin}{-0.4in}
\hyphenpenalty=9990

\begin{document}

\Large
\begin{center} {\bf Interface from GCL to X Windows} \\  \end{center}

\normalsize

\vspace*{0.1in}

\begin{center}
\large{Gordon S. Novak Jr. \\
Department of Computer Sciences \\
University of Texas at Austin \\
Austin, TX  78712} \\
\end{center}

Software copyright \copyright \/ by Gordon S. Novak Jr. and
The University of Texas at Austin.  Distribution and use are allowed
under the Gnu Public License.  Also see the copyright section at the end
of this document for the copyright on X Consortium software.

\vspace*{-0.2in}

\section{Introduction}

This document describes a relatively easy-to-use interface between
XGCL (X version of Gnu Common Lisp) and X windows.  The interface
consists of several parts:
\begin{enumerate}
\item Hiep Huu Nguyen has written (and adapted from X Consortium software)
an interface between GCL and Xlib, the X library in C.
Xlib functions can be called directly if desired, but most users will find
the {\tt dwindow} functions easier to use.  There is little documentation
of these functions, but the Xlib documentation can be consulted, and
the {\tt dwindow} functions can be examined as examples.

\item The {\tt dwindow} functions described in this document, which call
the Xlib functions and provide an easier interface for Lisp programs.

\item It is possible to make an interactive graphical interface
within a web page; this is described in a section below.
\end{enumerate}
The source file for the interface (written in GLISP) is
{\tt dwindow.lsp}; this file is compiled into a file in plain Lisp,
{\tt dwtrans.lsp}.  {\tt dwtrans.lsp} is compiled as part of XGCL.

The functions in this package use the convention that the coordinate
{\tt (0 0)} is the lower-left corner of a window, with positive {\tt y}
being upward.  This is different from the convention used by
X, which assumes that {\tt (0 0)} is the upper left corner and
that positive {\tt y} is downward.

In the descriptions below, some function arguments are shown with a type,
e.g. {\tt arg:type}, to indicate the expected type of the argument.
The type {\tt vector} is a list {\tt (x y)} of integers.  The argument
{\tt w} that is used with many functions is of type {\tt window}
({\tt window} is a Lisp data structure used by the {\tt dwindow} functions).

Both the Xlib and {\tt dwindow} functions are in the package {\tt xlib:}.
In order to use these functions, the Lisp command {\tt (use-package 'xlib)}
should be used to import the {\tt dwindow} symbols.


\section{Examples and Utilities}

\subsection{{\tt dwtest}}

The file {\tt dwtest.lsp} contains example functions that illustrate
the use of the {\tt dwindow} package.  The function call {\tt (wtesta)}
creates a small window for testing.  {\tt (wtestb)} through
{\tt (wtestk)} perform drawing and mouse interaction tests using the
window.  These functions may be consulted as examples of the use of
commonly used {\tt dwindow} functions.

\subsection{{\tt pcalc}}

The file {\tt pcalc.lsp} implements
a pocket calculator as a {\tt picmenu}; its entry is {\tt (pcalc)}.

\subsection{{\tt draw}}

The file {\tt drawtrans.lsp} contains an interactive drawing program;
its entry is {\tt (draw 'foo)} where {\tt foo} is the name of the drawing.
The file {\tt ice-cream.lsp} can be loaded, followed by
{\tt (draw 'ice-cream)} to examine an example drawing.
{\tt draw} can produce a Lisp program or a set of \LaTeX \  commands to
recreate the drawing; use {\tt origin to zero} before making a program.
{\tt (draw-out file names)} will write definitions of drawings in the
list {\tt names} to the file {\tt file}.

\subsection{{\tt editors}}

The file {\tt editorstrans.lsp} contains some interactive editing programs;
it is a translation of the file {\tt editors.lsp} .
One useful editor is the color editor; after entering {\tt (wtesta)}
(in file {\tt dwtest.lsp}), enter {\tt (edit-color myw)} to edit a
color.  The result is an {\tt rgb} list as used in {\tt window-set-color}.

A simple line editor and an Emacs-like text editor are described in sections
\ref{texted}  and \ref{emacsed} below.

\section{Menus}

The function {\tt menu} provides an easy interface to make a pop-up menu,
get a selection from it, and destroy it: \\

\vspace{-0.2in}
{\tt \hspace*{0.5in} (menu items \&optional title)} \\

\vspace{-0.1in}
Example: {\tt (menu '(red white blue))}

This simple call is all that is needed in most cases.
More sophisticated menu features are described below.

The {\tt items} in a menu is a list; each item may be a symbol, a {\tt cons}
of a symbol or string and the corresponding value, or a {\tt cons} of a
function name and the corresponding value.  In the latter case, the function
is expected to draw the corresponding menu item.

If a function name is specified as the first element of a menu item, the
drawing function should have arguments {\tt (fn w x y)}, where {\tt w}
is the window and {\tt x} and {\tt y} are the lower-left corner of the
drawing area.  The property list of the function name should have the
property {\tt display-size}, which should be a list {\tt (width height)}
in pixels of the displayed symbol.

Menus can be associated with a particular window; if no window is specified,
the menu is associated with the window where the mouse cursor is located
when the menu is initialized (which might not be a Lisp user's window).  If a
menu is associated with a user window, it may be {\em permanent} (left
displayed after a selection is made) and may be {\em flat} (drawn directly
on the containing window, rather than having its own window).

A menu can be created by {\tt menu-create} : \\

\vspace{-0.1in}
{\tt \hspace*{0.5in}
 (menu-create items \&optional title w:window x y perm flat font)} \\

\vspace{-0.1in}
{\tt title}, if specified, is displayed over the menu.
{\tt w} is an existing {\tt window}; if specified, the menu is put
within this window at the {\tt x y} offsets specified (adjusted if necessary
to keep the menu inside the window).  If no {\tt w}
is specified, or if {\tt x} is {\tt nil}, the menu is put where the cursor
is the first time the menu is displayed.
{\tt perm} is non-{\tt nil} if the menu is to be permanent, {\em i.e.}, is to
be left displayed after a selection has been made.
{\tt flat} is non-{\tt nil} if the menu is to be drawn directly on the
containing window.
{\tt font} is a symbol or string that names the font to be used; the
default is a {\tt 9x15} typewriter font.

The menu is returned as the value of {\tt menu-create}.  Such a menu can
be saved; selections can be made from a menu {\tt m} as follows: \\

\vspace{-0.1in}
{\tt \hspace*{0.5in} (menu-select m \&optional inside)} \ \ \ \ \ or
{\tt \hspace*{0.5in} (menu-select! m)} \\

\vspace{-0.1in}
{\tt menu-select} will return {\tt nil} if the mouse is clicked outside the
menu, or is moved outside after it has been inside (or if {\tt inside} is
not {\tt nil}), provided that the menu is contained within a user-created
window.
{\tt menu-select!} requires that a choice be made.

In order to avoid wasting storage, unused menus should be destroyed:
{\tt (menu-destroy m)}.  The simple {\tt menu} function destroys its
menu after it is used.

{\tt \hspace*{0.5in} (menu-size m)} \\
{\tt \hspace*{0.5in} (menu-moveto-xy m x y)} \\
{\tt \hspace*{0.5in} (menu-reposition m)} \

{\tt menu-reposition} will reposition a {\tt flat} menu within its parent
window by allowing the user to position a ghost box using the mouse.
{\tt menu-size} returns the size of the menu as a vector, {\tt (x y)}.
{\tt menu-moveto-xy} adjusts the offsets to move a {\tt flat} menu to
the specified position within its parent window.  These functions and
{\tt menu-destroy} work for picmenus and barmenus as well.

{\tt \hspace*{0.5in} (menu-item-position m name \&optional location)} \\

\vspace{-0.1in}
{\tt menu-item-position} returns a vector {\tt (x y)} that gives the
coordinates of the menu item whose name is {\tt name}.  {\tt location}
may be {\tt center}, {\tt left}, {\tt right}, {\tt top}, or {\tt bottom};
the default is the lower-left corner of the menu item.  {\tt center}
specifies the center of the box containing the menu item; the other
{\tt location} values are at the center of the specified edge of the box.

\subsection{Picmenus}

A {\tt picmenu} (picture menu) is analogous to a menu, but involves a
user-defined picture containing sensitive spots or ``buttons''.
The test function {\tt (wteste)} shows an example of a {\tt picmenu}.
A {\tt picmenu} is created by: \\

\vspace{-0.1in}
{\tt \hspace*{0.5in} (picmenu-create buttons width height drawfn \\
\hspace*{1.5in} \&optional title dotflg w:window x y perm flat font boxflg)} \\

\vspace{-0.1in}

If a picmenu is to be used more than once, the common parts can be made
into a {\tt picmenu-spec} and reused:

\vspace{-0.1in}
{\tt \hspace*{0.5in} (picmenu-create-spec buttons width height drawfn \\
\hspace*{1.5in} \&optional dotflg font)} \\

\vspace{-0.1in}
{\tt \hspace*{0.5in} (picmenu-create-from-spec spec:picmenu-spec \\
\hspace*{1.5in} \&optional title w:window x y perm flat boxflg)} \\

\vspace{-0.1in}
{\tt width} and {\tt height} are the size of the area occupied by the
picture.  {\tt (drawfn w x y)} should draw the picture at the offset
{\tt x y}.  Note that the {\tt draw} utility can be used to
make the drawing function, including {\tt picmenu} buttons.
{\tt dotflg} is non-{\tt nil} if it is desired that small boxes be
automatically added to the sensitive points when the picture is drawn.
{\tt boxflg} is non-{\tt nil} if a box is to be drawn around the picmenu
when the picture is drawn (this is only needed for flat
picmenus).  If {\tt perm} is non-nil, the drawing program is not called when
a selection is to be made, so that an external program must draw the
{\tt picmenu}; this avoids the need to redraw a complex picture.
The remaining arguments are as described for menus.

Each of the {\tt buttons} in a picmenu is a list: \\

\vspace{-0.1in}
{\tt \hspace*{0.5in} (buttonname offset size highlightfn unhighlightfn)} \\

\vspace{-0.1in}
{\tt buttonname} is the name of the button; it is the value returned when that
button is selected.
{\tt offset} is a vector {\tt (x y)} that gives the offset of the center
of the button from the lower-left corner of the picture.
The remainder of the button list may be omitted.
{\tt size} is an optional list {\tt (width height)} that gives the size of the
sensitive area of the button; the default size is {\tt (12\ 12)}.
{\tt (highlightfn w x y)} and {\tt (unhighlightfn w x y)} (where {\tt (x y)}
is the center of the button in the coordinates of {\tt w}) are optional
functions to highlight the button area when the cursor is moved into it and
unhighlight the button when the cursor is moved out; the default is to
display a box of the specified {\tt size}.

{\tt \hspace*{0.5in} (picmenu-select m \&optional inside)} \\
If the {\tt picmenu} is not {\tt flat}, its window should be destroyed
following the selection using {\tt menu-destroy}.

{\tt \hspace*{0.5in} (picmenu-item-position m name \&optional location)} \\

\vspace{-0.1in}
{\tt \hspace*{0.5in} (picmenu-delete-named-button m name:symbol)} \\
This deletes a button from a displayed {\tt picmenu}.  The set of
deleted buttons is reset to {\tt nil} when the picmenu is drawn.

\subsection{Barmenus}

A {\tt barmenu} displays a bar graph whose size can be adjusted using
the mouse.

{\tt \hspace*{0.5in} 
(barmenu-create maxval initval barwidth \\
\hspace*{1.5in} \&optional title horizontal subtrackfn subtrackparms \\
\hspace*{1.5in} parentw x y perm flat color)}

A value is selected by: {\tt (barmenu-select m:barmenu \&optional inside)} \\
If the {\tt barmenu} is not {\tt flat}, its window should be destroyed
following the selection using {\tt menu-destroy}.

The user must first click the mouse in the bar area; then
the size of the displayed bar is adjusted as the user moves the mouse
pointer.  In addition, the {\tt subtrackfn} is called with arguments
of the size of the bar followed by the {\tt subtrackparms}; this can
be used, for example, to display a numeric value in addition to the
bar size.


\subsection{Menu Sets and Menu Conns}

A {\tt menu-set} is a set of multiple menus, picmenus, or barmenus
that are simultaneously active within the same window.  Menu-sets
can be used to implement graphical user interfaces.  A {\tt menu-conns}
is a menu-set that includes connections between menus; this can be
used to implement interfaces that allow the user to construct a network
from components.

The source file for menu-sets is the GLISP file {\tt menu-set.lsp};
this file is translated as part of the file {\tt drawtrans.lsp} in
plain Lisp.  Examples of the use of menu sets are given at the top
of the file {\tt menu-set.lsp}.  In the following descriptions,
{\tt ms} is a {\tt menu-set} and {\tt mc} is a {\tt menu-conns}.

{\tt \hspace*{0.5in} (menu-set-create w)} creates a menu set to be displayed
in the window {\tt w}.

{\tt \hspace*{0.5in} (menu-set-name symbol)} makes a {\tt gensym} name that
begins with {\tt symbol}.

{\tt \hspace*{0.5in} (menu-set-add-menu ms name:symbol sym title items} \\
\hspace*{1.5in} {\tt \&optional offset:vector)}

This function adds a menu to a menu-set.  {\tt sym} is arbitrary
information that is saved with the menu.

{\tt \hspace*{0.5in} (menu-set-add-picmenu ms name sym title spec:picmenu-spec} \\
\hspace*{1.5in} {\tt \&optional offset:vector nobox)}

{\tt \hspace*{0.5in} (menu-set-add-component ms name \&optional offset:vector)}

This adds a component that has a {\tt picmenu-spec} defined on the
property list of {\tt name}.

{\tt \hspace*{0.5in} (menu-set-add-barmenu ms name sym barmenu title} \\
\hspace*{1.5in} {\tt \&optional offset:vector)}

{\tt \hspace*{0.5in} (menu-set-draw ms)} draws all the menus.

{\tt \hspace*{0.5in} (menu-set-select ms \&optional redraw enabled)}

{\tt menu-set-select} gets a selection from a menu-set.  If {\tt redraw}
is non-{\tt nil}, the menu-set is drawn.  {\tt enabled} may be a list
of names of menus that are enabled for selection.  The result is
{\tt (selection menu-name)}, or {\tt ((x y) BACKGROUND button)}
for a click outside any menu.


{\tt \hspace*{0.5in} (menu-conns-create ms)} creates a {\tt menu-conns}
from a {\tt menu-set}.

{\tt \hspace*{0.5in} (menu-conns-add-conn mc)}

This function allows the user to select two ports from menus of the
{\tt menu-conns}.  It then draws a line between the ports and adds the
connection to the {\tt connections} of the {\tt menu-conns}.

{\tt \hspace*{0.5in} (menu-conns-move mc)}

This function allows the user to select a menu and move it.
The {\tt menu-set} and connections are redrawn afterwards.

{\tt \hspace*{0.5in} (menu-conns-find-conn mc pt:vector)} \\
This finds the connection selected by the point {\tt pt}, if any.
This is useful to allow the user to delete a connection:

{\tt \hspace*{0.5in} (menu-conns-delete-conn mc conn)}

{\tt \hspace*{0.5in} (menu-conns-find-conns mc menuname port)} \\
This returns all the connections from the specified {\tt port} (selection)
of the menu whose name is {\tt menuname}.


\section{Windows}

{\tt \hspace*{0.5in} (window-create width height \&optional title parentw
 x y font)} \\

\vspace{-0.1in}
{\tt window-create} makes a new window of the specified {\tt width} and
{\tt height}.  {\tt title}, if specified, becomes the displayed title
of the window.  If {\tt parentw} is specified, it should be the
{\tt window-parent} property of an existing window, which becomes the parent
window of the new window.  {\tt x} and {\tt y} are the offset of the
new window from the parent window.  {\tt font} is the font to be used
for printing in the window; the default is given by
{\tt *window-default-font-name*}, initially {\tt courier-bold-12}.

{\tt \hspace*{0.5in} (window-open w)} causes a window to be displayed
on the screen.

{\tt \hspace*{0.5in} (window-close w)} removes the window from the display;
it can be re-opened.

{\tt \hspace*{0.5in} (window-destroy w)}

{\tt \hspace*{0.5in} (window-moveto-xy w x y)}

{\tt \hspace*{0.5in} (window-geometry w)} queries X for the window geometry.
The result is a list, \linebreak
{\tt (x y width height border-width)} .

{\tt \hspace*{0.5in} (window-size w)} returns a list {\tt (width height)} .

\vspace{-0.1in}
Note that the width and height are cached within the structure so that no call
to X is needed to examine them.  However, if the window is resized, it is
necessary to call {\tt (window-reset-geometry\ w)} to reset the local
parameters to their correct values.

% ; Paint in window with mouse \\   % these are not really working...
% {\tt \hspace*{0.5in} (window-paint w)} \\
%
% {\tt \hspace*{0.5in} (window-move w)} \\
%
% {\tt \hspace*{0.5in} (dowindowcom w)} \\

The following functions provide access to the parts of the {\tt window} data
structure; most applications will not need to use them. \\

\vspace{-0.1in}
{\tt \hspace*{0.5in} (window-gcontext        w)} \\
{\tt \hspace*{0.5in} (window-parent          w)} \\
{\tt \hspace*{0.5in} (window-drawable-height w)} \\
{\tt \hspace*{0.5in} (window-drawable-width  w)} \\
{\tt \hspace*{0.5in} (window-label           w)} \\
{\tt \hspace*{0.5in} (window-font            w)} \\
{\tt \hspace*{0.5in} (window-screen-height)} \\


\section{Drawing Functions}

{\tt \hspace*{0.5in} (window-clear w)} clears the window to the background
color.

{\tt \hspace*{0.5in} (window-force-output \&optional w)}

\vspace{-0.1in}
Communication between the running program and X windows is done through a
stream; actual drawing on the display is done asynchronously.
{\tt window-force-output} causes the current drawing commands, if any,
to be sent to X.  Without this, commands may be left in the stream buffer and
may appear not to have been executed.  The argument {\tt w} is not used.

In all of the drawing functions, the {\tt linewidth} argument is optional
and defaults to {\tt 1}.

\vspace{0.1in}
{\tt \hspace*{0.5in} (window-draw-line w from:vector to:vector linewidth)} \\
{\tt \hspace*{0.5in}
 (window-draw-line-xy w x1 y1 x2 y2 \&optional linewidth op)} \\
 \hspace*{1.0in} {\tt op} may be {\tt xor} or {\tt erase}.

\vspace{0.1in}
{\tt \hspace*{0.5in}
 (window-draw-arrow-xy w x1 y1 x2 y2 \&optional linewidth size)} \\
{\tt \hspace*{0.5in}
 (window-draw-arrow2-xy w x1 y1 x2 y2 \&optional linewidth size)} \\
{\tt \hspace*{0.5in}
 (window-draw-arrowhead-xy w x1 y1 x2 y2 \&optional linewidth size)}

\vspace{-0.1in}
These draw a line with an arrowhead at the second point, a line with an
arrowhead at both points, or an arrowhead alone at the second point,
respectively.  {\tt size} is the arrowhead size; the default is
{\tt (+ 20 (* linewidth 5))}.

\vspace{0.1in}
{\tt \hspace*{0.5in} (window-draw-box-xy w x y width height linewidth)} \\
{\tt \hspace*{0.5in} (window-xor-box-xy w x y width height linewidth)} \\
{\tt \hspace*{0.5in} (window-draw-box w offset:vector size:vector linewidth)} \\
{\tt \hspace*{0.5in} (window-draw-box-corners w x1 y1 x2 y2 linewidth)} \\
 \hspace*{1.0in} where {\tt (x1 y1)} and {\tt (x2 y2)} are opposite corners. \\
{\tt \hspace*{0.5in} (window-draw-rcbox-xy w x y width height radius linewidth)} \\
 \hspace*{1.0in} draws a box with rounded corners.

{\tt \hspace*{0.5in} (window-draw-arc-xy w x y radiusx radiusy anglea angleb linewidth)}

\vspace{-0.1in}
{\tt anglea} is the angle, in degrees, at which the arc is started.
{\tt angleb} is the angle, in degrees, that specifies the amount of arc
to be drawn, counterclockwise from the starting position.

\vspace{0.1in}
{\tt \hspace*{0.5in} (window-draw-circle-xy w x y radius linewidth)} \\
{\tt \hspace*{0.5in} (window-draw-circle w center:vector radius linewidth)} \\
{\tt \hspace*{0.5in} (window-draw-ellipse-xy w x y radiusx radiusy linewidth)} \\
{\tt \hspace*{0.5in} (window-draw-dot-xy w x y)}

\vspace{0.1in}
{\tt \hspace*{0.5in} (window-erase-area-xy w left bottom width height)} \\
{\tt \hspace*{0.5in} (window-erase-area w offset:vector size:vector)} \\
{\tt \hspace*{0.5in} (window-copy-area-xy w fromx fromy	tox toy width height)} \\
{\tt \hspace*{0.5in} (window-invert-area w offset:vector size:vector)} \\
{\tt \hspace*{0.5in} (window-invert-area-xy w left bottom width height)}

\vspace{0.1in}
{\tt \hspace*{0.5in} (window-printat-xy w s x y)} \\
{\tt \hspace*{0.5in} (window-printat w s at:vector)} \\
{\tt \hspace*{0.5in} (window-prettyprintat-xy w s x y)} \\
{\tt \hspace*{0.5in} (window-prettyprintat w s at:vector)} \\

\vspace{-0.1in}
The argument {\tt s} is printed at the specified position.
{\tt s} is stringified if necessary.
Currently, the pretty-print versions are the same as the plain versions.

\vspace{0.1in}
{\tt \hspace*{0.5in} (window-draw-border w)} draws a border just
inside a window.

\section{Fonts, Operations, Colors}

{\tt \hspace*{0.5in} (window-set-font w font)}

\vspace{-0.1in}
The font symbols that are currently defined are {\tt courier-bold-12},
{\tt 8x10}, and {\tt 9x15} .  The global variable {\tt *window-fonts*}
contains correspondences between font symbols and font strings.
A font string may also be specified instead of a font symbol.

{\tt \hspace*{0.5in} (window-string-width w s)} \\
{\tt \hspace*{0.5in} (window-string-extents w s)} \\
These give the width and the vertical size {\tt (ascent descent)} in pixels
of the specified string {\tt s} using the font of the specified window.
{\tt s} is stringified if necessary.

Operations on a window other than direct drawing are performed by
setting a condition for the window, performing the operation, and then
unsetting the condition with {\tt window-unset}.  {\tt window-reset}
will reset a window to its ``standard'' setting; it is useful primarily
for cases in which a program bug causes window settings to be in an
undesired state.

\vspace{-0.1in}
{\tt \hspace*{0.5in} (window-set-xor w)} \\
{\tt \hspace*{0.5in} (window-set-erase w)} \\
{\tt \hspace*{0.5in} (window-set-copy w)} \\
{\tt \hspace*{0.5in} (window-set-invert w)} \\
{\tt \hspace*{0.5in} (window-unset w)} \\
{\tt \hspace*{0.5in} (window-reset w)} \\

{\tt \hspace*{0.5in} (window-set-line-width w width)} \\
{\tt \hspace*{0.5in} (window-set-line-attr w width \&optional line-style cap-style join-style)} \\
{\tt \hspace*{0.5in} (window-std-line-attr w)} \\

{\tt \hspace*{0.5in} (window-foreground w)} \\
{\tt \hspace*{0.5in} (window-set-foreground w fg-color)} \\
{\tt \hspace*{0.5in} (window-background w)} \\
{\tt \hspace*{0.5in} (window-set-background w bg-color)} \\


\subsection{Color}

The color of the foreground (things that are drawn, such as lines or
characters) is set by:

{\tt \hspace*{0.5in} (window-set-color w rgb \&optional background)} \\
{\tt \hspace*{0.5in} (window-set-color-rgb w r g b \&optional background)} \\

{\tt rgb} is a list {\tt (red green blue)} of 16-bit unsigned integers in
the range {\tt 0} to {\tt 65535}.  {\tt background} is non-{\tt nil}
to set the background color rather than the foreground color.

{\tt \hspace*{0.5in} (window-reset-color w)} \\
{\tt window-reset-color} resets a window's colors to the default values.

Colors are a scarce resource; there is only a finite number of
available colors, such as 256 colors.  If you only use a small, fixed set
of colors, the finite set of colors will not be a problem.  However,
if you create a lot of colors that are used only briefly, it will be
necessary to release them after they are no longer needed.
{\tt window-set-color} will leave the global variable {\tt *window-xcolor*}
set to an integer value that denotes an X color; this value should be
saved and used as the argument to {\tt window-free-color} to release
the color after it is no longer needed.

{\tt \hspace*{0.5in} (window-free-color w \&optional xcolor)} \\

{\tt window-free-color} frees either the last color used, as given by
{\tt *window-xcolor*}, or the specified color.


\subsection{Character Input} \label{texted}

Characters can be input within a window by the call:

{\tt \hspace*{0.5in} (window-input-string w str x y \&optional size)} \\

{\tt window-input-string} will print the initial string {\tt str},
if non-{\tt nil},
at the specified position in the window; {\tt str}, if not modified
by the user, will also be the initial part of the result.  A caret
is displayed showing the location of the next input character.
Characters are echoed as they are typed; backspacing erases characters,
including those from the initial string {\tt str}.  An area of width
{\tt size} (default 100) is erased to the right of the initial caret.


\subsection{Emacs-like Editing} \label{emacsed}

{\tt window-edit} allows editing of text using an Emacs-subset editor.
Only a few simple Emacs commands are implemented.
\begin{verbatim}
   (window-edit w x y width height &optional strings boxflg scroll endp)
\end{verbatim}
{\tt x y width height} specify the offset and size of the editing
area; it is a good idea to draw a box around this area first.
{\tt strings} is an initial list of strings; the return value is a list
of strings.
{\tt scroll} is number of lines to scroll down before displaying text,
          or {\tt T} to have one line only and terminate on return.
{\tt endp} is {\tt T} to begin editing at the end of the first line.
Example:
\begin{verbatim}
  (window-draw-box-xy myw 48 48 204 204)
  (window-edit myw 50 50 200 200 '("Now is the time" "for all" "good"))
\end{verbatim}


\section{Mouse Interaction}

{\tt \hspace*{0.5in} (window-get-point w)} \\
{\tt \hspace*{0.5in} (window-get-crosshairs w)} \\
{\tt \hspace*{0.5in} (window-get-cross w)} \\
These functions  get a point position by mouse click; they return {\tt (x y)} .

The following function gets a point position by mouse click.  It returns
{\tt (button (x y))} where {\tt button} is {\tt 1} for the left button,
{\tt 2} for middle, {\tt 3} for right.

{\tt \hspace*{0.5in} (window-get-click w)} \\

The following function gets a point position by mouse click within a specified
region.  It returns {\tt (button (x y))} or {\tt NIL} if the mouse leaves
the region.  If {\tt boxflg} is {\tt t}, a box will be drawn outside the
region while the mouse is being tracked.

{\tt \hspace*{0.5in} (window-track-mouse-in-region w x y sizex sizey \&optional boxflg)} \\


The following functions get a point position indicated by drawing a line
from a specified origin position to the cursor position; they return
{\tt (x y)} at the cursor position when a mouse button is clicked.
The {\tt latex} version restricts the slope of the line to be a slope that
\LaTeX \ can draw; if {\tt flg} is non-{\tt nil}, the slope is restricted
to be a \LaTeX \ {\tt vector} slope.

{\tt \hspace*{0.5in} (window-get-line-position w orgx orgy)} \\
{\tt \hspace*{0.5in} (window-get-latex-position w orgx orgy flg)} \\

The following function gets a position by moving a ``ghost'' icon,
defined by the icon drawing function {\tt fn}.  This allows exact positioning
of an object by the user.

{\tt \hspace*{0.5in} (window-get-icon-position w fn args \&optional (dx 0)
 (dy 0))} \\

\vspace{-0.15in}
The function {\tt fn} has arguments {\tt (fn w x y . args)} , where {\tt x}
and {\tt y} are the offset within the window {\tt w} at which the icon is
to be drawn, and {\tt args} is a list of arbitrary arguments, e.g., the size
of the icon, that are passed through to the drawing function.
The icon is drawn in {\tt xor} mode, so it must be drawn using
only ``plain'' drawing functions, without resetting window attributes.
The returned value is {\tt (x y)} at the cursor position when a button
is clicked.  {\tt dx} and {\tt dy}, if specified, are offsets of {\tt x}
and {\tt y} from the cursor position.

The following function gets a position by moving a ``ghost'' box icon.

{\tt \hspace*{0.5in} (window-get-box-position w width height \&optional (dx 0) (dy 0))} \\

\vspace{-0.15in}
By default, the lower-left corner of the box is placed at the cursor position;
{\tt dx} and {\tt dy} may be used to offset the box from the cursor, e.g.,
to move the box by a different corner.  The returned value is {\tt (x y)}
at the cursor position when a button is clicked.

The following function gets coordinates of a box of arbitrary size and
position.

{\tt \hspace*{0.5in} (window-get-region w)} \\

\vspace{-0.15in}
The user first clicks for one corner of the box, moves the
mouse and clicks again for the opposite corner, then moves the box into
the desired position. The returned value is \linebreak
{\tt ((x y) (width height))},
where {\tt (x y)} is the lower-left corner of the box.

The following function gets the size of a box by mouse selection,
echoing the size in pixels below the box.  {\tt offsety}
should be at least {\tt 30} to leave room to display the size of the box.

{\tt \hspace*{0.5in} (window-get-box-size w offsetx offsety)} \\


The following function adjusts one side of a box.

{\tt \hspace*{0.5in} (window-adjust-box-side w x y width height side)} \\

\vspace{-0.15in}
{\tt side} specifies the side of the box to be adjusted: {\tt left},
{\tt right}, {\tt top}, or {\tt bottom}.  The result is
{\tt ((x y) (width height))} for the resulting box.

{\tt \hspace*{0.5in} (window-get-circle w \&optional center:vector)} \\
{\tt \hspace*{0.5in} (window-get-ellipse w \&optional center:vector)} \\
These functions interactively get a circle or ellipse.  For an ellipse,
a circle is gotten first for the horizontal size; then the vertical
size of the ellipse is adjusted.
{\tt window-get-circle} returns {\tt ((x y) radius)}.
{\tt window-get-ellipse} returns {\tt ((x y) (xradius yradius))}.

% {\tt \hspace*{0.5in} (window-sync w)} will clear the event queue of any
% previous motion events.

{\tt window-track-mouse} is the basic function for following the mouse
and performing some action as it moves.  This function is used in
the implementation of menus and the mouse-interaction functions described in
this section.

{\tt \hspace*{0.5in} (window-track-mouse w fn \&optional outflg)}
          
\vspace{-0.05in}
Each time the mouse position changes or a mouse button is pressed,
the function {\tt fn} is called with
arguments {\tt (x y code)} where {\tt x} and {\tt y} are the cursor
position, {\tt code} is a button code ({\tt 0} if no button, {\tt 1} for
the left button, {\tt 2} for the middle button, or {\tt 3} for the right
button).  {\tt window-track-mouse} continues to track the mouse until {\tt fn}
returns a value other than {\tt nil}, at which time {\tt window-track-mouse}
returns that value.  Usually, it is a good idea for {\tt fn} to return a
value other than {\tt nil} upon a mouse click.  If the argument {\tt outflg}
is non-{\tt nil}, the function {\tt fn} will be called for button clicks
outside the window {\tt w}; note, however, that such clicks will not be
seen if the containing window intercepts them, so that this feature will
work only if the window {\tt w} is inside another Lisp user window.


\section{Miscellaneous Functions}

{\tt \hspace*{0.5in} (stringify x)} makes its argument into a string.

{\tt \hspace*{0.5in} (window-destroy-selected-window)} waits 3 seconds,
then destroys the window containing the mouse cursor.  This function
should be used with care; it can destroy a non-user window, causing
processes associated with the window to be destroyed.  It is useful
primarily in debugging, to get rid of a window that is left on the screen
due to an error.
                

\section{Examples}

Several interactive programs using this software for their graphical
interface can be found at {\tt http://www.cs.utexas.edu/users/novak/}
under the heading Software Demos.


\section{Web Interface}

This software allows a Lisp program to be used interactively within
a web page.  There are two approaches, either using an X server on
the computer of the person viewing the web page, or using WeirdX, a
Java program that emulates an X server.  Details can be found at:
{\tt http://www.cs.utexas.edu/users/novak/dwindow.html} 


\section{Files}

\begin{tabular}{ll}
{\tt dec.copyright}  & Copyright and license for DEC/MIT files \\
{\tt draw.lsp}       & GLISP source code for interactive drawing utility \\
{\tt drawtrans.lsp}  & {\tt draw.lsp} translated into plain Lisp \\
{\tt draw-gates.lsp} & Code to draw {\tt nand} gates etc. \\
{\tt dwdoc.tex}      & \LaTeX \ source for this document \\
{\tt dwexports.lsp}  & exported symbols \\
{\tt dwimportsb.lsp} & imported symbols \\
{\tt dwindow.lsp}    & GLISP source code for {\tt dwindow} functions \\
{\tt dwtest.lsp}     & Examples of use of {\tt dwindow} functions \\
{\tt dwtrans.lsp}    & {\tt dwindow.lsp} translated into plain Lisp \\
{\tt editors.lsp}    & Editors for colors etc. \\
{\tt editorstrans.lsp}    & translation of {\tt editors.lsp} \\
{\tt gnu.license}    & GNU General Public License \\
{\tt ice-cream.lsp}  & Drawing of an ice cream cone made with {\tt draw} \\
{\tt lispserver.lsp} & Example web demo: a Lisp server \\
{\tt lispservertrans.lsp}    & translation of {\tt lispserver.lsp} \\
{\tt menu-set.lsp}   & GLISP source code for menu-set functions \\
{\tt menu-settrans.lsp}   & translation of {\tt menu-set.lsp} \\
{\tt pcalc.lsp}      & Pocket calculator implemented as a {\tt picmenu} \\
\end{tabular}


\pagebreak

\section{Data Types}

\begin{verbatim}
(window (listobject  (parent          drawable)
                     (gcontext        anything)
                     (drawable-height integer)
                     (drawable-width  integer)
                     (label           string)
                     (font            anything) )
\end{verbatim}

\vspace*{-.2in}

\begin{verbatim}
(menu (listobject (menu-window     window)
                  (flat            boolean)
                  (parent-window   drawable)
                  (parent-offset-x integer)
                  (parent-offset-y integer)
                  (picture-width   integer)
                  (picture-height  integer)
                  (title           string)
                  (permanent       boolean)
                  (menu-font       symbol)
                  (item-width      integer)
                  (item-height     integer)
                  (items           (listof symbol)) )
\end{verbatim}

\vspace*{-.2in}

\begin{verbatim}
(picmenu (listobject (menu-window     window)
                     (flat            boolean)
                     (parent-window   drawable)
                     (parent-offset-x integer)
                     (parent-offset-y integer)
                     (picture-width   integer)
                     (picture-height  integer)
                     (title           string)
                     (permanent       boolean)
                     (spec            (transparent picmenu-spec))
                     (boxflg          boolean)
                     (deleted-buttons (listof symbol)) )
\end{verbatim}

\vspace*{-.2in}

\begin{verbatim}
(picmenu-spec (listobject (drawing-width   integer)
                          (drawing-height  integer)
                          (buttons         (listof picmenu-button))
                          (dotflg          boolean)
                          (drawfn          anything)
                          (menu-font       symbol) ))
\end{verbatim}

\vspace*{-.2in}

\begin{verbatim}
(picmenu-button (list (buttonname     symbol)
                      (offset         vector)
                      (size           vector)
                      (highlightfn    anything)
                      (unhighlightfn  anything))
\end{verbatim}

\vspace*{-.2in}

\begin{verbatim}
(barmenu (listobject (menu-window     window)
                     (flat            boolean)
                     (parent-window   drawable)
                     (parent-offset-x integer)
                     (parent-offset-y integer)
                     (picture-width   integer)
                     (picture-height  integer)
                     (title           string)
                     (permanent       boolean)
                     (color           rgb)
                     (value           integer)
                     (maxval          integer)
                     (barwidth        integer)
                     (horizontal      boolean)
                     (subtrackfn      anything)
                     (subtrackparms   (listof anything)))
\end{verbatim}


\pagebreak

\section{Copyright}

The following copyright notice applies to the portions of the software
that were adapted from X Consortium software:
\begin{verbatim}
;;**********************************************************
;;Copyright 1987 by Digital Equipment Corporation, Maynard, Massachusetts,
;;and the Massachusetts Institute of Technology, Cambridge, Massachusetts.

;;                        All Rights Reserved

;;Permission to use, copy, modify, and distribute this software and its 
;;documentation for any purpose and without fee is hereby granted, 
;;provided that the above copyright notice appear in all copies and that
;;both that copyright notice and this permission notice appear in 
;;supporting documentation, and that the names of Digital or MIT not be
;;used in advertising or publicity pertaining to distribution of the
;;software without specific, written prior permission.  

;;DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
;;ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
;;DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
;;ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
;;WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
;;ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
;;SOFTWARE.

;;*****************************************************************

\end{verbatim}

\end{document}


% Previous UT copyright:

; Copyright 1992, The University of Texas at Austin (UTA).  All rights
; reserved.  By using this software the USER indicates that he or she
; has read, understood and will comply with the following:
;
; -UTA hereby grants USER nonexclusive permission to use, copy and/or
; modify this software for internal, noncommercial, research purposes only.
; Any distribution, including commercial sale or license, of this software,
; copies of the software, its associated documentation and/or modifications
; of either is strictly prohibited without the prior consent of UTA.  Title
; to copyright to this software and its associated documentation shall at
; all times remain with UTA.  Appropriate copyright notice shall be placed
; on all software copies, and a complete copy of this notice shall be
; included in all copies of the associated documentation.  No right is
; granted to use in advertising, publicity or otherwise any trademark,
; service mark, or the name of UTA.  Software and/or its associated
; documentation identified as "confidential," if any, will be protected
; from unauthorized use/disclosure with the same degree of care USER
; regularly employs to safeguard its own such information.
;
; -This software and any associated documentation is provided "as is," and
; UTA MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
; THOSE OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR THAT
; USE OF THE SOFTWARE, MODIFICATIONS, OR ASSOCIATED DOCUMENTATION WILL
; NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER INTELLECTUAL
; PROPERTY RIGHTS OF A THIRD PARTY.  UTA, the University of Texas System,
; its Regents, officers, and employees shall not be liable under any
; circumstances for any direct, indirect, special, incidental, or
; consequential damages with respect to any claim by USER or any third
; party on account of or arising from the use, or inability to use, this
; software or its associated documentation, even if UTA has been advised
; of the possibility of those damages.
;
; -Submit software operation questions to: Gordon S. Novak Jr., Department
; of Computer Sciences, UT, Austin, TX 78712, novak@cs.utexas.edu .
;
; -Submit commercialization requests to: Office of the Executive Vice
; President and Provost, UT Austin, 201 Main Bldg., Austin, TX, 78712,
; ATTN: Technology Licensing Specialist.