
                        ========== TEXTPLATE ==========
                          Forms print-out from Basic
                               by Kell Gatherer
                        ===============================


The "TextPlate" routine allows pre-designed text templates ("textplates")
to be used for printing out diagrams or forms from Basic.

The need for the routine arose because of the difficulty of using the IBM
character set from Basic. For example the following box:   ͸
                                                                     
would necessitate the following Basic lines:               
PRINT CHR$213;CHR$205;CHR$205;CHR$205;CHR$205;CHR$205;CHR$184
PRINT CHR$179"     "CHR$179
PRINT CHR$192;CHR$196;CHR$196;CHR$196;CHR$196;CHR$196;CHR$217
TextPlate is far easier to use!

 ====== "TextPlate" files ======

Inside the !TextPlate directory are three examples of textplate files:
  TxtPlt1, TxtPlt2 and TxtPlt3.
They have been created using Edit and the Forms Designer (Forms) which 
was published in RISC User 4:9 (September 1991) and is included on this
disc.

To view these files, you must first load the screen font "FormFont" which 
is supplied with Forms - it is also supplied within the !TextPlate 
directory. Either start up Forms as an application (i.e. the Forms 
window is open) or double-click on "FormFont" in this directory.

The textplate files may now be loaded into Edit. However here is an 
example (if it looks like a load of weird symbols, load FormFont now!):

\ Sunrise/Sunset text template
 ]ͻ
 ]                 Sunrise   Sunrise    Sunset    Sunset  
 ] Day  Date       Time      Azimuth    Time      Azimuth 
 ]͹
6] ###  ########   #####      ###      #####      ###   
 ]Ķ
6] ###  ########   #####      ###      #####      ###   
 ]Ķ
6] ###  ########   #####      ###      #####      ###   
 ]Ķ
6] ###  ########   #####      ###      #####      ###   
 ]Ķ
6] ###  ########   #####      ###      #####      ###   
 ]Ķ
6] ###  ########   #####      ###      #####      ###   
 ]Ķ
6] ###  ########   #####      ###      #####      ###   
 ]ͼ
 ]            Ŀ
1]   GMT/BST:  ###### 
 ]            


Any lines at the start of the file which start with a backslash ("\") are 
regarded as comment lines and ignored.

The first four lines of the above textplate do not contain fields and are 
printed out automatically. Only the characters after the "]" symbol are 
printed. The fifth line contains fields indicated by the use of the "#" 
symbol. The number of fields in that line is indicated by the "6" at the 
start of the line: this is to permit different lines to contain different 
numbers of fields.

The only other thing to note about textplate files is that the last line 
of the file must not be a "null" line, i.e. it must contain characters 
even if they are only spaces.

 ====== Using TextPlate from Basic ======

The TextPlate routines may be appended to your own Basic program or used 
as a LIBRARY routine. To do the latter, include the following line early 
in the program:

         LIBRARY "TextPlate"
 (or LIBRARY "<Obey$Dir>.TextPlate" or LIBRARY "<Test$Dir>.TextPlate" 
  or whatever)

The other lines which will then need to be included are as follows:

         DIM textplate$(6)             } maximum number of fields -1

         PROC_textplate_open(filename) } filename of the textplate
       
         textplate$(0)=string          }
         textplate$(1)=string          } Repeat this by the 
         textplate$(2)=string          } number of lines
         textplate$(3)=string etc.     } with fields
         PROC_textplate                }
      
         PROC_textplate_close
      
Your printer will need to be initialised to produce the IBM graphics 
set: sample set-up files are included at the and of the "Demo" program, 
otherwise you will have to consult your printer manual.

The output from the routines is passed back to the main program by a 
procedure PROC_textplate_print, which should be written according to 
your own set-up. As an example: 

         DEF PROC_textplate_print(text$)
         *FX3,10
         PRINTtext$
         *FX3,0
         ENDPROC

The Demo program loads the FormFont font and outputs to the screen.

The TextPlate routine initialises a variable "textplateopen%" to TRUE 
when the template file is open, and to FALSE when it is closed, so your 
error handling procedure should include the following line:

         IF textplateopen% PROC_textplate_close

This is to permit the file to be closed without knowing its handle, as 
is the case when the routine is used in a LIBRARY.

The data from your program is passed to TextPlate using the array 
textplate$(). Each line of the textplate that contains fields should 
fill the array from textplate$(0) and then call PROC_textplate. This 
could take different forms, e.g.:

         textplate$()="Fred","George","Mary":PROC_textplate

or       textplate$(0)="Harry"
         textplate$(1)="Jason"
         PROC_textplate

or       FOR loop% = 0 TO 3
          READ textplate$(loop%)
         NEXT
         PROC_textplate
         DATA 125,25,16,15

or       textplate$()=data$():PROC_textplate

You don't have to use or define all the elements of textplate$(): for 
example if the array has six elements, but you only need three on a line
you need only define elements 0 to 2 inclusive. The program reads the
number of printable fields in each line by the numeral at the start
of the line in the textplate file.

The contents of each field will be truncated if too long or padded with 
spaces if too short. Each field may be formatted prior to insertion in the 
textplate by preceding the string with either "#R", which will right-align 
the text, or "#C" which will centre it.
               
All variables used in the routine begin with the underline character "_"
(APART FROM textplate$() and textplateopen%) to avoid confusion with your
own variables. The actual procedures in the TextPlate file are as follows:

DEF PROC_textplate_open(_fname$)
DEF PROC_textplate
DEF FNt_field(_t$,_t%)
DEF PROC_textplate_close

The program "Demo" shows three ways in which the data is transferred to 
PROC_textplate, and also the "TextPlate" routine is fully documented.

To print this file, hold down Shift and double-click on !ReadMe - print out
the "Text" file.