View source for Clear.text.rect

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

== Syntax ==

clear.text.rect([[number|byt]] R1, [[number|byt]] C1, [[number|byt]] R2, [[number|byt]] C2, [[number|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 ==

<div class="CodeBlockHeader">Code:</div>
<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

#message 255 " "  [ single space
#define R1 v201
#define CL1 v202  [ can't use 'c1', as that is the data type marker for a controller
#define R2 v203
#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 ==

{| border="1" cellpadding="2"
| style="background-color: #efefef" width="200" | '''Required Interpreter Version:'''
| width="175" | Available in all AGI versions.
|-
| style="background-color: #efefef" | '''Byte-Code Value:'''
| 154 (0x9A hex)
|}

== See Also ==

[[Display Commands]]<br />
[[Text Display Mode]]<br />
[[Graphics Display Mode]]<br />
'''[[clear.lines]]'''<br />
[[Category:Commands]]<br />