The C Users' Group Library 1994 August

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

/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 324_01 / wgconio.doc < prev next >

Wrap

Text File | 1990-07-17 | 57KB | 1,651 lines

/* HEADER: ; TITLE: Documentation for WGCONIO; DATE: 07/17/1990; FILENAME: WGCONIO.DOC; SEE-ALSO: wgconio.c,wgconio.lib,wgconio.h; AUTHORS: Bill Giel; */ 1 WGCONIO A Text Windowing System by Bill Giel 40 Briarwood Lane Milford, Connecticut 06460 (203) 877-9438 General Information WGCONIO was designed to emulate the Turbo C v2.0 (TC) text window functions for PC compatible computers under the MS- DOS operating system. Most major functions are duplicated, and a few have been added. WGCONIO grew out of the author's experiments with TSR programs. Rather than adopt an entirely new set of unfamiliar windowing functions, these functions were developed to be called the same way as the standard TC functions. They have the same names as their TC counterparts, with the exception that the prefix "wg" has been added. In addition to anyone trying to develop TSR's using Turbo C, these functions should be useful if compiling code written for TC on a compiler that does not support the TC text window functions. For those who wish to modify and recompile WGCONIO.C, be advised that a number of functions call int86(). This function is available with TC and Microsoft C, but may not have the same name with other compilers. In this case, replace 'int86' with the name of the function supported on the particular compiler. While the WGCONIO functions are not intended to comprise a complete window tool kit, they could provide the building blocks for such a system. WGCONIO Files WGCONIO.H is an "include" file, that prototypes the functions of the WGCONIO system, declares needed structures and defines symbolic constants for screen colors and scrolling directions. WGCONIO.LIB is a small model library file of the WGCONIO functions, which was created using TLIB. It should be named when linking a program that uses the WGCONIO functions, or 2 made a part of a project file if using the TC integrated development environment, or similar system. WGCONIO.C is the source code from which WGCONIO.LIB was created. SAMPLE.EXE is a short program that demonstrates how the window functions are used, by creating six pop-up windows, and then removing them, one by one. SAMPLE.C is the source code for the SAMPLE.EXE program. In the listing of SAMPLE.C, please note that when compiling files that include WGCONIO.H, a symbolic constant named MAIN_MODULE must be defined in the first source file. MAIN_MODULE should not be defined in subsequent modules. Also note that the function initiallize_WGW() is called early in main(), to ensure that the windowing system is initiallized. 3 THE WGCONIO LIBRARY FUNCTIONS ------------------------------------------------------------ box Name box - prints a double-line box on the screen. Usage void box(int width, int height); Related Functions void box2(int width, int height); Description box places a double-line border width units wide and height units down from the current cursor position. box2 performs the same function, only a single- line border is displayed, rather than a double- line. ------------------------------------------------------------ box2 Name box2 - prints a single-line box on the screen. Usage void box2(int width, int height); Related Functions void box(int width, int height); Description See box. ------------------------------------------------------------ cursor_off Name cursor_off - hides the cursor. Usage void cursor_off(void); Description Turns the cursor off. See also size_cursor(). ------------------------------------------------------------ get_attrib Name get_attrib - gets the current attribute, forground color and background color. 4 Usage void get_attribute(unsigned char *attribute, unsigned char *foreground, unsigned char *background); Description This function assigns the current attribute, foreground color and background color to the variables pointed to by attribute, foreground and background. ------------------------------------------------------------ get_cursor_pos Name get_cursor_pos - gets current screen-relative cursor position. Usage void get_cursor_pos(unsigned char *x,unsigned char *y); Description This function assigns the current screen- relative cursor position to the variables pointed to by x and y. wgwherex and wgwherey find the window relative coordinates of the current cursor. This function is similar, only it finds the screen- relative coordinates. ------------------------------------------------------------ get_cursor_size Name get_cursor_size - gets the current cursor configuration. Usage void get_cursor_size(unsigned char *ch, unsigned char *cl); Description get_cursor_size assigns the current cursor starting and ending scan lines into the variables pointed to by ch and cl, respectively. See also cursor_off(), size_cursor(); ------------------------------------------------------------ get_keycode Name get_keycode - returns the 16-bit scan code of a key. 5 Usage int get_keycode(void); Description This function waits for a keypress and returns the 16-bit scan code of the key. See also wggetch(),wggetche(). ------------------------------------------------------------ get_video_mode Name get_video_mode - returns the current video mode. Usage int get_video_mode(void); Description This function returns the current video mode of the display adapter. The following table lists screen modes available for various adapters. Mode Type Dimensions Adapter ---- ---- ---------- ------- 0 text,b/w 40x25 CGA,EGA 1 text,16 colors 40x25 CGA,EGA 2 text,b/w 80x25 CGA,EGA 3 text,16 colors 80x25 CGA,EGA 4 graphics,4 colors 320x200 CGA,EGA 5 graphics,4 grays 320x200 CGA,EGA 6 graphics.b/w 640x200 CGA,EGA 7 text.b/w 80x25 monochrome 8 graphics,16 colors 160x200 PCjr 9 graphics,16 colors 320x200 PCjr 10 graphics,4 colors 640x200 PCjr graphics,16 colors 640x200 EGA 13 graphics,16 colors 320x200 EGA 14 graphics,16 colors 640x200 EGA 15 graphics,4 colors 640x350 EGA Return Value Returns an integer that corresponds to the current video mode. ------------------------------------------------------------ initiallize_WGW Name initiallize_WGW - initiallizes window system. Usage void initiallize_WGW(void); 6 Description This function must be called before using this alternative text windowing system. It places the initial values used by the system into the global structure WGW of type wgtext_info (defined in WGCONIO.H) struct wgtext_info{ unsigned char winleft; unsigned char wintop; unsigned char winright; unsigned char winbottom; unsigned char attribute; unsigned char currmode; unsigned char screenheight; unsigned char screenwidth; unsigned char curx; unsigned char cury; unsigned char foreground; unsigned char background; }WGW; wgtext_info is slightly different from its TC counterpart (text_info). winleft, wintop, winright and winbottom are the screen relative limits of the current text window. attribute is the current text attribute. currmode is the current text mode. screenheight and screenwidth define the size of the current screen, i.e. 25 and 80. curx and cury are the current window- relative coordinates of the cursor. foreground and background are the current foreground and background text colors. When initiallized, the default text window is a full screen (1,1,80,25 for 80-column modes, and 1,1,40,25 for 40-column modes). In addition to filling in the wgtext_info structure, a second global structure WGV is initiallized which is primarily used by the system. This is a structure of type wgvid_parameters. struct wgvid_parameters{ unsigned char textline; unsigned char textbytes; char far *vid_mem; }WGV; textline is the number of bytes needed to save a full line of text ( 2 bytes for each character, or 160 bytes in an 80-column mode). textchar is the number of bytes needed to save a character (typically 1 byte for the character 7 and 1 byte for the attribute). vid_mem is a pointer to the starting address of video memory. The function will determine the beginning of video memory, depending on the text mode when initiallized. By default, output goes directly to the video hardware. However, output can also be directed through the BIOS by changing the value of the global variable wg_directvideo (declared in WGCONIO.H) to 0. By default, the value is 1 for direct video output. Using BIOS output results in considerably slower response. ------------------------------------------------------------ make_window Name make_window - makes a bordered, titled window. Usage char *make_window(char *title, struct wgwind w, struct wgtext_info *t, int shadow_flag); Related Function void restore_screen(struct wgwind w, char *text_buf, struct wgtext_info t, int shadow_flag); Description make_window creates a window with an optional centered title, border and shadow. The window colors and size are passed in w, of type struct wgwind (defined in WGCONIO.H). struct wgwind{ unsigned char foreborder;/*border foreground*/ unsigned char backborder;/*border background*/ unsigned char foretitle;/*title foreground*/ unsigned char backtitle;/*title background*/ unsigned char foreground;/*text foreground*/ unsigned char background;/*text background*/ unsigned char leftlim;/*left boundary*/ unsigned char toplim;/*top boundary*/ unsigned char rightlim;/*right boundary*/ unsigned char bottomlim;/*bottom boundary*/ }; The function will save the underlying portion of the screen to a dynamically allocated portion of memory. 8 The previous status of the text screen will be assigned to a structure of type wgtext_info (defined in WGCONIO.H) pointed to by t. struct wgtext_info{ unsigned char winleft; unsigned char wintop; unsigned char winright; unsigned char winbottom; unsigned char attribute; unsigned char currmode; unsigned char screenheight; unsigned char screenwidth; unsigned char curx; unsigned char cury; unsigned char foreground; unsigned char background; }; The title can be bypassed by sending a null string for *title. Shadows can be turned on or off by passing SHADOW or NO_SHADOW (defined in WGCONIO.H) for shadow_flag. restore_screen removes the window, frees the allocated memory, restores the underlying portion of the screen to its previous condition, and resets the status of the current window to what it was before the call to make_window. If a shadowed window is being cleared, then the appropriate value for shadow_flag must be passed (the same value used when the window was created). Return Value If successful, make_window returns a pointer to the portion of memory where the underlying portion of the screen is saved. If unsuccessful (invalid coordinates, allocation failure) the function returns 0. Example #include"wgconio.h" main() { struct wgwind w0= {YELLOW, BLUE, WHITE, BLUE, LIGHTGRAY, BLUE, 5, 5,75, 20}; char *p0; struct wgtext_info t0; 9 initiallize_WGW(); p0=make_window("TEST WINDOW",w0,&t0,SHADOW); if(!p0){ printf("\nError creating window\n"); exit(1); } /* ... */ restore_screen(w0,p0,t0,SHADOW); } ------------------------------------------------------------ make_shadow Name make_shadow - created a shaded area on the text screen. Usage int make_shadow(int left, int top, int right, int bottom); Description make_shadow creates a shaded portion of the screen, defined by an upper left corner (left,top) and lower right corner (right, bottom). left, top, right and bottom are screen-relative coordinates. See also make_window(). ------------------------------------------------------------ make_tsr_window Name make_tsr_window - makes a bordered, titled window. Usage char *make_window(char *title, struct wgwind w, struct wgtext_info *t,char *buf); Related Function void restore_tsr_screen(struct wgwind w, char *text_buf, struct wgtext_info t); Description make_tsr_window creates a window with an optional centered title and border. 10 Unlike make_window, this function does not invoke malloc(). The contents of the screen underlying the window are saved to a statically declared text buffer buf. The window colors and size are passed in w, of type struct wgwind (defined in WGCONIO.H). struct wgwind{ unsigned char foreborder;/*border foreground*/ unsigned char backborder;/*border background*/ unsigned char foretitle;/*title foreground*/ unsigned char backtitle;/*title background*/ unsigned char foreground;/*text foreground*/ unsigned char background;/*text background*/ unsigned char leftlim;/*left boundary*/ unsigned char toplim;/*top boundary*/ unsigned char rightlim;/*right boundary*/ unsigned char bottomlim;/*bottom boundary*/ }; The function will save the underlying portion of the screen to buf. This should be declared with a sufficient size to hold the contents of the screen underlying the window. The previous status of the text screen will be assigned to a structure of type wgtext_info (defined in WGCONIO.H) pointed to by t. struct wgtext_info{ unsigned char winleft; unsigned char wintop; unsigned char winright; unsigned char winbottom; unsigned char attribute; unsigned char currmode; unsigned char screenheight; unsigned char screenwidth; unsigned char curx; unsigned char cury; unsigned char foreground; unsigned char background; }; The title can be bypassed by sending a null string for *title. restore_tsr_screen removes the window, restores the underlying portion of the screen to its previous condition, and resets the status of the current window to what it was before the call to make_tsr_window. 11 Return Value If successful, make_tsr_window returns a pointer to buf. If unsuccessful (invalid coordinates) the function returns 0. Example #include"wgconio.h" main() { struct wgwind w0= {YELLOW, BLUE, WHITE, BLUE, LIGHTGRAY, BLUE, 5, 5, 75, 20}; char buf[2272]; struct wgtext_info t0; initiallize_WGW(); make_tsr_window("TEST WINDOW",w0,&t0,buf); /* ... */ restore_tsr_screen(w0,p0,t0); } ------------------------------------------------------------ restore_screen Name restore_screen - restores underlying screen and window status after a call to make_window. Usage void restore_screen(struct wgwind w, char *text_buf, struct wgtext_info t,int shadow_flag); Related Functions char *make_window(char *title, struct wgwind w, struct wgtext_info *t); Description See make_window. ------------------------------------------------------------ restore_tsr_screen Name restore_tsr_screen - restores underlying screen and window status after a call to make_tsr_window. Usage void restore_tsr_screen(struct wgwind w, char *text_buf, struct wgtext_info t); 12 Related Functions char *make_tsr_window(char *title, struct wgwind w, struct wgtext_info *t,char *buf); Description See make_tsr_window. ------------------------------------------------------------ scroll_window Name scroll_window - scrolls a portion of the screen up or down. Usage void scroll_window(unsigned char direct, unsigned char lines, unsigned char top, unsigned char left, unsigned char bottom, unsigned char right, unsigned char attribute); Description scroll_window will scroll a portion of the screen, defined by corner coordinates top, left and bottom, right in the direction specified by direct (use UP or DOWN, defined in WGCONIO.H). The number of lines to scroll is specified in lines. The attribute of blank lines is specified by attribute. The corner coordinates are screen-relative. See also movetext(), wg_scroll(). ------------------------------------------------------------ size_cursor Name size_cursor - changes the cursor size. Usage void size_cursor(unsigned char start,unsigned char end); Description size_cursor changes the current cursor configuration. On color systems, calling the function with arguments of 7 and 8 (for start and end) will produce the default cursor. On monochrome systems (IBM video mode 7), 12 and 13 produce the default cursor. See also cursor_off() 13 ------------------------------------------------------------ wgclreol Name wgclreol - clears text from the current cursor position to the end of the current line within the active text window. Usage void wgclreol(void); Description This function clears text from the current cursor position to the end of the line in the active text window. The current cursor position remains where it was prior to the call to wgclreol. Turbo C Equivalent clreol. ------------------------------------------------------------ wgclrscr Name wgclrscr - clears all text from the active text window. Usage void wgclrscr(void); Description This function clears all text from the active window, and positions the cursor at the upper left corner (1,1). Turbo C Equivalent clrscr. ------------------------------------------------------------ wgcprintf Name wgcprintf - displays formatted output. Usage int wgcprintf(char *format[,argument,...]); Description This function displays formatted output in the current text window. '\r' (carriage return) will position the cursor at the beginning of the current line. '\n' (newline) positions the cursor at the beginning of the next line, scrolling up if necessary. Output will wrap to the next line if the window limit is exceeded. Turbo C Equivalent cprintf. 14 ------------------------------------------------------------ wgcputs Name wgcputs - outputs a text string to the current text window. Usage int wgcputs(char *string); Description This function is used to write a string of text to the current text window. Output begins at the current cursor position. If the text length exceeds the line length of the window, the text will wrap to the next line. The text in the window will scroll up if the function attempts to wrap beyond the bottom of the window. The cursor advances one position after each character that is written to the window. The '\r' (carriage return) character repositions the cursor at the beginning of the current line (with no linefeed). The '\n' (newline) character repostions the cursor at the beginning of the next line, scrolling the text in the window up one line if necessary. Return Value The function returns the last character printed (which might be '\r' or '\n'). Turbo C Equivalent cputs. ------------------------------------------------------------ wgdelline Name wgdelline - deletes the current line in the current text window. Usage void wgdelline(void); Description This function deletes the line containing the cursor (within the current text window). Lines below scroll up one line. 15 See also wgclreol(),wginsline(). Turbo C Equivalent delline. ------------------------------------------------------------ wggetch Name wggetch - gets a character from the keyboard (and does not echo to the screen). Usage int wggetch(void); Related Functions int wggetche(void); Description wggetch waits until a key is pressed and returns the character, without echoing to the screen. wggetche waits until a key is pressed, returns a character, and echoes the character in the current text window. In the case of extended key codes, wggetch and wggetche return 0. A second call to wggetch and wggetche will return the second byte of the two-byte code. Turbo C Equivalent getch. ------------------------------------------------------------ wggetche Name wggetche - gets a character from the keyboard and echoes to the current text window. Usage int wggetche(void); Related Functions int wggetch(void); Description See wggetch. Turbo C Equivalent getche. 16 ------------------------------------------------------------ wggettext Name wggettext - saves a portion of the text screen to memory. Usage int wggettext(int left,int top,int right,int bottom, char *buf); Related Functions int wgputtext(int left,int top,int right,int bottom, char *buf); Description wggettext copies a portion of the text screen to an area of memory pointed to by buf. wgputtext restores a portion of the text screen from an area of memory pointed to by buf. The arguments left, top, right and bottom are the screen-relative coordinates that define the upper left and lower right corners of the rectangular area to be saved or restored (as opposed to window-relative coordinates). Each text character requires 2 bytes of memory. The first byte stores the character, and the second byte stores the charcter's attribute. The memory required to store a rectangle of text can be calculated from bytes needed = rows x columns x 2 For example, the entire screen (1,1,80,25) requires 80*25*2, or 4000 bytes of memory. A smaller area, say (5,5,75,20) requires 71*16*2, or 2272 bytes. Passing invalid screen coordinates will cause the call to either function to fail (and be ignored). Return Value Both of these functions return 1 if successful, or 0 upon failure. Example /*declare buffer of sufficient size*/ char screen_buf[2272]; /*save text*/ wggettext(5,5,75,20,screen_buf); /*...*/ 17 /*restore text*/ wgputtext(5,5,75,20,screen_buf); Turbo C Equivalent gettext. ------------------------------------------------------------ wggettextinfo Name wggettextinfo - saves current text window status in stucture of type wgtext_info. Usage void wgtextinfo(struct wgtext_info *inforec); Description This function saves the status of the current text window into a structure of type wgtext_info (defined in WGCONIO.H). struct wgtext_info{ unsigned char winleft; unsigned char wintop; unsigned char winright; unsigned char winbottom; unsigned char attribute; unsigned char currmode; unsigned char screenheight; unsigned char screenwidth; unsigned char curx; unsigned char cury; unsigned char foreground; unsigned char background; }; See also initiallize_WGW() Turbo C Equivalent gettextinfo. ------------------------------------------------------------ wggotoxy Name wggotoxy - sets cursor position in current active text window. Usage void wggotoxy(int x, int y); Description This function permits setting the cursor to a specific position within the active text window. The arguments x and y are window relative coordinates (as opposed to screen relative). For example, the upper left corner 18 of the current window is (1,1), regardless of where this window appears on the screen. If invalid coordinates are passed, then the call to this function is ignored. Turbo C Equivalent gotoxy. ------------------------------------------------------------ wginsline Name wginsline - inserts a line in the current text window. Usage void wginsline(void); Description This function inserts a blank line at the line containing the cursor. Original lines scroll down one line. See also wgdelline(). Turbo C Equivalent insline. ------------------------------------------------------------ wgmovetext Name wgmovetext - copies a portion of the screen to a different location on the screen. Usage int wgmovetext(int left, int top, int right, int bottom, int newleft, int newtop); Description wgmovetext will copy a portion of the text screen, defined by upper left corner coordinates left, top and lower right corner coordinates right, bottom to a new location defined by upper left corner coordinates newleft, newtop. left, top, right, bottom, newleft and newtop are screen-relative coordinates. The new location must be situated so that the entire rectangle of text can be moved without requiring clipping. 19 Return Value The function returns 1 if successful, and 0 if unsuccessful (invalid coordinates, not enough room for rectangle at new location). See also wg_scroll(), scroll_window(). Turbo C Equivalent movetext. ------------------------------------------------------------ wgputch Name wgputch - outputs a character in the current text window. Usage int wgputch(int c); Description This function writes a character c at the current cursor position in the current text window. If the character is '\r' (carriage return) the cursor is positioned at the beginning of the current line. If the character is '\n' (newline) the cursor is positioned at the beginning of the next line. Text in the window will scroll up if necessary. Return Value The function returns the character that was printed to the screen. Turbo C Equivalent putch. ------------------------------------------------------------ wgputtext Name wgputtext - restores a portion of the text screen from memory. Usage int wgputtext(int left,int top,int right,int bottom, char *buf); Related Functions int wggettext(int left,int top,int right,int bottom, char *buf); 20 Description See wggettext. Turbo C Equivalent puttext. ------------------------------------------------------------ wg_scroll Name wg_scroll - scrolls the current text window one line. Usage void wg_scroll(unsigned char direct); Description wg_scroll will scroll the current text window one line in the direction specified by direct (use UP or DOWN, defined in WGCONIO.H). Blank lines are inserted at the top (scrolling DOWN) or bottom (scrolling UP) using the current attribute. See also movetext(),scroll_window(). ------------------------------------------------------------ wgtextattr Name wgtextattr - changes the current text attribute. Usage void wgtextattr(int attribute); Related Functions void textcolor(int color); void textbackground(int color); Description wgtextattr permits changing both foreground and background text colors with a single call. Characters already displayed on the screen will not be affected. But any new characters displayed using the console output functions in wgconio.lib will be displayed using the new attribute. Attribute is an 8 bit parameter of the form Bbbbffff B (bit 7) is the blink-enable bit. bbb (bits 4-6) is the 3 bit background color. 21 ffff(bits -3) is the 4-bit foreground color. If the symbolic constants for screen colors are being used to form an attribute, then the background color must be shifted left 4 bits so that it occupies the correct bit positions. Example wgtextattr(YELLOW + (BLUE<<4)); /* Display yellow text on a blue background*/ wgtextattr(WHITE + (RED + (WHITE<<4) + BLINK); /*Display blinking white on a red background*/ Turbo C Equivalent textattr. ------------------------------------------------------------ wgtextbackground Name wgtextbackground - sets the current background text color. Usage void wgtextbackground(int color); Related Functions void wgtextcolor(int color); Description See wgtextcolor. Turbo C Equivalent textbackground. ------------------------------------------------------------ wgtextcolor Name wgtextcolor - sets the current foreground text color. Usage void wgtextcolor(int color); Related Functions void wgtextbackground(int color); Description wgtextcolor and wgtextbackground permit changing the foreground and background colors for text. Characters already displayed on the screen are not affected. But any new characters that are displayed using the console output functions in wgconio.lib will be displayed with the new colors. 22 color is any integer from 0 to 7 for background colors, or from 0 to 15 for foreground colors. Characters can be made to blink by adding 128 to the foreground color. If a high-intensity color is accidentally chosen for background (8 through 15) it will be corrected to its low-intensity equivalent. The following symbolic constants are defined in WGCONIO.H, which can be used to set foreground and background colors. BLACK 0 BLUE 1 GREEN 2 CYAN 3 RED 4 MAGENTA 5 BROWN 6 LIGHTGRAY 7 DARKGRAY 8 LIGHTBLUE 9 LIGHTGREEN 10 LGHTCYAN 11 LIGHTRED 12 LIGHTMAGENTA 13 YELLOW 14 WHITE 15 BLINK 128 Example textcolor(YELLOW); /*Sets current foreground color to yellow*/ textcolor(WHITE + BLINK); /*Sets current foreground to blinking white*/ Turbo C Equivalent textcolor. ------------------------------------------------------------ wgwherex Name wgwherex - gets the current column position of the cursor. Usage int wgwherex(void); Related Functions int wgwherey(void); 23 Description These functions return the current window- relative position of the cursor. wgwherex returns the column position, and wherey returns the row position. Note that the upper left cell of any window is row 1, column 1 (1,1). Return Value wgwherex returns an integer from 1 through 80. wgwherey returns an integer from 1 through 25. Turbo C Equivalent wherex. ------------------------------------------------------------ wgwherey Name wgwherey - gets the current row position of the cursor. Usage int wgwherey(void); Related Functions int wgwherex(void); Description See wgwherex. Turbo C Equivalent wherey. ------------------------------------------------------------ wgwindow Name wgwindow - creates a text window. Usage void wgwindow(int left,int top,int right,int bottom); Description wgwindow creates an active text window on the screen. The window is defined by the upper left corner coordinates (left,top) and lower right corner coordinates (right,bottom). The initial default window is defined with initiallze_WGW() for a full screen. The minimum window is one character cell. The call to this function will be ignored if invalid coordinates are passed. 24 Return Value None Turbo C Equivalent window.