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

  Name:     setscreen() - set screen output to virtual pages
  Usage:    setscreen([<screen>])   or:
            setscreen([<seg>,<off>]) or:
            setscreen(<row>,<col>,<row2>,<col2>,<screen>) or:
            setscreen()

  Params:   Method 1:

            string <screen> - a full screen memory variable created by
            savescreen() or initscreen(). All video output will then
            go to the screen variable as if it were a normal video
            buffer. This variable must be a full size screen variable.

            Method 2:

            integer <seg> - video buffer segment address in decimal
            integer <off> - video buffer offset address in decimal

            Method 3:

            integer <row>  - the starting row of the initscreen()
            integer <col>  - the starting column of the initscreen()
            integer <row2> - the ending row of the initscreen()
            integer <col2> - the ending column of the initscreen()
            string <screen>- the screen variable that was returned
            by initscreen - it must be the same size as defined
            by the <row>/<col> coordinates.

            When using method 3, the virtual page can be smaller than
            a full screen. This lets you create unlimited virtual
            windows to be popped up with restscreen(). When using
            this method, all video coordinates are resized to
            the coordinates passed in the <row>, <col> parameters
            You must make sure that any coordinates you use for
            @ ... say, @ ... box, print(), box(), scroll() etc. are
            within the size of the screen variable you sent to
            setscreen(). Also, the max row and max col values
            are all adjusted to reflect the size of the virtual
            window, therefore, a screen set to row 10 col 10, row
            20 col 50 contains 11 rows and 51 columns. They can
            be accessed by row numbers 0-10 and column numbers
            0-50 where row 0 col 0 is the upper left hand corner
            of the virtual screen. Do not print to the virtual
            window as if it were a full screen. your row and
            col coordinates are calculated off the starting
            row and column numbers as if they were at row 0 col 0.

            To set the screen back to normal:

            If no parameters are sent, then all the video buffers
            are pointed back to the video page that is
            currently being displayed.

  Returns:  nothing

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

                 tempscrn = initscreen()
                 * initialize a full screen variable

                 csroff()
                 no cursor while writing to a virtual page

                 setscreen(tempscrn)
                 * all screen output goes to tempscrn variable

                 box(10,10,20,50,"",23)
                 @ 11,11 say "this is in the virtual screen"
                 scroll(21,0,24,79,0,23)
                 * all this output went to the virtual screen
                 * and was not displayed on the page being viewed

                 setscreen()
                 * return all video buffers to the screen being
                 * being displayed

                 restscreen(tempscrn)
                 * display the virtual buffer

                 * or if the screen initialized was full screen
                 * you can restore a portion of the virtual
                 * screen as if there was a window to it
                 * use the savescreen() from a saved screen trick:
                 tempscrn2 = savescreen(10,10,20,60,tempscrn)
                 restscreen(10,10,20,60,tempscrn2)

  Example 2:     This example uses buffer addresses to
                 to point all video output to a video
                 page that is not being displayed.

                 setpage(0)
                 * page zero now being displayed

                 csroff()
                 * cursor off while we write to a different page

                 * setup up the address of the video buffer
                 * for page 1 (see table)
                 colorseg = 47104
                 coloroff = 4096 (page 1)

                 * set all video output to the 1st page
                 setscreen(colorseg,coloroff)

                 @ 10,0 say "This is being printed on page 1"
                 @ 12,10,20,60 box "******** "
                 * print some text and a box into page 1

                 setscreen()
                 * reset all video output to the page currently
                 * being displayed

                 setpage(1)
                 * set the display page to the page that was
                 * written to in the background (page 1).

  Example 3:     This example uses buffer addresses to write
                 text to the monochrome monitor while leaving
                 the color monitor untouched. This is if you
                 have dual monitors attached to your system.

                 csroff()
                 * cursor off while we write to a different
                 * video buffer

                 * setup up the address of the monochrome
                 * video buffer (see table)
                 monoseg = 45056
                 monooff = 0

                 * set all video output to monochrome buffer
                 setscreen(monoseg,monooff)

                 @ 10,0 say "Printed on the monochrome screen"
                 @ 12,10,20,60 box "******** "
                 * print some text and a box into buffer, output
                 * appears on the monochrome screen

                 setscreen()
                 * reset all video output to the page currently
                 * being displayed on the 'active' monitor

                 You can also use this technique to write to the
                 color monitor if the monochrome monitor is the
                 active monitor

  Example 4:     This example initializes a screen variable that
                 is smaller than the full screen, thereby creating
                 a virtual window.

                 tempscrn = initscreen(10,10,20,50)
                 * initialize a partial screen variable

                 csroff()
                 no cursor while writing to a virtual window

                 setscreen(10,10,20,50,tempscrn)
                 * set screen output to the virtual window.
                 * use the exact same coordinates that the
                 * window was declared with

                 set color to W/B
                 cls()
                 * clear the virtual window to blue

                 box(0,0,maxrow(),maxcol(),"")
                 * draw a box around the entire window

                 @ 0,11 say "This Is In The Virtual Window"
                 * put a title on the window

                 * all this output went to the virtual window
                 * and was not displayed on the page being viewed

                 setscreen()
                 * return all video buffers to the screen being
                 * being displayed

                 restscreen(10,10,20,50,tempscrn)
                 * display the virtual window at the same
                 * coordinates it was initialized in

  Table:    The following buffer address are defined for the
            various modes and monitors when using method 2:

                 Segment             - Address
                 Color segment       = 47104 (B800h)
                 Mono segment        = 45056 (B000h)

            Video segments are always the same for alphanumeric
            modes.

            Page Offsets:

            Offsets into the various pages vary depending upon
            the screen mode currently in use.

            For 80x25 column mode use the following offset values:

            For CGA/EGA/VGA

                 Page - Address
                 0    - 0
                 1    - 4096
                 2    - 8192
                 3    - 12288

            For EGA/VGA

                 Page - Address
                 4    - 16384
                 5    - 20480
                 6    - 24576
                 7    - 28762

            For 80x43 column mode use the following offset values:

            For EGA/VGA only

                 Page - Address
                 0    - 0
                 1    - 7136
                 2    - 14272
                 3    - 28544

            For 40x25 column mode use the following offset values:

            For CGA/EGA/VGA

                 Page - Address
                 0    - 0
                 1    - 2048
                 2    - 4096
                 3    - 6144
                 4    - 8192
                 5    - 10240
                 6    - 12288
                 7    - 14336

            Monochrome is always segment = 45056, offset = 0
            no additional pages are available on an MDA. You
            can use virtual screens created with initscreen()
            and setscreen().

            If you plan to use any of the extended modes such
            as 43 line, 50 line, 120 col or 132 col, refer
            to your adaptors documentation on the number of
            pages allowed in the mode you want to work in. Some
            manuals may specify the video segment/offset address in
            hexadecimal. You can use the function hex2dec() to
            convert the hex number into an integer for use by
            setscreen().

            If you do not know how many pages the particular
            mode has, you can try and set the video page
            using setpage(), and try to write something there.
            If nothing appears, then the page number is not
            supported. If you cannot find the video page buffer's
            address, you can use an internal FUNCky function to
            get the offset part of the address. This function is
            called __getVoff(). It will return the offset address
            of the page currently being displayed.

            The way to get the buffers address is as follows:

            The segment portion of the address is always 47104 (B800h)
            for color and 45056 (B000h) for mono. The offset portion of
            the address varies upon the size of the screen. However, the
            first page of any video mode is always 0. It's the rest of the
            pages that vary. To get the offset address of a page, set the
            mode you want, then use setpage() to display the page you
            need the address of, then use __getVoff() to get the offset
            address. __getVoff() returns an integer equal to the offset
            address of the video page being displayed in decimal.

  Hint:     Since you can use setscreen() to point at different buffers in
            memory. And since all video output routines will work in the
            new buffer, you can use combinations of setscreen() to
            transfer information from one buffer to another using
            savescreen(), restscreen() and readscreen(). The possibilities
            for video buffer manipulation are tremendous. For example,
            the following settings produce interesting possibilities:

                 tempwin = savescreen(10,10,20,40)
                 * save a window off the currently displayed
                 * video page

                 tempscrn = initscreen()
                 * initialize a full screen variable

                 setscreen(tempscrn)
                 * point all video at it

                 restscreen(10,10,20,40,tempwin)
                 * restore the window saved into the
                 * VIRTUAL SCREEN

                 * setscreen()
                 * set all video output back to normal

                 restscreen(tempscrn)
                 * restore the virtual page to the video
                 * page currently being displayed. It also
                 * contains the window saved in the first
                 * savescreen()!!

            All this redirection can create for spectacular video
            manipulations. And since you can use savescreen() to restore
            portions of a screen variable, You can produce all kinds of
            slick effects like wipes instead of the usual popup stuff.

            Since setscreen() only manipulates the video buffer, bizarre
            windowing() functions are not necessary since all the normal
            Clipper video routines work in the buffer you create and set
            with setscreen(). This makes for easy coding using the video
            functions you already know how to use. Be aware however
            that the cursor is still updated on the video page being
            displayed. Whenever you write to a virtual page or window,
            you should turn the cursor off. Turn it back on when your
            ready to go back to the real video page being displayed.

  Warning!: When using the setscreen() function, it is your responsibility
            to ensure that the address you point all video output to is
            indeed a true video page, or a virtual screen buffer that is
            exactly equal to the size of the current displayed page, or
            correctly sized by the 4 row/col coordinates. If you point the
            video routines to a location in memory other than those
            appropriate for video output, you are sure to crash your
            system, often with spectacular results. Also, since all video
            output works within virtual screens, you can also do GETS
            and a READ into the virtual screen. However, the user will
            not see the text being typed into the get ...could be confusing.

            Since you can only initialize screens that are equal to or
            smaller than the actual size of the video screen, do not try to
            setscreen to a virtual window that is larger than the real
            video screen. That is not permitted and can cause system
            crashes since the video routines will be writing to memory
            that doesn't belong to them.