Click above to get retro games delivered to your door ever month!

 RESTBOX() 

          Possibly one of the most flexible functions in PROCLIP2, the
          RESTBOX function is the companion to SAVEBOX.  Once a section of
          the screen has been placed into a memory variable by SAVEBOX, the
          RESTBOX function may be used to restore it.

          RESTBOX "knows" where the screen portion originally came from, so
          remembering the coordinates is no longer a necessity.  It is
          possible, however, to override those original coordinates and
          reposition the screen portion anywhere on the screen.  You may also
          use either the original colors, as it was saved, or override them
          with a new color attribute.

          Through creative use of SAVEBOX, RESTBOX and the standard Clipper
          BOX command an impressive control of the screen may be obtained.

          RESTBOX is not compatible with memory variables saved by the
          Clipper SAVESCREEN function.


      Format: 

               restbox([top, left,] scrnarea [,attr][,type])


      Parameters: 

               top.... OPTIONAL. Numeric variable or constant indicating
                         the top row of where the SAVEBOX'd area is to be
                         restored.  Value checked to be between 0 and 24
                         inclusive.  If TOP is specified then LEFT must also
                         be specified.  If TOP,LEFT is not specified RESTBOX
                         will obtain the original position from within the
                         SAVEBOX'd variable.

               left... OPTIONAL. Numeric variable or constant indicating
                         the left column of where the SAVEBOX'd area is to be
                         restored.  Value checked to be between 0 and 79
                         inclusive.  If LEFT is specified then TOP must also
                         be specified.

               scrnarea..Character string variable containing a saved portion
                         of the screen which was saved with SAVEBOX.  No
                         changes to this memory variable should have occurred
                         between the SAVEBOX command and RESTBOX.  Cannot be
                         a memory variable saved by the Clipper SAVESCREEN
                         function.

               attr...  OPTIONAL . Character string variable or constant,
                         non case sensitive, which contains a valid color
                         combination for character and background.  This
                         color attribute will be used during the restore to
                         the screen but the original image as saved by
                         SAVEBOX will not be modified.  Must be the alpha
                         representation of the color, the numeric will be
                         rejected.

                                  (valid colors)
                          black                          N
                          blue                           B
                          green                          G
                          cyan                           BG
                          red                            R
                          magenta                        RB
                          brown                          GR
                          white                          W
                          intense                        +
                          blink                          *

              type... OPTIONAL. Logical variable or constant instructing
                         the function to use DMA updating or not.  As this is
                         an optional parameter the function will assume you
                         wish IBM standard BIOS INT 10H updating.

                         .T.            DEFAULT.  If not specified, the
                                        function will use DMA screen
                                        updating.

                         .F.            Setting this flag to a logical false
                                        will cause the function to use the
                                        standard BIOS INT 10H for screen
                                        updating.


      Examples: 

               1.   This will restore a previously saved screen area to the
                    original location but use a different color attribute.

                    .
                    .
                    .
                    restbox(scrn1,'+r/n')
                    .
                    .
                    .

               2.   This will restore a previously saved screen area to row
                    #10, column #20 even if this is a different location than
                    it was originally obtained from.

                    .
                    .
                    .
                    restbox(10,20,scrn1)
                    .
                    .
                    .

               3.   A typical SAVEBOX and RESTBOX combination.

                    .
                    .
                    .
                    scrn1 = savebox(10,20,12,60)
                    .
                    .
                    .
                    restbox(scrn1)
                    .
                    .
                    .


      Returns: 

               Nothing.


      Cautions: 

               None.