CD Actual 15

home *** CD-ROM | disk | FTP | other *** search

/ CD Actual 15 / CDACTUAL15.iso / cdactual / program / c / WNDWC21.ZIP / WNDWREF.DOC < prev

Wrap

Text File | 1989-08-01 | 98.5 KB | 2,057 lines

MULTI-LEVEL VIRTUAL WINDOWS USER'S GUIDE Version 2.1 August 1, 1989 Conversion to Turbo C / Microsoft C by Jordan Gallagher / Wisdom Research Copyright (C) 1989 Eagle Performance Software All Rights Reserved. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 T A B L E O F C O N T E N T S 1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 4 Purpose . . . . . . . . . . . . . . . . . . . . . . . 4 Common Parameters . . . . . . . . . . . . . . . . . . 4 Attributes . . . . . . . . . . . . . . . . . . . . . 5 2. FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . 6 accesswindow . . . . . . . . . . . . . . . . . . . . 6 changeborder . . . . . . . . . . . . . . . . . . . . 6 getlevelindex . . . . . . . . . . . . . . . . . . . . 6 heapok . . . . . . . . . . . . . . . . . . . . . . . 7 hidewindow . . . . . . . . . . . . . . . . . . . . . 7 initwindow . . . . . . . . . . . . . . . . . . . . . 7 locatecursor . . . . . . . . . . . . . . . . . . . . 7 makewindow . . . . . . . . . . . . . . . . . . . . . 8 move16 . . . . . . . . . . . . . . . . . . . . . . . 8 movewindow . . . . . . . . . . . . . . . . . . . . . 8 movewords . . . . . . . . . . . . . . . . . . . . . . 9 removewindow . . . . . . . . . . . . . . . . . . . . 9 restoreborder . . . . . . . . . . . . . . . . . . . . 9 restoretcwindow . . . . . . . . . . . . . . . . . . . 10 setcursordefault . . . . . . . . . . . . . . . . . . 10 setvirtualsize . . . . . . . . . . . . . . . . . . . 10 setwindowmodes . . . . . . . . . . . . . . . . . . . 11 showwindow . . . . . . . . . . . . . . . . . . . . . 11 titlewindow . . . . . . . . . . . . . . . . . . . . . 12 vresizewindow . . . . . . . . . . . . . . . . . . . . 12 vscrollview . . . . . . . . . . . . . . . . . . . . . 12 vupdatecursor . . . . . . . . . . . . . . . . . . . . 12 vupdaterows . . . . . . . . . . . . . . . . . . . . . 13 vupdatetitles . . . . . . . . . . . . . . . . . . . . 13 vupdateview . . . . . . . . . . . . . . . . . . . . . 13 vupdatewindow . . . . . . . . . . . . . . . . . . . . 13 vviewrc . . . . . . . . . . . . . . . . . . . . . . . 14 vviewrcrel . . . . . . . . . . . . . . . . . . . . . 14 vzoomwindow . . . . . . . . . . . . . . . . . . . . . 14 weosc . . . . . . . . . . . . . . . . . . . . . . . . 14 weosln . . . . . . . . . . . . . . . . . . . . . . . 15 weostorc . . . . . . . . . . . . . . . . . . . . . . 15 weosr . . . . . . . . . . . . . . . . . . . . . . . . 15 wbrdrh . . . . . . . . . . . . . . . . . . . . . . . 15 wbrdrpart . . . . . . . . . . . . . . . . . . . . . . 16 wbrdrv . . . . . . . . . . . . . . . . . . . . . . . 16 wclreol . . . . . . . . . . . . . . . . . . . . . . . 16 wclreos . . . . . . . . . . . . . . . . . . . . . . . 17 wclrfield . . . . . . . . . . . . . . . . . . . . . . 17 wclrfieldeos . . . . . . . . . . . . . . . . . . . . 17 wclrline . . . . . . . . . . . . . . . . . . . . . . 17 wclrscr . . . . . . . . . . . . . . . . . . . . . . . 18 wclrtitle . . . . . . . . . . . . . . . . . . . . . . 18 wdelline . . . . . . . . . . . . . . . . . . . . . . 18 wgotoeos . . . . . . . . . . . . . . . . . . . . . . 18 wgotorc . . . . . . . . . . . . . . . . . . . . . . . 19 2 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 winsline . . . . . . . . . . . . . . . . . . . . . . 19 wlineh . . . . . . . . . . . . . . . . . . . . . . . 19 wlinepart . . . . . . . . . . . . . . . . . . . . . . 20 wlinev . . . . . . . . . . . . . . . . . . . . . . . 20 writeandviewpage . . . . . . . . . . . . . . . . . . 20 writetocrt . . . . . . . . . . . . . . . . . . . . . 21 writetohidden . . . . . . . . . . . . . . . . . . . . 21 writetopage . . . . . . . . . . . . . . . . . . . . . 21 writetovirtual . . . . . . . . . . . . . . . . . . . 21 wscrolldown . . . . . . . . . . . . . . . . . . . . . 22 wscrollup . . . . . . . . . . . . . . . . . . . . . . 22 wwherec . . . . . . . . . . . . . . . . . . . . . . . 22 wwherer . . . . . . . . . . . . . . . . . . . . . . . 22 wwrite . . . . . . . . . . . . . . . . . . . . . . . 23 wwritec . . . . . . . . . . . . . . . . . . . . . . . 23 wwrite_sub . . . . . . . . . . . . . . . . . . . . . 24 3. DATA STRUCTURE . . . . . . . . . . . . . . . . . . . . 25 Basic Types . . . . . . . . . . . . . . . . . . . . . 25 Macros . . . . . . . . . . . . . . . . . . . . . . . 27 Static Variables . . . . . . . . . . . . . . . . . . 28 Dynamic Variables . . . . . . . . . . . . . . . . . . 31 APPENDIX A: MEMORY ALLOCATION . . . . . . . . . . . . . . 32 Global Memory . . . . . . . . . . . . . . . . . . . . 32 Dynamic Memory . . . . . . . . . . . . . . . . . . . 32 Code Size . . . . . . . . . . . . . . . . . . . . . . 33 APPENDIX B: ERROR MESSAGES . . . . . . . . . . . . . . . 34 3 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 1. I N T R O D U C T I O N PURPOSE This document is a technical reference manual describing each routine and variable in detail in a format similar to the TC manual. The routines are described in alphabetical order. Since this manual is on disk, you can find your interest easily with any search utility. Application - Because WNDWC uses QWIKC, all routines will perform in the following applications: . All video text modes - 0, 1, 2, 3 and 7. . Any column mode - 40, 80, or variable. . For IBM PC, XT, AT, PCjr, PC convertible, all PS/2 models, 3270 PC, and compatibles. . With MDA, CGA, EGA, MCGA, VGA, 8214/A, all Hercules video cards. . Perform routines in both absolute and window-relative coordinates. COMMON PARAMETERS Common Parameters - Most procedures use the same parameters. Rather than repeating them for each routine, detailed descriptions for those parameters are listed below. Window Coordinates - Unless otherwise stated, all WNDWC routines work in window-relative coordinates. For simplicity, virtual routines check for bounds to keep routines confined to the windows and screen. However, to be fast, some other routines indicated in this document do not check for bounds in the windows or on the screen, so be sure to stay in range. The upper left column in a window is row 1, column 1, which is also called a 1-based coordinate system. row/col - row and col were chosen in lieu of the X/Y scheme used in TC. Since WNDWC is for only text modes, the screen is treated like a word processor with rows and columns. It is more intuitive to use the X/Y scheme in graphics and the row/col scheme for text. rows/cols - Using rows/cols is much easier than row2/col2 to describe the height and width of a block such as: void makewindow( row, col, rows, cols, wattr, battr, border, name ); Should you decide to move the window, only row and col need to be changed, and therefore rows and cols don't need to be mentally recalculated and altered. Please keep cols limited to one row. numofrows/numofcols - These parameters indicate a relative shift from a given point that can be positive or negative. astr - The window-relative writing routines wwrite and wwritec actually use QWIKC to write this string. Chapter 1, Introduction Page 4 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 ATTRIBUTES *attr - Use the convenient attribute macros for the foreground and background colors supplied in the QWIKC unit rather than having to use TC functions or procedures to get a desired color, for example: makewindow( 1, 1, 8, 8, WHITE+BLUE_BG, YELLOW+BLUE_BG, SINGLE_BORDER, AWINDOW ); will make a window with a white on blue window and yellow on blue border. All subsequent routines will use these attributes for writing. Turbo C's textattr function is called, setting the attribute to the window attribute in case TC's screen functions are used. The foreground macros in QWIKC are duplicates of those in TC's conio.h and are repeated here for convenience: BLACK 0x00 DARKGRAY 0x08 BLUE 0x01 LIGHTBLUE 0x09 GREEN 0x02 LIGHTGREEN 0x0A CYAN 0x03 LIGHTCYAN 0x0B RED 0x04 LIGHTRED 0x0C MAGENTA 0x05 LIGHTMAGENTA 0x0D BROWN 0x06 YELLOW 0x0E LIGHTGRAY 0x07 WHITE 0x0F BLINK 0x80 In addition, the QWIKC background color constants were included to take advantage of macro addition. BLACK_BG 0x00 BLUE_BG 0x10 GREEN_BG 0x20 CYAN_BG 0x30 RED_BG 0x40 MAGENTA_BG 0x50 BROWN_BG 0x60 LIGHTGRAY_BG 0x70 SAMEATTR -1 SAMEATTR - A powerful and unique feature of all WNDWC routines is the use of the macro SAMEATTR. If SAMEATTR, or a negative value, is used as an attribute, the routine will suppress any changes to the attributes and use what is currently on the screen. Chapter 1, Introduction Page 5 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 2. F U N C T I O N S In this section, a detailed description is provided for each function. --------------------------------------------------------------------------- accesswindow WNDWC --------------------------------------------------------------------------- Function Randomly accesses a covered window and places it on the top. If the window is hidden, it uses showwindow to put it on top. Syntax void accesswindow( int windowname ); Remarks All underlays are properly updated in the heap with a high speed technique. If NOACCESSMODE has been set for this window or an invalid window name is used, the function is simply ignored. Virtual windows are updated after being shown. Zoom effect is optional. The wndwstat array is shuffled to match the new levels. Return value None. Screens All video pages. EOS Restored to new window. Restrictions Shadows are permitted, but exposed corners on lower level windows with shadows will not be updated until moved. For human factors, shadows are only recommended for the top window anyway. Heap Temporarily uses (underlay size * 1.5). Upon return Forced to write to CRT. See also hidewindow, showwindow --------------------------------------------------------------------------- changeborder WNDWC --------------------------------------------------------------------------- Function Changes the border to a new border style. Syntax void changeborder( int newbrdr ); Remarks The original border style is already saved in viewbrdr. The current border is changed by searching for a match of wsbrdr for each border part with the current attribute. If a match is found, it is replaced with newbrdr. Tees as well as virtual borders are also replaced. The original border can later be restored with restoreborder. Return value None. Screens All video pages. EOS Restored to CRT. Restrictions NO_BORDER is ignored as either the original or new border. Upon return Forced to write to CRT. See also restoreborder --------------------------------------------------------------------------- getlevelindex WNDWC --------------------------------------------------------------------------- Function Returns the wndwstat index given the windowname. Syntax int getlevelindex( int windowname ); Remarks This routine scans for the first matching windowname. It scans from the top level index (li) first and then down. Hidden windows from the hidden level index (hli) up are Chapter 2, Procedures and Functions Page 6 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 scanned last. If no match is found, the result is >MAXWINDOW. Return value None. --------------------------------------------------------------------------- heapok WNDWC --------------------------------------------------------------------------- Function Returns 1 if enough far heap space is available for allocation using farmalloc or farcalloc. Syntax void heapok( int numofbytes ); Remarks If there is insufficient heap, the program terminates by calling showgoof. The error window will display coreleft and farcoreleft. All WNDWC functions that use the heap call this routine. Return value Returns 1 on success, calls showgoof on failure. --------------------------------------------------------------------------- hidewindow WNDWC --------------------------------------------------------------------------- Function Hides the current top window on the CRT. Syntax void hidewindow(void); Remarks The window is saved in RAM and the underlay is restored on the screen showing the new top window. If NOHIDEMODE has been set for this window, the procedure is ignored. The windows are saved with the border, but without any shadow. Return value None. Screens All video pages. EOS Altered to (wrow,wcol) before hiding, then restored to the new top window. Heap Temporarily uses (underlay size * 1.5). Upon return Forced to write to CRT. See also showwindow --------------------------------------------------------------------------- initwindow WNDWC --------------------------------------------------------------------------- Function Initializes static data for WNDWC routines. In brief, it sets the defaults for wndwstat, indexes and margins for each video page, and calls qinit. Syntax void initwindow( int wattr, int clearscr, char cursorok ); Remarks This is the first routine required to be called early in the main program and only needs to be done once. wattr is the attribute for the full screen (WINDOW0) for all video pages. If clearscr is 1, then all video pages are cleared with wattr. Over 50 variables are initialized with this function. qinit is also called. See initwindow source code for details. Return value None. EOS Set to (1,1). Heap Allocates virtualstat and pagestat pointers as required. See also setcursordefault, WNDWC21.DOC and Data Structure section. --------------------------------------------------------------------------- locatecursor WNDWC --------------------------------------------------------------------------- Chapter 2, Procedures and Functions Page 7 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Function Locates the cursor within the window. Syntax void locatecursor(void); Remarks This routine, a subroutine of restoretcwindow, locates the cursor as set in the wndwstat for fixed or virtual windows. It is usually handled automatically, but is available for handling exceptions. vupdatecursor is called by locatecursor. Return value None. Screens All video pages. See also restoretcwindow, vupdatecursor --------------------------------------------------------------------------- makewindow WNDWC --------------------------------------------------------------------------- Function Makes a window. Syntax void makewindow( unsigned char row, unsigned char col, unsigned char rows, unsigned char cols, int wattr, int battr, int brdrsel, int windowname ); Remarks This is the main routine to create windows. row, col, rows, and cols are the absolute coordinates for the window inclusive of any border. For RELMODE, (row,col) is window relative. wattr and battr are the window and border attributes, respectively (SAMEATTR is permitted). brdrsel is the selection of one of 15 different borders. windowname is a unique window name required for random access. EOS set to (1,1). Return value None. Screens All video pages. Restrictions Minimum size - (1x1) without borders, (3x3) with borders. Heap Allocates underlay size until removed. See also setwindowmodes, removewindow --------------------------------------------------------------------------- move16 WNDWC --------------------------------------------------------------------------- Function Copies a specified number of contiguous bytes from a source range to a destination range. Syntax void move16( void far *source, void far *dest, int numofbytes ); Remarks move16 is a suitable replacement for memcpy, and is faster since it uses 16-bit transfers. Overlap of data space is allowed. Return value None. See also movewords --------------------------------------------------------------------------- movewindow WNDWC --------------------------------------------------------------------------- Function Moves the current top window on the CRT a relative number of rows and columns. Syntax void movewindow( int numofrows, int numofcols ); Remarks If NOMOVEMODE or PERMMODE has been set for this window, the function does nothing. Shadows are fully supported. Margins are respected. Chapter 2, Procedures and Functions Page 8 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Return value None. Screens All video pages. EOS Moved relatively to the same place. Heap Maximum requirement is full screen size plus the underlay size. Upon return Forced to write to CRT. See also showwindow --------------------------------------------------------------------------- movewords WNDWC --------------------------------------------------------------------------- Function Copies a specified number of contiguous bytes from a source range to a destination range. Syntax void movewords( int far *source, int far *dest, int numofwords ); Remarks Even faster than move16. Return value None. Restrictions source[0] and dest must not overlap. See also move16 --------------------------------------------------------------------------- removewindow WNDWC --------------------------------------------------------------------------- Function Removes the current top window on the CRT. Syntax void removewindow(void); Remarks Basically, the top window is removed, restoring the underlay, and then erased from memory. Depending on the window mode, removewindow responds differently: RELMODE - The window-relative stats are simply replaced with the parent window stats. PERMMODE - The stats are simply dropped from the stack. VIRTUALMODE - The virtual screen is additionally removed from the heap. Return value None. Screens All video pages. EOS Restored to the new top window. Heap Deallocates the underlay. Upon return Forced to write to CRT. See also makewindow --------------------------------------------------------------------------- restoreborder WNDWC --------------------------------------------------------------------------- Function Restores the border to the original border style. Syntax void restoreborder(void); Remarks Reverses the effect of changeborder by replacing the current border style back to the original. Return value None. Screens All video pages. EOS Restored to CRT. Upon return Forced to write to CRT. See also changeborder Chapter 2, Procedures and Functions Page 9 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 --------------------------------------------------------------------------- restoretcwindow WNDWC --------------------------------------------------------------------------- Function Restores attributes, cursor, and EOS marker for the current window. Syntax void restoretcwindow(void); Remarks Usually this procedure is handled automatically. If there is some exception in handling, then this procedure can be used. It does the following: . Resets TC's textattr and QWIKC's scroll_attr to tws.origattr . Restores TC's text window . Resets EOS marker to last saved location . Resets cursor mode . Locates cursor with locatecursor Return value None. Screens All video pages. EOS Restored. See also locatecursor --------------------------------------------------------------------------- setcursordefault WNDWC --------------------------------------------------------------------------- Function Sets the default cursor mode to be used by makewindow. Syntax void setcursordefault( int cursormode ); Remarks This routine simply assigns a value to the global variable cursordefault. This value is already assigned by initwindow to the current cursor mode. If a specific cursor mode is required for the initial window as well, use setcursor instead before initwindow. Return value None. See also initwindow, makewindow, setcursor (QWIKC) --------------------------------------------------------------------------- setvirtualsize WNDWC --------------------------------------------------------------------------- Function Sets the dimensions for the virtual screen of virtual windows. Syntax void setvirtualsize( unsigned char rows, unsigned char cols ); Remarks This optional function sets the rows-by-columns dimensions for a virtual screen. Keep in mind that two additional rows will be internally added for titles if borders are used. The default at startup is the CRT screen size. Return value None. Restrictions Maximum buffer size is 64k. See also makewindow Example To set the size for a virtual screen with 80 columns and a maximum number of rows: setvirtualsize( 253, 80 ); The resulting size would be (253+2)*80*2 = 40,800 bytes Chapter 2, Procedures and Functions Page 10 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 which is under 64k. Rows 254 and 255 would be reserved for top and bottom titles on the border. --------------------------------------------------------------------------- setwindowmodes WNDWC --------------------------------------------------------------------------- Function Sets the window modes to be used by makewindow. Syntax void setwindowmodes( int sumofallmodes ); Remarks There are several different modes that can be used: RELMODE - Window-relative frame of reference, no underlay PERMMODE - Can't be moved or removed, no underlay SHADOWLEFT - Shadow on the left side SHADOWRIGHT - Shadow on the right side ZOOMMODE - Zoom effect on make, show and accesswindow HIDDENMODE - Create window as hidden VIRTUALMODE - Create virtual screen as well CURSOROFFMODE - Leaves cursor off for window SEETHRUMODE - Doesn't clear area inside window NOHIDEMODE - Ignores request to hide window NOACCESSMODE - Ignores request to access window NOMOVEMODE - Ignores request to move/resize window The startup mode is equivalent to zero while the base window is PERMMODE. The modes should be summed logically, but can also be done arithmetically with care. All PERMMODE windows must be created first. Return value None. See also makewindow Example Set the modes for the next window to have a right shadow, zoom effect, cursor off, and a virtual screen: setwindowmodes( SHADOWRIGHT | ZOOMMODE | CURSOROFFMODE | VIRTUALMODE ); Example Set the modes back to defaults: setwindowmodes( 0 ); --------------------------------------------------------------------------- showwindow WNDWC --------------------------------------------------------------------------- Function Shows a hidden window to become the current top window on the CRT. Syntax void showwindow( int windowname ); Remarks The underlay is saved from the screen and the window is restored from RAM to become the new top window. Invalid window names are simply ignored. Virtual windows are updated before being shown. Zoom effect is optional. Return value None. Screens All video pages. EOS Set to (1,1). Heap Temporarily uses (underlay size * 1.5). Upon return Forced to write to CRT. See also hidewindow, accesswindow Chapter 2, Procedures and Functions Page 11 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 --------------------------------------------------------------------------- titlewindow WNDWC --------------------------------------------------------------------------- Function Places a title on the current window. Syntax void titlewindow( int toporbottom, int justify, int titleattr, char *title ); Remarks There are six positions where the title can be placed in any combination of TOP or BOTTOM, and LEFT, CENTER, or RIGHT. titleattr is the title attribute (SAMEATTR is permitted). The titles can be written to hidden windows or virtual screens as well. titleofs can be adjusted for justification. Return value None. Screens All video pages. EOS Unaltered. See also titleofs in Data Structure section. --------------------------------------------------------------------------- vresizewindow WNDWC --------------------------------------------------------------------------- Function Resizes the current top virtual window. Syntax void vresizewindow( int numofrows, int numofcols ); Remarks The top window is resized by moving the right and/or bottom border. If NOMOVEMODE or PERMMODE has been set for this window, the function does nothing. Shadows are fully supported. Margins are respected. Return value None. Restrictions None. Heap Maximum requirement is full screen size plus the underlay size. Upon return Forced to write to CRT. See also vzoomwindow --------------------------------------------------------------------------- vscrollview WNDWC --------------------------------------------------------------------------- Function Alters the upper left viewing reference point of the current virtual screen by a relative number of rows and columns. The view window is also updated no matter where its location even if hidden or overlapped. Syntax void vscrollview( int numofrows, int numofcols ); Remarks The reference point may be adjusted to keep the viewing window within the virtual window limits. Works in any "writeto" mode. Return value None. Restrictions None. Heap If covered, wsrows * wcols * 5 bytes is temporarily used. See also vviewrc, vviewrcrel --------------------------------------------------------------------------- vupdatecursor WNDWC --------------------------------------------------------------------------- Function Updates the current virtual window cursor if it is the top window on the CRT. Chapter 2, Procedures and Functions Page 12 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Syntax void vupdatecursor(void); Remarks When the cursor is moved on the virtual screen, the cursor may or may not be seen in the view. This routine updates the location. Works in any "writeto" mode. Return value None. See also vupdatetitles, vupdateview, vupdatewindow --------------------------------------------------------------------------- vupdaterows WNDWC --------------------------------------------------------------------------- Function Updates certain rows in the current virtual window view only on the top window. Syntax void vupdaterows( unsigned char row, unsigned char rows ); Remarks This routine is primarily used for fast response for spot updates for data entry or the like where the fastest speed is desirable. If the window is not the top window, the entire view is updated. Return value None. See also vupdateview, vupdatewindow --------------------------------------------------------------------------- vupdatetitles WNDWC --------------------------------------------------------------------------- Function Updates the current virtual window titles. It is also updated no matter where its location even if hidden or overlapped. Syntax void vupdatetitles(void); Remarks This routine updates the titles to the window and truncates them to fit in the current view. Works in any "writeto" mode. Return value None. Heap If covered, wsrows * wcols * 5 bytes is temporarily used. See also vupdatecursor, vupdateview, vupdatewindow --------------------------------------------------------------------------- vupdateview WNDWC --------------------------------------------------------------------------- Function Updates the current virtual window view. It is also updated no matter where its location even if hidden or overlapped. Syntax void vupdateview(void); Remarks This routine updates the full view of the window. Works in any "writeto" mode. Return value None. Heap If covered, wsrows * wcols * 5 bytes is temporarily used. See also vupdaterows, vupdatetitles, vupdatewindow --------------------------------------------------------------------------- vupdatewindow WNDWC --------------------------------------------------------------------------- Function Updates the current virtual window including the view, titles and the cursor. It is also updated no matter where its location even if hidden or overlapped. Syntax void vupdatewindow(void); Remarks This is the main routine to update virtual windows. This routine simply executes three procedures: vupdatecursor, Chapter 2, Procedures and Functions Page 13 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 vupdateview, and vupdatetitles. Works in any "writeto" mode. Return value None. Heap If covered, wsrows * wcols * 5 bytes is temporarily used. See also vupdatecursor, vupdaterows, vupdatetitles, vupdateview --------------------------------------------------------------------------- vviewrc WNDWC --------------------------------------------------------------------------- Function Alters the upper left viewing reference point of the current virtual window. Syntax void vviewrc( unsigned char row, unsigned char col ); Remarks The reference point may be adjusted to keep the viewing window within the virtual window limits. Works in any "writeto" mode. It does not update the viewing window. Return value None. Restrictions None. See also vviewrcrel, vscrollview --------------------------------------------------------------------------- vviewrcrel WNDWC --------------------------------------------------------------------------- Function Alters the upper left viewing reference point of the current virtual window by a relative number of rows and columns. Syntax void vviewrcrel( int numofrows, int numofcols ); Remarks The reference point may be adjusted to keep the viewing window within the virtual window limits. Works in any "writeto" mode. It does not update the viewing window. Return value None. Restrictions None. See also vviewrc, vscrollview --------------------------------------------------------------------------- vzoomwindow WNDWC --------------------------------------------------------------------------- Function Toggles top virtual window between full screen size and original size. Syntax void vzoomwindow(void); Remarks If the window is less than full size, the window is zoomed to full size and centered if necessary. Executing the function again will restore the size and location of this window. If NOMOVEMODE or PERMMODE has been set for this window, the function does nothing. Shadows are fully supported. Margins are respected. Return value None. Heap Maximum requirement is full screen size plus the underlay size. Upon return Forced to write to CRT. See also vresizewindow --------------------------------------------------------------------------- weosc WNDWC --------------------------------------------------------------------------- Function Returns the window-relative column of the EOS marker. Syntax unsigned char weosc(void); Chapter 2, Procedures and Functions Page 14 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Remarks Operates on the currently written screen. The upper left corner of the window is (1,1). Return value weosc returns an unsigned char between 1 and 255. Screens All video pages and virtual screens. See also weosr, weostorc, weosln, wgotoeos --------------------------------------------------------------------------- weosln WNDWC --------------------------------------------------------------------------- Function Moves the EOS marker to column 1 of the next window-relative row with a possible scroll up. Syntax void weosln(void); Remarks Operates on the currently written window. If weosr becomes greater than the number of window rows, then the window will scroll up. The new blank row will have the attribute set by wndwattr which is the window attribute. Return value None. Screens All video pages and virtual screens. EOS Updated to first cleared column of the cleared row. See also weosr, weosc, weostorc, wgotoeos --------------------------------------------------------------------------- weostorc WNDWC --------------------------------------------------------------------------- Function Positions the EOS marker relative to the current window. Syntax void weostorc( unsigned char row, unsigned char col ); Remarks Use this function to manually locate the EOS marker. All EOS functions will write where this marker is located on the currently written screen. Return value None. Screens All video pages and virtual screens. EOS Updated. Restrictions Stay within the window limits. See also QWIKC, weosr, weosc, weosln, wgotoeos --------------------------------------------------------------------------- weosr WNDWC --------------------------------------------------------------------------- Function Returns the window-relative row of the EOS marker. Syntax unsigned char weosr(void); Remarks Operates on the currently written screen. The upper left corner of the window is (1,1). Return value weosr returns an unsigned char between 1 and 255. Screens All video pages and virtual screens. See also weosc, weostorc, weosln, wgotoeos --------------------------------------------------------------------------- wbrdrh WNDWC --------------------------------------------------------------------------- Function Places a horizontal partition of the same type as the window border from edge to edge of the border. Syntax void wbrdrh( unsigned char row ); Remarks This routine divides a window using wsbrdr and brdrattr from the top window record. It provides a horizontal line complete with a tee on each end using parts BRDR_HL, Chapter 2, Procedures and Functions Page 15 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 BRDR_LT, and BRDR_RT. If brdrattr is set to SAMEATTR, then the attributes will remain the same on the screen. If there is no border, the function does nothing. Return value None. Screens All video pages and virtual screens. EOS Unaltered. Restrictions Stay within window limits. Cannot use NO_BORDER. See also wbrdrpart, wbrdrv, wlineh, wlinepart, wlinev --------------------------------------------------------------------------- wbrdrpart WNDWC --------------------------------------------------------------------------- Function Places a single border part of the same type as the window border at a window-relative location. Syntax void wbrdrpart( unsigned char row, unsigned char col, int part ) Remarks This routine places the part using wsbrdr and brdrattr from the top window record. It is usually used for crosses or tees, but there are 15 different parts that can be used. If brdrattr is set to SAMEATTR, then the attributes will remain the same on the screen. If there is no border, the function does nothing. Return value None. Screens All video pages and virtual screens. EOS Unaltered. Restrictions Stay within window limits. Cannot use NO_BORDER. See also wbrdrh, wbrdrpart, wlineh, wlinev, wlinepart --------------------------------------------------------------------------- wbrdrv WNDWC --------------------------------------------------------------------------- Function Places a vertical partition of the same type as the window border from edge to edge of the border. Syntax void wbrdrv( unsigned char row ); Remarks This routine divides a window using wsbrdr and brdrattr from the top window record. It provides a vertical line complete with a tee on each end using parts BRDR_VL, BRDR_TT, and BRDR_BT. If brdrattr is set to SAMEATTR, then the attributes will remain the same on the screen. If there is no border, the function does nothing. Return value None. Screens All video pages and virtual screens. EOS Unaltered. Restrictions Stay within window limits. Cannot use NO_BORDER. See also wbrdrh, wbrdrpart, wlineh, wlinev, wlinepart --------------------------------------------------------------------------- wclreol WNDWC --------------------------------------------------------------------------- Function Clears a row to End-Of-Line (EOL). Syntax void wclreol( unsigned char row, unsigned char col, int attr ); Remarks The row is cleared using the attribute attr (SAMEATTR is permitted). To clear using the window attribute, pass attr as tws.wndwattr. Chapter 2, Procedures and Functions Page 16 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Return value None. Screens All video pages and virtual screens. EOS Set to (row,col). Restrictions Stay within window limits. See also wdelline, wclrline, wclreos --------------------------------------------------------------------------- wclreos WNDWC --------------------------------------------------------------------------- Function Clears a row from EOS to End-Of-Line. Syntax void wclreos( int attr ); Remarks The row is cleared starting at the EOS marker using the attribute attr (SAMEATTR is permitted). To clear using the window attribute, pass attr as tws.wndwattr. Return value None. Screens All video pages and virtual screens. EOS Unaltered. Restrictions Stay within window limits. See also wdelline, wclrline, wclreos --------------------------------------------------------------------------- wclrfield WNDWC --------------------------------------------------------------------------- Function Clears a field. Syntax void wclrfield( unsigned char row, unsigned char col, unsigned char cols, int attr ); Remarks The field is cleared starting at (row,col) using the attribute attr (SAMEATTR is permitted). To clear using the window attribute, pass attr as tws.wndwattr. Return value None. Screens All video pages and virtual screens. EOS Set to (row,col). Restrictions Stay within window limits. See also wclreol, wclreos, wclrfieldeos --------------------------------------------------------------------------- wclrfieldeos WNDWC --------------------------------------------------------------------------- Function Clears a field starting at EOS. Syntax void wclrfieldeos( unsigned char cols, int attr ); Screens All video pages and virtual screens. Remarks The field is cleared starting at EOS using the attribute attr (SAMEATTR is permitted). To clear using the window attribute, pass attr as tws.wndwattr. Return value None. EOS Unaltered. Restrictions Stay within window limits. See also wclreol, wclreos, wclrfield --------------------------------------------------------------------------- wclrline WNDWC --------------------------------------------------------------------------- Function Clears a specified row. Syntax void wclrline( unsigned char row ); Remarks The row is cleared using the window attribute tws.wndwattr Chapter 2, Procedures and Functions Page 17 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 (SAMEATTR is permitted). Return value None. Screens All video pages and virtual screens. EOS Set to (row,1). Restrictions Stay within window limits. See also wdelline, wclreol, wclreos --------------------------------------------------------------------------- wclrscr WNDWC --------------------------------------------------------------------------- Function Clears the entire window. Syntax void wclrscr(void); Remarks Clears the screen using the window attribute tws.wndwattr (SAMEATTR is permitted). Return value None. Screens All video pages and virtual screens. EOS Set to (1,1). See also wclrline, wdelline, winsline --------------------------------------------------------------------------- wclrtitle WNDWC --------------------------------------------------------------------------- Function Clears the titles from the specified row. Syntax void wclrtitle( int toporbottom ); Remarks Clears the top or bottom border where the titles are located and restores the original border if any. If wsbrdr is NO_BORDER, the row is simply cleared. Works on both fixed and virtual titles. Return value None. Screens All video pages and virtual screens. EOS Unaltered. See also titlewindow, vupdatetitle --------------------------------------------------------------------------- wdelline WNDWC --------------------------------------------------------------------------- Function Deletes a line at a specified row, scrolls up the remaining part of the window and clears the bottom row. Syntax void winsline( unsigned char row ); Remarks Similar to Turbo C's delline, the indicated row of the window will be deleted. The bottom row is cleared with tws.wndwattr (SAMEATTR is permitted). The cursor is not moved, but is ready to be moved with wgotoeos as EOS is set to the first column of the cleared row. Return value None. Screens All video pages and virtual screens. EOS Updated to first cleared column of the cleared row. Restrictions Stay within window limits. See also winsline, wscrollup, wgotoeos --------------------------------------------------------------------------- wgotoeos WNDWC --------------------------------------------------------------------------- Function Positions the cursor to match the EOS marker on both fixed or virtual windows. Chapter 2, Procedures and Functions Page 18 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Syntax void wgotoeos(void); Remarks The cursor is simply moved to match the position of the EOS marker of the currently written video page. tws.wswherer and tws.wswherec are also updated. For virtual windows, this routine also calls vupdatecursor. Return value None. Screens All video pages and virtual screens. EOS Unaltered. See also weosr, weosc, weostorc, weosln, wgotorc, vupdatecursor Restrictions EOS should be within window limits. Example Center a string in a window and place the cursor at the end of the string: wwritec( 1, "Correct (Y/N)? " ); wgotoeos(); --------------------------------------------------------------------------- wgotorc WNDWC --------------------------------------------------------------------------- Function Positions the cursor relative to the window. Syntax void wgotorc( unsigned char row, unsigned char col ); Remarks The cursor is positioned to the currently written window. For virtual windows, this routine also calls vupdatecursor. Return value None. Screens All video pages and virtual screens. EOS Unaltered. Restrictions Stay within the window limits. See also wgotoeos, wwherer, wwherec --------------------------------------------------------------------------- winsline WNDWC --------------------------------------------------------------------------- Function Inserts a blank line at a specified row using the window attribute tws.wndwattr scrolling down the remaining part. Syntax void winsline( unsigned char row ); Remarks Similar to Turbo C's insline, the indicated row of the window is scrolled down and then cleared (SAMEATTR is permitted). The cursor is not moved, but is ready to be moved with wgotoeos as EOS is set to the first column of the cleared row. Return value None. Screens All video pages and virtual screens. EOS Updated to first cleared column of the cleared row. Restrictions Stay within window limits. See also wdelline, wscrolldown, wgotoeos --------------------------------------------------------------------------- wlineh WNDWC --------------------------------------------------------------------------- Function Places a horizontal line in the window using the window line set. Syntax void wlineh( unsigned char row, unsigned char col, unsigned char cols ); Remarks This routine divides a window using wsline and wndwattr from the top window record. It provides just a horizontal line Chapter 2, Procedures and Functions Page 19 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 using part BRDR_HL. If wndwattr is set to SAMEATTR, then the attributes will remain the same on the screen. If wsline=nobrdr, then the function does nothing. Return value None. Screens All video pages and virtual screens. EOS Updated. Restrictions Stay within window limits. Cannot use NO_BORDER. See also wbrdrh, wbrdrpart, wbrdrv, wlinepart, wlinev --------------------------------------------------------------------------- wlinepart WNDWC --------------------------------------------------------------------------- Function Places a single line part of the same type as the window line set at a window-relative location. Syntax void wlinepart( unsigned char row, unsigned char col, int part ); Remarks This routine places the part using wsline and wndwattr from the top window record. It is usually used for crosses or tees, but there are 15 different parts that can be used. If SAMEATTR is used for wndwattr, then the attributes will remain the same on the screen. If wsline=NO_BORDER, the function is ignored. Return value None. Screens All video pages and virtual screens. EOS Updated. Restrictions Stay within window limits. Cannot use NO_BORDER. See also wbrdrh, wbrdrpart, wbrdrv, wlineh, wlinev --------------------------------------------------------------------------- wlinev WNDWC --------------------------------------------------------------------------- Function Places a vertical line in the window using the window line set. Syntax void wlinev( unsigned char row, unsigned char col, char rows ); Remarks This routine divides a window using wsline and wndwattr from the top window record. It provides just a vertical line using part BRDR_VL. If wndwattr is set to SAMEATTR, then the attributes will remain the same on the screen. If wsline=NO_BORDER, then the function does nothing. Return value None. Screens All video pages and virtual screens. EOS Updated. Restrictions Stay within window limits. Cannot use NO_BORDER. See also wbrdrh, wbrdrpart, wbrdrv, wlineh, wlinepart --------------------------------------------------------------------------- writeandviewpage WNDWC --------------------------------------------------------------------------- Function Changes the video page to be both viewed and written on the CRT. Syntax void writeandviewpage( char pagenum ); Remarks If another video page is available, this routine will switch to both view and write to that page. It does nothing if pagenum is already the currently written video page Chapter 2, Procedures and Functions Page 20 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 (qvideo_page) and viewed page (videopage), or if pagenum is invalid. All wndwstats are swapped to exact same conditions as before. Return value None. Screens All video pages. EOS Restored to new page. See also writetopage, QWIKC --------------------------------------------------------------------------- writetocrt WNDWC --------------------------------------------------------------------------- Function Prepares QWIKC and WNDWC to write to the top window on the CRT and restores TC's window. Syntax void writetocrt(void); Remarks This function switches back to writing to the top window on the CRT after writing to a hidden window or virtual screen. Return value None. Screens Back to any video page. EOS Restored to top window. See also writetohidden, writetovirtual --------------------------------------------------------------------------- writetohidden WNDWC --------------------------------------------------------------------------- Function Prepares QWIKC and WNDWC to write to a hidden window. Syntax void writetohidden( int windowname ); Remarks This function switches to writing to a hidden window. The window must be a valid window name, otherwise the program is terminated with an error message. Return value None. EOS Restored to hidden window. See also writetocrt, writetovirtual --------------------------------------------------------------------------- writetopage WNDWC --------------------------------------------------------------------------- Function Changes the video page on which the WNDWC routines write without changing the viewed page. Syntax void writetopage( char pagenum ); Remarks If another video page is available, this routine will switch to write to that page. It does nothing if pagenum is already the currently written video page (qvideo_page) or if the page is invalid. All wndwstats are swapped to exact same conditions as before. Return value None. Screens All video pages. EOS Restored to new page. See also writeandviewpage, QWIKC --------------------------------------------------------------------------- writetovirtual WNDWC --------------------------------------------------------------------------- Function Prepares QWIKC and WNDWC to write to a virtual screen. Syntax void writetovirtual( int windowname ); Remarks This function switches to writing to a virtual screen. The Chapter 2, Procedures and Functions Page 21 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 window must be a valid window name, otherwise, the program is terminated with an error message. Return value None. EOS Restored to virtual screen. See also writetocrt, writetohidden --------------------------------------------------------------------------- wscrolldown WNDWC --------------------------------------------------------------------------- Function Scrolls the current window down and clears the top row with the window attribute wndwattr. Syntax void wscrolldown(void); Remarks The last row of the window will be scrolled out and lost while the first row will be cleared (SAMEATTR is permitted). The cursor is not moved, but is ready to be moved with wgotoeos as EOS is set to the first column of the cleared row. Return value None. Screens All video pages and virtual screens. EOS Updated to first cleared column of the cleared row. Restrictions None. See also wscrollup, wgotoeos --------------------------------------------------------------------------- wscrollup WNDWC --------------------------------------------------------------------------- Function Scrolls the current window up and clears the bottom row with the window attribute wndwattr. Syntax void wscrollup(void); Remarks The first row of the window will be scrolled out and lost while the last row will be cleared (SAMEATTR is permitted). The cursor is not moved, but is ready to be moved with wgotoeos as EOS is set to the first column of the cleared row. Return value None. Screens All video pages and virtual screens. EOS Updated to first cleared column of the cleared row. Restrictions None. See also wscrolldown, wgotoeos --------------------------------------------------------------------------- wwherec WNDWC --------------------------------------------------------------------------- Function Returns the window-relative column of the cursor on the currently written video page. Syntax unsigned char wwherec(void); Remarks Operates on the currently written video page. The upper left corner of the screen is (1,1). Return value wwherec returns an unsigned char from 1 to 255. Screens All video pages only. See also wgotorc, wwherer --------------------------------------------------------------------------- wwherer WNDWC --------------------------------------------------------------------------- Chapter 2, Procedures and Functions Page 22 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Function Returns the window-relative row of the cursor on the currently written video page. Syntax void wwherer(void); Remarks Operates on the currently written video page. The upper left corner of the screen is (1,1). Return value wwherer returns an unsigned char from 1 to 255. Screens All video pages only. See also wgotorc, wwherec --------------------------------------------------------------------------- wwrite WNDWC --------------------------------------------------------------------------- Function Writes a string relative to the current window using the window attribute. Syntax void wwrite( unsigned char row, unsigned char col, char *astr ); Remarks This routine writes the string astr at window-relative (row,col) with the attribute wndwattr from the window record. If SAMEATTR is used for wndwattr, then the attributes will remain the same on the screen. Return value None. Screens All video pages and virtual screens. EOS Updated. Restrictions Stay within the window limits. Long strings will not wrap around to column 1. See also wwritec, wwritea Example Write the string "Enter" at (2,1) with the current window attribute: wwrite( 2, 1, "Enter" ); Example Write the string "Answer" at (2,1) with the attribute of flashing white on red and then restore the current window attribute: tws.wndwattr = BLINK+WHITE+RED_BG; wwrite( 2, 1, "Answer" ); tws.wndwattr = tws.origattr; --------------------------------------------------------------------------- wwritec WNDWC --------------------------------------------------------------------------- Function Writes a string centered column-wise to the current window using the window attribute. Syntax void wwritec( unsigned char row, char *astr ); Remarks This routine writes the string astr centered between the left and right columns of the window. The attribute used is wndwattr from the window structure. If SAMEATTR is used for wndwattr, then the attributes will remain the same on the screen. Return value None. Screens All video pages and virtual screens. EOS Updated. Restrictions Stay within the window limits. Long strings will not wrap around to column 1. Chapter 2, Procedures and Functions Page 23 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 See also wwrite, wwritea Example Write a message centered in a window on row 5: wwritec( 5, "My message" ); --------------------------------------------------------------------------- wwrite_sub WNDWC --------------------------------------------------------------------------- Function Writes a substring with a specified length relative to the current window using the window attribute. Syntax void wwrite_sub( unsigned char row, unsigned char col, int length, char far *astr ); Remarks This routine writes length characters of the string astr at window-relative (row,col) for the number of columns specified by length. This enables you to write substrings. The attribute used is wndwattr from the window record. If wndwattr is set to SAMEATTR, then the attributes will remain the same on the screen. Return value None. Screens All video pages and virtual screens. EOS Updated. Restrictions Stay within the window limits. Long strings will not wrap around to column 1. See also wwrite, wwritec Example The following will write "Testing out this line." with the current window attribute: strcpy( mystring, "Step B: Testing out this line." ); wwrite_sub( 1, 1, 22, &mystring[8] ); Chapter 2, Procedures and Functions Page 24 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 3. D A T A S T R U C T U R E This section will help describe the data structure of WNDWC and how it can be adjusted. The variables in WC21VAR.C are allocated according to the values of the macros set near the beginning of WNDWC21.H. There are several basic variables, but if desired, there are additional variables for virtual windows and multiple video pages. Please refer to the source code in WC21VAR.C and WNDWC21.H for the exact listing. BASIC TYPES Basic Types - These types are used for all windows and modes to define the data structure. This will describe the purpose of each type. Type Description ------------ ----------------------------------------------------------- borders This enumerated type gives a name for 15 different border styles each having 15 different parts already assigned in the static array brdr. The name NO_BORDER is reserved. NO_BORDER - No border at all. Just the text area. BLANK_BORDER - Blank character on all sides. SINGLE_BORDER - Single lines on all sides. DOUBLE_BORDER - Double lines on all sides. HDOUBLE_BORDER - Horizontal double lines. Single vertical lines. VDOUBLE_BORDER - Vertical double lines. Single horizontal lines. SOLID_BORDER - Solid box character on all sides. EVEN_SOLID_BORDER - Vertical solid box. Horizontal half box. THIN_SOLID_BORDER_1 - Half box on all sides. Squeezed horizontally. THIN_SOLID_BORDER_2 - Half box on all sides. Squeezed vertically. LHATCH_BORDER - Light hatch character on all sides. MHATCH_BORDER - Medium hatch character on all sides. HHATCH_BORDER - Heavy hatch character on all sides. USER_BORDER_1 - User defined border. USER_BORDER_2 - User defined border. brdrparts Each border has 15 different parts. This enumerated type identifies each part by name. Using acronyms, the relative position can be easily identified. For example, BRDR_TL means the Top Left border part. The order corresponds with the brdr_t type: Chapter 3, Data Structure Page 25 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Relative Position The first letter means: ------------------ T = Top B = Bottom TL TH TT TH TR V = Vertical H = Horizontal LV VL RV L = Left R = Right LT HL CL HL RT C = Cross LV VL RV Second letter exceptions: BL BH BT BH BR T = Tee L = Line brdr_t This type provides the array for storing a border. All 15 different border parts can be accessed by merely indexing the array. dir_t This enumerated type identifies various directions. They can be extended. margin_t Groups the margins used for moving or resizing windows. windownames This enumerated type gives a name or handle for each window to uniquely identify a window structure for random access. Any additional name can be used, but three are reserved: Name Description ---------- --------------------------------------------- WINDOW0 Identifies the initial base screen and must be first in the list. FREEWINDOW Identifies virtual screen records that are free to be overwritten. AWINDOW A generic name to be used when the window does not need to be unique. It is usually used for temporary windows like error messages. wndwstat_t This type sets up the window structure. Each field in the structure is worth describing. The "ws" prefix is an acronym meaning wndwstat. There are 50 bytes per structure. wsrow .. wscol2 - These variables identify the location and size of the window INCLUDING the border if any. The "2" suffix means the right column or bottom row location. wrow .. wcol2 - These variables identify the location and size of the window EXCLUDING the border if any. The "2" suffix means the right column or bottom row location. wndwattr/brdrattr/origattr - These the attributes for the window and border respectively. They can even be set to SAMEATTR. origattr is a second copy of wndwattr used to restore wndwattr to its original value. wsbrdr/wsline - The former is the current border style while the latter is a line set that can be used within the window. When a window is made, these two values are the same, but wsline is available to be changed to the needed line set. Chapter 3, Data Structure Page 26 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 wsname - The unique name assigned to the window structure. wswherer/wswherec - These variables save the window- relative row and column of the cursor. wsmodes - Saves all the modes that created the window including the current status. wscursor - Save the cursor mode used with this window. ulcol .. ulbytes - Saves the location and size of the underlay of a window including the border and shadow if any. ulptr - Points to the saved underlay in the heap. vscr - Holds the QWIKC screen data for this window. refrow/refcol - These two scratch coordinates are used for two cases. It saves the absolute row/col where a window is positioned before it is hidden. For virtual screen stats, it saves the view reference point. viewbrdr - Saves the border style originally created with the window. wsbrdr differs from viewbrdr in that wsbrdr contains the current border. For virtual screens, wsbrdr is always set to NO_BORDER even though the view on the CRT may be a different style. vi - Virtual screen index for its associated virtual window stat if any. MACROS Macros - These macros are used to control the data structure size or to conveniently set window mode bits. Macro Value Description -------------- ----- ------------------------------------------------ MAXWINDOW 1-254 Set by the user, this value determines the maximum number of windows that can be on the CRT on any video page. This sets the amount of static data to be used. MAXVIRTUALWINDOW 0-254 Set by the user, this value determines the total number of virtual screens minus one that will be maintained at any one time. If no virtual windows are wanted, undefine the macro ADDVIRTUAL. MAXPAGEUSED 0 - 7 Set by the user, this value determines the highest page number to be managed in a multi- Chapter 3, Data Structure Page 27 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 page program. If only page 0 is going to be used (which is usually the case), then undefine the directive MULTIPAGE. This will reduce the static data by a significant amount. Window Modes - There are several window modes and combinations of modes that can be set using setwindowmodes and saved in the variable windowmodes. This is a list of those modes, values and descriptions. After the window is created, the modes are saved in wsmodes as well as the "to" modes which indicate the status of the window. Macro Value Description -------------- ------ ------------------------------------------------- RELMODE 0x0001 (Bit 0) Simply overwrites the screen relative to the current window. The row/col coordinate is window relative. Works and stays in the current writeto mode. This is usually used for flexible screen design. The stats are only temporary and lost after changing windows. To get back to the parent window, use removewindow. PERMMODE 0x0002 (Bit 1) Makes the window permanent on the screen. This means that no underlay is saved. These windows must be the first ones created. They can be accessed, but be sure no other window is covering it (wi<=pli) before writing to the screen, because they are not necessarily the top window. SHADOWLEFT 0x0004 (Bit 2) Places a shadow on the left side. SHADOWRIGHT 0x0008 (Bit 3) Places a shadow on the right side. ZOOMMODE 0x0010 (Bit 4) Creates a zoom effect with makewindow, showwindow, and accesswindow. HIDDENMODE 0x0020 (Bit 5) Creates the window as hidden. VIRTUALMODE 0x0040 (Bit 6) Creates a virtual window with a virtual screen. CURSOROFFMODE 0x0080 (Bit 7) Always leaves cursor off. SEETHRUMODE 0x0100 (Bit 8) Doesn't clear screen inside the border and ignores ZOOMMODE. NOHIDEMODE 0x0200 (Bit 9) Ignores request to hide window. NOACCESSMODE 0x0400 (Bit 10) Ignores request to access window. NOMOVEMODE 0x0800 (Bit 11) Ignores request to move/resize window. TOCRTMODE 0x1000 (Bit 12) Indicates writing to CRT. TOHIDDENMODE 0x2000 (Bit 13) Indicates writing to hidden window. TOVIRTUALMODE 0x4000 (Bit 14) Indicates writing to virtual screen. STATIC VARIABLES Static Variables - Finally, the variables used in WNDWC can be described in detail and can be accessed by the user. Window Flags - While writing to a window, it is difficult to try to analyze the bits in wsmodes to figure out its modes. So, each mode has been given a corresponding flag. These flags are set for the current window. Though rather intuitive, each of the flag variables is listed below with its corresponding mode: Chapter 3, Data Structure Page 28 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 Flag Mode -------------- -------------- relflag RELMODE permflag PERMMODE zoomflag ZOOMMODE hiddenflag HIDDENMODE virtualflag VIRTUALMODE cursoroffflag CURSOROFFMODE seethruflag SEETHRUMODE nohideflag NOHIDEMODE noaccessflag NOACCESSMODE nomoveflag NOMOVEMODE tocrtflag TOCRTMODE tohiddenflag TOHIDDENMODE tovirtualflag TOVIRTUALMODE Single Page Variables - The following variables are grouped together because they are specific to the current video page being used. If you do use more than one page, these variables will be swapped with another page. Variable Description -------------- --------------------------------------------------------- wndwstat (Type: wndwstats_t) This is the array for the maximum number of windows both hidden and shown at one time. Each structure only uses 52 bytes of static data. wndwstat[0] is always the record for the initial window. topwndwstat (Type: macro) This structure makes it easy to always access the data for the current window and is always up to date. This data will be saved in the correct wndwstat before accessing another window. topwndwstat is a macro defined as tws. tws (Type: wndwstat_t) tws is used to actually store the data, whereas topwndwstat is simply a more elaborate way of coding it. topvirtualstat (type: macro) For virtual windows, in addition to tws, there is the topvirtualstat for the associated virtual screen which has its own structure. tvs (Type: wndwstat_t) tvs is used to actually store the data, whereas topvirtualstat is simply a more elaborate way of coding it. Keep in mind that when writing direct to the virtual screen (writetovirtual), tws and tvs are reversed. It would then be helpful to think of tvs as the top VIEW stat, since the view is on the CRT. li (Type: int) This is the top Level Index for the top window currently shown on the CRT. Windows shown on the CRT are sequentially stacked from index 0 upward. hli (Type: int) This is the Hidden Level Index. Hidden windows are stacked from index MAXWINDOW downward. If Chapter 3, Data Structure Page 29 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 there are no hidden windows, hli=MAXWINDOW+1. wi (Type: int) For the current Window Index, the program saves and retrieves the wndwstat from this index whether it is hidden or shown. It ranges from 0 to MAXWINDOW. For hidden windows, wi can range from hli to MAXWINDOW. For the top window on the CRT, wi=li. For PERMMODE windows, it can be <=li. pli (Type: char) This Permanent Level Index keeps track of the order of the permanent windows on the CRT. They must be stacked contiguously as the first ones on the CRT or else an error message will be displayed. This value is <=li. cursordefault (Type: int) This is the value saved by setcursordefault for the cursor mode. It is just as easy to set it directly. When makewindow is used, this is the value saved for that window. margins (Type: margin_t) These margins limit the moving or resizing of windows for each video page. This prevents windows from covering status lines or the like. windowmodes (Type: int) This is the value saved by setwindowmodes. It is best to use the function for this value since it filters out incompatible modes. Universal Variables - These variables are not specific to any window or video page and are used universally in the program. Variable Description -------------- --------------------------------------------------------- brdr (Type: brdr_t array) Contains 14 different border styles each with 15 border parts. The data structure enables you to access parts by index name: mypart = brdr[ SINGLE_BORDER ][ BRDR_TL ]; prefer_multitask (Type: char) This boolean defaults to 0 so that would ignore any multi-tasking environment. When set to 1 just before initwindow, WNDWC will then use the higher speed video buffer (MTVB) if available. shadowchar (Type: char) This is the character used to produce a shadow. It is set to a space. This may not be desirable for monochrome monitors which may look better with hatch characters. shadowcolor (Type: int) This is the attribute used to produce a shadow. It is initially set to BLACK on BLACK. Any attribute can be used. titleofs (Type: int) When writing titles, this offset is used to Chapter 3, Data Structure Page 30 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 adjust where the title starts writing. Left justified titles start at wcol+titleofs while those right justified end at wcol2-titleofs. Center justified titles are not affected. The default value is 1. virtualrows (Type: unsigned char) This is the row height saved from setvirtualsize setting the number of rows used in the virtual screen. The default value is crt_rows. virtualcols (Type: unsigned char) This is the column width saved from setvirtualsize setting the number of columns used in the virtual screen. The default value is crt_cols. virtualsize (Type: int) This is the size in bytes to be reserved for the virtual screen. The size is virtualcols * (virtualrows+2) * 2. Remember the last two rows are added for the virtual titles. maxvalidpage (Type: char) The program can reserve enough data for all video pages being addressed with MAXPAGEUSED. However, the machine that runs the program must have those pages available. This variable additionally limits the pages that can be addressed. It is set to the lesser of max_page or MAXPAGEUSED. zoomdelay (Type: char) This value is set by initwindow to control the zoom rate on non-snowing video cards. This value is set according to the cpuid that QWIKC detected. DYNAMIC VARIABLES Dynamic Variables - These variables are allocated to the heap to leave more room for global variables. The far heap is always used, therefore the Tiny Model is not supported. The allocations are done in initwindow. Pointer Description -------------- --------------------------------------------------------- virtualstat (Type: wndwstat_t far *) This array of window structures is for the virtual screens associated with the virtual windows. All routines use this data when writing to virtual screens by copying it to tws. The index for this record is obtain from tws.vi. Since this array is filled at random, vi does not correspond to wi. When a virtual window is removed, these stats are "freed" by setting wsname to FREEWINDOW - they are not freed by calling free(). All video pages use this one array. pagestat (Type: wndwstat_t far *) If your program uses multiple video pages, a complete structure containing all the window records and indexes is saved for each video page. Any pagestat can be swapped with the top page variables (the first 10 listed under "Single Page Variables" above) to work on the current video page. The writetopage function handles this operation. Chapter 3, Data Structure Page 31 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 A P P E N D I X A : M E M O R Y A L L O C A T I O N This section covers the memory requirements for static data in the data segment and dynamic data in the heap. This will give you the figures on how to calculate the memory needed for your program. GLOBAL MEMORY Global Memory - WNDWC is very frugal with global data. Here is the breakdown on the fixed amount of data required: Variables Bytes ------------------------------- ----- Border array 210 Basic windows 142 Additional for virtual windows 69 Additional for multi-page video 4 ----- Fixed allocation 425 The additional data space for virtual windows and multi-page video, if not used, can be excluded by undefining the macros. This is the allocation for MAXWINDOW=0. For each additional window structure, add 52 bytes. So, for MAXWINDOW=10, the allocation would be (52*10)+425=945 bytes. DYNAMIC MEMORY Dynamic Variables - To alleviate using global data, dynamic variables are used for permanent and temporary use. The allocation for virtual screen records and video page records are permanent throughout the program. Many other procedures such as movewindow temporarily use the heap to perform operations. Permanent Variables - If the macros have been defined, the following allocation can be calculated: Variables Bytes --------------- ------------------------------- virtualstat 52 per virtual window pagestat (sizeof(pagestat_t)) per video page Virtual screen virtualsize Virtual screens are kept in memory until removewindow is called. Temporary Variables - For functions that temporarily use the heap, the size of allocation is listed along with each function in section 2 above. Generally, you should allow about the same size as 3 CRT screens of available heap for those functions. For a video mode with 25 rows and 80 columns, this is (80*25*2)*3=12000 bytes, in addition to the random allocation. Random Allocation - Because of the nature of random access to windows and underlays, the program does far allocation. This means that there are Appendix A: Memory Allocation Page 32 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 going to be gaps of free memory in the heap. To account for this, you should more than double the amount of data expected for underlays and virtual screens. It is up to you to judge just how much of the heap is going to be truly random. In the case of simple serial-access to windows, the heap will be contiguous and doubling of the heap is unnecessary. CODE SIZE Code Size - WNDWC is also very frugal with code. Here is the breakdown for code usage in the Small model (this may vary slightly): Code Description Bytes ------------------------------- ----- Basic windows 9385 Additional for virtual windows 742 Additional for multi-page video 4049 ----- Total code 14176 Of course the linker will optimize the code leaving out unused functions. But this gives you a good idea of how small the code really is! Appendix A: Memory Allocation Page 33 WNDWC Multi-level Virtual Windows Reference Guide, Version 2.1 A P P E N D I X B : E R R O R M E S S A G E S Because WNDWC is so powerful, it writes to screen in memory as well as the CRT. Should you make a mistake in programming, it may not show up on the CRT screen. So, to prevent the errors before they happen, programs written with errors will terminate with an error message window on the CRT to reveal the problem. The program terminates through the GOOF module, which can be freely edited. "Not enough heap space" - There is not enough far heap space. Too much memory is being taken. When running under the Turbo C environment in the Small or Medium models, you may get this error if you set your near heap size (_heaplen) to anything very large. This will cause the near heap to take a greater portion of available memory, leaving a smaller amount for the far heap. This is disastrous since WNDWC does all allocating on the far heap. "Too many windows" - Tried to create more windows than MAXWINDOW allows. Either remove windows or increase MAXWINDOW. "Too many virtual windows" - Tried to create more virtual windows than MAXVIRTUALWINDOW allows. Either remove windows or increase MAXVIRTUALWINDOW. "Perm window out of order" - Tried to create a PERMMODE window while a normal window is the top window. Remove or hide window before making a permanent window. Routinely, all PERMMODE windows are created first. "No window to remove" - Tried to remove the initial window WINDOW0 which is permanent. "Hidden window not found" - Tried to write to a hidden window that does not exist. Check for the correct name. "Virtual screen not found" - Tried to write to a virtual screen that does not exist. Check for the correct name. "Video page not available" - Tried to write to a video page that has not been allocated or does not exist for the hardware as expected. Be sure to use maxvalidpage. Appendix B: Error Messages Page 34