/*------------------------ VIS_WIND.TXT ------------------------*/
/*                                                              */
/*  This file contains the VISIONS Window Library Manual        */
/*                                                              */
/*         Copyright 1990 Dan Vogel & David Bernazzani          */
/*                                                              */
/*   Date        Initials        Comments                       */
/*                                                              */
/*  03/13/90       DCV       Initial Release 0.00.              */
/*--------------------------------------------------------------*/

                        Overview


   The VISIONS window library is a simple library, written in C, to 
provide color or monochrome text windows on PC/XT/AT class machines.  The 
library was originally written in Microsoft C 5.1, but an attempt to 
separate compiler specific code into a separate source was made, and 
this file, COMPSPEC.C, is provided with the library source.
   The window library supports the following functions:


     MGA, CGA, EGA, VGA, MCGA compatible color text windows.
     Automatic color conversion for monochrome adaptors.
     User selectable window colors and sizes.
     Optional window borders and border type.
     Pop-Up windows.
     Exploding and Imploding windows.
     Error windows.
     Pagable file display windows.




                        Theory of Operation


   The following is an overview of the operation of the window 
library routines.  This is intended to help the user to understand 
the library's operation better, so that it may be used more effectively.
   The VISIONS window system is intended to execute structures which 
define windows.  These structures consist of headers which define 
window coordinates, colors, and attributes.  Each structure is created 
by a single call to a define windows routine.  Note that a window may not 
be defined until the windows package is initialized by a call to 
InitWindows.  Once a window has been defined it can be executed at any time.  
Execution of a window causes the window to be displayed upon the screen in 
the defined location.  Several attributes may affect the way in which a 
window is displayed.  A pop up window saves the screen data underneath itself 
prior to display, so that the previous screen may be restored when the window 
is removed.  An exploded window 'explodes' outward from its defined center.  
A window may also have a title and a border.  Once the window is executed, 
it is displayed on the screen with appropriate colors, borders, and titles, 
but the rest of the contents of the window will be blank.  This may be filled 
in using other window routines provided, such as WindMesgPtr.  
   Removing a window from the display is accomplished by the RemoveWindow 
routine.  This routine determines the correct way to remove a window 
depending upon its attributes, such as implode and pop-up.  The window 
definition structure is still active at this point and the window could be 
executed again, but the contents of the window prior to removal are lost.  
Finally the window definition structure is freed by the routine DeleteWindow.

   In brief, to use the VISIONS window library to execute a window, up to 
seven steps must be taken:
        1) Initialize windows once.            - InitWindow.
        2) Define the window structure.        - DefineWindow.
        3) Display the window.                 - DisplayWindow.
        4) Display items within the window.    - SetWindow, SetWindowPtr, 
                                                 WindMesg, WindMesgPtr.
        5) Remove the window from the screen.  - RemoveWindow.
        6) Release the window storage.         - DeleteWindow.
        7) Exit windows once.                  - ExitWindow.

   Two windows may be created without any of these steps.  The routines, 
ErrWindow and HelpWindow may be used to display a single line error message 
and to display the contents of a file to a window respectively.  These two 
routines create, display, and remove a window without any further routine 
calls.





                        Routine Definitions

   In order to use the below routines you must include the file 
"USERWIND.H" in your source code with the following statement.

                #include "USERWIND.H"

Examples of the use of these routines are available in the VISIONS 
demonstration program, in the file DEMOWIND.C.



/*------------------------------------------------------------------------*/
                        DefineWindow

Purpose:  This routines creates a new window structure, complete with color, 
  border, and position definitions.

Calling Sequence: 
   status = DefineWindow(new_wind,topy,leftx,height,width,bkcol,txtcol,
        title, border, explode, implode, popup);

Inputs:
   BYTE topy, leftx, height, width;  - Respective row, col, height and width 
        coordinates.  The height parameter is the # of rows to make the 
        window down and the width is the # of cols to make the window wide.  
        The row and col values specify the top left corner of the help
        window created.

   long int bkcol, txtcol;  - These are the background and text colors to 
        be used for the help window.  Possible values include TEXT_BLUE, 
        TEXT_BLACK, and others specified in InitWindow.

   char *title;  - This is the title of the window created.  This title can 
        be NULL, the empty string, or a string shorter than the window is 
        wide.

   BYTE border;  - This is the type of border desired for the menu.  
        Possibilities are NOBORDER, SINGLEBORDER, and DOUBLEBORDER.

   BYTE explode, implode, popup;  - These are TRUE/FALSE options for window 
        display.  The options are for the window to explode outward, implode 
        inward on closing, and whether or not to popup (save underlying 
        screen).

