Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / C / CXL.ZIP / CXL.DOC next >

Wrap

Text File | 1988-07-26 | 165.5 KB | 4,501 lines

C X L The C Programmer's Extended Function Library Version 4.0 July 27, 1988 by Mike Smedley Copyright (c) 1987, 1988 All Rights Reserved Reference Manual 1 TABLE OF CONTENTS Page Introduction..................................6 Features of the Library...................6 Registration Information..................7 How to Contact the Author.................7 Disclaimer................................8 Trademarks................................8 Tutorial......................................9 Windowing Functions (General).............9 Formatted Keyboard Input Functions.......10 Multi-Field Formatted Input Functions....13 Bar-Selection Menu Functions.............16 String Selection Functions...............20 Expanded Memory (EMS) Functions..........21 Mouse Functions..........................23 Global Variables.............................24 _cgasnow.................................24 _kbloop..................................24 _mouse...................................24 _onkey...................................24 _videoseg................................24 _werrno..................................24 _wesc....................................24 _whandle.................................24 _winp....................................24 _wmenu...................................25 _wrec....................................25 _wsel....................................25 _wtotal..................................25 Library Functions............................26 attrib...................................26 beep.....................................26 biosver..................................26 box_.....................................26 boxd.....................................27 capsoff..................................27 capson...................................27 clearkeys................................27 clockcal.................................27 clreol_..................................28 clrscrn..................................28 clrwin...................................28 cvaltype.................................28 delay_...................................29 disktoscrn...............................29 disktowin................................29 emsalloc.................................29 emsdealloc...............................30 emsexist.................................30 emsframe.................................30 emsfree..................................30 emsmap...................................31 2 emsread..................................31 emstotal.................................31 emsver...................................31 emswrite.................................32 expmem...................................32 extmem...................................32 fill_....................................32 filld....................................33 gameport.................................33 getchf...................................33 getns....................................34 getxch...................................34 gotoxy_..................................34 inputsf..................................34 kbstat...................................35 lcrlf....................................35 lprintc..................................35 lprintf..................................36 lprintns.................................36 lprints..................................36 lprintsb.................................36 lprintsu.................................36 machid...................................37 mathchip.................................37 mode.....................................37 msbpress.................................37 msbreles.................................38 mscursor.................................38 msgotoxy.................................38 mshbounds................................39 mshidecur................................39 msinit...................................39 msmotion.................................39 msshowcur................................40 msspeed..................................40 msstatus.................................40 msvbounds................................40 numflop..................................40 numoff...................................41 numon....................................41 numpar...................................41 numser...................................41 printc...................................41 printcd..................................42 prints...................................42 printsd..................................42 readchat.................................43 readcur..................................43 revattr..................................43 scrndump.................................43 scrntodisk...............................43 setattr..................................44 setcursz.................................44 setkbloop................................44 setlines.................................44 setonkey.................................45 sound_...................................45 3 spc......................................46 srestore.................................46 ssave....................................46 strblank.................................46 strbmatch................................46 strchg...................................47 strcode..................................47 strdel...................................47 strichg..................................48 stridel..................................48 striinc..................................48 strinc...................................49 strins...................................49 striocc..................................49 strleft..................................50 strltrim.................................50 strmatch.................................50 strmid...................................50 strocc...................................51 strright.................................51 strrol...................................51 strror...................................52 strsetsz.................................52 strshl...................................52 strshr...................................52 strtrim..................................53 struplow.................................53 sysdate..................................53 systime..................................54 tabstop..................................54 timer....................................54 touplow..................................54 videoinit................................55 vidtype..................................55 wactiv...................................55 waitkey..................................56 waitkeyt.................................56 waitvret.................................56 wblocked.................................56 wborder..................................57 wbox.....................................57 wcclear..................................57 wcenters.................................57 wchgattr.................................58 wclear...................................58 wclose...................................58 wcloseall................................58 wclreol..................................59 wclreos..................................59 wcopy....................................59 wdelline.................................59 wdupc....................................60 werrmsg..................................60 wfill....................................60 wfindrec.................................60 wgetc....................................61 wgetchf..................................61 4 wgetns...................................62 wgets....................................62 wgotoxy..................................62 whandle..................................63 whide....................................63 whline...................................63 winpdef..................................63 winpread.................................64 winputsf.................................64 winsline.................................65 wintodisk................................65 wisactiv.................................65 wmenudef.................................66 wmenuget.................................66 wmessage.................................67 wmove....................................67 wopen....................................68 wperror..................................68 wpgotoxy.................................68 wprintc..................................69 wprintf..................................69 wprints..................................69 wputc....................................70 wputns...................................70 wputs....................................70 wrestore.................................70 wrjusts..................................71 wsave....................................71 wsbounds.................................71 wscanf...................................72 wscroll..................................72 wsetesc..................................72 wsize....................................72 wsseldef.................................73 wsselget.................................73 wtextattr................................73 wtitle...................................74 wunhide..................................74 wvline...................................74 5 INTRODUCTION The CXL library is intended to be a supplement to your compiler's run-time library. It contains over 170 multi-purpose functions. The main feature is the windowing system. There are many supporting features as well. The library is available for several of today's popular C compilers. These routines were written in highly-optimized C code ensuring maximum program speed and minimum program size. This release is an evaluation release containing everything you need to write C programs using the small memory model. The libraries for the other memory models are supplied when you register. Features of the CXL Library. - Multi-layered, overlapping windowing system - Pop-up menus - Pull-down menus - Lotus-style menus - Multi-field keyboard data entry - Formatted keyboard input - EGA 43-line and VGA 50-line modes - DESQview compatibility - Microsoft compatible mouse functions - Lotus/Intel/Microsoft EMS memory functions - Screen/window swapping to memory or disk - Direct screen writing for fast screen writes - Advanced string manipulation - Keyboard event trapping - Simple context sensitive help - Pattern matching - Data encryption - Date and time functions - Equipment detection - Printing functions - Sound functions - and more! 6 Registration Information. You are free to copy and distribute this library freely, however, if you find this library of use to you, you are encouraged to register your copy. The registration cost is only $25! Included in the registration cost is: - two 5.25-inch diskettes containing: - the complete library source code! (100% native C code). - libraries for the remaining memory models. - royalty-free use of library functions. - technical support. - low-cost upgrades to future revisions. - shipping and handling. To register, print the registration form, REGISTER.DOC, by typing the command "copy register.doc prn" from the DOS prompt and fill in the requested information. Or you can use any piece of paper and include on it your name, address, phone number, CompuServe/GEnie mail address, CXL version, your compiler and its version, where you received CXL from, and any comments. Non-U.S. orders add $5 for air mail. Send payment along with registration information to: Mike Smedley P.O. Box 33603 San Antonio, TX 78265 How to Contact the Author. U.S. Mail - see address above Telephone - (512) 590-2910 (after 5 PM & weekends, not collect) BIX - msmedley CompuServe - 71331,2244 GEnie - M.SMEDLEY Abbey Road BBS - (512) 590-6036 1200/2400/9600 8-N-1 Telstar BBS - (512) 822-8882 1200/2400 8-N-1 7 Disclaimer. The author claims no responsibility for any damages caused by the use or misuse of this library. This product is distributed "as is" with no warranty expressed or implied. The author will not be responsible for any losses incurred by the use of this product. The author reserves the right to make modifications at any time. Prices are subject to change without notice. Trademarks. BIX is a trademark of McGraw-Hill Inc. CompuServe is a registered trademark of CompuServe Incorporated. DESQview is a trademark of Quarterdeck Office Systems. Epson is a registered trademark of Seiko Epson Corporation. GEnie is a trademark of GE Information Services. IBM is a registered trademark of International Business Machines. LIM and EMS are trademarks of Lotus, Intel, and Microsoft Corps. Lotus is a registered trademark of Lotus Development Corporation. Microsoft is a registered trademark of Microsoft Corporation. Turbo C is a registered trademark of Borland International. Zortech is a trademark of Zortech Limited. 8 TUTORIAL Windowing Functions (General). CXL has a a powerful windowing system that can be very useful in an application program. All windowing functions are prefixed with a 'w'. The windowing is controlled by CXL's window manager which is called by every windowing function. The window manager keeps track of which window is active; each window's position, cursor location, attributes, etc.; how many windows are open; and other information. All windowing functions set the _werrno global variable before returning. The literal value of this variable can be viewed by calling the werrmsg() function. This feature is useful for debugging programs that use the windowing functions. Windows can have a border or be borderless. Borderless windows have a greater effective region of which to work with. Window borders can be a variety of styles. Windows may also have titles. If the window has a border, the title will be displayed on the top border. The window title can also be used to name a window allowing easier identification. You may open as many windows as memory permits. Once a window is opened, it immediately becomes the active window. CXL's windowing functions can only be performed on the active window. If you want to perform a function on a inactive window, you must activate it first. Once you have a window opened, you may perform a variety of tasks in it including displaying output, accepting input, resizing, changing colors, moving, changing border style, and more. See the supplied CXLDEMO.C program for a complete example of how to use the windowing system. Example: WINDOW w1,w2; /* window handles */ /* open 1st window */ w1=wopen(0,0,10,40,0,LCYAN|_BLUE,LCYAN|_BLUE); if(!w1) error_routine(); /* check for error */ wputs("Hello, "); /* display string */ /* open 2nd window */ w2=wopen(7,20,18,60,2,LRED|_MAGENTA,LRED|_MAGENTA); if(!w2) error_routine(); /* check for error */ wputs("Hello, "); /* display string */ wactiv(w1); /* activate 1st window */ wputs("there"); /* display string */ wactiv(w2); /* activate 2nd window */ wputs("there"); /* display string */ wclose(); /* close 2nd window */ wclose(); /* close 1st window */ 9 Formatted Keyboard Input Functions. The inputsf() and winputsf() functions in CXL accept keyboard input through the use of CXL's own input format strings. These format strings are not the same as what scanf() uses. They have the ability to restrict and convert input for each character received from the keyboard. They also allow for custom prompts between each character input. The format control characters can be in any order in the string, but all letters must be in the case shown here. Invalid control characters will cause the function to return an error and the receiving string will be empty. Spaces can be used to improve readability of the format string. If the Escape key is not disabled, when pressed it will return an error code and the receiving string will be empty. Valid format control characters are: !.......! - start and end exclamation points, any letters between them are format command toggles. The valid format command toggles are: - - decreases text attribute, works with winputsf() only + - increases text attribute, works with winputsf() only C - toggles copying of display (quoted) characters to the receiving string. (default is off) E - toggles Escape key checking off/on. When off, if the Escape key is pressed, the function returns an error code and the string will be null. The default for inputsf() is on. For winputsf(), the default is the value of the global variable _wesc upon calling. L - toggles lower-case conversion. When on, the case of input letters will be forced to lower case. (default is off) M - toggles mixed-case conversion. When on, the case of input letters will be forced to upper-case for the first letter of each word and lower-case for the remaining letters. (default is off) P - toggles password mode. When on, input characters will be echoed to the screen as spaces. (default is off) R - toggles return key checking. When off, the carriage return key will be ignored until the end of the format string. (default is on) U - toggles upper-case conversion. When on, the case of input letters will be forced to 10 upper-case. (default is off) '.......' - start and end quotes, any characters between them will .OR. be displayed as text. If the 'C' command toggle is \".....\" on, the characters will also be copied to the receiving string. # - accept numeric character '0' thru '9'. 9 - accept numeric character '0' thru '9', '.', '-', and '+'. ? - accept any character. * - accept any printable character. A - accept alpha character 'A' thru 'Z', 'a' thru 'z', and space. D - accept character associated with a numeric date '0' thru '9', '-', and '/'. L - accept alpha character 'A' thru 'Z', 'a' thru 'z', and space. Input characters will be converted to lower case. M - accept alpha character 'A' thru 'Z', 'a' thru 'z', and space input character will be converted to mixed case. P - accept alphanumeric password character 'A' thru 'Z', 'a' thru 'z', '0' thru '9', and space. T - accept character associated with a telephone number '0' thru '9', '(', ')', '-', and space. U - accept alpha character 'A' thru 'Z', 'a' thru 'z', and space input character will be converted to upper case. X - accept alphanumeric character 'A' thru 'Z', 'a' thru 'z', '0' thru '9', and space. Y - accept a yes/no character 'Y', 'y', 'N', and 'n'. <.......> - set inclusion. Accept a character from valid list of characters between angle brackets. [.......] - set exclusion. Accept a character which cannot be present in between the square brackets. Examples: inputsf(str,"'Enter name: ' !UR! XXXXX !R! XXXXXXXXXX"); Prompts for name, inputs string from keyboard converting characters to upper case as it goes, allows up to 15 alphanumeric characters as input. The return key is disabled until at least 5 characters have been entered. Characters will be copied to str. This space must already be allocated! inputsf(str,"!R! 'Enter phone: '!C! '(' ### ') ' ### '-' ####"); Prompts for a full phone number including area code, allows only digit characters and displays format punctuation as it goes. The entire field must be filled before return can be pressed. All of the characters except the prompt will be copied to the receiving string. The input string will be copied to str, which must have already been allocated. 11 inputsf(str,"!R!'Enter SSAN: '<0123456>##'-'##'-'####"); Prompts for a Social Security number. Will not allow return to be pressed until all digits have been entered. The first digit of the SSAN must be 0 - 6. Dashes will be displayed as you are typing in the data, but will not be contained in the receiving string str. inputsf(str,"!R!'Enter DOB (MM/DD/YY): '<01>#'/'<0123>#'/'##"); Prompts for Date of Birth. Allows only valid digits for the input date. Prevents the return key from working until all digits have been typed in. 12 Multi-Field Formatted Input Functions. Two functions are needed to process multi-field keyboard input from windows: winpdef(), and winpread(). The winpdef() function defines your input field and is called for each input field to be defined. The winpread() function processes all defined fields. The formatted input capabilities are much like those of the inputsf() and winputsf() functions. The major difference is that with the winpdef()/winpread() combination, you can edit back and forth between fields before finally accepting the input. For every input field you want to define, you must call winpdef(). This will allocate memory to hold the input record information. The first two parameters, wrow and wcol, specify where in the active window the field will be loaded. The next parameter, str, is the address of the string buffer to receive the input data. The next parameter, format, is the input field format string. It controls how each character is input and how large the input field will be. It consists of 1 or more format characters, and may have displayed text in between any of the format control characters. You may use spaces in between the format control characters for readability. Valid format control characters are listed in the "Formatted Keyboard Input Functions" section. The case of the format control characters must be as shown. Format strings for winpdef() are just like those of inputsf() and winputsf() except there are no command toggles. If you make a syntax error in the format string, winpdef() will return W_INVFORMT to notify you of the mistake. The next parameter in the winpdef() function is fconv. These are similar to the command toggles of inputsf() and winputsf() except that the fconv character applies conversion to the whole field. Valid fconv characters are: 0 - apply no conversion 'L' - convert letters to lower case 'M' - convert letters to mixed upper & lower case 'P' - password field (do not echo characters) 'U' - convert letters to upper case The next parameter in the winpdef() function is fattr. This is the text attribute of the screen field. After the fattr parameter comes the update parameter. This parameter allows you to specify if the input field is going to create new data or update old data. If the update parameter is 0, then the input field will be used for entering new data. If the update parameter is non-zero, then the input field will be used to update the old data contained in the str parameter. If you do choose to update, then the length of the str string must be the same as the length of the input field defined in the format string. If the two lengths don't match, then winpdef() will return W_LENFORMT. The last parameter in the winpdef() function is validate. This parameter is the address of an optional user validation/modification function. If no validation function is to be used, then specify NULL. Your user validation/modification function must be declared like: 13 int func(char *str); where str is the address of the input field that will be passed to it. Once your user function has the address of the input field, you can validate and/or modify the input field. Your function can also display an error message, sound a bell, or just about anything. When your function is done, it must return 0 for no error. Once you have defined all input fields with winpdef(), you call winpread() to process them. The user is allowed to move around and edit all of the fields. The input fields are validated on the fly and after entering the last field. Valid editing keys are: LeftArrow - moves cursor left a position. RightArrow - moves cursor right a position. UpArrow - moves cursor to the previous field up. DownArrow - moves cursor to the next field down. Ctrl-LeftArrow - moves cursor to previous word left. Ctrl-RightArrow - moves cursor to next word right. Tab - moves cursor to the next field right. Shift-Tab - moves cursor to the previous field left. Enter - if the cursor is in the last field on the screen, it will process all fields. Otherwise it will skip to the next field. Ctrl-Enter - processes all fields, wherever cursor may be Home - moves cursor to first position of field. End - moves cursor to last position of field. Ctrl-Home - moves cursor to the first position of the first field on the screen. Ctrl-End - moves cursor to the last position of the last field on the screen. Ins - inserts a space at cursor location. All text to the right of the cursor will be shifted right. The end character will be dropped. Del - deletes character at the cursor location. All text to the right of the cursor will be shifted left and a space will be inserted at the end of the field. BackSpace - deletes a character to the left. Ctrl-BackSpace - deletes a word to the left. Text following the word will be shifted left. Ctrl-T - deletes a word to the right. Text following the word will be shifted left. Ctrl-U - deletes all characters from current cursor postion to end of field. Ctrl-Y - deletes all characters in all fields from current cursor position to end of last field. Esc - if enabled, cancels input and returns a W_ESCPRESS value. Escape checking can be enabled or disabled by calling the wsetesc() function before winpread() is called. After the winpread() function is called, all fields defined with winpdef() will be cleared. The receiving strings of all defined fields will now contain the data entered. If Escape checking was on and the Esc key was pressed, then all receiving strings will contain the values 14 they held before winpread() was called and W_ESCPRESS will be returned. 15 Bar-Selection Menu Functions. Two functions are needed to use CXL's bar-selection menus: wmenudef(), and wmenuget(). These two functions can be used as part of a pull-down, pop-up, Lotus-style, or any other bar-selection menu system. The wmenudef() function defines a menu record in memory and displays the menu option on the screen. The wmenuget() function processes the user's selection and deallocates the defined menu records. The wmenudef() function accepts 7 parameters. The first two parameters, wrow and wcol, indicate where in the active window the menu option will be displayed. The 3rd parameter, attr, is the text attribute of the menu option. The 4th parameter, str, is the address of the string containing the menu option. The 5th parameter, tagchar, is used for identification of the menu option. The tag character may be any ASCII character (value 0 - 255). Lower case tag characters will automatically be converted to upper case. The 6th parameter, tagattr, is the attribute of the tag character (if the tag character is present in the menu option). The last parameter, desc, is the address of a text description of the menu option. This is only used if you plan to use Lotus-sytle menus, otherwise specify NULL. When all menu options have been defined, you will call the wmenuget() function. The first argument to wmenuget() is the attribute of the selection bar. The second argument is the tag character of where you want the selection bar to initially be located. If an undefined tag character is used, then the initial position of the selection bar will default to the upper-leftmost option. The third argument of wmenuget() is the pulldown parameter. This is used for a pull-down menu system. If a pull-down menu system is not being used, then the pulldown parameter should be specified as zero. If you are using pull-down menus, then the pulldown parameter may have one of four values. PDMAIN is used to signify that the menu you have just defined is to be the main menu (usually the horizontal bar across the top) of a pull-down menu system. PDMENU is used to signify that the menu you have just defined is one of the pull-down menus from the main menu. The other two values that the pulldown parameter can have are used for movement between pull-down menus. PDPREV is used to signify that the menu you have just defined is the main menu and you wish to automatically select the option previous to the specified taginit. PDNEXT is used to signify that the menu you have just defined is the main menu and you wish to automatically select the next option after the specified taginit. A mouse can be used for motion/selection of menu options. The mouse must first be initialized with a call to msinit(). It is also recommended that you adjust the mouse sensitivity by calling msspeed(128,32) - the recommended settings for pull-down menus. Keyboard movement/selection keys that can be used during the wmenuget() function are: LeftArrow - moves selection bar to previous option left. If inside a pull-down menu, pressing this will cause 16 wmenuget() to return PDPREV. RightArrow - moves selection bar to next option right. If inside a pull-down menu, pressing this will cause wmenuget() to return PDNEXT. UpArrow - moves selection bar to previous option up. DownArrow - moves selection bar to next option down. If pull-down menus are being used and you are currently in the main menu, then the option that the selection bar is on is selected. Tab - moves selection bar to next option right. Shift-Tab - moves selection bar to previous option left. Enter - selects the option that the selection bar is on. Pressing the left mouse button will have the same effect. Home - moves selection bar to upper left option. End - moves selection bar to lower right option. Esc - if enabled, cancels input and returns a zero. Escape checking can be enabled or disabled by using the wsetesc() function before wmenuget() is called. If inside a pull-down menu, pressing this will cause wmenuget() to return PDMAIN. Pressing the right mouse button will have the same effect. When an option is selected, it's tag character will be returned by wmenuget(). The tag character will be in the same case as when defined. If the Esc key was pressed and Escape checking was on, a zero will be returned and the global variable _werrno will be set to W_ESCPRESS. If any other error occurred, the return value will be zero and the global variable _werrno will be set to an error code (see CXLWIN.H). Once a selection is made, the wmenuget() function automatically clears all menu options defined by wmenudef(). If you are using wmenuget() to process a pull-down menu (PDMENU), and the LeftArrow or RightArrow key is pressed, then wmenuget() will return PDPREV or PDNEXT, respectively. This allows you to input these return values back into the main menu's wmenuget() pulldown parameter to automatically select the previous or next pull-down window from the current pull-down window. The Escape checking status will be ignored while inside a pull-down menu. Instead, if in a pull-down menu (PDMENU), and the Esc key is pressed, wmenuget() will return PDMAIN, which allows you to reinput that value back into the main menu's wmenuget() pulldown parameter. If your pull-down system needs 3rd-level menus, they should be defined as pop-up menus (pulldown = 0). Example for a Vertical Pop-Up Menu: int selection; /* open the window */ wopen(5,10,20,50,4,LMAGENTA|_RED,LMAGENTA|_RED); /* define the menu */ wmenudef(2,2,LGREEN|_RED,"Add record",'A',WHITE|_RED,NULL); wmenudef(4,2,LGREEN|_RED,"Delete record",'D',WHITE|_RED,NULL); wmenudef(6,2,LGREEN|_RED,"Print record",'P',WHITE|_RED,NULL); wmenudef(8,2,LGREEN|_RED,"Update record",'U',WHITE|_RED,NULL); /* process the menu, load selection bar at the definition for 'A' */ 17 selection=wmenuget(LRED|_GREEN,'A',0); wclose(); /* close the window */ Example for a Horizontal Lotus-Style Menu: int selection; /* open the window */ wopen(7,15,10,65,0,YELLOW,LCYAN|_BLUE); /* define the menu */ wmenudef(0,0,LMAGENTA|_BLUE,"Add",'A',WHITE|_BLUE, "Create a new record"); wmenudef(0,8,LMAGENTA|_BLUE,"Delete",'D',WHITE|_BLUE, "Delete an existing record"); wmenudef(0,19,LMAGENTA|_BLUE,"Print",'P',WHITE|_BLUE, "Print hardcopy of existing record"); wmenudef(0,28,LMAGENTA|_BLUE,"Show",'S',WHITE|_BLUE, "Display an existing record on screen"); wmenudef(0,36,LMAGENTA|_BLUE,"Update",'U',WHITE|_BLUE, "Modify an existing record"); wmenudef(0,45,LMAGENTA|_BLUE,"Quit",'Q',WHITE|_BLUE, "Quit program and return to DOS"); wtextattr(LGREEN|_BLUE); /* attribute of text description */ /* process the menu, load the selection bar at 'A'dd. */ selection=wmenuget(YELLOW|_LGREY,'A',0); wclose(); /* close the window */ Model for a Complete Pull-Down Menu System: int m1,m2; m1='F'; /* init main menu */ m2=PDMAIN; while(m1) { /* or use " for(;;) { " */ wmenudef( ); /* define main menu */ wmenudef( ); wmenudef( ); m1=wmenuget(attrib,m1,m2); /* get main menu selection */ switch(m1) { /* test main menu selection */ case 'F': wopen( ); /* open pull-down menu */ m2='L'; /* init pull-down menu */ while(m2>PDMENU) { wmenudef( ); /* define pull-down menu */ wmenudef( ); wmenudef( ); /* get pull-down menu selection */ m2=wmenuget(attrib,m2,PDMENU); switch(m2) { /* test pull-down menu selection */ case 'A': funca(); break case 'B': funcb(); break; 18 } } wclose(); /* close pull-down menu */ break; case 'E': .... break; case 'D': .... break; } } 19 String Selection Functions. There are two functions needed for string selection: wsseldef() and wsselget(). The wsseldef() function defines a string selection record and is called for every string selection you want to define. The wsselget() function processes all of the defined string selection records and returns the address of the string that was selected. The following keys can be during string selection: Enter - selects the displayed selection string LeftArrow - previous selection string UpArrow - " " " Shift-Tab - " " " RightArrow - next selection string DownArrow - " " " Tab - " " " Esc - if Escape checking is on, then pressing this will cause wsselget() to return NULL and set the global variable _werrno to W_ESCPRESS. Escape checking is on by default, but you can use wsetesc(0) to turn it off. This is the way it works: char *prn; FILE *fpout; .... wsseldef("PRN"); /* define each possible string */ wsseldef("LPT1"); wsseldef("LPT2"); wsseldef("COM1"); wsseldef("COM2"); wputs("Select printer: "); /* display prompt */ prn=wsselget(YELLOW|_BLUE); /* get selection from keyboard */ if(prn==NULL) { /* test for error */ error_routine(); } fpout=fopen(prn,"w"); .... What the display would initially look like is: Select printer: PRN and by using the arrow keys, you can change the selection. Once Enter is pressed, the selection will be made. 20 Expanded Memory (EMS) Functions. CXL contains several functions for simple management of expanded memory. All of CXL's EMS functions are prefixed with 'ems'. For those not familiar with expanded memory, I will briefly explain it. The 8088 microprocessor is only able to address 1 Megabyte of memory. When applications started needing more memory, Lotus, Intel, and Microsoft developed the Expanded Memory Specification. This specification allows access to more than 1 Megabyte of memory by mapping 16K 'windows' of memory on an expanded memory board in and out of an unused area of DOS memory. The Expanded Memory Manager (EMM) is a software driver that controls the mapping. Physical pages are 16K blocks of memory which are located in an unused area of DOS memory. There are typically 4 physical pages comprising a 64K contiguous area of mappable DOS memory. The EMS page frame base address points to the beginning of the first physical page. Logical pages are 16K blocks of memory on the expanded memory board. There can be as many logical pages as the expanded memory board has, up to 8 Megabytes. Every program that uses expanded memory must do the following: 1. determine if the EMM device driver is loaded 2. determine if there are enough free pages for its application 3. allocate pages of expanded memory 4. find out what the EMS page frame base address is 5. map logical pages onto physical pages 6. deallocate pages when finished with them Here's an example of using CXL's EMS functions to perform these procedures: int handle1,handle2; char buf[14]; if(!emsexist()) { /* check for the EMM driver */ printf("EMM not loaded\n"); exit(1); } handle1=emsalloc(2); /* request 2 pages of EMS memory */ handle2=emsalloc(2); /* request 2 more pages */ if(handle1==-1 || handle2==-1) {/* test for allocation error */ printf("EMS allocation error\n"); exit(1); } emsmap(handle1,0,0); /* map logical page 0 of handle 1 to physical page 0 */ emswrite("Hello, world",0,13); /* write a string at offset 0, automatically determines what the page frame address is */ emsmap(handle2,0,0); /* map logical page 0 of handle 2 to physical page 0 */ emswrite("How are you?",0,13); /* write a string at offset 0 */ 21 emsmap(handle1,0,0); /* map logical page 0 of handle 1 to physical page 0 */ emsread(buf,0,13); /* read 13 bytes from offset 0 into buffer */ printf("buf = %s\n",buf); /* display buffer contents */ emsmap(handle2,0,0); /* map logical page 0 of handle 2 to physical page 0 */ emsread(buf,0,13); /* read 13 bytes from offset 0 into buffer */ printf("buf = %s\n",buf); /* display buffer contents */ emsdealloc(handle2); /* deallocate pages belonging to handle 2 */ emsdealloc(handle1); /* deallocate pages belonging to handle 1 */ 22 Mouse Functions. CXL has several functions used to facilitate Microsoft compatible mice. All of these functions are prefixed with am 'ms'. These functions will work on Microsoft mice or other mice using a Microsoft compatible driver. These mouse functions allow you to: 1. Initialize mouse/determine if mouse exists. 2. Get the status of button presses/releases. 3. Hide/reveal the mouse cursor. 4. Get/set the mouse cursor position. 5. Select type of mouse cursor (hardware or software). 6. Adjust the mouse sensitivity (speed). 7. Get information on direction of mouse movement. 8. Establish horizontal/vertical boundaries of mouse movement. When reading or setting mouse coordinates, the values used are in pixels. To calculate mouse coordinates in terms of column and row instead of X and Y, you would multiply character width by column, and character height by row. Typically, screen characters are 8 pixels wide by 8 pixels tall. So, to position the mouse cursor at column 60, row 15, you would use: msgotoxy(60*8,15*8); The mscursor() function sets the cursor type. It takes 3 parameters: ctype, smask, and cmask. If ctype = 1 then the cursor type is hardware. The hardware cursor is the flashing block on your screen. If this type of cursor is used, it will interfere with normal text cursor functions. When using the hardware cursor type, the value for smask is the start scan line of the cursor, and the value for cmask is the stop scan line of the cursor. If the ctype parameter = 0, then a software cursor is used. For the software cursor, the smask parameter is the screen mask, and the cmask parameter is the cursor mask. The screen mask determines which of the characters attributes are preserved. The cursor mask defines how the attributes are changed to show the cursor. For both masks, the bit values are as follows: Bits 0-7: ASCII value of character Bits 8-10: Foreground color Bit 11: Intensity Bits 12-14: Background color Bit 15: Blink The msmotion() function determines direction and distance traveled since last msmotion() call. The xcount and ycount parameters will either be negative or positive depending on direction mouse moved. The amount will be the number of pixels travelled. When updating the screen, the mouse cursor should be hidden with the mshidecur() function first, and then after the screen is updated, the msshowcur() should be called to re-display the mouse cursor. 23 GLOBAL VARIABLES Name: _cgasnow Purpose: a flag that tells CXL's functions whether or not to use CGA snow reduction. Defaults to 0 (off). To enable CGA snow reduction, set this variable to 1. Type: int Name: _kbloop Purpose: points to a procedure to be called while waiting for a keypress. Type: void (*) (void) Name: _mouse Purpose: this is set by the msinit() function. It contains a zero if a mouse is not installed or a non-zero if mouse is installed. Type: int Name: _onkey Purpose: a pointer which points to the highest defined onkey record. Type: struct _onkey_t * (see CXLKEY.H for definition) Name: _videoseg Purpose: contains the current video RAM segment address used by direct screen writes. Defaults to 0xb800. The videoinit() function may update this variable. Type: unsigned int Name: _werrno Purpose: contains the error code from the most recently performed windowing function. See CXLWIN.H for a complete list of possible error codes. Type: int Name: _wesc Purpose: Escape key checking flag. This is set by the wsetesc() function and used by several window keyboard input functions. Type: int Name: _whandle Purpose: contains the last handle number given to a window. Type: WINDOW Name: _winp 24 Purpose: a pointer to the highest defined window keyboard input record. Type: struct _winp_t * (see CXLWIN.H for definition) Name: _wmenu Purpose: a pointer to the highest defined bar-selection menu record. Type: struct _wmenu_t * (See CXLWIN.H for definition) Name: _wrec Purpose: a pointer to the active window's record. Type: struct _wrec_t * (see CXLWIN.H for definition) Name: _wsel Purpose: a pointer to the highest defined string selection record. Type: struct _wsel_t * (see CXLWIN.H for definition) Name: _wtotal Purpose: contains the total number of open windows Type: int 25 LIBRARY FUNCTIONS Name: attrib Purpose: creates an attribute. Prototype: int attrib(int fore,int back,int bright,int blink); Header: cxlvid.h cxlwin.h Inputs: fore - foreground color code (0-7) back - background color code (0-7) bright - intensity (0-1) blink - blinking (0-1) Return: attribute Also see: setattr wtextattr Example: prints(15,10,attrib(7,5,1,0),"Hello, world"); Name: beep Purpose: sounds a beep in the speaker. Prototype: void beep(void); Header: cxldef.h cxlvid.h Inputs: none Return: none Also see: sound_ Example: beep(); Name: biosver Purpose: returns the ROM BIOS version date. Prototype: char *biosver(void); Header: cxldef.h Inputs: none Return: address of the static string containing the ROM BIOS version date Also see: machid Example: printf("ROM BIOS version date is %s\n",biosver()); Name: box_ Purpose: displays a text box on the screen. Prototype: void box_(int srow,int scol,int erow,int ecol,int btype, int attr); Header: cxlvid.h Inputs: srow - starting row upper left corner scol - starting column upper left corner erow - ending row lower right corner ecol - ending column btype - box type (0-5) attr - attribute Return: none Also see: boxd Example: box_(0,0,22,79,1,WHITE|_BLUE); 26 Name: boxd Purpose: displays a text box directly on the screen (no BIOS calls). Prototype: void boxd(int srow,int scol,int erow,int ecol,int btype, int attr); Header: cxlvid.h Inputs: srow - starting row upper left corner scol - starting column upper left corner erow - ending row lower right corner ecol - ending column btype - box type (0-5) attr - attribute Return: none Also see: box_ videoinit Example: boxd(0,0,22,79,1,WHITE|_BLUE); Name: capsoff Purpose: toggles the CapsLock key off. Prototype: void capsoff(void); Header: cxlkey.h Inputs: none Return: none Also see: capson kbstat numoff Example: capsoff(); Name: capson Purpose: toggles the CapsLock key on. Prototype: void capson(void); Header: cxlkey.h Inputs: none Return: none Also see: capsoff kbstat numon Example: capson(); Name: clearkeys Purpose: clears the keyboard buffer. Prototype: void clearkeys(void); Header: cxlkey.h Inputs: none Return: none Also see: waitkey Example: clearkeys(); Name: clockcal Purpose: determines if a clock-calendar board is installed (usually this board will only be in XT machines). Prototype: int clockcal(void); Header: cxldef.h 27 Inputs: none Return: a non-zero value if a clock-calendar board is present Example: printf("A clock-calendar is%s installed\n", clockcal()?"":" not"); Name: clreol_ Purpose: clears to the end of line using current attribute. Prototype: void clreol_(void); Header: cxlvid.h Inputs: none Return: none Also see: clrscrn clrwin Example: clreol_(); Name: clrscrn Purpose: clears the screen (up to 50 lines) using current attribute, and homes the cursor. Prototype: void clrscrn(void); Header: cxlvid.h Inputs: none Return: none Also see: clreol_ clrwin Example: clrscrn(); Name: clrwin Purpose: clears a window of the screen using current attribute. Prototype: void clrwin(srow,scol,erow,ecol); Header: cxlvid.h Inputs: srow - starting row upper left corner scol - starting column upper left corner erow - ending row lower right corner ecol - ending column lower right corner Return: none Also see: clreol_ clrscrn Example: clrwin(11,11,19,19); Name: cvaltype Purpose: checks given character against a given CXL character type code, determines if character is valid type. Prototype: int cvaltype(int ch,int ctype); Header: cxlstr.h Inputs: ch - character to test ctype - character type code to compare with, see section on CXL format strings for a list of valid character type codes. Return: a 0 if character is not valid, a 1 if character is valid, or a -1 if invalid ctype was given zero Example: 28 int valid=0; char ch='Z'; valid=cvaltype(ch,'#'); printf("%c is %sa valid char of type '#'\n",ch, valid?"":" not"); Name: delay_ Purpose: delays program execution for a specified duration. Prototype: void delay_(unsigned duration); Header: cxldef.h Inputs: duration - duration (0-65535) ie. 18 = 1 second Return: none Also see: timer waitkeyt Example: delay_(36); /* delays for 2 seconds */ Name: disktoscrn Purpose: copies a previously saved screen disk file back to the screen. Prototype: int disktoscrn(char *fname); Header: cxlvid.h Inputs: fname - address of the string containing file name to read from Return: a zero if no error Also see: disktowin scrntodisk Example: if(disktoscrn("SCREEN.DAT")) { printf("Error reading input file\n"); exit(1); } Name: disktowin Purpose: copies a previously saved window disk file back to the screen. Prototype: int disktowin(char *fname); Header: cxlwin.h Inputs: fname - address of the string containing file name to read from Return: a zero if no error Also see: disktoscrn wintodisk Example: if(disktowin("WINDOW.DAT")) { printf("Error reading input file\n"); exit(1); } Name: emsalloc Purpose: allocates pages of EMS memory. See the "Expanded Memory (EMS) Functions" section for complete details. Prototype: unsigned emsalloc(int numpages); Header: cxlems.h Inputs: numpages - the number of pages (16K blocks) requested Return: the EMS handle or a -1 if an error occurred 29 Also see: emsdealloc emsexist emsfree Example: int emm_handle; ...... emm_handle=emsalloc(2); /* request 2 pages (32K) */ if(emm_handle==-1) { printf("EMS allocation error\n"); exit(1); } Name: emsdealloc Purpose: deallocate previously allocated pages of EMS memory. Prototype: int emsdealloc(int handle); Header: cxlems.h Inputs: handle - the previously assigned EMS handle Return: a 0 if no error or else an EMS error code Also see: emsalloc Example: if(emsdealloc(emm_handle)) { printf("EMS deallocation error\n"); exit(1); } Name: emsexist Purpose: determines if the EMS device driver is loaded. See the "Expanded Memory (EMS) Functions" section for complete details. Prototype: int emsexist(void); Header: cxlems.h Inputs: none Return: a 0 if EMS driver not loaded, or a 1 if EMS driver is loaded Also see: emsfree emstotal expmem Example: printf("EMS device driver is %sloaded\n", (emsexist())?"":"not "); Name: emsframe Purpose: returns the EMS page frame base address (segment). Prototype: unsigned emsframe(void); Header: cxlems.h Inputs: none Return: the EMS page frame base address (segment) or a zero if an error occurred Also see: emsmap Example: printf("EMS page frame address is at: %X\n",emsframe()); Name: emsfree Purpose: returns the number of free EMS pages (16K blocks). Prototype: unsigned emsfree(void); Header: cxlems.h Inputs: none Return: the number of free EMS pages 30 Also see: emsalloc emstotal Example: printf("Free EMS pages: %u\n",emsfree()); Name: emsmap Purpose: maps a logical EMS page onto a physical page address. The emsalloc() function must be called prior to this. Prototype: int emsmap(int handle,int lpage,int ppage); Header: cxlems.h Inputs: handle - the EMS handle previosly assigned lpage - the logical EMS page to map (0 - ?) ppage - the physical DOS page to map to (0 - 3) Return: a zero if no error, or else an EMS error code Also see: emsalloc emsframe Example: if(emsmap(ems_handle,0,0)) { printf("Error mapping logical page 0 " "to physical page 0\n"); exit(1); } Name: emsread Purpose: reads bytes from an EMS page(s), emsalloc() and emsmap() must be called prior to this function. The source segment used will be the current EMS page frame address and the destination segment will be the program's data segment. Prototype: int emsread(char *dest,unsigned emsofs,unsigned numbytes); Header: cxlems.h Inputs: dest - address to receive bytes read emsofs - offset from the EMS page frame base address at which to read the bytes from numbytes - the number of bytes to read Return: a zero if no error Also see: emsmap emswrite Example: if(emsread(buf,0x100,64)) { printf("Failed to read 64 bytes from EMS memory\n"); exit(1); } Name: emstotal Purpose: returns the total number of EMS pages (16K blocks) on the system. Prototype: unsigned emstotal(void); Header: cxlems.h Inputs: none Return: the total number of EMS pages on the system or a zero if an error occurred Also see: emsfree expmem Example: printf("You have %u pages of EMS memory\n",emstotal()); Name: emsver 31 Purpose: returns the current EMS version. Prototype: char *emsver(void); Header: cxlems.h Inputs: none Return: the address of the static string containing the EMS version number or NULL if error Example: printf("Your EMS version is %s\n",emsver()); Name: emswrite Purpose: writes bytes to an EMS page(s), emsalloc() and emsmap() must be called prior to this function. The source segment will be the program's DATA segment and the destination segment will be the EMS current EMS page frame address. Prototype: int emswrite(char *src,unsigned emsofs,unsigned numbytes); Header: cxlems.h Inputs: src - address of where to write bytes from emsofs - offset from EMS page frame base address of where to write bytes to numbytes - number of bytes to write Return: a zero if no error Also see: emsframe emsmap emsread Example: if(emswrite(buf,0x100,64)) { printf("Failed to write 64 bytes to EMS memory\n"); exit(1); } Name: expmem Purpose: determines the amount (if any) of expanded memory on the system. Prototype: unsigned expmem(void); Header: cxldef.h cxlems.h Inputs: none Return: the amount of expanded memory in kilobytes Also see: emsexist extmem Example: printf("Amt of expanded memory = %uK\n",expmem()); Name: extmem Purpose: determines the amount of extended memory on an AT machine. Prototype: unsigned extmem(void); Header: cxldef.h Inputs: none Return: the amount of extended memory in kilobytes Also see: expmem Example: printf("Amt of extended memory = %uK\n",extmem()); Name: fill_ Purpose: fills in a region of the screen with specified character/attribute. Prototype: void fill_(int srow,int scol,int erow,int ecol,int ch, 32 int attr); Header: cxlvid.h Inputs: srow - starting row upper left corner scol - starting column upper left corner erow - ending row lower left corner ecol - ending column lower left corner ch - character to fill with attr - attribute of character Return: none Also see: attrib filld Example: fill_(2,2,9,9,' ',WHITE|_RED); Name: filld Purpose: fills in a region of the screen with specified character/attribute by writing directly to the screen (no BIOS calls). Prototype: void filld(int srow,int scol,int erow,int ecol,int ch, int attr); Header: cxlvid.h Inputs: srow - starting row upper left corner scol - starting column upper left corner erow - ending row lower left corner ecol - ending column lower left corner ch - character to fill with attr - attribute of character Return: none Also see: attrib fill_ videoinit Example: filld(2,2,9,9,' ',WHITE|_RED); Name: gameport Purpose: determines if a game port is installed. Prototype: int gameport(void); Header: cxldef.h Inputs: none Return: a zero if game port is not installed, a 1 if installed Also see: mathchip numflop numpar numser Example: printf("Game port is %sinstalled\n", gameport()?"":"not "); Name: getchf Purpose: gets a character from the keyboard from a list of valid characters, provides Escape checking. Prototype: int getchf(char *valid,int defchar); Header: cxlkey.h Inputs: valid - address of list of valid characters defchar - default selection in case Enter is pressed, or a zero for no default Return: the character pressed or 0 if the Escape key was pressed Also see: getxch waitkey Example: int ch; 33 ...... ch=getchf("YyNn",'N'); if(!ch) { printf("Escape was pressed\n"); exit(1); } Name: getns Purpose: inputs a string of specified length from the keyboard, provides Escape checking. Prototype: int getns(char *str,int max); Header: cxlkey.h Inputs: str - address of allocated space to receive input string max - maximum length of the input string Return: a 1 if the <Esc> key was pressed Also see: inputsf Example: char age[2]; printf("Enter your age: "); if(getns(age,2)) { printf("Escape was pressed\n"); exit(0); } Name: getxch Purpose: gets a key (ASCII code/extended ASCII code) from the keyboard. If a mouse is present and initialized, it can be used. The mouse movements will translate to the arrow keys, the left button will translate to Enter, and the right button will translate to Escape. Prototype: unsigned getxch(void); Header: cxlkey.h Inputs: none Return: none Also see: getchf Example: unsigned int xch; ...... xch=getxch(); printf("ASCII code = %d, scan code = %d\n",xch,xch>>8); Name: gotoxy_ Purpose: sets cursor coordinates on the screen. Prototype: void gotoxy_(int row,int col); Header: cxlvid.h Inputs: row - cursor row (Y coordinate) col - cursor column (X coordinate) Return: none Also see: readcur Example: gotoxy_(20,30); /* set cursor at row 20, column 30 */ Name: inputsf 34 Purpose: inputs a formatted string from the keyboard. Prototype: int inputsf(char *str,char *fmt); Header: cxlkey.h Inputs: str - address of the allocated space to receive string fmt - address of the format string, see section on using format strings Return: 0 - no error 1 - Escape key was pressed 2 - invalid format string Also see: getns Example: char phone_nr[25]; ...... inputsf(phone_nr," !RE! 'Enter phone number: (' ### " " ') '###'-'#### "); Name: kbstat Purpose: returns the status of the keyboard control keys. Prototype: unsigned kbstat(void); Header: cxlkey.h Inputs: none Return: status word of the keyboard flag. You can determine which key(s) are being pressed/toggled by masking the status with one of the following: RSHIFT - right shift pressed LSHIFT - left shift pressed CTRL - <Ctrl> pressed ALT - <Alt> pressed SCRLOCK - <Scroll Lock> toggled NUMLOCK - <Num Lock> toggled CAPSLOCK - <Caps Lock> toggled INS - <Ins> toggled Also see: capsoff capson numoff numon Example: if(kbstat()&CTRL) { printf("The <Ctrl> key is now being pressed\n"); } Name: lcrlf Purpose: prints a carriage return and line feed on the printer. Prototype: void lcrlf(void); Header: cxlprn.h Inputs: none Return: none Also see: lprintc Example: lcrlf(); Name: lprintc Purpose: prints a character on the printer. Prototype: void lprintc(int ch); Header: cxlprn.h Inputs: ch - the character to print Return: none 35 Also see: lcrlf lprintf Example: lprintc(0x12); /* sends a form-feed to the printer */ Name: lprintf Purpose: sends formatted output to the printer, works like printf(). Prototype: void lprintf(const char *format,...); Header: cxlprn.h Inputs: format - format string, refer to the section on printf() in the run-time library reference. ... - any additional arguments Return: none Also see: lprintc lprintns lprints Example: lprintf("%s %c %d\n",str_arg,char_arg,int_arg); Name: lprintns Purpose: prints a string on the printer, formatting width. Prototype: void lprintns(char *str,int width); Header: cxlprn.h Inputs: str - the address of the string to print width - width to print string, uses padding or truncating Return: none Also see: lprintf lprints lprintsu Example: lprintns("Hello, world",5); Name: lprints Purpose: prints a string on the printer. Prototype: void lprints(char *str); Header: cxlprn.h Inputs: str - the address of the string to print Return: none Also see: lprintf lprintns lprintsu Example: lprints("Hello, world\n"); Name: lprintsb Purpose: prints a bold-faced string on the printer. Prototype: void lprintsb(char *str); Header: cxlprn.h Inputs: str - the address of the string to print Return: none Also see: lprints lprintsu Example: lprintsb("Hello, world\n"); Name: lprintsu Purpose: prints an underlined string on the printer. Prototype: void lprintsu(char *str); Header: cxlprn.h Inputs: str - the address of the string to print 36 Return: none Also see: lprints lprintsb Example: lprintsu("Hello, world\n"); Name: machid Purpose: returns the value of the machine ROM ID byte. Prototype: int machid(void); Header: cxldef.h Inputs: none Return: the value of the machine ROM ID byte. Will usually be one of the following values: IBMPC - IBM PC IBMPCXT - IBM PC/XT IBMPCJR - IBM PCjr IBMPCAT - IBM PC/AT IBMPCXT2 - IBM PC/XT-2 IBMCONV - IBM PC Convertible SPERRYPC - Sperry PC Also see: biosver Example: if(machid()==IBMPCAT) printf("You have an IBM PC/AT\n"); Name: mathchip Purpose: determines if a math coprocessor is installed. Prototype: int mathchip(void); Header: cxldef.h Inputs: none Return: a 1 if a math coprocessor is installed Also see: gameport numflop numpar numser Example: printf("Math coprocessor is %sinstalled\n", mathchip()?"":"not "); Name: mode Purpose: sets the video mode. Prototype: void mode(int mode_code); Header: cxlvid.h Inputs: mode_code - mode code number Return: none Also see: setlines vidtype Example: mode(4); /* sets CGA graphics mode */ Name: msbpress Purpose: gets info about specific button presses of mouse. Prototype: void msbpress(int button,int *bstat,int *bcount,int *x, int *y); Header: cxlmou.h Inputs: button - button to check, 0 = left button, 1 = right button bstat - address to receive button status (0 = not being pressed, 1 = currently being pressed) bcount - address to receive number of times pressed since 37 last call x - address to receive X pixel coordinate at time of press y - address to receive Y pixel coordinate at time of press Return: none Also see: msbreles msstatus Example: int bstat,bcount,x,y; ...... msbpres(0,&bstat,&bcount,&x,&y); Name: msbreles Purpose: gets info about specific button releases of mouse. Prototype: void msbreles(int button,int *bstat,int *bcount,int *x, int *y); Header: cxlmou.h Inputs: button - button to check, 0 = left button, 1 = right button bstat - address to receive button status (0 = not being pressed, 1 = currently being pressed) bcount - address to receive number of times released since last call x - address to receive X pixel coordinate at time of release y - address to receive Y pixel coordinate at time of release Return: none Also see: msbpress msstatus Example: int bstat,bcount,x,y; ...... msbreles(0,&bstat,&bcount,&x,&y); Name: mscursor Purpose: sets the mouse cursor mode. Prototype: void mscursor(int curtype,int smask,int cmask); Header: cxlmou.h Inputs: curtype - cursor type, 0 = software, 1 = hardware smask - screen mask (SW) or start scan line (HW), see section on using mouse functions for a description of mask cmask - cursor mask (SW) or stop scan line (HW), see section on using mouse functions for a description of mask Return: none Also see: msshowcur Example: mscursor(1,7,1); Name: msgotoxy Purpose: sets the mouse coordinates. Prototype: void msgotoxy(int x,int y); Header: cxlmou.h Inputs: x - X pixel coordinate 38 y - Y pixel coordinate Return: none Also see: msstatus Example: msgotoxy(20*8,10*8); /* sets mouse cursor at row 10, column 20 */ Name: mshbounds Purpose: sets the mouse horizontal bounds. Prototype: void mshbounds(int left,int right); Header: cxlmou.h Inputs: left - left pixel boundary right - right pixel boundary Return: none Also see: msvbounds Example: /* limits mouse movement between columns 40 and 60 */ mshbounds(40*8,60*8); Name: mshidecur Purpose: hides the mouse cursor. Prototype: void mshidecur(void); Header: cxlmou.h Inputs: none Return: none Also see: msshowcur Example: mshidecur(); Name: msinit Purpose: determines if mouse is present. If so, initializes mouse and sets the global variable _mouse to a non-zero value. See the "Mouse Functions" section for complete details. Prototype: int msinit(void); Header: cxlmou.h Inputs: none Return: a 0 if mouse is not present Example: if(msinit()) { printf("Mouse initialized!\n"); } else { printf("Mouse does not exist\n"); } Name: msmotion Purpose: gets information about the movement of mouse. Prototype: void msmotion(int *xcount,int *ycount); Header: cxlmou.h Inputs: xcount - address to receive amount of X movement in pixels ycount - address to receive amount of Y movement in pixels Return: none Example: 39 int xcount,ycount; ...... msmotion(&xcount,&ycount); Name: msshowcur Purpose: reveals the mouse cursor. Prototype: void msshowcur(void); Header: cxlmou.h Inputs: none Return: none Also see: mshidecur Example: msshowcur(); Name: msspeed Purpose: adjusts mouse speed by changing its sensitivity. Prototype: void msspeed(int xratio,int yratio); Header: cxlmou.h Inputs: xratio - horizontal speed (higher numbers are slower) yratio - vertical speed (higher numbers are slower) Return: none Example: msspeed(15,15); Name: msstatus Purpose: returns the mouse status. Prototype: void msstatus(int *bstat,int *x,int *y); Header: cxlmou.h Inputs: bstat - address to receive button status (0 = not pressed, 1 = pressed) x - address to receive current X pixel coordinate y - address to receive current Y pixel coordinate Return: none Example: int bstat,x,y; ...... msstatus(&bstat,&x,&y); Name: msvbounds Purpose: sets the mouse vertical bounds. Prototype: void msvbounds(int top,int bottom); Header: cxlmou.h Inputs: top - top pixel boundary bottom - bottom pixel boundary Return: none Also see: mshbounds Example: /* limits mouse movement between rows 10 and 20 */ msvbounds(10*8,20*8); Name: numflop Purpose: returns the number of floppy disk drives installed. 40 Prototype: int numflop(void); Header: cxldef.h Inputs: none Return: the number of floppy disk drives installed Also see: gameport mathchip numpar numser Example: printf("Number of floppy disk drives = %d\n", numflop()); Name: numoff Purpose: toggles the NumLock key off. Prototype: void numoff(void); Header: cxlkey.h Inputs: none Return: none Also see: capsoff kbstat numon Example: numoff(); Name: numon Purpose: toggles the NumLock key on. Prototype: void numon(void); Header: cxlkey.h Inputs: none Return: none Also see: capson kbstat numoff Example: numon(); Name: numpar Purpose: determines the number of parallel ports. Prototype: int numpar(void); Header: cxldef.h Inputs: none Return: the number of parallel ports installed Also see: gameport mathchip numflop numser Example: printf("Number of parallel ports = %d\n", numpar()); Name: numser Purpose: determines the number of serial ports installed. Prototype: int numser(void); Header: cxldef.h Inputs: none Return: the number of serial ports installed Also see: gameport mathchip numflop numpar Example: printf("Number of serial ports = %d\n", numser()); Name: printc 41 Purpose: prints a character to the screen at a specified location and attribute. Prototype: void printc(int row,int col,int attr,int ch,int count); Header: cxlvid.h Inputs: row - row col - column attr - attribute of character ch - character to print count - number of times to print character Return: none Also see: attrib printcd Example: printc(18,60,LGREEN|BLINK,'Z',5); Name: printcd Purpose: prints a character directly to the screen at a specified location and attribute (no BIOS calls). Prototype: void printcd(int row,int col,int attr,int ch); Header: cxlvid.h Inputs: row - row col - column attr - attribute of character ch - character to print Return: none Also see: attrib printc videoinit Example: printcd(18,60,LGREEN|BLINK,'Z'); Name: prints Purpose: displays a string on the screen at a specified location and attribute. Prototype: void prints(int row,int col,int attr,char *str); Header: cxlvid.h Inputs: row - cursor row col - cursor column attr - character attribute str - address of string to display Return: none Also see: attrib printsd Example: prints(20,10,LRED|_LGREY,"Hello, world"); Name: printsd Purpose: displays a string at a specified location in a specified attribute directly on the screen (no BIOS calls). Prototype: void printsd(int row,int col,int attr,char *str); Header: cxlvid.h Inputs: row - cursor row col - cursor column attr - character attribute str - address of string to display Return: none Also see: attrib prints videoinit Example: 42 printsd(20,10,LRED|_LGREY,"Hello, world"); Name: readchat Purpose: reads the character and attribute under the cursor. Prototype: int readchat(void); Header: cxlvid.h Inputs: none Return: integer containing character in low byte and attribute in high byte Also see: revattr setattr Example: int i; ...... i=readchat(); printf("character is %c and attribute is %d\n",i,(i>>8)); Name: readcur Purpose: reads the current cursor location. Prototype: void readcur(int *row,int *col); Header: cxlvid.h Inputs: row - address of location to receive cursor row col - address of location to receive cursor column Return: none Also see: gotoxy_ Example: int row,col; ...... readcur(&row,&col); Name: revattr Purpose: reverses the attribute of the character under the current cursor location, continues for the specified number of characters. Prototype: void revattr(int count); Header: cxlvid.h Inputs: count - the number of characters to reverse attribute of Return: none Also see: readchat setattr Example: revattr(5); Name: scrndump Purpose: dumps the current screen to the printer. Prototype: void scrndump(void); Header: cxlprn.h Inputs: none Return: none Also see: scrntodisk ssave videoinit Example: scrndump(); Name: scrntodisk 43 Purpose: copies the current screen to a disk file. Prototype: int scrntodisk(char *fname); Header: cxlvid.h Inputs: fname - address of the string containing file to write to Return: a zero if no error Also see: disktoscrn scrndump ssave wintodisk Example: if(scrntodisk("SCREEN.DAT")) { printf("Error creating file\n"); exit(1); } Name: setattr Purpose: sets the attribute of the character under the current cursor location, continues for the specified number of characters. Prototype: void setattr(int attr,int count); Header: cxlvid.h Inputs: attr - attribute to set character count - the number of characters to set the attribute of Return: none Also see: attrib readchat revattr Example: setattr(LRED|BLINK,5); Name: setcursz Purpose: sets the cursor size. Prototype: void setcursz(int sline,int eline); Header: cxlvid.h Inputs: sline - start line of cursor (32 for no cursor) eline - end line of cursor Return: none Example: setcursz(1,7); /* makes a large cursor */ Name: setkbloop Purpose: sets a procedure that will be called while waiting for a keypress. Prototype: void setkbloop( void (*func) (void)); Header: cxlkey.h Inputs: func - address of the procedure to be called while waiting for keypress or NULL to cancel the procedure. Return: none Also see: waitkey waitkeyt Example: setkbloop(myfunc); Name: setlines Purpose: sets the number of lines on the display. Prototype: int setlines(int numlines); Header: cxlvid.h Inputs: numlines - the number of lines to set the display to, valid numbers are 25 for all video adapters, 44 43 for EGA, and 50 for VGA. Return: zero if no error Also see: mode vidtype Example: if(setlines(43)) { printf("You need an EGA monitor for 43-line mode\n"); } else { printf("You are now in EGA 43-line mode\n"); } Name: setonkey Purpose: attaches/detaches a keypress to a function call. Works by intercepting any calls to CXL keyboard input functions. Whenever you use one of CXL's keyboard input functions, the input function will check to see if the pressed key has been defined. If so, then the input function will call the corresponding function. If not, then the input function will pass on the keypress as normal. This function can be used for simple context sensitive help by defining the help key for one procedure and redefining for the next. Prototype: int setonkey(unsigned keycode,void (*func) (void),int pass); Header: cxlkey.h Inputs: keycode - scan code/ASCII code of the keypress to define. If the keycode was previous defined, it will be re-defined. The scan code must be in the upper 8 bits and the ASCII code must be in the lower 8 bits. This is easily accomplished using a scan code/ASCII code reference table and using the hex values for both codes. For example, the Escape key has a scan code of 0x01 and an ASCII code of 0x1b, so the value you would input for keycode would be 0x011b. func - address of the function to call upon keypress. The called function must have the prototype: void func(void); If NULL is specified for func, then the specified keycode will be un-defined. pass - pass the keypress on to the caller? 0=no, 1=yes After the function corresponding to the defined keypress has been called, the keyboard input function can pass on the keypress to its caller or it can wait for another keypress. Return: a zero if no error, otherwise a memory allocation error Example: /* attaches Ctrl-T to myfunc() */ setonkey(0x1414,myfunc,0); Name: sound_ Purpose: sounds a tone of specified pitch and duration. Prototype: void sound_(unsigned pitch,unsigned duration); Header: cxldef.h Inputs: pitch - pitch of tone (0-65535) duration - duration of tone (0-65535) ie. 18 = 1 second Return: none 45 Also see: beep Example: sound_(255,3); Name: spc Purpose: displays a specified number of spaces to the screen. Prototype: void spc(int num); Header: cxlvid.h Inputs: num - number of spaces to display Return: none Example: spc(3); Name: srestore Purpose: restores a previously saved screen. Prototype: void srestore(int *sbuf); Header: cxlvid.h Inputs: sbuf - address of previously saved screen buffer Return: none Also see: ssave videoinit wrestore Example: srestore(sbuf); Name: ssave Purpose: saves the current screen to a buffer. Prototype: int *ssave(void); Header: cxlvid.h Inputs: none Return: address of newly created screen buffer or 0 if allocation error Also see: scrndump scrntodisk srestore videoinit wsave Example: int *sbuf; ...... sbuf=ssave(); if(!sbuf) { printf("Memory allocation error\n"); exit(1); } Name: strblank Purpose: determines if a given string is blank (whitespace) Prototype: int strblank(char *str); Header: cxlstr.h Inputs: str - address of the string to check Return: a 0 if not blank, a 1 if blank Example: char *str=" "; printf("str is %sblank\n",strblank(str)?"":"not "); Name: strbmatch Purpose: returns the best match of a string in an array of strings. 46 Prototype: char *strbmatch(char *str,char *strarr[]); Header: cxlstr.h Inputs: str - address of string to match strarr - address of array of string pointers, the last pointer in the array must be NULL Return: address of the string in the array that best matched the given string. Also see: strmatch Example: char *strarr[]= { "Hello","Computer","World",NULL }; char *str="xhelpx"; printf("best match is: %s\n",strbmatch(str,strarr)); Name: strchg Purpose: finds all letters in a string matching one character and replaces them with another. Prototype: int strchg(char *str,int oldch,int newch); Header: cxlstr.h Inputs: str - address of string to search oldch - character to search for newch - character to replace with Return: the number of matches found Also see: strichg Example: char *str="Hello there"; printf("Before: %s\n",str); strchg(str,'h','*'); printf("After: %s\n",str); Name: strcode Purpose: encodes/decodes a string. Call this function to encode a string, then call again using the same key to decode. When reading or writing from a disk file, be sure to open the file in binary mode. Prototype: char *strcode(char *str,char *key); Header: cxlstr.h Inputs: str - the address of the string to encode/decode key - the address of the key string to encode/decode with. The string can consist of any valid characters (1-255) and can be of any length. Remember this key or your data will be lost forever! Return: the address of the encoded/decoded string Example: char *str="Hello, world"; printf("Before: %s\n",str); strcode(str,"m{&!\xfc"); printf("Encoded: %s\n",str); strcode(str,"m{&!\xfc"); printf("Decoded: %s\n",str); Name: strdel Purpose: deletes a substring from within a string. Prototype: char *strdel(char *substr,char *str); Header: cxlstr.h 47 Inputs: substr - address of substring to delete str - address of string to delete from Return: a NULL if the substring was not found, or the address of the modified string. Also see: stridel strinc strins strmid Example: char *str="Hello, XXXXXworld"; strdel("XXXXX",str); printf("%s\n",str); Name: strichg Purpose: finds all letters in a string matching one character and replaces them with another, ignoring case of letters. Prototype: int strichg(char *str,int oldch,int newch); Header: cxlstr.h Inputs: str - address of string to search oldch - character to search for newch - character to replace with Return: the number of matches found Also see: strchg Example: char *str="Hello there"; printf("Before: %s\n",str); strichg(str,'h','*'); printf("After: %s\n",str); Name: stridel Purpose: deletes a substring from within a string, ignoring case of letters. Prototype: char *stridel(char *substr,char *str); Header: cxlstr.h Inputs: substr - address of substring to delete str - address of string to delete from Return: a NULL if the substring was not found, or the address of the modified string Also see: strdel striinc Example: char *str="Hello, XXXXXworld"; stridel("XXXXX",str); printf("%s\n",str); Name: striinc Purpose: determines if one string is included in another, ignoring case of letters. Prototype: char *striinc(char *str1,char *str2); Header: cxlstr.h Inputs: str1 - address of string1 str2 - address of string2 Return: the address where string1 is included in string2, or a NULL if string1 is not included in string2 Also see: strinc strmid Example: char *str1="HeLlo WOrLd"; char *str2="XXXXXXXHello, worldXXXXX"; 48 if(striinc(str1,str2)) { printf("%s is included in %s\n",str1,str2); } Name: strinc Purpose: determines if one string is included in another. Prototype: char *strinc(char *str1,char *str2); Header: cxlstr.h Inputs: str1 - address of string1 str2 - address of string2 Return: the address where string1 is included in string2, or a NULL if string1 is not included in string2 Also see: striinc strmid Example: char *str1="Hello world"; char *str2="XXXXXXXHello, worldXXXXX"; if(strinc(str1,str2)) { printf("%s is included in %s\n",str1,str2); } Name: strins Purpose: inserts one string into another. Prototype: char *strins(char *instr,char **str,int st_pos); Header: cxlstr.h Inputs: instr - the address of the string to insert str - the address of the address of the string to insert into st_pos - the starting position for where to insert Return: the address of the newly allocated string, or a NULL if a memory allocation error occurred Also see: strdel strinc Example: char *str="Hello!"; printf("%s\n",str); strins(", world",&str,5); printf("%s\n",str); free(str); /* free memory when done with string */ Name: striocc Purpose: returns the number of occurrences of a character in a string ignoring the case of letters. Prototype: int striocc(char *str,int ch); Header: cxlstr.h Inputs: str - address of the string to search ch - the character to look for Return: the number of occurrences of the character in the string Also see: strocc Example: char ch='L'; char *str="Hello, world"; printf("%c occurs in %s %d times\n",ch,str, striocc(str,ch)); 49 Name: strleft Purpose: takes a specified portion of a string from the left and creates a new string. Prototype: char *strleft(char *str,int num_chars); Header: cxlstr.h Inputs: str - address of input string num_chars - number of characters to copy Return: address of the newly created string or a NULL if a memory allocation error occurred Also see: strmid strright strtrim Example: char *left; char *str="Hello, worldXXXX"; left=strleft(str,12); printf("%s\n",left); free(left); /* free memory when done with string */ Name: strltrim Purpose: trims leading spaces off of a string. Prototype: char *strtrim(char *str); Header: cxlstr.h Inputs: str - address of the string to trim Return: address of the modified string Also see: strright strsetsz strtrim Example: char *str=" Hello, world"; printf("Before: %s.\n",str); strltrim(str); printf("After: %s.\n",str); Name: strmatch Purpose: compares 2 strings, returns a match score. Prototype: int strmatch(char *str1,char *str2); Header: cxlstr.h Inputs: str1 - address of first string str2 - address of second string Return: a match score, the higher the score, the better they match Also see: strbmatch Example: char *str1="hello"; char *str2="help"; printf("match score = %d\n",strmatch(str1,str2)); Name: strmid Purpose: takes a section from input string starting at given position and taking the given amount of characters creating a new string. Prototype: char *strmid(char *str,int st_pos,int num_chars); Header: cxlstr.h Inputs: str - address of input string st_pos - position in input string to start copying characters (starting at position 0) num_chars - number of characters to copy Return: address of the newly created string or a NULL if a memory 50 allocation error occurred Also see: strleft strright Example: char *middle; char *str="XXXXXHello, worldXXXX"; middle=strmid(str,5,12); printf("%s\n",middle); free(middle); /* free memory when done with string */ Name: strocc Purpose: returns the number of occurrences of a character in a string. Prototype: int strocc(char *str,int ch); Header: cxlstr.h Inputs: str - address of the string to search ch - the character to look for Return: the number of occurrences of the character in the string Also see: striocc Example: char ch='l'; char *str="Hello, world"; printf("%c occurs in %s %d times\n",ch,str,strocc(str,ch)); Name: strright Purpose: takes a specifed portion from the right side of a string creating a new string. Prototype: char *strright(char *str,int num_chars); Header: cxlstr.h Inputs: str - address of input string num_chars - number of characters to copy Return: address of the newly created string or a NULL if a memory allocation error occurred Also see: strleft strltrim strmid Example: char *right; char *str="XXXXXHello, world"; right=strright(str,12); printf("%s\n",right); free(right); /* free memory when done with string */ Name: strrol Purpose: rotates a string specified number of characters left, characters wrap around. Prototype: char *strrol(char *str,int count); Header: cxlstr.h Inputs: str - the address of the string to rotate count - number of characters to rotate Return: the address of the modified string Also see: strror strshl Example: char *str="Hello, world"; printf("Before: %s.\n",str); strrol(str,3); printf("After: %s.\n",str); 51 Name: strror Purpose: rotates a string specified number of characters right, characters wrap around. Prototype: char *strror(char *str,int count); Header: cxlstr.h Inputs: str - the address of the string to rotate count - number of characters to rotate Return: the address of the modified string Also see: strrol strshr Example: char *str="Hello, world"; printf("Before: %s.\n",str); strror(str,3); printf("After: %s.\n",str); Name: strsetsz Purpose: adjusts the length of a string by truncation or padding with spaces. Prototype: char *strsetsz(char **str,int newsize); Header: cxlstr.h Inputs: str - address of pointer to the string newsize - the new length of the string Return: address of the new string or a NULL if a memory allocation error occurred. Also see: strtrim Example: char *str="Hello, world"; strsetsz(&str,25); printf("%s.\n",str); strsetsz(&str,5); printf("%s.\n",str); Name: strshl Purpose: shifts a string specified number of characters left, characters 'drop off' and spaces are added to the string. Prototype: char *strshl(char *str,int count); Header: cxlstr.h Inputs: str - the address of the string to shift count - number of characters to shift Return: the address of the modifed string Also see: strrol strshr Example: char *str="Hello, world"; printf("Before: %s.\n",str); strshl(str,3); printf("After: %s.\n",str); Name: strshr Purpose: shifts a string specified number of characters right, characters 'drop off' and spaces are added to the string. Prototype: char *strshr(char *str,int count); Header: cxlstr.h 52 Inputs: str - the address of the string to shift count - number of characters to shift Return: the address of the modified string Also see: strror strshl Example: char *str="Hello, world"; printf("Before: %s.\n",str); strshr(str,3); printf("After: %s.\n",str); Name: strtrim Purpose: trims trailing spaces off of a string. Prototype: char *strtrim(char *str); Header: cxlstr.h Inputs: str - address of the string to trim Return: address of the modified string Also see: strleft strltrim strsetsz Example: char *str="Hello, world "; printf("Before: %s.\n",str); strtrim(str); printf("After: %s.\n",str); Name: struplow Purpose: converts a string to mixed upper & lower case characters. Prototype: char *struplow(char *str); Header: cxlstr.h Inputs: str - the address of the string to convert Return: the address of the modified string Also see: touplow Example: char *str="heLlO, wOrLd"; printf("Before: %s.\n",str); struplow(str); printf("After: %s.\n",str); Name: sysdate Purpose: returns a string containing the current system date. Prototype: char *sysdate(int dtype); Header: cxldef.h Inputs: dtype - date type code. Can be one of the following: Code Example ---- ------- 0 December 3, 1988 1 3 Dec 88 2 12-3-88 3 12/3/88 4 3/12/88 Return: the address of the static string containing the system date. Also see: systime Example: printf("The system date is: %s\n",sysdate(0)); 53 Name: systime Purpose: returns a string containing the system time. Prototype: char *systime(int ttype); Header: cxldef.h Inputs: ttype - time type code. Can be one of the following: Code Example ---- ------- 0 16:30:57.89 1 16:30:57 2 4:30 PM 3 4:30p 4 4:30 Return: the address of the static string containing the system time. Also see: sysdate Example: printf("The current system time is: %s\n",systime(2)); Name: tabstop Purpose: calculates a tab stop from given column and tab width. Prototype: int tabstop(int col,int tabwidth); Header: cxldef.h Inputs: col - column tabwidth - tab width Return: the next tab stop column Example: printf("The next tab stop after column 5 is %d\n", tabstop(5,8)); Name: timer Purpose: returns the value of the BIOS timer. Prototype: unsigned long timer(void); Header: cxldef.h Inputs: none Return: current value of the BIOS timer Also see: delay_ Example: printf("%lu\n",timer()); delay_(36); printf("%lu\n",timer()); Name: touplow Purpose: converts a character to upper or lower case depending on previous character. Prototype: int touplow(char *str,char *pos,int ch); Header: cxlstr.h Inputs: str - address of string pos - current position in string ch - character to convert Return: the converted character Also see: struplow Example: char *str="Hello, world"; printf("Before: %s\n",str); *(str+7)=touplow(str,str+7,*(str+7)); 54 printf("After: %s\n",str); Name: videoinit Purpose: initializes CXL's video system. By default all CXL functions performing direct screen writes go to the CGA video RAM segment at 0xb800. If you want these functions to work correctly with a monochrome video adapter or within a DESQview window, you must call this function. This function sets the value of the global variable _videoseg. Prototype: void videoinit(void); Header: cxlvid.h cxlwin.h Inputs: none Return: none Also see: vidtype Example: videoinit(); Name: vidtype Purpose: determines the display adapter type. Prototype: int vidtype(void); Header: cxlvid.h Inputs: none Return: video adapter type. Will be one of the following values: MDA - Monochrome Display Adapter HGC - Hercules Graphics Card HGCPLUS - Hercules Graphics Card Plus INCOLOR - Hercules InColor card CGA - Color Graphics Adapter EGA - Enhanced Graphics Adapter VGA - Video Graphics Array adapter Also see: mode videoinit Example: int vid_adapt; vid_adapt=vidtype(); if(vid_adapt>HGCPLUS) { printf("A color adapter is installed\n"); } Name: wactiv Purpose: activates a previously opened window. Prototype: int wactiv(WINDOW whandle); Header: cxlwin.h Inputs: whandle - the window handle returned from the wopen() function Return: W_NOERROR - no error W_NOTFOUND - window handle not found W_NOACTIVE - no open windows Also see: wisactiv wopen Example: int window_handle; ...... wactiv(window_handle); 55 Name: waitkey Purpose: halts execution until a key is pressed, the keyboard buffer is cleared first. Prototype: int waitkey(void); Header: cxlkey.h Inputs: none Return: the ASCII value of the key pressed Also see: clearkeys getchf waitkeyt Example: waitkey(); Name: waitkeyt Purpose: halts execution until a key is pressed or the specified time limit expires, the keyboard buffer is cleared first. Prototype: int waitkeyt(int duration); Header: cxlkey.h Inputs: duration - length of time to wait for keypress (18 = 1 sec) Return: the ASCII value of the key pressed or a -1 if time expired Also see: clearkeys delay_ getchf waitkey Example: waitkeyt(182); /* wait for a max of 10 seconds */ Name: waitvret Purpose: waits for vertical retrace on CGA adapters. This is useful for writing your own routines that access the screen memory directly. Calling this first will give you at least 512 bytes of snow-free direct screen memory access. The faster your machine is, the more bytes you can move during vertical retrace. Although setting CXL's _cgasnow variable to 1 reduces snow, it doesn't eliminate it. You can use this function for "problem sections" of your code. Prototype: void waitvret(void); Header: cxlvid.h Inputs: none Return: none Example: if(_cgasnow) waitvret(); Name: wblocked Purpose: determines if a window is being blocked by any other windows. Prototype: int wblocked(WINDOW whandle); Header: cxlwin.h Inputs: whandle - handle of window to check Return: -1 - error. The global variable _werrno will be set to one of the following: W_NOACTIVE - no active window W_NOTFOUND - window handle not found 0 - window is not blocked 1 - window is blocked Also see: wisactiv Example: WINDOW w1,w2; w1=wopen(0,0,10,20,0,LCYAN|_BLUE,LCYAN|_BLUE); 56 w2=wopen(8,8,15,40,0,LMAGENTA|_RED,LMAGENTA|_RED); wopen(5,45,15,75,0,YELLOW|_GREEN,YELLOW|_GREEN); printf("the blue window is %sblocked\n", wblocked(w1)?"":"not "); printf("the red window is %sblocked\n", wblocked(w2)?"":"not "); Name: wborder Purpose: changes the active window's border box type. Prototype: int wborder(int btype); Header: cxlwin.h Inputs: btype - box type (0-5). Use btype 5 for a borderless window. Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVBTYPE - invalid box type Example: wborder(1); Name: wbox Purpose: displays a text box in active window. Prototype: int wbox(int wsrow,int wscol,int werow,int wecol,int btype, int attr); Header: cxlwin.h Inputs: wsrow - window start row wscol - window start column werow - window end row wecol - window end column btype - box type (0-5) attr - attribute Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates Also see: wfill whline wvline Example: wbox(2,2,10,20,0,LMAGENTA|_RED); Name: wcclear Purpose: clears the currently active window using specified attribute. Prototype: int wcclear(int attr); Header: cxlwin.h Inputs: none Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wclear wclreol wclreos Example: wcclear(LBLUE|_RED); Name: wcenters Purpose: displays a string centered in active window. Prototype: int wcenters(int wrow,int attr,char *str); Inputs: wrow - window row 57 attr - attribute str - address of string to display Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid window row W_STRLONG - string too long to be centered in window Also see: wprints wrjusts Example: wcenters(2,LBLUE,"Hello, world"); Name: wchgattr Purpose: changes attribute of the active window, all text within the window will be changed also. Prototype: int wchgattr(int battr,int wattr); Header: cxlwin.h Inputs: battr - the attribute to make the window's border wattr - the attribute to make the window Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wtextattr Example: wchgattr(LMAGENTA|_RED,YELLOW|_BLUE); Name: wclear Purpose: clears the currently active window. Prototype: int wclear(void); Header: cxlwin.h Inputs: none Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wcclear wclreol wclreos Example: wclear(); Name: wclose Purpose: closes the currently active window. Prototype: int wclose(void); Header: cxlwin.h Inputs: none Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wcloseall wopen Example: wclose(); Name: wcloseall Purpose: closes all open windows. Prototype: int wcloseall(void); Header: cxlwin.h Inputs: none Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wclose 58 Example: wcloseall(); Name: wclreol Purpose: clears to the end of the active window's line. Prototype: int wclreol(void); Header: cxlwin.h Inputs: none Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wclear wclreos Example: wclreol(); Name: wclreos Purpose: clears from current cursor position to the end of the active window. Prototype: int wclreos(void); Header: cxlwin.h Inputs: none Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wclear wclreol Example: wclreos(); Name: wcopy Purpose: creates a new window duplicating the active window, the new window becomes the active window. Prototype: WINDOW wcopy(int nsrow,int nscol); Header: cxlwin.h Inputs: nsrow - start row of the duplicate window nscol - start column of the duplicate window Return: the handle of the new window or a zero if an error occurred. If error, the global variable _werrno will be set to one of the following: W_ALLOCERR - memory allocation error W_INVCOORD - invalid coordinates Also see: wactiv wmove wopen Example: wcopy(10,20); /* make copy of active window at row 10, col 20 */ Name: wdelline Purpose: deletes a line in active window Prototoype: int wdelline(int wrow,int direc); Header: cxlwin.h Inputs: wrow - window row to delete direc - scroll direction: SUP - scroll up SDOWN - scroll down Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid window row 59 Also see: winsline wscroll Example: wdelline(4,SDOWN); Name: wdupc Purpose: displays a character specified number of times in active window. Characters will be displayed in the attribute set by the wtextattr() function. Control characters are recognized. Cursor position is updated. Prototype: int wdupc(int ch,int count); Header: cxlwin.h Inputs: ch - character to be displayed count - number of times to display character Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wputc Example: wdupc('X',5); /* displays 'X' 5 times */ Name: werrmsg Purpose: returns an error message from the last windowing function. Prototype: char *werrmsg(void); Header: cxlwin.h Inputs: none Return: the address of a static string containing an error message corresponding to the error code from the last performed windowing function. Also see: wperror Example: wgotoxy(255,255); /* invalid coordinates */ printf("Error message = %s\n",werrmsg()); Name: wfill Purpose: fills in a region of active window with specified character and attribute. Prototype: int wfill(int wsrow,int wscol,int werow,int wecol,int ch, int attr); Header: cxlwin.h Inputs: wsrow - window start row wscol - window start column werow - window end row wecol - window end column ch - character to fill with attr - attribute Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates Also see: wbox Example: wfill(2,2,10,20,'Z',LMAGENTA|_RED); Name: wfindrec Purpose: finds the address of the window record of the specified 60 window handle. Prototype: struct _wrec_t *wfindrec(WINDOW whandle); Header: cxlwin.h Inputs: whandle - window handle of window record to find Return: the address of the found window record or NULL if no record was found for specified handle. Example: struct _wrec_t *wrecptr; .... wrecptr=wfindrec(3); Name: wgetc Purpose: gets a character from the keyboard within the active window, echos character pressed to the screen in the attribute set by the wtextattr() function. Prototype: int wgetc(void); Header: cxlwin.h Inputs: none Return: the ASCII value of the key pressed or a zero if an error occurred. If error, the global variable _werrno will be set to one of the following: W_NOACTIVE - no active window Also see: wgetchf wscanf wtextattr Example: int ch; ...... ch=wgetc(); Name: wgetchf Purpose: gets a character from the keyboard within the active window, allows only characters listed in the string of valid characters. Escape checking is provided by default. This can be turned off with the wsetesc() function. Selected character is echoed into the current window using the attribute set by the wtextattr() function. Prototype: int wgetchf(char *valid,int defchar); Header: cxlwin.h Inputs: valid - address of the string containing the valid characters defchar - default selection in case Enter is pressed, or a zero for no default Return: the ASCII value of the key pressed or a zero if an error occurred. If error, the global variable _werrno will be set to one of the following: W_NOACTIVE - no active window W_ESCPRESS - Escape key was pressed Also see: wgetc wscanf wtextattr Example: int ch; ...... ch=wgetchf("YyNn",'N'); if(_werrno==W_ESCPRESS) { printf("Escape key was pressed\n"); exit(1); } 61 Name: wgetns Purpose: gets a string from the keyboard within active window, limits the number of characters input to specified length. Escape checking is provided by default. This can be turned off with the wsetesc() function. Entered characters will echo to the active window in the attribute set by the wtextattr() function. Prototype: int wgetns(char *str,int maxlen); Header: cxlwin.h Inputs: str - address of the allocated space to receive the input string maxlen - the maximum length of the input string Return: W_NOERROR - no error W_NOACTIVE - no active window W_ESCPRESS - Escape key was pressed Also see: wgets winputsf wscanf wsetesc wtextattr Example: char fname[20]; ...... wputs("Enter your first name: "); wgetns(fname,5); Name: wgets Purpose: gets a string from the keyboard within active window, echos the characters to the screen in the attribute set by the wtextattr() function. Prototype: int wgets(char *str); Header: cxlwin.h Inputs: str - the address of the allocated memory to receive the input string Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wgetns winputsf wscanf wtextattr Example: char fname[20]; ...... wputs("Enter your first name: "); wgets(fname); Name: wgotoxy Purpose: sets cursor coordinates within the currently active window. Prototype: int wgotoxy(int wrow,int wcol); Header: cxlwin.h Inputs: wrow - window row (Y coordinate) wcol - window column (X coordinate) Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates Also see: wpgotoxy wreadcur Example: wgotoxy(2,3); /* set cursor to row 2, column 3 */ 62 Name: whandle Purpose: returns the handle of the active window Prototype: WINDOW whandle(void); Header: cxlwin.h Inputs: none Return: the handle of the active window or zero if error. If error, the global variable _werrno will be set to one of the following: W_NOACTIVE - no active window Also see: wactiv wisactiv Example: printf("active handle = %d\n",whandle()); Name: whide Purpose: hides a previously saved window. Prototype: int *whide(int **wbuf); Header: cxlwin.h Inputs: wbuf - address of the pointer to the window buffer to hide Return: the address of the hidden window's buffer or a NULL if a memory allocation error occurred. Also see: wsave wunhide Example: /* hides active window */ if(!whide(_wrec->wbuf)) { printf("Memory allocation error\n"); exit(1); } Name: whline Purpose: draws a horizontal text line in active window using characters defined by given box type. If horizontal line crosses a vertical line of the same box type, an appropriate intersection or corner will be used. Prototype: int whline(int wsrow,int wscol,int count,int btype); Header: cxlwin.h Inputs: wsrow - window start row of line wscol - window start column of line count - number of line characters to display btype - box type (0-5) Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - text line too long for window W_INVBTYPE - invalid box type Also see: wtextattr wvline Example: whline(2,5,7,3); Name: winpdef Purpose: defines an area of the active window for keyboard input. See the section "Multi-Field Formatted Input Functions" for the complete details. Prototype: int winpdef(int wrow,int wcol,char *str,char *format, int fconv,int fattr,int update, int (*validate) (char *)); 63 Header: cxlwin.h Inputs: wrow - start of input, window's row coordinate wcol - start of input, window's column coordinate str - address of string buffer to receive input format - input field format string fconv - input field conversion character. Applies conversion to all letters in the input field. Can be one of the following: 0 - apply no conversion 'L' - convert letters to lower case 'M' - convert letters to mixed case 'P' - password field (no echo) 'U' - convert letters to upper case fattr - field attribute update - update pre-existing field? 0 = no, 1 = yes validate - address of your user validation/modification function. The function must be declared like: int func(char *str); Your user function will receive the field input from the keyboard and will return zero if no error. If there was an error, then your function will return the position of the error in the string (starting at 1, not 0). If you do not wish to validate the field, then input NULL. Return: W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates W_INVFORMT - invalid format string W_LENFORMT - length of format string is invalid Also see: winpread winputsf wscanf Example: char name[11]; ...... wputs("Enter name:"); winpdef(1,13,name,"MMMMMMMMMM",0,LCYAN|_BLUE,0,NULL); Name: winpread Purpose: processes keyboard input of all defined areas of active window allowing editing back and forth between defined fields. See the section "Multi-Field Formatted Input Functions" for the complete details. Prototype: int winpread(void); Header: cxlwin.h Inputs: none Return: W_NOERROR - no error W_NOACTIVE - no active window W_ESCPRESS - Escape key was pressed W_NOINPDEF - no inputs defined Also see: winpdef wsetesc wtextattr Example: winpread(); Name: winputsf Purpose: inputs a formatted string from the keyboard within a window. 64 Input characters will be echoed to the active window in the attribute set by the wtextattr() function. Prototype: int winputsf(char *str,char *fmt); Header: cxlwin.h Inputs: str - address of the allocated space to receive string fmt - address of the format string, see section on using format strings for a complete description. Return: W_NOERROR - no error W_NOACTIVE - no active window W_ESCPRESS - Escape key was pressed W_INVFORMT - invalid format string Also see: wgetns wgets winpdef wscanf wsetesc wtextattr Example: winputsf(str," !RE! 'Enter phone number: (' ### " " ') ' ### '-' #### "); Name: winsline Purpose: inserts a blank line in active window Prototoype: int winsline(int wrow,int direc); Header: cxlwin.h Inputs: wrow - window row to insert at direc - scroll direction: SUP - scroll up SDOWN - scroll down Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid window row Also see: wdelline wscroll Example: winsline(3,SUP); Name: wintodisk Purpose: copies a screen window to a disk file. Prototype: int wintodisk(int srow,int scol,int erow,int ecol, char *fname); Header: cxlwin.h Inputs: srow - starting row scol - starting column erow - ending row ecol - ending column fname - address of the string containing file to write to Return: a zero if no error Also see: disktowin scrntodisk wsave Example: if(wintodisk(10,10,20,20,"WINDOW.DAT")) { printf("Error creating file\n"); exit(1); } Name: wisactiv Purpose: determines if specified window handle is active. Prototype: int wisactiv(WINDOW whandle); Header: cxlwin.h Inputs: whandle - the handle of the window to check. 65 Return: a zero if handle is not active, a 1 if it is active. Also see: wactiv wblocked whandle Example: printf("handle 5 is %sactive\n",wisactiv(5)?"":"not "); Name: wmenudef Purpose: defines a window bar-selection menu option. See the "Bar-Selection Menu Functions" section for complete details. Prototype: int wmenudef(int wrow,int wcol,int attr,char *str, int tagchar,int tagattr,char *desc); Header: cxlwin.h Inputs: wrow - window row to display option at wcol - window column to display option at attr - attribute to display option with str - address of the option string tagchar - tag character to use for identification, may be an ASCII value (0-255), lower case letters will automatically be converted to upper case. tagattr - attribute of tag character desc - address of a string describing the menu option or a NULL if no description is to be used. If not NULL, then the text description of the option will appear on the next line down and will change with each menu option, similar to the menus in many popular spreadsheet packages. The text description will be displayed in the window's current text attribute which can be set with the wtextattr() function. Thus, desc should be NULL unless using horizontal menus. Return: W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window Also see: wmenuget Example: if(wmenudef(2,3,LCYAN|_BLUE,"Add record",'A', WHITE|_BLUE,NULL)) { printf("Error: %s\n",werrmsg()); exit(1); } Name: wmenuget Purpose: gets a window bar-selection menu selection from the keyboard. See the "Bar-Selection Menu Functions" section for complete details. Prototype: int wmenuget(int barattr,int taginit,int pulldown); Header: cxlwin.h Inputs: barattr - the attribute to use for the selection bar taginit - tag character of initial selection bar position. If an invalid tag character is specified, the position defaults to the upper left. pulldown - this specifies how the defined bar-selection menu will act. It can be one of the following values: 0 - not part of a pull-down menu system 66 PDMAIN - main menu of a pull-down menu system PDPREV - main menu, automatically select the previous pull-down menu PDNEXT - main menu, automatically select the next pull-down menu PDMENU - pull-down menu Return: the tag character of the selected option or zero if an error. If error, the global variable _werrno will be set to one of the following: W_ESCPRESS - Escape key was pressed If PDMENU is specified for the pulldown parameter, then wmenuget() will return PDPREV if LeftArrow is pressed, PDNEXT if the RightArrow is pressed, or PDMENU if Esc is pressed. Also see: wmenudef wsetesc wtextattr Example: option=wmenuget(LCYAN|_GREEN,'A',0); switch(option) { case 'A': ...... case 'D': ...... case 0: error_routine(); etc. } Name: wmessage Purpose: displays text on the top or bottom border of active window Prototype: int wmessage(char *str,int border,int leftofs,int attr); Header: cxlwin.h Inputs: str - address of message string border - 0 = top border, 1 = bottom border leftofs - offset from left border to display message at attr - attribute of message text Return: W_NOERROR - no error W_NOACTIVE - no active window W_STRLONG - string could not fit in window W_NOBORDER - window has no border Also see: wtitle Example: wmessage("Error!",0,3,LRED|_BLINK); Name: wmove Purpose: moves the currently active window to a new location. Prototype: int wmove(int nsrow,int nscol); Header: cxlwin.h Inputs: nsrow - new starting row of window nscol - new starting column of window Return: W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window Also see: wcopy wsize Example: 67 if(wmove(3,10)) { printf("Error: %s\n",werrmsg()); exit(1); } Name: wopen Purpose: opens a screen window and makes it active, the cursor location will be initialized to window row 0, column 0, and the text attribute will be initialized to the same attribute as the window. Prototype: WINDOW wopen(int srow,int scol,int erow,int ecol,int btype, int battr,int wattr); Header: cxlwin.h Inputs: srow - starting row scol - starting column erow - ending row ecol - ending column btype - border box type (0-5). Use btype 5 for a borderless window. battr - attribute of window's border. wattr - attribute of window (and initially the text) Return: the window handle of the new window or a zero if an error occurred. If error, the global variable _werrno will be set to one of the following: W_ALLOCERR - memory allocation error W_INVCOORD - invalid coordinates W_INVBTYPE - invalid box type Also see: videoinit wactiv wclose wcloseall Example: if(!wopen(10,10,20,20,0,LCYAN|_BLUE,LCYAN|_BLUE)) { printf("Error: %s\n",werrmsg()); exit(1); } Name: wperror Purpose: displays an error message window, waits for a keypress, then returns to caller. Prototype: int wperror(char *message); Header: cxlwin.h Inputs: message - address of the string containing the error message Return: W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window W_STRLONG - error message string too long Also see: werrmsg Example: wperror("Input must be numeric"); Name: wpgotoxy Purpose: sets pseudo cursor coordinates within the currently active window by wrapping around if coordinates are out of range. Prototype: int wpgotoxy(int wrow,int wcol); Header: cxlwin.h Inputs: wrow - window row (Y coordinate) 68 wcol - window column (X coordinate) Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates Also see: wgotoxy wreadcur Example: wpgotoxy(3,20); Name: wprintc Purpose: displays a character in the currently active window. Does not update cursor position. Does not recognize control characters. Prototype: int wprintc(int row,int col,int attr,int ch); Header: cxlwin.h Inputs: row - cursor row (of the window) col - cursor column (of the window) attr - character attribute ch - character Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates Also see: wprints wputc Example: wprintc(5,10,LMAGENTA|BLINK,"T"); Name: wprintf Purpose: outputs a formatted string to active window at current cursor position. Works like the standard printf() function does. Recognizes control characters. Updates cursor position. Characters will be displayed in the attribute set by the wtextattr() function. Prototype: int wprintf(const char *format,...); Header: cxlwin.h Inputs: format - format string, refer to the section on printf() in the run-time library reference. ... - any additional arguments Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wputc wputns wputs wtextattr Example: wprintf("%s %c %d\n",string_arg,char_arg,int_arg); Name: wprints Purpose: displays a string in the currently active window. Does not update cursor position. Does not recognize control characters. Prototype: int wprints(int row,int col,int attr,char *str); Header: cxlwin.h Inputs: row - cursor row (of the window) col - cursor column (of the window) attr - attribute str - address of string Return: W_NOERROR - no error W_NOACTIVE - no active window 69 W_INVCOORD - invalid coordinates W_STRLONG - string too long for window Also see: wcenters wputs wrjusts Example: wprints(5,10,7,"Hello, world"); Name: wputc Purpose: displays a character in currently active window at current cursor location. Characters are displayed in the attribute set by the wtextattr() function. Recognizes control characters. Updates cursor position. Prototype: int wputc(int ch); Header: cxlwin.h Inputs: ch - the character to be printed Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wdupc wprintc wprintf wtextattr Example: wputc('X'); Name: wputns Purpose: displays a string in the active window, formatting width of output. Characters are displayed in the attribute set by the wtextattr() function. Recognizes control characters. Updates cursor location. Prototype: int wputns(char *str,int width); Header: cxlwin.h Inputs: str - address of the string to print width - width to display output string with Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wprintf wputs wtextattr Example: wputns("Hello, world",5); Name: wputs Purpose: displays a string in currently active window at the current cursor location. Characters are displayed in the attribute set by the wtextattr() function. Recognizes control characters. Updates cursor location. Prototype: int wputs(char *str); Header: cxlwin.h Inputs: str - the address of the string to print Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wprintf wprints wputns wtextattr Example: wputs("\tHello, world\n\7"); Name: wrestore Purpose: restores a previously saved window of screen memory. Prototype: void wrestore(int *wbuf); Header: cxlwin.h 70 Inputs: wbuf - address of previously saved window Return: none Also see: srestore wsave wunhide Example: wrestore(wbuf); Name: wrjusts Purpose: displays a string right justified to specified column in active window. Prototype: int wrjusts(int wrow,int wjcol,int attr,char *str); Inputs: wrow - window row wjcol - window column to right justify to attr - attribute of string text str - address of string to display Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates W_STRLONG - string too long to fit in window at specified right justification column. Also see: wcenters wprints Example: wrjusts(3,20,LMAGENTA,"Hello, world"); Name: wsave Purpose: saves a window of screen memory. Prototype: int *wsave(int srow,int scol,int erow,int ecol); Header: cxlwin.h Inputs: srow - starting row, upper left corner scol - starting column, upper left corner erow - ending row, lower right corner ecol - ending column, lower right corner Return: address of newly created window buffer or NULL if a memory allocation error occurred. Also see: ssave videoinit whide wintodisk wrestore Example: int *wbuf; ...... wbuf=wsave(7,7,18,60); if(!wbuf) { printf("Memory allocation error\n"); exit(1); } Name: wsbounds Purpose: sets active window's scroll boundaries. Prototype: int wsbounds(int wssrow,int wsscol,int wserow,int wsecol); Header: cxlwin.h Inputs: wssrow - window scroll start row wsscol - window scroll start column wserow - window scroll end row wsecol - window scroll end column Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - invalid coordinates 71 Also see: wscroll Example: wsbounds(10,10,20,20); Name: wscanf Purpose: inputs a formatted string from keyboard, works like scanf() does. This function is only supported by Turbo C. Prototype: int wscanf(const char *format,...); Header: cxlwin.h Inputs: format - format string, refer to the section on scanf() in the run-time library reference. ... - any additional arguments Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wgetc wgetns wgets winpdef winputsf wtextattr Example: wscanf("%d %c",&int_value,&char_value); Name: wscroll Purpose: scrolls text within the active window, up or down. Prototype: int wscroll(int count,int direc); Header: cxlwin.h Inputs: count - number of lines to scroll direc - scroll direction: SUP - scroll up SDOWN - scroll down Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: wdelline winsline wsbounds Example: wscroll(2,SDOWN); Name: wsetesc Purpose: sets the Escape checking for window keyboard input functions that allow Escape checking. Prototype: void wsetesc(int option); Header: cxlwin.h Inputs: option - (0-1), 0 = turn Escape checking off, 1 = turn Escape checking on Return: none Also see: wgetchf wgetns winpread winputsf wmenuget Example: wsetesc(0); /* turns Escape checking off */ Name: wsize Purpose: adjusts the size of the active window. Prototype: int wsize(int nerow,int necol); Header: cxlwin.h Inputs: nerow - new end row of sized window necol - new end column of sized window Return: W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window 72 W_INVCOORD - invalid coordinates Also see: wcopy wmove Example: if(wsize(23,40)) { printf("Error: %s\n",werrmsg()); exit(1); } Name: wsseldef Purpose: defines a window string selection record. For a complete example of using these string selection functions, see the section "String Selection Functions" in the Tutorial. Prototype: int wsseldef(char *str); Header: cxlwin.h Inputs: str - string to be used for selection Return: W_NOERROR - no error W_ALLOCERR - memory allocation error W_NOACTIVE - no active window Also see: wsselget Example: if(wsseldef("LPT1")) { printf("%d %s\n",_werrno,werrmsg()); exit(1); } Name: wsselget Purpose: gets a string selection from the keyboard Prototype: char *wsselget(int attr); Inputs: attr - attribute of the selections Return: the address of the selected string or NULL if error. If error, the global variable _werrno will be set to one of the following: W_NOERROR - no error W_NOACTIVE - no active window W_ESCPRESS - Escape key was pressed W_NOSELDEF - no selection records defined Also see: wsetesc wsseldef Example: char *p; p=wsselget(LRED|_GREEN); if(p==NULL) { printf("%d %s\n",_werrno,werrmsg()); exit(1); } Name: wtextattr Purpose: sets the default text attribute for text displayed in active window. Prototype: int wtextattr(int attr); Header: cxlwin.h Inputs: attr - the new text attribute Return: W_NOERROR - no error W_NOACTIVE - no active window Also see: attrib wchgattr Example: 73 wtextattr(LMAGENTA|BLINK); Name: wtitle Purpose: gives active window a title and displays title on top border line of window. Prototype: int wtitle(char *str,int tpos,int tattr); Header: cxlwin.h Inputs: str - address of title string or NULL to delete title tpos - position of title: TDELETE - to delete title TLEFT - left justified TCENTER - centered TRIGHT - right justified tattr - attribute of window's title Return: W_NOERROR - no error W_NOACTIVE - no active window W_STRLONG - title string too long for window W_INVTPOS - invalid title position argument Also see: wmessage Example: wtitle("[ My Window ]",TCENTER,YELLOW); Name: wunhide Purpose: unhides a previously hidden window. Prototype: int *wunhide(int **wbuf); Header: cxlwin.h Inputs: wbuf - address of the pointer to the window buffer to unhide Return: the address of the unhidden window's buffer or a NULL if a memory allocation error occurred Also see: whide wrestore Example: if(!wunhide(wbuf)) { printf("Memory allocation error\n"); exit(1); } Name: wvline Purpose: draws a vertical text line in active window using characters defined by given box type. If vertical line crosses a horizontal line of the same box type, an appropriate intersection or corner will be used. Prototype: int wvline(int wsrow,int wscol,int count,int btype); Header: cxlwin.h Inputs: wsrow - window start row of line wscol - window start column of line count - number of line characters to display btype - box type (0-5) Return: W_NOERROR - no error W_NOACTIVE - no active window W_INVCOORD - entire text line could not fit in window W_INVBTYPE - invalid box type Also see: whline wtextattr Example: 74 wvline(3,9,14,1); 75