		    GIS --- A GRAPHICAL USER INTERFACE

              Some notes on dependencies and implementation.

                             Douglas A. Young
			Telephone: (415) 857-6478
                    Net address: dayoung@hplabs.hp.com


There are three basic dependencies in this interface which need to be dealt
with in any attempted port. These are
   1) dependencies on Macsyma
   2) dependencies on the Tek 4404 hardware and
   3) Dependencies on Franz Lisp.
I'll try to anticipate some of these.

1) Macsyma
The top level loop of this interface is called "continue", as this is the
top level of Macsyma.  It is basically a loop which calls the editor.  The
editor returns a string of fixnums in the variable "st".  There are three
entry points into Macsyma. These are:
 1) Parse uses the global variable st as input. Parse returns the lisp
    (Macsyma) internal form of the expression and checks for syntax errors
 2) Continue1 takes the result of Parse and executes the command, returning
    the result
 3) Displa takes the result of Continue1, still in internal form and
   formats it for output. The displa function is the gateway to the
   interface, and the old Macsyma function has been replaced by the
   new displa in the interface.
So continue is basically
     While (TRUE)
         st = editor
         result = parse(st)
         result = continue1(result)
         displa(result)
    endWhile

Displa and its auxiliary functions work very much like the old functions
from Macsyma.  See Martin, W. M., ``Computer Input/Output of Mathematical
Expressions,'' Proceedings of the Second Symposium on Symbolic and
Algebraic Manipulation, for an explanation of the strategy.  For porting
the interface to a new algebra system, there will have to be some
comparison of the internal form.  Either a conversion function will need to
be defined, or the displa functions rewritten to reflect the different
structure.

2) Dependencies on the Tek hardware
These are theoretically minimized by using a very small graphics library
provided by Tektronix, found in gelib.l (which is not yet distributed).
Similar functions should be available on most workstations.  The functions
used make extensive use of the BitBlt operation (ala Smalltalk).  So the
choice is whether to emulate the basic graphics library on another
workstation, or just use the window manager and such provided.  The editor
serves as the central control point for the interface and is event driven,
allowing the editor to treat both keyboard input and mouse input uniformly.

3) The Franz Lisp used is Version 42 which has an objects package.  However
no objects are used, since this interface was mostly written on a Vax and a
chromatics graphics terminal and version 38 of Franz.  The primary source
of problems with this version of Franz may be the c-declare function, but a
replacement should be easy to write.  The c-declare provides C-like
structures.  A struct may be defined by:

   (c-declare
         (struct rect
            (x short)
            (y short)
            (w short)
            (h short)))

This is a macro that automatically provides access and creation functions,
including (make-rect) (rect->x)(rect->y)(rect->w)(rect->h). (make-rect)
returns a vector with space for the declared fields.  They may be set at
creation time (setf newrect (make-rect :x 10 :y 20 :w 30 :h 40)) or later
as (setf (rect->x newrect) 200).  Another problem that could be encountered
is the use of keyword arguments, as seen above.  This is mostly contained
in the window manager and menu functions, fewer keywords are used in the
older portions (the format and display files).

WINDOW MANAGER FUNCTIONS
If these functions are available, (as they must be in any window manager)
it would be simpler to use an existing window manager than to port this
one.  Only the starred ones are really necessary.

create window   *
delete window   *
move window    
change window size
window -> icon
icon -> window
select window (pop window)  *

These are the graphics functions lifted from the Tek 4404 graphics library
Not all of these are used.  In fact, if another window manager is used, the
only graphics needed are move(x,y), draw_vector(x,y), and
put_character(x,y,char).  Several higher level primitives are built on the
Tek primitives and are in devdep.l.  These include: draw-box, draw-rect,
draw-line(x,y,x1,y1), paint-char(x,y,ch).  If a graphics library is
available (i.e.  GKS, etc) these primitives should be available directly,
and most of devdep.l could be replaced.

The only place the bitblt operation is used other than the window manager
is in the highlight operation.  The Tek 4404 doesn't provide the ability to
selectively highlight in graphics mode, so it is done by copying the line
(using bitblt) to a save area, drawing a halftone over the area to be
highlighted, and then restoring the saved area.  This isn't even the
correct way to do this of course.  It should have been done by simply
drawing a box or solid rectangle over the area to be highlighted in
exclusive-or mode.  I tried this and ran into problems with dynamically
moving the highlight, so I took the other route.  In hindsight, a little
more logic would have made the exclusive-or work correctly, and would have
been much cleaner.
;   
;   functions from graphics and events library:   
;
;     function		      arguments		      value returned  
; 
; 	bitblt 			(bbcom)			t
; 	clearscreen 		()			t
; 	cursortrack		(boolean)		t
; 	cursorvisible 		(boolean)		boolean
; 	displayvisible 		(boolean) 		boolean
; 	eclearalarm		()			t
; 	egetcount		()			fixnum
; 	egetnewcount		()			fixnum
; 	egetnext		()			fixnum
; 	egetparam		(fixnum)		fixnum
; 	egettime		()			fixnum
; 	egettype		(fixnum)		fixnum
; 	esetminterval		(fixnum)		t	(no-op)
; 	esetalarm		(fixnum)		t
; 	esetsignal		()			t
; 	eventdisable		()			t
; 	eventenable		()			t
; 	exitgraphics		()			t
; 	getbuttons  		()			fixnum
; 	getcposition		(point)  		point
; 	getcursor 		(form)			form
; 	getmbounds 		(point point)	 	list (point point)
; 	getmposition 		(point)	 	 	point
; 	getviewport 		(point) 		point
; 	initgraphics 		(boolean)		form 
; 	paintline 		(bbcom point)		t
; 	pancursorenable 	(boolean)		boolean
; 	pandiskenable 		(boolean)		boolean
; 	pointtorc 		(rowcol point)		rowcol
; 	protectcursor 		(rect rect)		t
; 	rctorect 		(rect fixnum fixnum)	rect
; 	releasecursor 		()	 		t
; 	restoredisplaystate 	(dispstate)		t
; 	savedisplaystate 	(dispstate)	 	dispstate
; 	screensaverenable 	(boolean) 		boolean
; 	setcposition 		(point)			t
; 	setcursor 		(form) 			t
; 	setkbcode		(boolean)		t		
; 	setmbounds 		(point point)		t
; 	setmposition 		(point)			t
; 	setviewport 		(point)			t
; 	terminalenable 		(boolean)		boolean 
; 	videonormal 		(boolean)		boolean 
;	formcreate		(fixnum fixnum)		form
; 	readform		(string)		form
; 	
;-----------------------------------------------------------------------------


Menus

Two functions are provide for menus. These (like the small windows that they
are) use the bitblt operation and the c-struct feature of Franz. They could
be easily replaced. The functions used are

(make-menu ( ("string" (function))(" string" (function)) ......))

This returns a menu object to be used in menu-choose.

(menu-choose menu-object :title "string")

Menu-choose returns a Lisp function or S-expression to be eval'd.
