/*------------------------ 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. 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. 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 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. 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.