GfA Basic

GFA BASIC TIPS & TRICKS by Richard Karsmakers

In the previous issues of ST NEWS we already explained the syntax 
and  the use of some specific GfA Basic commands,  but this  time 
we'll start giving examples of programs that can be used in  your 
own  projects.  What  about  31 colours on  your  screen  in  low 
resolution, or 19 colours on the screen in medium resolution? And 
what about reading a directory from disk?  In this article, we'll 
give  some practical samples of this,  as well as a reference  to 
all ESC codes for use with GfA Basic.
First,   something   about  reading  in  directories,   by   Paul 
Kolenbrander.

Although  GfA-Basic  has  two excellent commands  for  getting  a 
directory,  an  increasing number of people would like some  more 
control over directory-entries.  For example,  being able to sort 
them,  manipulate them, or any other reason. It is quite possible 
to read a directory,  check for the kind of entry or only read in 
specific entries. This can be done by using the GEMDOS functions.
The  following listing is a small example of this.  It reads  the 
root-directory,  extracts the entry-names and checks if an  entry 
is a folder or a volumelabel.
' Program to read a root directory 
' using GEMDOS functions
' Written in GfA-Basic Version 1
Counter=2
' Filename;  here you can specify if all files or only  files     
' corresponding with a specified extension or names should be   
' read in. eg *.PRG or *.P?2 or FILE????.FIL
File$="*.*"
' Set up the DTA-buffer  
Dim Buf(43)
Dim Label$(250)
' Set up the Device Transfer Address using DTA-buffer
Pointer=Gemdos(26,L:Varptr(Buf))
' Read first directory entry 
Found=Gemdos(&H4E,L:Varptr(File$),&H1F)
' extract name from DTA-buffer
For X=30 To 42
  Label$(1)=Label$(1)+Chr$(Peek(Varptr(Buf)+X))
Next X
' check if entry is a folder

If Peek(Varptr(Buf)+21)=16
  Label$(1)=Chr$(7)+Label$(1)
Endif
' check if entry is a volume-label
If Peek(Varptr(Buf)+21)=8
  Label$(1)=Chr$(8)+Label$(1)
Endif
While Found>-1 And Counter<248
  ' read next directory entry
  Found=Gemdos(&H4F)
  ' extract name 
  For X=30 To 42
    Label$(Counter)=Label$(Counter)+Chr$(Peek(Varptr(Buf)+X))
  Next X
  If Peek(Varptr(Buf)+21)=16
    Label$(Counter)=Chr$(7)+Label$(Counter)
  Endif
  Counter=Counter+1
Wend
Ndx=1

' clean up all directory entries in Label$()
' remove trailing Chr$(0)'s
While Ndx<>Counter
  For X=1 To 12
    If Mid$(Label$(Ndx),X,1)=Chr$(0)
      Label$(Ndx)=Mid$(Label$(Ndx),1,X)
    Endif
  Next X
  Ndx=Ndx+1
Wend

After  running  this program you will have  an  array  (label$()) 
containing  all the names of the entries in the  root  directory, 
with a maximum of 250 entries.  Folders are preceded by a CHR$(7) 
and the volume-name by a checkmark.

A bit more about the GEMDOS functions used in the program:

- Pointer=Gemdos(26,L:Varptr(Buf))
This function sets up the buffer for the Device Transfer Address. 
In  this  44 bytes long Buffer the directory entry data  will  be 
put.  If you have GfA-Basic V2.0 you can replace Pointer by  Void 
giving an increase in speed of execution.
The buffer positions are:

Offset  Size       Meaning
  0     20 Bytes   Reserved for the Operating System
 21      1 Byte    File Attribute
 22      2 Bytes   Time Stamp (encoded binary)
                   highest 5 bits: Hours (00-23)
                   Middle  6 bits: Minutes (00-59)
                   Lowest  5 bits: Seconds (00-29)
                  (multiply seconds by 2 to get the right number)
 24      2 Bytes   Date Stamp (encoded Binary)
                   Highest 7 bits: Year (subtract 1980 from this)
                   Middle  4 bits: Month (00-12)
                   Lowest  5 bits: day (01-31)
 26      4 Bytes   File Length
 30     14 Bytes   File name and extension

- Found=Gemdos(&H4E,l:Varptr(File$),Fileattribute)
This  function reads te first directory entry on  the  parameters 
specified in File$ and the numerical variable Fileattribute.
Found returns:   0 if Ok
               -33 if no file could be found
               -49 if end of directory  
File$ must contain at least '*.*',  specifying all files but  all 
other  characters and combinations may be used depending on  what 
you  want.  For example if you want a directory  containing  only 
filenames of Degas pictures you could enter '*.P??'.  This  would 
find  all Degas pictures.  or '*.P?2',   which would only  return 
medium resolution pictures. 
Fileattribute specifies the type of file to be searched for.  You 
can  search for a specified attribute,  for example only  display 
folders or Read-Only files, or a combination. The following table 
specifies the attributes and the relevant bit. '1' means set.

