SIMPLE TEXT SCREEN CONTROL  IN CF83
                      Copyright (c)  1992
                      by M. David Johnson

This file should be printed at 63 characters per line.

With any new language, one of the first tasks a programmer
wants to learn is how to input information and output results. 
CF83 Forth comes ready-to-run for simple interactive input and
output, but programmers often want to format screen input and
output to make their programs easier to use and understand.

CF83 words that provide simple text screen control are
presented in Forth blocks 1 through 5 of TEXTCONT.BLK.  Before
you can use these blocks, you must first convert them from file
format to CF83 Forth Block format using the FILTOBLK.BAS
program ( available on Delphi or on BDS Software's CF83 Public
Domain Disk No. 1 ).

In order to use these blocks, you will also need a copy of the
CF83 Forth Master Disk available from:

          BDS Software
          P.O. Box 485
          Glenview, IL 60025-0485 

Blocks 6 through 8 of TEXTCONT.BLK are an example of how these
words could be used in a database program, and Block 9 is a
faster version of that example.  

CF83's standard text screen is a CoCo PMODE 4 screen maintained
in memory from address 2560 through address 8703 (All numbers
and addresses in this article are in decimal).

The screen memory is addressed by pixel x-coordinates 0-255 and
y-coordinates 0-191.  The current 16-bit x-coordinate location
is held in memory at 243:244 and the current 16-bit
y-coordinate location is held in memory at 245:246.  The
coordinates range from the origin at the upper left corner of
the screen.  ( 16-bit coordinates are used instead of 8-bit
coordinates because the same memory locations are used for
16-bit HMODE graphics coordinates ).

Standard CF83 characters are 3 pixels + 1 pixel space wide by 7
pixels + 1 pixel space high, and are located by the upper left
pixel of the character.

So, for text purposes, the screen can also be described as 64
characters wide and 24 lines high.  An ASCII image of the
screen can, therefore, be maintained in 64 x 24 = 1536 bytes.  

To use the simple text screen controller, start CF83 and, at
the "ok" prompt, place the disk containing blocks 1 through 9 
( in the converted block format ) in drive zero and enter 1
LOAD to load blocks 1 through 5.

Enter KMGR to start the controller's keyboard manager. 
Pressing a character key at the keyboard activates the CF83
word ( addchr ) which echoes the key to the screen and to its
ASCII image array SCRIMG, and then advances the cursor's
coordinates on the screen and the ASCII image array pointer
SCRPTR.  Special control keys include:

          KEY                 ACTION

          Left Arrow          Moves the cursor left one
                                position (ek8, x-)

          Right Arrow         Moves the cursor right one
                                position (ek9, x+)

          Down Arrow          Moves the cursor down one
                                line (eka, y+)

          Up Arrow            Moves the cursor up one
                                line (ekb, y-)

          Shift - Left        Moves the cursor to the start 
          Arrow                 of the current line
                                (ek15, x0)

          Shift - Right       Moves the cursor to the end 
          Arrow                 of the current line
                                (ek16, xe)

          Shift - Down        Moves the cursor to the bottom
          Arrow                 of the screen (ek17, ye)

          Shift - Up          Moves the cursor to the top
          Arrow                 of the screen (ek18, y0)

          ENTER               Carriage Return - Line Feed
                                (ekd, crlf)     

          Clear - Up          Homes the cursor to the upper
          Arrow                 left corner of the screen
                                (ek7, home)

          Clear - Down        Exits the keyboard manager and
          Arrow                 returns to normal interactive
                                CF83 I/O with the screen's
                                ASCII image in SCRIMG (ek6)

KMGR executes the simple text screen controller in its most
elementary form.  This form allows programmers to build text
screens of their own design.  Some additional words allow
programmers to build their own customized text screen
controllers to guide users of their programs with specific I/O
screen formats.  These words include:

          WORD                ACTION

          setxy               Sets the cursor and image pointer
                                to a specific screen location

          cls                 Clears the screen and its image

          cpys                Copies the screen image to the
                                screen

To execute an example of such a customized text screen
controller, return to normal interactive CF83 I/O and enter:

                    8 LOAD RUN

CF83 will slowly build a formatted input screen to guide the
input of personal and automobile data for a database ( the
database is not actually included - this is only an example ). 
When the cursor re-appears to the right of NAME: you can begin
input of any sample data you wish.

You may use the left and right arrow keys to correct any errors
( by overwriting them with the correct input ).  When you press
ENTER, the cursor automatically moves to the next entry field. 
When you press ENTER after entering the State of the
automobile's license, the screen clears and leaves the cursor
in the lower right corner.    Press ENTER again to redisplay  
( cpys ) the screen.  Pressing ENTER once more returns to
normal interactive CF83 I/O.

     Since the screen redisplay is slow, enter:

                    9 LOAD RUN2

to run the example with a faster redisplay method.  When you
press ENTER after entering the State of the automobile's
license, the screen again clears and leaves the cursor in the
lower right corner.  But now, when you press ENTER again, the
screen redisplays instantly instead of slowly.

Of course, nothing is free in this life.  In order to gain this
increase in speed, CF83 has to CMOVE a 6144 byte picture image
( SCRPCT ) of the screen instead doing a TYPE of the 1536 byte
ASCII image ( SCRIMG ).  You pay for the speed by using more
memory.

CF83 products available from BDS Software as of 6/30/92:

                                            PRICE     PRICE
                                            WITH      WITH
                                            MANUAL    PRINTED
ITEM                                        ON DISK   MANUAL

CF83 Forth Master Disk                      $ 15.00   $ 19.00

Technical Reference Manual                  $ 10.00   $ 25.00

Tutorial                                    $ 10.00   $ 22.00

Block Editor                                $ 15.00   $ 23.00

Double Number Set                           $  5.00   $  7.00

Assembler Set                               $ 15.00   $ 22.00

System Extension Set                        $  5.00   $  7.00

Controlled Reference Set                    $ 10.00   $ 12.00

Uncontrolled Reference Set *                $ 10.00   $ 20.00  

PMODE Graphics Set                          $ 15.00   $ 28.00

RS-DOS File Handling Set **                 $ 10.00   $ 13.00

  * Includes case structure, string operations, printer
    control, and more.

 ** Includes words to allow making ML files that will EXEC
    directly from BASIC, system saving, and more.

          Send SSAE for current detailed list. 

The versions with the Manual on Disk also include a READER
program which allows viewing the manual on the screen and/or
printing the manual to your own printer.

A CF83DEMO disk is available for $3.00 - the same demo can be
downloaded free from Delphi - but note that the demo will NOT
allow loading of CF83 Forth Blocks - you need the master disk
for that.