Outputs:
   WINDOW_HEAD **new_wind;  - This is a pointer to the window structure 
        created describing the window.

   int status;  - This is the result of the function.  Possible values are:
        0                         Success
        OUT_OF_WINDOW_HEAP        Out of heap for allocating window.
        BAD_WINDOW_DEF            Bad coordinates passed for window.
        <others>                  As returned by called functions.

Functions called:
   SaveWindow.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        DeleteWindow

Purpose:  This routine releases all memory attached to the window structure.

Calling Sequence: 
   status = DeleteWindow(window_ptr);

Inputs:
   WINDOW_HEAD *window_ptr;  - This is a pointer to the window structure 
        describing the window to be deleted.

Outputs:
   int status; - This is the result of the function.  Possible values are:
        0                       Success
        NOT_A_WINDOW_POINTER    Bad pointer passed, not a window structure.

Functions called:
   free.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        DisplayWindow

Purpose:    This routine displays the window described in the passed 
 structure.

Calling Sequence: 
   status = DisplayWindow(window_ptr);

Inputs:
   WINDOW_HEAD *window_ptr;  - This is a pointer to the window structure 
        describing the window to be displayed.

Outputs:
   int status;  - This is the result of the call.  Possible values are:
        0                       Success.
        NOT_A_WINDOW_POINTER    Bad pointer passed, not a window structure.
        <Others>                As returned by called routines.

Functions called:
   ExplodeWindow,  Window,  SaveWindow.

/*------------------------------------------------------------------------*/



/*------------------------------------------------------------------------*/
                        ErrWindow

Purpose:  This routine displays a window centered in the screen with 
 the passed message displayed.  Background is always set to red with 
 white text.

Calling Sequence: 
   status = ErrWindow(msg);

Inputs:
   char *msg;  - This is the message stirng to be displayed.

Outputs:
   int status; - This is the result of the function.  Possible values are:
        0               Success
        <others>        As returned by called functions.

Functions called:
   DefineWindow,  DisplayWindow,  WindMesg,  RemoveWindow,  DeleteWindow
   GetKey.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        ExitWindow

Purpose:   This routine restores wrapon, and the cursor, and the default
 video setup.  All windows should be popped before this call.

Calling Sequence: 
   ExitWindow();

Inputs:
   None.

Outputs:
   None.

Functions called:
   WrapOn,  hidecursor,  SetVideoMode.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        HelpWindow

Purpose: This routine displays the passed files name in window sized 
 chunks as a help screen.  Note that this routine can be used for 
 generalized file display!

Calling Sequence: 
   status = HelpWindow(row, col, height, width, 
        bkcol, txtcol, border, title, filename);

Inputs:
   BYTE row, col, height, width;  - Respective row, col, height and width 
        coordinates.  The height parameter is the # of rows to make the 
        window down and the width is the # of cols to make the window wide.  
        The row and col values specify the top left corner of the help
        window created.

   long int bkcol, txtcol;  - These are the background and text colors to 
        be used for the help window.  Possible values include TEXT_BLUE, 
        TEXT_BLACK, and others specified in InitWindow.

   BYTE border; - This is the type of border to be drawn around the window.
        Possible values are: NOBORDER, SINGLEBORDER, DOUBLEBORDER.

   char *title;  - This is the string to be used for the title of the 
        window.  The null string, NULL, means no title to be displayed.

   char *filename;  - This is the name of the text file to be displayed
        in the window created.

Outputs:
   int status;  - This is the result of the call.  Possible values are:
        0                               Success
        UNABLE_TO_OPEN_HELPFILE         File Error.
        HELP_WINDOW_TOO_SMALL           Window to small for display.
        <others>                        As returned by called functions.

Functions called:
   RemoveWindow,  DeleteWindow,  GetKey,  WindMesg,  DefineWindow,  
   DisplayWindow.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        InitWindow

Purpose:   This routine sets up the video segments that window routines
 need to access the screen.  The video mode is also set and the cursor is 
 turned off.  Colors used for all windows are defined at this point.  Call 
 this routine before using the other window routines.

Calling Sequence: 
        InitWindow();

Inputs:
   None.

