VIDEO.RW

The function VIDEO.RW allows you to save, restore, and clear specific areas of the display.

error = VIDEO.RW(1eft, top, right, bottom, operator,image)

VIDEO.RW addresses areas of the screen by indicating the left and right column numbers (0-79), and the top and bottom row numbers (depends on video mode). A program can use these four coordinates to create the dimensions of a box. The box can then be read, cleared, or written to, and then restored to its original state.

When you read part of the display screen using VIDEO.RW, you store that image in a variable. When you restore the screen image with a write, you use that variable to restore the data for the image. It is possible to restore a different image by using a different variable, but if the new data is too small for the area to be restored, VIDEO.RW will generate an error. If the data is too large, only the portion that fits will be displayed.

Typically, you use VIDEO.RW in a three-step process:

• Read the relevant display area (saving that image in a variable).
• Clear the screen within that area (optionally changing the background character and/or its attribute).
• When ready, write the image back from the stored variable.

Use the left parameter to pass a value for the left column coordinate of the window space being defined. Be sure that this value is less than the value of right.

Use the top parameter to pass a value for the top row coordinate of the window space being defined. This value must be less than that for bottom.

Use the right parameter to pass a value for the right column coordinate of the window space being defined. This value must be greater than that for left.

Use the bottom parameter to pass a value for the bottom row coordinate of the window space being defined. This value must be greater than that for top.

There are three possible actions to be taken by VIDEO.RW:

R Read and save the specified area of display.

W Write the stored image back to the specified area.

C Clear the specified area of display.

If operator is "R", image is the variable to which the display is written.

If operator is "W", image is the variable from which the display is restored.

If operator is "C", image can be a two-byte value affecting the background and display attribute values. The first byte controls the background character, while the second byte controls the display attribute. For more information, see Appendix 2, "Video Attributes."

This function returns only one value, "error".

The value returned by this function is an error code:

/* The following code demonstrates the three operator modes of VIDEO.RW.
It first saves the display image of a central part of the screen, then clears that portion (substituting various video attributes),
and finally restores the stored image. */

DECLARE FUNCTION VIDEO.RW
DECLARE SUBROUTINE MSG, MONITOR

left = 20
top = 5
right = 60
bottom = 15
operator = ""
image = ""

background = 5
monochrome = 14
bgrd_color = char(178) ;* dark magenta
frgr_color = char(143) ;* light yellow

color          = (bgrd_color * 16) + frgr_color

verrors = ""
verrors<l> = "Out of memory during read attempt"
verrors<2> = "Display is not memory-mapped" 
verrors<3> = "Col or Row is out of range"
verrors<4> = "Left col is greater than right col, or"
verrors<4,-1> = "top row is greater than bottom row"
verrors<5> = "MODE is not 'C', 'R', 'W'"
verrors<6> = "Size of saved image is less than area to be restored"


error= VIDEO.RW(left, top, right, bottom, operator, saved_image)
IF error THEN                                    -
     MSG(verrors<error>,"","","")
     STOP
END

MONITOR(status)

operator= "C"         ;* clear the screen
* a value of 7 indicates monochrome monitor
IF status= 7 THEN
     image= background:monochrome
END ELSE
     image= background:color
END
error= VIDEO.RW(left, top, right, bottom, operator, image)
IF error THEN
     MSG(verrors<error>,"","","")
     STOP
END

MSG("this is just to delay","T2","","")
operator= "W"
error= VIDEO.RW(left, top, right, bottom, operator, saved_image)
IF error THEN                                           -
     MSG(verrors<error>,"","","")
END