Bit  Attribute
 0   Read Only
 1   Hidden File
 2   System File (implies hidden from directory search)
 3   Volume Label
 4   Folder (subdirectory)
 5   File has been written to and closed  

-Found=Gemdos(&H4F)
This  function finds the next valid directory entry and uses  the 
parameters set by GEMDOS(&H4E).  Found returns the same values as 
above.

It is possible to use the above program to read the the  contents 
of  a  subdirectory  if  at the top of  the  program  the  GEMDOS 
function(&H3D)    is    used.    The   syntax   of    which    is 
Gemdos(&H3D,Folder$),  where  Folder$  contains the name  of  the 
subdirectory.   

On  this same disk you will find a listing of the above  program, 
with which you can experiment to your heart's delight.  A warning 
though,  if you make changes,  first save them before you run the 
program  and also write protect the disk you work on because  the 
functions  are very unforgiving when used incorrectly  and  might 
crash your system if treated wrongly. So, beware of the Kraken. 

So,  that's all about directory entries. Now, let's continue with 
the color phenomena. The principle is very simple: You simply put 
a color picture (made in Degas or so) on the screen (you can also 
put several objects on the screen) using 15 colours (in low  res) 
or  3  colours (in medium res).  Don't forget to set  all  colors 
according  to the picture using the SETCOLOR command.  Take  care 
not to load the picture on the wrong address.  The following line 
should do the job if it is an uncrunched Degas file:

BLOAD "TITLE.PI?",XBIOS(2)-34

When you want to load a Neochrome picture, you'll have to replace 
the  '34'  by  the length  of  a  Neochrome  picture-32000.  Most 
pictures  of  most  drawing programs can  be  loaded  using  this 
technique.
The colour we'll start changing rapidly will be the border colour 
(color 0 on the color palette).  Using the speed of GfA Basic, it 
is possible to create up to 16 colours in the border,  that  will 
create  a  nice scrolling colour effect.  All the pixels  on  the 
screen  that have the same colour number will be changed in  much 
the same way (although timing might mean that it is a bit  before 
or after the actual border 'scrolling').  The actual routine that 
does the color switching would be like this:

Loop
  For X=0 To 7
    Setcolor 0,7,7,X
    Pause 0.0001
  Next X
  For X=0 To 7
    Setcolor 0,7,X,7
    Pause 0.0001
  Next X
Loop

When you experiment a bit with the values that are currently  set 
to '7', you can get some nice effects. If you want the colours to 
go up and down as well, you can add a line like:

 For X=7 Down To 0

When you do that with yellow-white-yellow,  it is possible to get 
an  almost perfect colour shading.  When you  incorporate  raster 
techniques   in  an  even  faster  programming   language   (like 
assembler),  it  might  even  be possible to have  more  than  31 
colours  on the screen at one time.  But experimenting  with  GfA 
Basic also lets you achieve nice things.
We are very interested to publish nice more-than-16-colours demos 
written  in GfA Basic in an upcoming issue of ST NEWS,  so  don't 
hesitate to experiment a bit and send your stuff to us on a sigle 
sided  disk.  Don't forget to add stamps or  International  Reply 
Coupons so we can send everything back to you!

Now about the TOS "Escape" functions.  With the help of these TOS 
functions and the PRINT command,  it is possible to do all  kinds 
of things with text, etc. The following is a list of the possible 
functions, starting on the next page.
Chr$(27);"A"           Cursor one line up
Chr$(27);"B"           Cursor one line down
Chr$(27);"C"           Cursor one character to the right
Chr$(27);"D"           Cursor one character to the left
Chr$(27);"E"           Clear/Home
Chr$(27);"H"           Home
Chr$(27);"I"           Cursor one line up with scroll
Chr$(27);"J"           Clear screen after cursor
Chr$(27);"K"           Clear line after cursor
Chr$(27);"L"           Insert line
Chr$(27);"M"           Clear one whole line, scroll up rest
Chr$(27);"b";color     Set character color1
Chr$(27);"c";color     Set background color1
Chr$(27);"d"           Clear screen before cursor
Chr$(27);"e"           Turn cursor on
Chr$(27);"f"           Turn cursor off
Chr$(27);"j"           Save cursor position
Chr$(27);"k"           Put cursor on saved position
Chr$(27);"l"           Clear one whole line

1=  Only  the upper four bits of the character 'color'  are  used 
(MOD 16). So you can select color one with e.g. '1', 'a' or 'A'.
Chr$(27);"o"           Clear line before cursor
Chr$(27);"p"           Reverse video on
Chr$(27);"q"           Reverse video off
Chr$(27);"v"           When the cursor is at the end of a  line, 
                       it will automatically be put on the first
                       position of the next line after this
Chr$(27);"w"           When the cursor is at the end of a  line,
                       it will remain there. All printed charac-
                       ters will be put at that position

That's  it for this issue of ST NEWS.  If you have  any  problems 
with GfA Basic, please don't hesitate to write to us. Here again, 
you  shouldn't  forget to add enough  stamps/International  Reply 
Coupons for the answer.

The  program listing of Paul Kolenbrander's part of this  article 
may be found in the "PROGRAMS"-folder on this ST NEWS disk.