   The IE Terminal Driver - by Richard M. Marshall

      The  IE  Terminal  Driver  is  a  terminal  and  system   independent
      procedural  video  terminal  interface.   If differs significantly in
      philosophy from  the  Hamish  Dewar    VTLIB  while  offering  almost
      identically the same useful features.

      What IE_T_D does NOT provide:

         *  "Windows"  -  conventional  video  terminals do not provide the
                          correct hardware "hooks" to support  full  window
                          systems on them so why pretend!
         *   Short  identifiers  -  All  facilities  are  identified  by  a
                                    meaningful name.

      What IE_T_D does provide:

         * Systematic access to ALL terminal advanced features.
         * Insert/Delete character operations.
         * Terminal independant graphics characters.
!PAGE

   Access to these declarations is by including "IE:Terminal.Inc"

   Currently the following terminals are supported:

      Visual 200
      Visual 55   (in V210 emulation mode NOT V55 mode)
      VT100
      VT220

   More terminals can be added as needed with no difficulty.

Suggestions for improvements are welcomed.
!PAGE
Establishing the terminal type:  (pending being done properly!)

For the moment this variable should be assigned as follows:

%external %byte %spec Terminal Model

%constant %integer Visual 200 
                   Visual 55  
                   VT100      
                   VT220      

Then call the procedure to initialise the package:

%external %routine %spec Set Terminal Characteristics

It may well also be advantageous to set Terminal Width if your terminal is
not 80 columns wide:

%external %integer %spec Terminal Width

!PAGE
To allow access to advanced features of the terminal the following %integer
has bits set in it to tell whether or not the terminal has a capability.

%external %integer %spec Terminal Characteristics

%constant %integer Reverse Scroll   Ability
                   Delete Character Ability
                   Static Insert    Ability
                   Dynamic Insert   Ability
                   Noisy Insert     Ability
                   Supress Cursor   Ability

%constant %integer Bright Text      Ability
                   Dim Text         Ability
                   Reverse Text     Ability
                   Blink Text       Ability
                   Underline Text   Ability
                   Double Width     Ability
                   Double Height    Ability


The meaning of each bit will become clear as required.
!PAGE
The following routines manipulate the cursor:

%external %routine %spec Cursor (%integer X, Y)
   X is normally in the range 0 to 79
   Y is normally in the range 0 to 23
      with (0, 0) being at the TOP LEFT as this has (unfortunately) become
      conventional in text manipulation.

%external %routine %spec Left  %alias "IE_TT_C_L"
%external %routine %spec Right %alias "IE_TT_C_R"
%external %routine %spec Up    %alias "IE_TT_C_U"
%external %routine %spec Down  %alias "IE_TT_C_D"

!PAGE
Scroll operations are provided by the following two routines.  
Each makes a SINGLE LINE scroll in the appropriate direction.  Here is one
of the philosophy distinctions between IE_T_D and VTLIB.  The extra cost,
when taking text drawing into account, of introducing lines singly in a 
scroll is minimal and by so doing the whole screen maintains readability
and the effect is much smoother.

%external %routine %spec Forward Scroll (%integer Top, Bottom)
   The line TOP is deleted and another line is added at BOTTOM, where
   TOP and BOTTOM are valid Y coordinates on the screen.
%external %routine %spec Reverse Scroll (%integer Top, Bottom)
   The Line at BOTTOM is deleted and another line is added at TOP.

!PAGE
The following routines are involved in clearing parts of the screen.  The
names are historical.

%external %routine %spec Clear Line
   The clears all text from the current line and leaves the cursor at the
   left hand margin.
%external %routine %spec Clear Screen
   The clears all text from the whole screen and leaves the cursor at HOME,
   ie (0, 0), top left of the screen.
%external %routine %spec Erase Line
   This clears all text from the current cursor position up to the end of
   the line, leaving the cursor unmoved.  This will not normally delete
   protected text on terminals that provide this facility.

!PAGE
It is usually advantageous to be able to display text in different
"colours" and modes.

The following routines enable (if the terminal is capable) these
facilities:

%external %routine %spec Dim On 
%external %routine %spec Reverse On 
%external %routine %spec Underline On 
%external %routine %spec Blink On 

To go back to plain text use:
%external %routine %spec Normal  