Outputs:
   The color variables below are defined for color or monochrome operation.
 The definitions are:
       Color Variable       Color Value         Monochrome value

        TEXT_BLACK         INIT_TEXT_BLACK      INIT_TEXT_BLACK
        TEXT_BLUE          INIT_TEXT_BLUE       INIT_TEXT_BLACK
        TEXT_GREEN         INIT_TEXT_GREEN      INIT_TEXT_BLACK
        TEXT_CYAN          INIT_TEXT_CYAN       INIT_TEXT_BLACK
        TEXT_RED           INIT_TEXT_RED        INIT_TEXT_BLACK
        TEXT_MAGENTA       INIT_TEXT_MAGENTA    INIT_TEXT_BLACK
        TEXT_BROWN         INIT_TEXT_BROWN      INIT_TEXT_BLACK
        TEXT_WHITE         INIT_TEXT_WHITE      INIT_TEXT_WHITE
        TEXT_DGREY         INIT_TEXT_DGREY      INIT_TEXT_BLACK
        TEXT_LBLUE         INIT_TEXT_LBLUE      INIT_TEXT_WHITE
        TEXT_LGREEN        INIT_TEXT_LGREEN     INIT_TEXT_WHITE
        TEXT_LCYAN         INIT_TEXT_LCYAN      INIT_TEXT_WHITE
        TEXT_LRED          INIT_TEXT_LRED       INIT_TEXT_BWHITE
        TEXT_LMAGENTA      INIT_TEXT_LMAGENTA   INIT_TEXT_WHITE
        TEXT_YELLOW        INIT_TEXT_YELLOW     INIT_TEXT_WHITE
        TEXT_BWHITE        INIT_TEXT_BWHITE     INIT_TEXT_BWHITE

Functions called:
   WrapOn,  hidecursor,  SetVideoMode.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        RemoveWindow

Purpose:   This routine removes the passed window from the screen.  This 
 only has an effect if the window was a pop up window.

Calling Sequence: 
   status = RemoveWindow(window_ptr);

Inputs:
   WINDOW_HEAD *window_ptr;  - This is a pointer to the window structure 
        describing the window to be removed from the display.

Outputs:
   int status;  - This is the result of the call.  Possible values are:
        0                       Success
        NOT_A_WINDOW_POINTER    Bad pointer passed, not a window structure.

Functions called:
   ImplodeWindow.

/*------------------------------------------------------------------------*/



/*------------------------------------------------------------------------*/
                        SetWindow

Purpose:   This routine defines the window to be in use and sets up the 
 color definitions.  This is mainly used for jumping between 
 non-popup windows.

Calling Sequence: 
   SetWindow(row, col, height, width, bkcol, txtcol);

Inputs:
   BYTE row, col, height, width;  - Respective row, col, height and width 
        coordinates.  The height parameter is the # of rows to make the 
        window down and the width is the # of cols to make the window wide.  
        The row and col values specify the top left corner of the help
        window created.

   long int bkcol, txtcol;  - These are the background and text colors to 
        be used for the help window.  Possible values include TEXT_BLUE, 
        TEXT_BLACK, and others specified in InitWindow.

Outputs:
   None.

Functions called:
   SetTextWindow,  SetBkColor,  SetTextColor.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        SetWindowPtr

Purpose:   This routine defines the window to be in use and sets up the 
 color definitions.  This is mainly used for jumping between 
 non-popup windows.

Calling Sequence: 
   status = SetWindowPtr(window_ptr);

Inputs:
   WINDOW_HEAD *window_ptr;  - This is a pointer to the window structure 
        describing the window desired.

Outputs:
   int status;  - This is the result of the call.  Possible values are:
        0                        Success
        NOT_A_WINDOW_POINTER     Bad pointer passed, not a window structure.

Functions called:
   SetWindow.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        WindMesg

Purpose:   This routine displays a text string at a specific point on the 
   current window.

Calling Sequence: 
   WindMesg(row, col, message);

Inputs:
   BYTE row, col;  - Respective row, and column where message is to be 
        displayed.

   char *message;  - This is the text string to display.

Outputs:
   None.

Functions called:
   SetTextPosition,  OutText.

/*------------------------------------------------------------------------*/




/*------------------------------------------------------------------------*/
                        WindMesgPtr

Purpose:   This routine displays a text string at a specific point in the 
   specified window.

Calling Sequence: 
   WindMesgPtr(window_ptr,row, col, message);

Inputs:
   WINDOW_HEAD *window_ptr;  - Pointer to window structure to be 
        made current.
   BYTE row, col;  - Respective row, and column where message is to be 
        displayed.
   char *message;  - This is the text string to display.

Outputs:
   None.

Functions called:
   SetWindowPtr,  WindMsg.

/*------------------------------------------------------------------------*/




                        Error Codes

   The following is the list of error codes that can be returned from the 
VISIONS window library.

Error Name              Value       Description.

UNABLE_TO_OPEN_HELPFILE -201        File opening error.
HELP_WINDOW_TOO_SMALL   -202        Display window too small!
OUT_OF_WINDOW_HEAP      -203        Out of heap for pop up storage.
NOT_A_WINDOW_POINTER    -204        Bad window structure pointer.
BAD_WINDOW_DEF          -205        Size of window exceeds screen.
                    