Clear.text.rect

The clear.text.rect command clears a rectangular text area on the screen.

Syntax

clear.text.rect(byt R1, byt C1, byt R2, byt C2, byt COLOR);

Remarks

This command clears a rectangular area from row R1, column C1 to row R2, column C2 using color COLOR. It can be used on both the text screen and the graphics screen.

If the area cleared will encompass the entire row (C1 = 0 and C2 = 39), it is more efficient to use the clear.lines command.

On the graphics screen, the color used to clear the area is specified by COLOR. If COLOR is 0, the lines are cleared to black. if COLOR in nonzero, white is used to clear the area. Keep in mind that if any screen objects move over the cleared area, the screen will revert back to the original pixels once the object has moved past; the cleared area is not stored in memory.

On the text screen, the color argument is ignored. The area is always cleared to black. If you want the cleared area to have a color other than black or white, a workaround, using a single space message and the display.v command, is demonstrated in the example below.

Possible Errors

AGI does not validate the argument values, so if either row argument is > 24, or either column argument is > 39, or R2 < R1 or C2 < C1, the results will be unpredictable.

Example

Code:

<syntaxhighlight lang="agi"> clear.text.rect(2, 2, 10, 20, 0);

[ a simple method to clear text on the text screen with [ a non-black background color [ this could be put in a separate logic, and called when [ necessary in lieu of the clear.text.rect command

1. message 255 " " [ single space
2. define R1 v201
3. define CL1 v202 [ can't use 'c1', as that is the data type marker for a controller
4. define R2 v203
5. define CL2 v204

set.text.attribute(0, 4); [set background to red v207 = 255; [ value of message index

v205 = R1; [ starting row if(v205 <= R2) [ verify R1 <= R2

 {
 RowLoop:
 v206 = CL1;     [ starting column
 if(v206 <= CL2) [ verify CL1 <= CL2
   {
   ColLoop:
   display.v(v205, v206, v207);
   }
 addn(v206, 1);  [ next column
 if(v206 <= CL2) 
   {
   goto(ColLoop);
   }
 }

addn(v205,1); [ next row if(v205 <= R2)

 {
 goto(RowLoop);
 }

</syntaxhighlight>

Technical Information

Required Interpreter Version:	Available in all AGI versions.
Byte-Code Value:	154 (0x9A hex)

See Also

Display Commands
Text Display Mode
Graphics Display Mode
clear.lines