/*------------------------ 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. */ /* 07/24/90 DCV Release 1.2. */ /*--------------------------------------------------------------*/ 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. Pageable file display windows. EGA/VGA 43/50 line display mode. 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 Window_Init. 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 Window_MesgPtr. Removing a window from the display is accomplished by the Window_Remove 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. - Window_Init. 2) Define the window structure. - Window_Define. 3) Display the window. - Window_Display. 4) Display items within the window. - Window_Set, Window_SetPtr, Window_Mesg, Window_MesgPtr. 5) Remove the window from the screen. - Window_Remove. 6) Release the window storage. - Window_Delete. 7) Exit windows once. - Window_Exit. Two windows may be created without steps 2 through 7. The routines, Window_Err and Window_Help 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. With the release of Version 1.2 VISIONS, 43 and 50 line modes are supported for EGA and VGA adapters with appropriate displays. The routines added for this purpose are Window_ScreenWidth, Window_ScreenHeight, and Window_SetScreenRows. Window_SetScreenRows should be called before creating or displaying a window, menu, or form that will exceed the default 25 lines of the display! 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. If you are compiling a program written for VISIONS 1.0 and do not wish to modify the routine names in your source, add the following statement to provide name conversions. #include "WINDCONV.H" /*------------------------------------------------------------------------*/ Window_Define Purpose: This routines creates a new window structure, complete with color, border, and position definitions. Calling Sequence: status = Window_Define(new_wind,topy,leftx,height,width,bkcol,txtcol, title, options); Inputs: UBYTE 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 topy and leftx values specify the top left corner of the help window created. DWORD 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 Window_Init. TEXT *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. BITS options; - This is the set of bits defining different window options. Possible bit settings are: SINGLE_BORDER_BIT - Single line border. -No border is also DOUBLE_BORDER_BIT - Double line border. -possible by setting EXPLODE_BIT - Exploding window. -no bit. IMPLODE_BIT - Imploding window. POPUP_BIT - Popup window. Outputs: WINDOW_HEAD **new_wind; - This is a pointer to the window structure created describing the window. WORD status; - This is the result of the function. Possible values are: WINDOW_ERR_NO_ERR Success WINDOW_ERR_NO_HEAP Out of heap for allocating window. WINDOW_ERR_BAD_DEF Bad coordinates passed for window. As returned by called functions. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Delete Purpose: This routine releases all memory attached to the window structure. Calling Sequence: status = Window_Delete(window_ptr); Inputs: WINDOW_HEAD *window_ptr; - This is a pointer to the window structure describing the window to be deleted. Outputs: WORD status; - This is the result of the function. Possible values are: WINDOW_ERR_NO_ERR Success WINDOW_ERR_NOT_WPTR Bad pointer passed, not a window structure. Functions called: free. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Display Purpose: This routine displays the window described in the passed structure. Calling Sequence: status = Window_Display(window_ptr); Inputs: WINDOW_HEAD *window_ptr; - This is a pointer to the window structure describing the window to be displayed. Outputs: WORD status; - This is the result of the call. Possible values are: WINDOW_ERR_NO_ERR Success. WINDOW_ERR_NOT_WPTR Bad pointer passed, not a window structure. As returned by called routines. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_DrawBox Purpose: The routine draws a box around the specified coordinates in the current window. Calling Sequence: Window_DrawBox(topy, topx, height, width, border); Inputs: UBYTE topy, topx, height, width; - Box coordinates to draw. BITS border; - This is the type of border to draw, SINGLE_BORDER_BIT, DOUBLE_BORDER_BIT, or neither for no border. Outputs: None, screen display only. Functions called: Window_Mesg. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_DrawTitle Purpose: This routine draws a title in the at the coordinates specified in the current window. If a border value is passed, then a title box is drawn around the title, by adding a bottom border to below the title to connect to an existing border around the entire window. A null title will cause immediate return. A window that is not high enough to support the title and its box will have truncated output. The title is center-justified in its own box. Calling Sequence: Window_DrawTitle(topy, topx, height, width, border, title); Inputs: UBYTE topy, topx, height, width; - Window coordinates. BITS border; - This is the type of border to draw, SINGLE_BORDER_BIT, DOUBLE_BORDER_BIT, or neither for no border. TEXT *title; - This is the title to be displayed, or NULL, if no title is to be displayed. Outputs: None, screen display only. Functions called: Window_Mesg. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Err Purpose: This routine displays a window centered in the screen with the passed message displayed. Background is always set to red with white text. The user is forced to make a keystroke before return. Calling Sequence: status = Window_Err(msg); Inputs: TEXT *msg; - This is the message string to be displayed. Outputs: WORD status; - This is the result of the function. Possible values are: WINDOW_ERR_NO_ERR Success As returned by called functions. Functions called: Window_Define, Window_Display, Window_Mesg, Window_Remove, Window_Delete, Comp_GetAnyKey, Comp_GetKey, Comp_Kbhit. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Exit Purpose: This routine restores wrapon, and the cursor, and the default video setup. All windows should be popped before this call. Calling Sequence: Window_Exit(); Inputs: None. Outputs: None. Functions called: Comp_WrapOn, Comp_UnhideCursor, Comp_SetVideoMode, Comp_ClearScreen, Window_Set. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_GetDefine Purpose: This routine returns the settings for a window to the caller. Calling Sequence: status = Window_GetDefine(windptr, &topy, &leftx, &height, &width, &bkcol, &txtcol, &title, &options); Inputs: windptr - struct window_head * - This is the window whose parameters are desired. Outputs: UBYTE *topy, *height, *leftx, *width; - These are the screen coordinates for the window. BITS *options; - This is the set of bits defining the window options. Possible bit settings are: SINGLE_BORDER_BIT - Single line border. -No border is also DOUBLE_BORDER_BIT - Double line border. -possible by setting EXPLODE_BIT - Exploding window. -no bit. IMPLODE_BIT - Imploding window. POPUP_BIT - Popup window. DWORD *bkcol, *txtcol; - These are the colors used for the text and background display of the window. TEXT **title; - This is the pointer to the displayed title of the window. Outputs: WORD status; - This is the result of the function. Possible values are: WINDOW_ERR_NO_ERR Success. WINDOW_ERR_NOT_WPTR Bad pointer passed, not a window structure. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Help Purpose: This routine displays the passed file's contents in window sized chunks as a help screen. Note that this routine can be used for generalized file display! Calling Sequence: status = Window_Help(row, col, height, width, bkcol, txtcol, border, title, filename); Inputs: UBYTE 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. DWORD 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. UBYTE border; - This is the type of border to be drawn around the window. Possible values are: NOBORDER, SINGLEBORDER, DOUBLEBORDER. TEXT *title; - This is the string to be used for the title of the window. The null string, NULL, means no title to be displayed. TEXT *filename; - This is the name of the text file to be displayed in the window created. Outputs: WORD status; - This is the result of the call. Possible values are: WINDOW_ERR_NO_ERR Success WINDOW_ERR_HELP_WIND File Error. WINDOW_ERR_HELP_WIND Window to small for display. As returned by called functions. Functions called: Window_Remove, Window_Delete, Comp_GetKey, Window_Mesg, Window_Define, Window_Display. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Init 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. This routine also initializes the calibrated code loop delay service. This may incur a delay in this routine's execution of from 3 to 12 seconds. Calling Sequence: Window_Init(); 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: Comp_WrapOn, Comp_HideCursor, Comp_SetVideoMode, Comp_ClearScreen, Comp_GetVideoInfo, Comp_Interrupt86, VISIONS_Logo, User_Check, Comp_Delay, Window_Set. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Mesg Purpose: This routine displays a text string at a specific point on the current window. Calling Sequence: Window_Mesg(row, col, message); Inputs: UBYTE row, col; - Respective row, and column where message is to be displayed. TEXT *message; - This is the text string to display. Outputs: None. Functions called: Comp_SetTextPosition, Comp_OutText. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_MesgPtr Purpose: This routine displays a text string at a specific point in the specified window. Calling Sequence: Window_MesgPtr(window_ptr,row, col, message); Inputs: WINDOW_HEAD *window_ptr; - Pointer to window structure to be made current. UBYTE row, col; - Respective row, and column where message is to be displayed. TEXT *message; - This is the text string to display. Outputs: None. Functions called: Window_SetPtr, Window_Mesg. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_ModifyColors Purpose: This routine dynamically modifies the displayed color attributes of the passed window. The window must be displayed before calling this routine. The stored attributes within the window itself are not modified, this must be done with WINDOW_ReDefine. Calling Sequence: status = Window_ModifyColors(windptr, txtcol_mask, txtcol, bkcol_mask, bkcol); Inputs: WINDOW_HEAD *windptr; - This is the window whose colors are to be modified. DWORD txtcol_mask, bkcol_mask; - These are the masks of the colors bits to be affected by the color changes. Only the 4 LSBs of each parameter is currently used. Normal values are 0, meaning no change, or 0xff, meaning change to passed color. Other values will allow true masking of individual bits of the color specifiers. DWORD txtcol, bkcol; - These are the colors to be ORed into the specified screen area. Possible values are: BLACK 0 BLUE 1 GREEN 2 CYAN 3 RED 4 MAGENTA 5 BROWN 6 WHITE 7 DARK GREY 8 LIGHT BLUE 9 LIGHT GREEN 10 LIGHT CYAN 11 LIGHT RED 12 LIGHT MAGENTA 13 YELLOW 14 BRIGHT WHITE 15 Outputs: status - WORD - This is the result of the function. Possible values are: WINDOW_ERR_NO_ERR Success. WINDOW_ERR_NOT_WPTR Bad pointer passed, not a window structure. Functions called: Comp_ModifyColors. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_ReDefine Purpose: This routine changes the parameter settings of the passed, existing window structure to the parameters passed. Calling Sequence: status = Window_ReDefine(windptr, topy, leftx, height, width, bkcol, txtcol, title, options); Inputs: struct window_head *windptr; - This is the pointer to the window structure that is to be modified. UBYTE topy, height, leftx, width; - These are the desired screen coordinates for the window. BITS options; - This is the set of bits defining different window options. Possible bit settings are: SINGLE_BORDER_BIT - Single line border. -No border is also DOUBLE_BORDER_BIT - Double line border. -possible by setting EXPLODE_BIT - Exploding window. -no bit. IMPLODE_BIT - Imploding window. POPUP_BIT - Popup window. DWORD bkcol, txtcol; - These are the colors used for the text and background display. TEXT *title; - This is the displayed title of the window. It will be automatically center justified. A null string causes no title to be displayed. Outputs: WORD status; - This is the result of the function. Possible values are: WINDOW_ERR_NO_ERR Success. WINDOW_ERR_NOT_WPTR Bad pointer passed, not a window structure. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Remove 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 = Window_Remove(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: WORD status; - This is the result of the call. Possible values are: WINDOW_ERR_NO_ERR Success WINDOW_ERR_NOT_WPTR Bad pointer passed, not a window structure. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_ScreenHeight Purpose: This routine returns the number of rows available on the display. Calling Sequence: rows = Window_ScreenHeight(); Inputs: None. Outputs: rows - UBYTE - This is the number of rows available on the display. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_ScreenWidth Purpose: This routine returns the number of columns available on the display. Calling Sequence: cols = Window_ScreenWidth(); Inputs: None. Outputs: cols - UBYTE - This is the number of columns available on the display. Functions called: None. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_Set Purpose: This routine defines the window to be in use and sets up the color definitions. This is mainly used for jumping between non-overlapped windows. Calling Sequence: Window_Set(row, col, height, width, bkcol, txtcol); Inputs: UBYTE 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. DWORD 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 Window_Init. Outputs: None. Functions called: Comp_SetTextWindow, Comp_SetBkColor, Comp_SetTextColor. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_SetPtr Purpose: This routine defines the window to be in use and sets up the color definitions. This is mainly used for jumping between non-overlapped windows. Calling Sequence: status = Window_SetPtr(window_ptr); Inputs: WINDOW_HEAD *window_ptr; - This is a pointer to the window structure describing the window desired. Outputs: WORD status; - This is the result of the call. Possible values are: WINDOW_ERR_NO_ERR Success WINDOW_ERR_NOT_WPTR Bad pointer passed, not a window structure. Functions called: Comp_SetTextWindow, Comp_SetBkColor, Comp_SetTextColor. /*------------------------------------------------------------------------*/ /*------------------------------------------------------------------------*/ Window_SetScreenRows Purpose: This routine trys to set the EGA or VGA monitor into 25, 43 or 50 line modes as requested. Other adaptors must stay in 25 line mode. Calling Sequence: status = Window_SetScreenRows(rows); Inputs: UBYTE rows; - This is the desired number of text rows on the display. Legal values are 25, 43, or 50, assuming a display and adaptor that will support the selection. WINDOW_HEAD *window_ptr; - This is a pointer to the window structure describing the window desired. Outputs: WORD status; - This is the result of the call. Possible values are: WINDOW_ERR_NO_ERR Success WINDOW_ERR_BAD_ROWS Illegal rows/adapter combination As returned by called routines Functions called: Comp_GetVideoInfo, Comp_SetScreenRows. /*------------------------------------------------------------------------*/ Error Codes The following is the list of error codes that can be returned from the VISIONS window library. Error Name Value Description. WINDOW_ERR_NO_ERR 0 Success. WINDOW_ERR_HELP_WIND -200 File opening error. WINDOW_ERR_HELP_WIND -201 Display window too small! WINDOW_ERR_NO_HEAP -202 Out of heap for pop up storage. WINDOW_ERR_NOT_WPTR -203 Bad window structure pointer. WINDOW_ERR_BAD_DEF -204 Size of window exceeds screen.