Since various terminals do not support all the above features a special
procedure is provided to HIGHLIGHT text.  It is recommended that this is
normally used instead of the <feature> On routines:

%external %routine %spec Feature

!PAGE
Some even more exotic facilities are available:

%external %routine %spec Upper Half Double Height 
%external %routine %spec Lower Half Double Height 
%external %routine %spec Double Width On 
%external %routine %spec Normal Size 

And it is even possible on some terminals to switch off the blob or
whatever that is the cursor:

%external %routine %spec Cursor On  
%external %routine %spec Cursor Off 

!PAGE!
Terminal independant graphics characters (form filling line graphics) are 
available.  The set is currently not complete and can be extended as required.

Graph mode must be enabled before use of the procedures:
%external %routine %spec Graph On  
%external %routine %spec Graph Off 

%external %routine %spec Left T                 { |- }
%external %routine %spec Top Left               { r shape}
%external %routine %spec Horizontal             { - }
%external %routine %spec Vertical               { | }
%external %routine %spec Top Right              { backwards 'r' shape}

Other possibilities include:
   Right T, Bottom Left, Bottom Right, Centre

   and various odd characters such as pound, cent, yen and degrees signs.
!PAGE
Character row operations are supported, but are unlikely to be used in programs
other than editors.  Note that NONE of these facilities may be available on a
terminal and IE_T_D does not emulate them as this has not yet been needed.  IE
itself is in a much better position to update the sceen than the package so it
simply checks TERMINAL CHARACTERISTICS.

%external %routine %spec Delete Characters (%integer N)
   This deletes the N characters after the cursor.

There are three classes of INSERT CHARACTER:
   1) Dynamic Insert:  This is optimal - stick the terminal into the mode
                       and all output sent to the terminal is inserted.
   2) Noisy Insert:    This is named after the the V200 mode.  It is essentially
                       the same as Dynamic Insert but for various reasons the
                       mode cannot be left enabled, and must be used as:
                           Insert On;  Put Character;    Insert Off
                       On the V200 keystrokes beep in Insert Mode, hence the
                       name.
   3) Static Insert:   Terminals supporting this class of insertion can
                       insert a given number of spaces after the cursor which
                       can then be filled in.

Classes 1 and 2 are catered for with:
%external %routine %spec Insert On 
%external %routine %spec Insert Off 

Class 3 uses:
%external %routine %spec Static Insert (%integer N)

!PAGE
Output is only half the terminal independent battle!  Yes, the other half is
input.  IE_T_D uses a KEY PACKAGE which reads in ALL the odd keys on a terminal
and encodes them in the 128..255 range of the byte.   A systematic approach
has been used to providing ranges and SHIFTs.   

These routines enter non-numeric mode on keyboards that have this facility.
%external %routine %spec Keypad On  
%external %routine %spec Keypad Off 

This routine is equivalent to READ SYMBOL but returns packaged keystrokes.

%external %byte %function %spec Get Key

This routine returns the name of the key, for example "Keypad ENTER".
%external %string (255) %function %spec Key Name (%integer Key)
!PAGE

The key codes returned are as follows in the next few pages.  Symbolic names 
should always be used in preference
%constant %integer NUL = 0,
                   SOH = 1,
                   STX = 2,
                   ETX = 3,
                   EOT = 4,
                   ENQ = 5,
                   ACK = 6,
                   BEL = 7,
                   BS  = 8,
                   TAB = 9, HT = TAB,
                   LF  = 10,
                   VT  = 11,
                   FF  = 12,
                   CR  = 13,
                   SO  = 14,
                   SI  = 15,
                   DLE = 16,
                   DC1 = 17, XON  = DC1,
                   DC2 = 18,
                   DC3 = 19, XOFF = DC3,
                   DC4 = 20,
                   NAK = 21,
                   SYN = 22,
                   ETB = 23,
                   CAN = 24,
                   EM  = 25,
                   SUB = 26,
                   ESC = 27,
                   FS  = 28,
                   GS  = 29,
                   RS  = 30,
                   US  = 31,
                   DEL = 127
   
%constant %integer Extra Keys = 128

%constant %integer Unknown Key = Extra Keys ! 0

{Cursor Keys}

