Function SaveScreen() Foundation

Saves a screen segment as a character string.

Syntax
SaveScreen([<nTop>], [<nLeft>], [<nBottom>], [<nRight>]) --> cScreen
Parameters
<nTop>
<nTop> is an integer numeric value specifying the top screen row for the area whose screen information is saved. The four arguments <nTop>, <nLeft>, <nBottom> and <nRight>determine the coordinates of the screen segment saved.
<nLeft>
<nLeft> is an integer numeric value which determines the left screen column for the area saved.
<nBottom>
<nBottom> is an integer numeric value which determines the bottom screen row for the area saved. If the value for <nBottom> exceeds the maximum visible row number, it is reset to MaxRow().
<nRight>
<nRight> is an integer numeric value which determines the right screen column for the area saved. If the value for <nRight> exceeds the maximum visible column number, it is reset to MaxCol().
Return

SaveScreen() returns the specified screen segment as a character string. The character string contains the visible characters within the screen segment along with the accompanying color attributes. The function only saves character based, not graphic, elements on the screen.

Description

The screen function SaveScreen() saves the visible characters in a screen segment along with their color attributes in a character string. Graphic elements are not saved. The visible characters on the screen are found as the odd numbered characters in the character string. The accompanying color attributes are in the respective even numbered positions. A saved screen segment can be redisplayed with the function RestScreen(). If no coordinates are specified, the entire screen area (0, 0 to MaxRow(), MaxCol()) is saved. This is identical to the command SAVE SCREEN.

Examples
SaveScreen()
// The example shows the common use of the two functions 
// SaveScreen() and RestScreen(). Before output on the 
// screen a screen segment is saved and after output it 
// is restored again. 

PROCEDURE Main 
   LOCAL cScreen 

   cScreen := SaveScreen( 7,10,17,60 )  // save screen 

   DispBox( 7,10,17,60 )                // output box 
   @ Row(), Col() SAY "Press any key..." 
   Inkey(0)                             // wait 

   RestScreen( 7,10,17,60, cScreen )    // restore screen 

RETURN 
Screen output with SaveScreen() and RestScreen()
// The example shows how screen output can be attained 
// using only RestScreen(). Note color change by 
// exchange of color attributes. 

PROCEDURE Main 
   LOCAL cScreen, n, cNewScreen 

   CLS 
   ?? "Hello World" 

   cScreen := SaveScreen( 0,0,0,10 )    // save screen 
   Inkey(0)                             // wait 

   RestScreen(10,0,10,10,cScreen)       // output to row 10 
   Inkey(0)                             // wait 

   cNewScreen := "" 
   FOR n:=1 TO Len(cScreen) STEP 2      // exchange color attributes 
      cNewScreen += SubStr(cScreen,n,1)+"O" 
   NEXT                                 // "O" corresponds to "W+/R" 

   RestScreen(20,0,20,10,cNewScreen)    // output to row 20 
                                        // with new color 
RETURN 

Shifts box interactively on the screen
// This example shows how a box is shifted on the 
// screen using the cursor keys. 

 #include "Inkey.ch" 

 PROCEDURE Main 
    LOCAL nTop:=7, nLeft:=10, nBottom:=17 , nRight:=60, ; 
          cScreen, nKey 
                                   // save background 
    cScreen := SaveScreen( nTop, nLeft, nBottom, nRight ) 
    nKey    := 0 

    DO WHILE nKey <> K_ESC         // display foreground 
       DispBox( nTop, nLeft, nBottom, nRight, 2, "W+/R" ) 
       nKey := Inkey(0) 

       DO CASE 
       CASE nKey == K_UP 
          IF nTop > 0              // restore old background 
             RestScreen( nTop, nLeft, nBottom, nRight, cScreen ) 
             nTop-- ; nBottom--    // save new background 
             cScreen := SaveScreen( nTop, nLeft, nBottom, nRight ) 
          ENDIF 

       CASE nKey == K_LEFT 
          IF nLeft > 0 
             RestScreen( nTop, nLeft, nBottom, nRight, cScreen ) 
             nLeft-- ; nRight-- 
             cScreen := SaveScreen( nTop, nLeft, nBottom, nRight ) 
          ENDIF 

       CASE nKey == K_DOWN 
          IF nBottom < MaxRow() 
             RestScreen( nTop, nLeft, nBottom, nRight, cScreen ) 
             nTop++ ; nBottom++ 
             cScreen := SaveScreen( nTop, nLeft, nBottom, nRight ) 
          ENDIF 

       CASE nKey == K_RIGHT 
          IF nRight < MaxCol() 
             RestScreen( nTop, nLeft, nBottom, nRight, cScreen ) 
             nLeft++ ; nRight++ 
             cScreen := SaveScreen( nTop, nLeft, nBottom, nRight ) 
          ENDIF 
       ENDCASE 

    ENDDO 

RETURN 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.