Introduction

     It is hard to imagine using CA-Clipper without using windows.  Windows
     are the best way to show multiple tasks so you can get a genuine
     overview of the system operation.  The functions in this chapter offer a
     particularly valuable extension to CA-Clipper in this area.

 The Window System

     If you are only working with one screen, the CA-Clipper Tools functions
     permit up to 255 windows, depending on available memory.  In conjunction
     with the MONISWITCH() function from the Video Function chapter,
     CA-Clipper Tools can even support two screens linked to a single CPU,
     with one monochrome screen and one color screen.  In this way two
     entirely independent window systems, each with 255 windows, are
     available.

     The window functions take into account the fact that CA-Clipper Tools
     supports larger screens than the common 25 rows x 80 columns.  A screen,
     and therefore also a window, can be up to 255 rows or 255 columns in
     size.  However, the complete contents of a screen can never require more
     than 32 KB of memory.  So with 255 rows, no more than 128 columns are
     possible.

 Moving Interactively

     As soon as SCROLL LOCK is activated, the active window can be moved with
     different cursor keys.  Depending on how you open them, windows can even
     overlap.  The gray Plus key in the numeric key pad works like the
     function WCENTER().  You use the Plus key to move a partially visible
     window  back into a completely visible area.  All window movements done
     after you activate SCROLL LOCK can be undone using the ESC key.

 Programming with Window Functions

     .  Each window is assigned a number between 1 and 255 when it is
        opened.  This number is known as the window handle.  Handle 0 is the
        original screen, with no open windows.  The window handle returned
        will be used to refer to that window during programming.  (For
        example, you need the window handle when you select a background
        window.)

        WMODE(.T., .T., .T., .T.)         // Overlap permitted

        nWindow1 := WOPEN(....)
        nWindow2 := WOPEN(....)           // This is the active window

        WSELECT(nWindow1)                 // Activate first window

     .  The coordinates used for screen output are relative only to
        the selected window, and not the entire screen.

        nWindow1 := WOPEN(....)           // Selected window

        @ 02, 02 SAY  "CA-Clipper Tools"

     .  Since a window behaves exactly as the normal screen would,
        QOUT() style output (?, ??, etc.) will be scrolled up as soon as it
        reaches the bottom row.

     .  The window in the following example, which extends to row 24,
        will not overwrite the help message on row 25:

        @ 24, 00 SAY "........ HELP-ROW........"
        nWindow1 := WOPEN(0, 0, 23, 79)   // Protects the last row
        FOR nI = 1 TO 100
           ? "CA-Clipper Tools ...."
        NEXT nI

     .  A window displays as a full value, but is a virtual screen,
        which differs from the original physical screen only in size.
        Extended drivers make the MAXROW() and MAXCOL() functions available
        in a version enhanced over and above CA-Clipper  to accommodate the
        changed size.  Now the coordinates of virtual screens can also be
        determined; these functions return the last row or column concerned
        with the currently selected window:

        nWindow1 := WOPEN(10, 10, 20, 60)

        ? MAXROW()                        // Row:     10
        ? MAXCOL()                        // Column: 50

     .  The underlying screen area is saved automatically when a new
        window is opened.  This applies equally to any area of the screen
        that becomes overlapped by the movement of a window.  At the same
        time, all settings in the areas that have been overwritten are saved.
        These settings include cursor shape and position, as well as color
        attributes.  So you do not have to save anything out of the affected
        screen area; CA-Clipper Tools takes over this task automatically.

     .  The following example shows you how the window functions save
        both the color and cursor setting:

        SET COLOR TO R                      // Set color RED
        ? "Test-Text 1 ..."                 // Output in RED
        nWindow1 := WOPEN(10, 10, 20, 55)
        WBOX()                              // RED window border
           SET COLOR TO BG                  // Set color CYAN
           ? "Test-Text 2 ..."              // Output in CYAN
           INKEY(0)                         // Wait for keystroke
        WFCLOSE()                           // Close window again

        ? "Test-Text 3 ..."                 // Output again in RED
                                            // and directly below "Text 1"

 Active Windows

     After you close a window, the active window with the highest handle is
     the one selected, not the window that was previously active.  If, for
     example, the highest window handle is 9 and window 5 was just selected,
     a newly opened window is assigned handle 10.  However, after you close
     this window number 10, window 9 is selected.  It is therefore important
     to save the window's handle to a variable when you open it, so that you
     can select the required window later.

     You can save the active window handle by calling WSELECT() with no
     parameters.

     .  The external output of programs called with RUN within a
        CA-Clipper program can be tied to windows:

        DSETWINDOW(.T.)
        nWindow1 := WOPEN(10, 10, 22, 70)
        RUN DIR                     // Display results in window

     The only prerequisite is that such output is through DOS or BIOS.  The
     DSETWINDOW() function controls whether or not this output is
     subsequently redirected.  The Extended Driver chapter has more details.

     In addition to the examples shown here there are many more window
     functions available for use that contribute to a comprehensive windows
     system.