!bm3
!pr2
Text Area Erase Routine..........................Jeff Creamer
                                 Yavapai College, Prescott AZ

Good programs interact frequently with their users, providing error messages, helpful prompts, and information about what the program is doing.  For programmers, this raises the question of what to do with the messages once they have been printed, especially if you want to get rid of them while leaving the rest of the screen intact.  

I have used several strategies to clear specific areas of the text screen.  The simplest solution, and probably the most commonly used, is to place all messages at the end of the page.  Then you can HTAB and VTAB to the first character of the message and CALL the Monitor routine at $FC42 (CLREOP).  From Applesoft, CALL -958.  Such messages must be kept to the lower part of the screen, however, and the method can interfere with decorative borders, etc., placed around your screens.

Another thing I have done is to print strings of blanks over the offending message.  I use a loop to HTAB and VTAB to the left margin of the message area, incrementing the vertical coordinate each time, then printing a string variable set to a predetermined number of blanks.  This method is slow, but not unbearable.  Still, it is clumsy and wastes memory storing the blanks.

Of course, instantaneous clears of a given area are easily done by resetting the text window through POKEing values to locations $25-$28, then executing a HOME.  This requires POKEing 4 values before the clear, however, and POKEing 4 coordinates to reset the current window when you are done (or "TEXT" to reset the default window).  Downright unpleasant.  For a time I resorted to this method to protect my decorative borders, however. 

Now I have come up with a routine that I think is an improvement over the above.  It clears rectangular areas of the text screen given the width and depth (number of lines) needed.  Because it uses the Monitor COUT routine, it should also work with those hi-res character generator utilities that interface to the normal output hooks, giving a controlled hi-res screen clear.  While it requires Applesoft in ROM, it is fully relocatable, making it ideal for people who use Ampersand utilities like AmperMagic or The Routine Machine.

The routine, which I call "ERASE", is used by first HTABing and VTABing to the upper left corner of the area to be cleared.  Then CALL the routine giving the width and depth of the area to be cleared, using commas, like so:

     CALL ADDRESS,WIDTH,DEPTH

For example, assume you BLOAD the routine at $300, the most common place to do such things.  (At least while we are testing the program.)  Then, to clear an area 15 characters wide by 4 lines deep, write:

     CALL 768,15,4
The command shown above uses simple constants, but ERASE can handle any quantities "width" and "depth" up to formulas as complex as those Applesoft can normally handle.  (I can't brag about that part, since all the work is done by Applesoft's formula evaluation routine "FRMEVL", called indirectly in my program by the "JSR GETBYT".

In case you don't have John Crossley's article on Applesoft Internal Entry Points, GETBYT is a subsidiary routine that evaluates formulas, bringing back a single-byte integer in the X-register and in location $A1--"FACLO".  I don't use "FACLO" in this routine.  GETBYT gives an illegal quantity error if the formula evaluates to more than 255 or less than 0.)

If you specify a width or depth of zero, ERASE will give an illegal quantity error.  If the width of the line goes past the right edge of the screen, the blanks will wrap around the screen on the next line down.  ERASE will pick up at the correct horizontal/vertical location when clearing subsequent lines, however.  If the area to be erased goes past the bottom of the screen, do not fear:  ERASE wraps around to the top of the screen.  Your program and variables will not be hurt.

Here is a short Applesoft program that demonstrates ERASE in action.  The program first fills the entire screen with asterisks, and then clears three windows.  The first window wraps around from the right edge of the screen to the left.  The second wraps around from the bottom to the top.  The third is in the middle of the screen.  (I am assuming a 40-column screen here.)

!lm+5
100  FOR I = 1 TO 24: PRINT
     "****************************************"; : NEXT
110  HTAB 30: VTAB 10: CALL 768,20,5
120  HTAB 10: VTAB 20: CALL 768,20,8
130  HTAB 15: VTAB 10: CALL 768,10,5
!lm-5

And here is another demo, one which is closer to the way you will find yourself using ERASE.  This one prints an array of six messages in six windows on the scrren, and lets you selectively erase them in any order one-by-one.  As it turned out, the way I located the upper corners of the messages involved some lengthy formulas, but these ended up in the HTAB and VTAB statements. Note that I could have used data statements for similar results.
