Power-Programmierung

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

/ Power-Programmierung / CD2.mdf / c / library / dos / window / miscutil / c_window.doc < prev next >

Wrap

Text File | 1987-01-16 | 34.0 KB | 991 lines

C Windowing Toolbox ------------------- for IBM Personal Computers and Compatibles Version 1.2 IBM, IBM PC are trademarks of International Business Machines Corp. Microsoft is a trademark of Microsoft Corp. Lattice is a trademark of Lattice Corp. C Windowing Toolbox ---------------------------------------------------------------------- INTRODUCTION C Windowing Toolbox is a collection of functions that give windowing capability to the C programmer using an IBM PC or true compatible. The windowing functions are written entirely in Microsoft C and were compiled using the small model for both code and data. It is distributed in .OBJ format, ready to be linked to your Microsoft and Lattice C programs. The source code of the C Windowing Toolbox, compatible with both the Microsoft (Lattice) C version 2.xx compiler and the Microsoft C version 3/4 compiler is available for $15. See the end of this documentation for details. The C Windowing Toolbox files are: C_WINLAT.OBJ - The compiled windowing code linkable to programs compiled by the Microsoft version 2/Lattice C compiler C_WINMSC.OBJ - The compiled windowing code linkable to programs compiled by the Microsoft version 3 or 4 C compiler C_WINDOW.DOC - The documentation C_WDEF.H - Include file for your C code C_WDEMO.C - Source of windowing demonstration program C_WDEMO.EXE - Windowing demonstration program To use the Windowing functions in your Microsoft/Lattice C program: (1) Include the file C_WDEF.H in your C source file. C_WDEF.H defines the windowing functions and associated constants and variables. (2) Compile your C source using the small code and data model. (3) Link the windowing code to your program: Microsoft C version 2/Lattice - LINK CS + yourprog + C_WINLAT, yourprog.EXE,, MCS.LIB Microsoft C version 3/4 - LINK yourprog + C_WINMSC; To allow other C compilers to compile the windowing source code, standard C syntax is used where-ever possible. There are only three non-standard C functions used: INT86(), PEEK() and POKE(). The Microsoft version 2/Lattice C compiler has these functions in 1 C Windowing Toolbox ---------------------------------------------------------------------- its library. The Microsoft C version 3/4 compiler doesn't support PEEK() and POKE() so suitable versions, written in C, are included in the C_WINDOW.C source file. Microsoft C version 2/Lattice compatible versions of the three above functions written in assembler, plus a full explanation, are also on the source code disk. If your compiler doesn't include INT86() PEEK() or POKE(), you can modify either the C or assembler sources mentioned above to suit your compiler. Also, if you don't have an IBM PC or compatible, and you are familiar with reading and writing to the video RAM of your computer, you can adapt the windowing code for use on your PC. C_WDEMO.C is the C source of a sample windowing program. It has been compiled as C_WDEMO.EXE and is part of the windowing package. SCREEN CONCEPTS An array of bytes, called the window buffer, is used to store each defined window, plus the section of the screen that each window overlays. The window buffer size has been defined in the windowing code to be 10000 bytes. This is a compromise value. Larger allows more active window definitions, smaller means a smaller program. When a window is defined, storage is allocated in the window buffer. The standard IBM PC screen, in 80 column alphanumeric mode, uses 4000 bytes (80 x 25 x 2) of video RAM. Each character on the screen has a trailing attribute byte that indicates if the character is bright or dark, blinking, red, blue, etc. 10000 bytes is enough to create a window the size of the screen (4000 bytes to save old screen, 4000 for window), plus another little window. Or several medium sized windows. C Windowing Toolbox allows deallocation of window storage so you can have as many windows as you like by deallocating and redefining them as needed. The only restriction is that only as many windows as can be defined in the window buffer can be visible at any one time. The main reason why the window buffer's size is explicitly defined in the code, rather than using dynamic memory allocation is that if the program can load on a particular computer with x amount of memory, then it will run on that computer. The program is self-contained. OVERVIEW OF THE WINDOWING FUNCTIONS YOU MUST ALWAYS CALL W_INIT() BEFORE USING ANY WINDOWING FUNCTIONS. Do NOT neglect to do this, as several important data pointers are initialized. There are two kinds of functions available: those that are specific to the windowing environment, and those that are comple- mentary. The functions specific to windowing are preceded by "W_". 2 C Windowing Toolbox ---------------------------------------------------------------------- The four major windowing functions are: (1) Defining a window with W_DEF(). (2) Opening a window with W_OPEN(). (3) Closing the most recently opened window with W_CLOSE(). (4) Deallocating window(s) and releasing window buffer space with W_KILL(). The flag "err_exit" controls the action taken when a windowing error occurs. "err_exit" is declared as EXTERNal CHAR in C_WDEF.H. If you set "err_exit" to TRUE (default), the program will return to the operating system after an error message window is displayed. The name of the windowing function and what is wrong with what you are asking the function to do will be indicated in the error message window. If you set "err_exit" FALSE, for all windowing functions that return a status code (1 == OK, 0 == error), be sure to check that no error has occurred. If a windowing function returns an error code, do not ignore it. Terminate the program and check your code for the cause of the error. Often the problem is as simple as mixing the X and Y coordinates up, or not specifying enough arguments when a function is called. A window's width and height is specified when it is defined. When it is opened, it can be located at any location on the screen, as long as it doesn't stray outside of the screen's boundaries. If you have specified a border for a window, the writable area of the window is reduced to fit inside the border. THE UPPER LEFT CORNER OF THE WRITABLE AREA OF A WINDOW IS AT HORIZONTAL (X) COORDINATE 0 AND VERTICAL (Y) COORDINATE 0. IF NO WINDOWS ARE OPEN, WINDOWING COMMANDS ARE RELATIVE TO THE STANDARD 80 x 25 SCREEN. No more than one version of a defined window can be open at any one time, irregardless of screen placement. This is because each window's storage contains information about the section of screen it overlaid and opening a second version of the same window would overwrite that information. W_WRITE() is the windowing screen writing function. It does not attempt to interpret and act on any characters, including carriage returns and line feeds. The only action taken is to wrap-around on the active window if the cursor is at the right side of the window and to scroll up if the bottom of the window is reached. Any extra text handling will have to be added by you. The advantage is that you can write any character to a window with W_WRITE(). W_GETSTR() is the windowing screen string input function. You can specify the maximum length of an input string so that no borders are over-written. Character editing capabilities are included. The standard C function SSCANF() can be used to perform formatted input conversion on the string read by W_GETSTR(). 3 C Windowing Toolbox ---------------------------------------------------------------------- Any standard C input/output functions that involve outputting carriage returns or line feeds to the screen MUST be avoided when a window is open. The standard C input/output functions know nothing about the windowing environment and can easily write across a window's border. Functions like PRINTF() can be used with care, providing the user (1) first positions the cursor in a window with W_GOTOXY() (2) never sends a carriage return or line feed to the screen and (3) avoids writing across a window's border. All function calls must include all parameters, even if they are only dummy place-holders. For example, if a window has been defined without a border, the window opening function W_OPEN() must include all 8 parameters, even though the border specifications are ignored. The windowing code automatically selects 80 column alphanumeric mode whether you have a monochrome or graphics screen. The windowing functions W_FGCOLOR() and W_BGCOLOR() set character display attributes. Attribute definitions, controlling character color, intensity, etc, are contained in C_WDEF.H. To select standard white-on-black for either a monochrome or color screen, specify 0 (black) as the character background attribute and 7 (white) as the foreground attribute. The foreground and background bit masks defined in C_WDEF.H correspond to the the actual bit values in a character attribute byte. The integer variable "b_usage" is always set to the maximum amount of windowing buffer space used so far. You can use it to determine the smallest windowing buffer that will work with your program. 4 C Windowing Toolbox ---------------------------------------------------------------------- FUNCTIONS CONTAINED IN C WINDOWING TOOLBOX W_INIT - Initialize windowing Usage: w_init(); W_INIT() sets up pointers to the window buffer, detects the type of monitor (color or monochrome), selects 80 column alphanumeric mode, sets the display page to zero, and sets up initial window dimensions to 80 x 25. It also initializes the text foreground color to white and the text background color to black. If your computer is not an IBM PC or compatible, W_INIT will detect this and abort the program. YOU MUST CALL W_INIT() BEFORE CALLING ANY OTHER windowing FUNCTIONS. Failure to do this can cause random sections of memory to be overwritten. W_DEF - Define a window Usage: wnum = w_def (wid, hgt, border); int wnum; /* 0 if error, window access number otherwise */ int wid; /* Width of window, including optional border */ int hgt; /* Height of window, including optional border */ char border; /* TRUE (1) if border, FALSE (0) if no border */ Example: if ((w1 = w_def(x1, y1, TRUE)) == 0) /* w_def error handler here */ /* otherwise continue */ Define a window and reserve storage for it in the window buffer. A window must be defined before it is opened. The width and height parameters include the window border, if a border is specified. If the window has a border, then the writable area of the window is reduced to fit inside the border. For example, a bordered window that has a width of 30 and a height of 10 has writable coordinates of 0..27 in the horizontal (X) direction and 0..7 in the vertical (Y) direction. If the window didn't have a border, the X and Y ranges would be 0..29 and 0..9 respectively. You cannot define a window larger than the standard screen. Also, the window must not be smaller than three columns by three rows if a border is specified and one row by one column if no border is specified. In other words, at least one writable character position must be on the window. 5 C Windowing Toolbox ---------------------------------------------------------------------- Be sure to check the return code for 0, the error condition. Errors occur if the window is too small, too big, or if there is not enough room for the window in the window buffer. W_OPEN - Open a pre-defined window Usage: status = w_open (wnum, x, y, clear, wbgc, bdr_type, bfgc, bbgc); int status; /* 1 if success, 0 if error */ int wnum; /* Value returned by a previous W_DEF() */ int x; /* Horizontal coordinate of upper left corner */ int y; /* Vertical coordinate of upper left corner */ char clear; /* TRUE means pre-clear window, FALSE means retain previous contents */ char wbgc; /* Window background color */ char bdr_type; /* Border type (if specified by W_DEF()) */ char bfgc; /* Border foreground color */ char bbgc; /* Border background color */ Open a window that has been previously defined by a call to W_DEF(). If a window is being opened for the first time, then the contents of the window are initialized to spaces. If the window is being opened after having been previously open, the previous contents of the window will be re-displayed, unless "clear" is set to TRUE. The include file C_WDEF.H defines the six border types. "x" and "y" are absolute locations on the standard 80 x 25 screen and specify the location of the upper left corner of the window to be opened. "wbgc" is the background color for the window. Any spaces in the window will take on the background color attribute. Non-blank areas are not affected. Set this to 0 (black) for a monochrome screen. "bfgc" is the foreground color and "bbgc" is the background color of the border. The include file C_WDEF.H defines the colors available. If you have a color graphics adapter, you can set the background and foreground of the border to the same color to produce an extra thick border. Be sure to check the return code for 0, the error condition. Errors occur if wnum is to small or big, if the window is already open, or if the window won't fit on the screen at the absolute X,Y location specified. 6 C Windowing Toolbox ---------------------------------------------------------------------- W_CLOSE - Close a window Usage: w_close(); Close the most recently opened window and restore the previously overwritten section of screen. If you attempt to close the standard screen, W_CLOSE() will simply return, so extra W_CLOSE() calls are ignored. There is no error return code. W_KILL - Deallocate window(s) Usage: status = w_kill (wnum); int status; /* 1 if success, 0 if error */ int wnum; /* Number of window to kill */ Deallocate window, and all subsequently defined windows. For example: if ((w1 = w_def(x1, y1, FALSE)) == 0) /* Error handler here */ if ((w2 = w_def(x2, y2, TRUE)) == 0) /* Error handler here */ if ((w3 = w_def(x3, y3, TRUE)) == 0) /* Error handler here */ /* De-allocate w2. Also de-allocate w3, because */ /* it was defined after w2, but not w1, because */ /* it was defined before w2 */ if ((status = w_kill(w2)) == 0) /* w_kill error handler here */ When W_KILL() is called, all of the open windows on the screen are automatically closed. This is done because the deallocated window(s) may be partially or fully under a window that is not being deallocated. Be sure to check the return code for 0, the error condition. Errors occur if wnum is too small or too big or if no window is associated with wnum. 7 C Windowing Toolbox ---------------------------------------------------------------------- W_SCROLL - Scroll contents of window Usage: w_scroll (dir, num); int dir; /* Direction of scroll; 0 == up, 1 == down */ int num; /* Number of lines to scroll */ The current window is scrolled in "dir" direction for "num" lines. W_WRITE - Write a string to a window Usage: w_write (s); char *s; /* Pointer to string */ Display NULL terminated string in current window at location set by W_GOTOXY(). If the right hand side of the window is reached, the cursor will wrap-around to the next line. If the cursor reaches the bottom of the current window, the contents of the window will scroll up 1 line. The cursor will locate at the character position immediately beyond the last character in the string. No control characters are recognized, so any character can be displayed. W_FGCOLOR() and W_BGCOLOR() set the background and foreground attributes of the displayed character(s). See C_WDEF.H for the pre-defined display attribute values. W_GETSTR - Read string Usage: w_getstr (s, maxc); char *s; /* Pointer to input buffer */ int maxc; /* Max char count */ Read a string from the keyboard. Always position the cursor with W_GOTOXY() before calling W_GETSTR(). "maxc" is the maximum number of characters allowed. The cursor will not move beyond the limit specified by "maxc". For example, if "maxc" == 10, then only 10 characters can be entered. This is useful for avoiding over-writing a window's borders. You can edit the input string: (1) Pressing <RETURN> as the first keystroke leaves the input buffer unaltered. (2) If the first keystroke is a printable character, the 8 C Windowing Toolbox ---------------------------------------------------------------------- rest of the input buffer will be cleared. (3) The back-space key deletes one character to the left of the cursor. (4) The DEL key deletes the character above the cursor. (5) The left and right arrow keys move the cursor along the input buffer string. (6) The END key moves the cursor to the end of the string. (7) The HOME key moves the cursor to the beginning of the string. (8) Pressing <RETURN> ends the editing. The input buffer must be at least 1 byte longer than "maxc", to make room for the trailing '\0', which is always appended. W_FGCOLOR() and W_BGCOLOR() set the background and foreground attributes of the displayed character(s). See C_WDEF.H for the pre-defined display attribute values. W_DSP1 - Display 1 character Usage: status = w_dsp1 (x, y, ch); int status; /* 1 if success, 0 if error */ int x; /* X position */ int y; /* Y position */ char ch; /* character */ Display a single character at an X, Y location relative to the currently open window. The cursor will locate directly over the displayed character. If no windows are open, the X and Y coordinates correspond to absolute locations on the standard 80 x 25 screen. The upper left coordinate is (0, 0). W_FGCOLOR() and W_BGCOLOR() set the background and foreground attributes of the displayed character. See C_WDEF.H for the pre-defined display attribute values. Be sure to check the return code for 0, the error condition. An error occurs if the X,Y position is outside of the currently active window. W_FGCOLOR - Set text foreground color Usage: i = w_fgcolor(color); int i; /* 1 if success, 0 if error */ int color; /* foreground color bit mask */ 9 C Windowing Toolbox ---------------------------------------------------------------------- Set the text foreground color for text displayed by W_WRITE(), W_DSP1(), W_GETSTR() and BORDER(). The value of color can be one of the values defined in C_WDEF.H for foreground colors. Note that the foreground color is an exact attribute byte bit mask. Be sure to check the return code for 0, the error condition. An error occurs if "color" is less than 0 or greater than 255. W_BGCOLOR - Set text background color Usage: i = w_bgcolor(color); int i; /* 1 if success, 0 if error */ int color; /* background color bit mask */ Set the text background color for text displayed by W_WRITE(), W_DSP1(), W_GETSTR() and BORDER(). The value of color can be one of the values defined in C_WDEF.H for background colors. Note that the background color value is an exact attribute byte bit mask. Be sure to check the return code for 0, the error condition. An error occurs if the color value is less than 0 or greater than 255. W_GETCY - Get vertical (Y) position of cursor Usage: i = w_getcy(); int i; /* Y position */ This function returns the current Y position of the cursor, relative to the upper left corner (0, 0) of the writable part of the current window. If no windows are open, the Y position is relative to the upper left corner of the standard screen. W_GETCX - Get horizontal (X) position of cursor Usage: i = w_getcx(); int i; /* X position */ This function returns the current X position of the cursor, relative to the upper left corner (0, 0) of the writable part of the current window. If no windows are open, the X position is relative to the upper left corner of the standard screen. 10 C Windowing Toolbox ---------------------------------------------------------------------- W_GOTOXY - Move cursor Usage: status = w_gotoxy (x, y); int status; /* 1 if success, 0 if error */ int x; /* Horizontal position */ int y; /* Vertical position */ Go to specified X, Y location on the writable part of the current window. If you specified a border when you defined and opened the window, the writable part of the window is reduced to fit inside the border. For example, if you specified a window that was 10 x 10, and it had a border, then the horizontal (X) and vertical (Y) coordinates for W_GOTOXY() can vary between 0..7. If there are no windows open, the coordinates refer to the standard 80 x 25 screen. Be sure to check the return code for 0, the error condition. An error occurs if the X,Y position is outside of the currently active window. W_WRITEXY - Write a string to a window at X, Y Usage: w_write (x, y, s); int x,y; /* Location */ char *s; /* Pointer to string */ This function combines W_GOTOXY () and W_WRITE (). Display NULL terminated string in current window at location (X,Y). If the right hand side of the window is reached, the cursor will wrap- around to the next line. If the cursor reaches the bottom of the current window, the contents of the window will scroll up 1 line. The cursor will locate at the character position immediately beyond the last character in the string. No control characters are recognized, so any character can be displayed. W_FGCOLOR() and W_BGCOLOR() set the background and foreground attributes of the displayed character(s). See C_WDEF.H for the pre-defined display attribute values. 11 C Windowing Toolbox ---------------------------------------------------------------------- COMPLEMENTARY FUNCTIONS The following functions are not part of the windowing environment. They are included because they provide useful windowing support. BORDER - Draw border on screen Usage: status = border (x, y, wid, hgt, type); int status; /* 1 if success, 0 if error */ int x; /* Upper left horizontal position */ int y; /* Upper left vertical position */ int wid; /* Width of border */ int hgt; /* Height of border */ char type; /* Type of border */ Draw a border around an area of the screen. X and Y are absolute coordinates, relative to the standard 80 x 25 screen. The upper leftmost coordinate of the standard screen is (0, 0) and the lower right coordinate of the standard screen is (79, 24). There are six types of borders: (a) type = 0; /* Border outline is spaces */ (b) type = 1; /* Single line border, Horizontal and vertical */ (c) type = 2; /* Double line border, Horizontal and vertical */ (d) type = 3; /* Double horizontal lines, Single vertical lines */ (e) type = 4; /* Single horizontal lines, Double vertical lines */ (f) type = 5; /* Solid block horizontal and vertical */ The include file C_WDEF.H defines the border types listed above. W_FGCOLOR() and W_BGCOLOR() set the background and foreground attributes of the displayed character(s). See C_WDEF.H for the pre-defined display attribute values. Be sure to check the return code for 0, the error condition. An error occurs if the border type is not one of the types specified or if the border will not fit on the standard 80 x 25 screen. KEYIN - Read a keyboard character Usage: c = keyin(); char c; /* Character returned */ 12 C Windowing Toolbox ---------------------------------------------------------------------- Read the next character entered at the keyboard. The character is not echoed to the screen. C_WDEF.H declares a variable "extend" as EXTERNal CHAR. If the character location "extend" is set to TRUE (1) when KEYIN() returns, then the value returned by KEYIN() is the extended character code. Otherwise, the character is a regular ASCII character. For example: c = keyin(); if (extend) /* process function keys, etc */ else /* standard character */ BEEP - Sound speaker Usage: beep(count); int count; /* Duration */ Beep the speaker. A value of 500 for "count" gives a short chirp. "count" is an integer value, so it must not exceed 32,767. 13 C Windowing Toolbox ---------------------------------------------------------------------- GETTING THE C SOURCE You can get the C Windowing Toolbox source code for $15 from: Christopher McVicar 124 Wellington Heights Avon, Connecticut 06001 The above price includes North American shipping. Add $3 for overseas air mail shipping. I will include a receipt with every order so businesses can keep their records straight. The source will be on a DOS 2.1 formatted single sided 5 1/4" floppy diskette. Also on the diskette are: (1) A text file explaining what the Lattice C functions PEEK(), POKE(), and INT86() do. (2) Assembler sources for PEEK(), POKE(), and INT86(). (3) Assembler source and .OBJ files for an alternate screen display function that checks the horizontal retrace signal of the video display so that no "snow" appears when writing to the screen. (4) A text file indexer program with C source. (5) An ImagePrint demonstration. ImagePrint is a print quality enhancing program that my company sells. It runs on Epson (tm) compatible printers. DISCLAIMER Users of C Windowing Toolbox do so at their own risk. No representations as to the program's suitability for any purpose are made. Users of C Windowing Toolbox are entirely responsible for loss or damage of any kind caused by C Windowing Toolbox. RESTRICTIONS Non-commercial users of C Windowing Toolbox may use C Windowing Toolbox without any restrictions. Commercial users of C Windowing Toolbox, i.e. individuals or companies using or planning to use C Windowing Toolbox as part of a saleable product, must contact me, Christopher McVicar, and get written permission to include part or all of C Windowing Toolbox in their product. 14