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

  Name:     initscreen() - initialize a virtual screen in memory
  Usage:    <string> = initscreen([<r1>,<c1>,<r2>,<c2>],[<attrib>])
  Params:   integer <r1> - the top row to start at
            integer <c1> - the left column to start at
            integer <r2> - the bottom row to end at
            integer <c3> - the right column to end at
            integer <attrib> - the color to initialize the screen to,
            if left off then Clipper's current foreground color is
            used. This parameter is only available when all four
            row/col coordinates are passed.

            The parameters are optional. If all four are left off,
            then a screen equal to the size of the currently
            defined video screen is initialized. This size can change
            when setmode() or setscreen() is used. You must specify
            all four parameters, or none. If no parameters are sent,
            the attribute defaults to the current Clipper foreground
            color. The attribute cannot be passed if no row/col
            coordinates are passed.

  Returns:  a string variable that is equal in length to the number
            of rows times the number of columns.

 ---------------------------------- Example ---------------------------------

            This example initializes a full screen variable called
            tempscrn in Clipper's current foreground color:

                 tempscrn = initscreen()

            This example initializes a smaller virtual 'window' in
            the color white on blue:

                 tempscrn = initscreen(10,10,20,50,23)

            This example initializes a screen, then uses setscreen to write
            into that screen using standard Clipper and FUNCky video
            routines.

                 tempscrn = initscreen()
                 setscreen(tempscrn)
                 * video output now goes into tempscrn

                 csroff()
                 * no cursor while writing to virtual screens

                 @ 0,0 say "this is in the virtual screen!"
                 box(10,10,20,50,"",33,1,8)

                 csron()
                 * cursor back on

                 setscreen()
                 * restore video output to the real video screen

                 restscreen(tempscrn)
                 * display the virtual screen

            You can also initialize virtual windows that are
            smaller than the size of the real video screen, as in
            this example:

                 tempscrn = initscreen(10,10,20,50,23)
                 * initialize a white on blue window

                 csroff()
                 * no cursor when writing to virtual windows

                 setscreen(10,10,20,50,tempscrn)
                 * pass the virtual window to setscreen along with
                 * the exact coordinates of the window. setscreen()
                 * will calculate the maxrow() and maxcol() values
                 * and will inform Clipper of the new size screen.
                 * The upper left hand column can be accessed
                 * as row 0, col 0, the maxrow is 10, and the
                 * maxcol is 50. Total is 11 rows by 51 columns

                 box(0,0,11,50,"",33)
                 * draws a box around the virtual window

                 @ 5,10 say "This is on row 5 col 10 in the window!"

                 csron()   && cursor back on

                 setscreen()
                 * setscreen() with no params returns all video

                 * output to the real screen

                 restscreen(10,10,20,50,tempscrn)
                 * display the virtual screen

  Note:     The maximum screen size you can initialize can only be as
            large as the currently defined screen size. Therefore, if your
            monitor is in 43 line by 80 column mode you can only
            initialize a screen to be no more than 43 rows by 80 columns.
            Likewise, if your monitor is in 80 column by 25 line mode
            the maximum screen you can initialize is 80 columns by 25
            rows. When writing to virtual windows that are smaller than
            the actual screen size, be careful when calculating the
            maximum row and column boundaries of the virtual window.
            If you miscalculate you will most likely overwrite data that
            belongs to another procedure or memory variable. You must
            be sure that the text you are writing into the virtual window is
            contained within that window.