%constant %integer Up    Key = Extra Keys ! 1,
                   Down  Key = Extra Keys ! 2,
                   Right Key = Extra Keys ! 3,
                   Left  Key = Extra Keys ! 4


{Keypad Numbers}

%constant %integer Keypad 0 = Extra Keys ! 10,
                   Keypad 1 = Extra Keys ! 11,
                   Keypad 2 = Extra Keys ! 12,
                   Keypad 3 = Extra Keys ! 13,
                   Keypad 4 = Extra Keys ! 14,
                   Keypad 5 = Extra Keys ! 15,
                   Keypad 6 = Extra Keys ! 16,
                   Keypad 7 = Extra Keys ! 17,
                   Keypad 8 = Extra Keys ! 18,
                   Keypad 9 = Extra Keys ! 19

{Keypad odd keys}

%constant %integer Keypad Comma = Extra Keys ! 20,
                   Keypad Dot   = Extra Keys ! 21,
                   Keypad Minus = Extra Keys ! 22,
                   Keypad Enter = Extra Keys ! 23

{Keypad with Function}

%constant %integer Function Keypad 0 = Extra Keys ! 30,
                   Function Keypad 1 = Extra Keys ! 31,
                   Function Keypad 2 = Extra Keys ! 32,
                   Function Keypad 3 = Extra Keys ! 33,
                   Function Keypad 4 = Extra Keys ! 34,
                   Function Keypad 5 = Extra Keys ! 35,
                   Function Keypad 6 = Extra Keys ! 36,
                   Function Keypad 7 = Extra Keys ! 37,
                   Function Keypad 8 = Extra Keys ! 38,
                   Function Keypad 9 = Extra Keys ! 39

{Keypad Odd Keys Shifted}

%constant %integer Function Keypad Comma = Extra Keys ! 40,
                   Function Keypad Dot   = Extra Keys ! 41,
                   Function Keypad Minus = Extra Keys ! 42,
                   Function Keypad Enter = Extra Keys ! 43

{Function Keys}

%constant %integer Key F0 = Extra Keys ! 50,
                   Key F1 = Extra Keys ! 51,
                   Key F2 = Extra Keys ! 52,
                   Key F3 = Extra Keys ! 53,
                   Key F4 = Extra Keys ! 54,
                   Key F5 = Extra Keys ! 55,
                   Key F6 = Extra Keys ! 56,
                   Key F7 = Extra Keys ! 57,
                   Key F8 = Extra Keys ! 58,
                   Key F9 = Extra Keys ! 59,
                   Key F10 = Extra Keys ! 60,
                   Key F11 = Extra Keys ! 61,
                   Key F12 = Extra Keys ! 62,
                   Key F13 = Extra Keys ! 63,
                   Key F14 = Extra Keys ! 64,
                   Key F15 = Extra Keys ! 65,
                   Key F16 = Extra Keys ! 66,
                   Key F17 = Extra Keys ! 67,
                   Key F18 = Extra Keys ! 68,
                   Key F19 = Extra Keys ! 69,
                   Key F20 = Extra Keys ! 70 

{Any odd other keys}

{All terminals}
%constant %integer Panic Key = Extra Keys ! 100

{VT100 and VT220}
%constant %integer PF1 Key = Extra Keys ! 101,
                   PF2 Key = Extra Keys ! 102,
                   PF3 Key = Extra Keys ! 103,
                   PF4 Key = Extra Keys ! 104,
                   Function PF2 = PF2 Key + 20,
                   Function PF3 = PF3 Key + 20,
                   Function PF4 = PF4 Key + 20

{Visual 200 and Visual 55}
%constant %integer Home  Key = Extra Keys ! 105,
                   BTAB  Key = Extra Keys ! 106

{Visual 200 only}
%constant %integer CP    Key = Extra Keys ! 107,
                   CL    Key = Extra Keys ! 108 

{VT220}
%constant %integer Help Key = Key F15,
                   Do   Key = Key F16,
                   Find Key = Extra Keys ! 109,
                   Insert Here Key = Extra Keys ! 110,
                   Remove Key = Extra Keys ! 111,
                   Select Key = Extra Keys ! 112,
                   Prev Screen Key = Extra Keys ! 113,
                   Next Screen Key = Extra Keys ! 114
