GINREAD                                           Aaron Sloman   January 1977

------------------------------------------------------------------------------
WARNING: The programmes mentioned in this file are liable to be removed or
substatially altered in future version of POPLOG.  If you find a use for them
then you are advised to make a private copy.
------------------------------------------------------------------------------

GRAPHICAL INPUT FROM THE TEKTRONIX UNIT
=======================================

To load the facilities described below, type:

    : LIB GINREAD;

this compiles a collection of routines for using the cursors on the Tektronix
terminal to input picture co-ordinates. It works in conjunction with the
facilities described in the TEKTRONIX demo, including the use of GXSCALE and
GXSCALE to control scale transformations, and GXORIGIN and GYORIGIN to
control the screen position corresponding to user co-ordinates.

The basic procedure provided by the GINREAD package is called APPGIN. It
takes a procedure as argument, and repeatedly applies that procedure to a
character code, and a pair of screen co-ordinates read in from the terminal.
For details of APPGIN see the code in /pop/usr/lib/ginread.p . For most
purposes the next procedure will suffice.

The procedure GINREAD uses APPGIN to read in a picture made up of
sub-pictures, where each sub-picture is a connected set of lines. GINREAD
returns a list of subpictures, each represented by a list of points to be
joined by lines. Each point is represented by a pair (not a two element list)
of numbers.

If you call GINREAD it switches off echoing, and puts the terminal into GIN
mode (graphical input mode). This makes cursor-controlled crossed lines
appear on the screen. To input a point use the cursors to the desired
location and then depress a character key. Which key is depressed determines
what GINREAD does with the point.

1. If the space bar is depressed, it will be assumed that the current
point is the next point in the current sub-picture. A line will be
drawn on the screen showing this.

2. If the comma key is depressed, it will be assumed that the previous
sub-picture is now complete and a new sub-picture is to be started from the
current point. This is indicated on the screen by a dot, at the current
point.

3. If the question-mark key "?" is depressed, then it is assumed that
the last line of the current sub-picture was a mistake and should have
been drawn to the present location. The previous line is removed from
the record of the current sub-picture, and to indicate this the new
line is drawn on the screen from the beginning of the previous line
to the current point. (The old line cannot be erased from the screen).

4. If the hash-key "#" is depressed, it is assumed that the previous
sub-picture is to be abandoned and restarted from the current point.
A dot is drawn on the screen.

5. To indicate that the picture is finished, depress the dot key ".".
The current point is then ignored and GINREAD exits.

The procedure DRAWPIC can be applied to the result of GINREAD to
draw the picture on the screen, if any of GXSCALE, GYSCALE,
GXORIGIN, GYORIGIN is altered, this will altered the size, location,
and possibly orientation of the picture (e.g. a negative scale causes
a reflection).

The list produced by GINREAD can be stored in a file for future use, but the
ordinary POP11 printing routines are not suitable for printing a list
including pairs, so for storage purposes it may be best to use a different
representation for points. This is easily achieved by altering the procedures
CONSPOINT and DESTPOINT. Their standard definitions are CONS and DEST. But
you could do

    DEFINE CONSPOINT(X,Y);
        [%X, Y%]
    ENDDEFINE;

    DL -> DESTPOINT;

, for reading a list containing negative numbers from a file it will be
necessary to use a special list-reading procedure.
