The Window BOSS & Data Clerk Revision 02.15.90 Star Guidance Consulting, Inc. 273 Windy Drive Waterbury, Connecticut 06705 (203) 574-2449 _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER Copyright (c) 1984-1990 by Philip A. Mongelluzzo All Rights Reserved. The Window BOSS Shareware diskette, containing a copy of this manual may be freely copied and shared, but printed copies of this document may not be copied in any way without permission in writing from Star Guidance Consulting. Thank you. The Window BOSS 1. Introduction The Window BOSS is one of the most powerful and cost-effective products available to enhance and accelerate the development of system and applications programs in the "C" language. The BOSS will let you create programs that have the same look and feel as top sellers like Lotus 1-2-3, Sidekick, dBASE III, and Framework! Pop-up windows, pull down menus, status lines, and in context on- line help functions can be easily implemented. Your applications can drag windows around the screen and automatically sense the video card installed. All of this without snow, flicker, or delay! The BOSS's assistant, The Data Clerk is always on call to handle the tasks associated with data entry. Whether they be as simple as fetching a line of text or as complicated as the coordination of filling out a form, the Data Clerk will be there to assist, and if necessary, validate precious information as it is entered. Registered users can take advantage of our "Source Plus" policy that provides meticulously commented source code, technical support, and minimal fee updates. 2. Technical Nitty Gritties The Window BOSS supports PC/MSDOS for the IBM PC/XT/AT, PS/2 and compatiables. However, you'll need one of the following compilers in order to take advantage of the state-of-the-art techniques available from the BOSS: Lattice C, Microsoft C Microsoft Quick C, Borland Turbo C Computer Innovations CI86, Datalight Watcom & Watcom Express C, Zortech Aztec C, Mix Power C The BOSS is written in "C" and assembly language. You'll need the Microsoft Assembler, MASM, to assemble any local changes to the assembler source. Stats: Maximum windows: limited only by compiler and memory Maximum window: full screen (25x80, 43x80, 50x80) Minimum window: 1 row 1 column (borderless) 3 rows 3 columns (framed) Minimum fields: none Maximum fields: limited only by compiler and memory Operation: Simply include the library at link time and invoke the function desired. Page: 1 The Window BOSS 3. User Supported Software Star Guidance Consulting distributes The Window BOSS with a unique marketing approach called Shareware. The Shareware diskette with the programs and manual may be freely copied and shared. It is also available from Star Guidance for $20.00. We ask you to help us distribute The Window BOSS by sharing unmodified copies of the Shareware diskette with others. We also encourage you to register your copy for $55.00. You'll find a registration form at the end of this manual. Thank you for your support and enjoy the BOSS. 3.1. Registering Shareware is a term for software that can be freely copied and shared. The term describes copyrighted software which the author supports and encourages people to copy and share. Shareware is like public television: the programming is freely distributed, but support from users is encouraged. The concept is based on these principles: 1. People need to try programs to see if they are useful. 2. Software authors can be supported directly by users. 3. Copying and networking of programs can be encouraged. We encourage you to register your copy of The Window BOSS for $55.00. Registration has a number of benefits to you: 1. Serialized diskette containing all source code for all supported compilers. 2. Telephone Support and minimal fee updates. Minimial fees cover the cost of media, shipping, handling, and update preparation. 3. Thanks from us for your support and encouragement! 3.2. Support Services You may call or write for support services. Unless the problem is relatively complex, you will get the best results by calling. If you write, please include a phone number and the times when you will be available. Our response to written questions is much slower, but we do give priority to overseas users. We are available between 9AM and 5PM Monday through Friday, and sometimes on Saturday and Sunday. Page: 2 The Window BOSS Support Services - continued. With reference to calls, if we do not call back, please remember that about 15% of our call backs do not get completed because of faulty phone numbers, unanswered, or busy phones. If we have not called back within 1 work day, call us again. Frequent, difficult to reach, or foreign callers can expect "person to person" collect return calls. 3.2.1. Electronic Support Electronic support is provided on both GENIE and CompuServe. Support previously provided by our BBS is now provided on these services. You are strongly advised to obtain a USER ID on at least one of these fine services as no other form of electronic support can be provided. On GENIE, a special topic on the IBM PC Round Table Bulletin Board has been set up to provide support to Window BOSS users. The Window BOSS topic can be found in the "On-Line Product Support" category of the Bulletin Board. As of this writing, The IBM PC Round Table main menu is page 615 and the "On-Line Product Support" category is category # 9 of the Round Table's Bulletin Board. Simply move to page 615 by typing "M 615", select the IBM PC Round Table Bulletin Board from the menu by typing "1", then SET the category by typing "SET 9". Reading and entering messages is straight forward. The on-line help system and GENIE's user guide should assist you if you have questions. If you prefer, you can leave mail addressed to MONGELLUZZO. Round Table and Mail messages are answered on a daily basis. If you need information on obtaining a GENIE account you can call GENIE toll free at 1-800-638-9636. CompuServe electronic correspondence is limited to EMAIL. Our EMAIL ID is [71565,1001]. SIG(s) are also ocassionaly checked for messages but should not be considered a vehicle for effective communication to Star Guidance. If you are a CompuServe user and you need to reach us, use EMAIL. EMAIL messages are answerd on a daily basis. If you need information on obtaining a CompuServe account you can call CompuServe toll free at 1-800-848-8199. Page: 3 The Window BOSS 4. The Basics The Window BOSS is an extensive library of C functions for the creation, the management and the manipulation of text windows. We take care of all the housekeeping and let you, the programmer, get on with developing your application with a minimum of fuss. Both The Window BOSS and The Data Clerk are based on a layered software design in which powerful, easy to use functions are created from a series of lower level primitives. As a programmer, you will quickly appreciate our clean and uncluttered approach to getting the job done. Windows are created and defined by opening them. Once created, you can write to them, move them around, change their attributes, use them as the basis for data entry, or "kill" them by closing them. Windows are nothing more than a sub display of a larger display - the physical screen. They are defined to have size, location, and attributes like foreground color, background color, border colors and so on. The BOSS includes a whole host of functions for defining and manipulating your windows. Windows can also serve as the backdrop for data entry. Once a window is created, you can use it to convey information or to retrieve it! The Data Clerk will assist you in obtaining the desired goal, whether it be as simple as a single line of text or as complex as a complete form. Forms are an ordered collection of input requests (fields) that occur within a specific window. Fields have size, location (relative to the window which they will be displayed in), and attributes (foreground color, background color, mask values, fill characters, type [integer, float, long, text], validation ranges) and so on. Like windows, forms are created by opening them. Their contents must then be defined by using the field definition functions provided, or with your own custom field definition functions. Once created and defined, a form becomes part of the window and moves with it. Forms are "killed" by closing them (n.b. killing a form has no effect on the window to which it was anchored or to the information displayed in it, form or otherwise). The same functions used to input single data items are used to build forms. This consistency, coupled with an uncluttered approach and flexibility, gives The Window BOSS its power. Page: 4 The Window BOSS 4.1. Window Basics Here is the famous "hello" program! As you can see it's pretty simple to get windows into your applications with The Window BOSS!! You should review this code in conjunction with the function descriptions found in this manual and the concepts outlined in the Important Concepts section following the examples. #include "windows.h" /* REQUIRED */ main() { WINDOWPTR w1; /* window handle */ int batrib; /* border atrib */ int watrib; /* window atrib */ /* * Set attributes: * * border - blue/white box * window - white background/black letters * */ batrib = (BLUE << 4) | WHITE; /* border atrib */ watrib = (WHITE <<4) | BLACK; /* window atrib */ /* * Open window at 0,0 - 25 cells wide and 10 cells high */ w1 = wn_open(0,0,0,25,10,watrib,batrib); if(!w1) exit(); /* * Print the famous string and wait for key to be struck. * Close window on key strike.. exit. */ wn_printf(w1,"Hello World..."); v_getch(); /* wait for key */ wn_close(w1); /* close the window */ exit(0); /* and exit */ } /* End */ Page: 5 The Window BOSS 4.2. Data Entry Basics Lets expand our "hello" program to prompt and fetch a name. #include "windows.h" /* REQUIRED */ main() { WINDOWPTR w1; /* window handle */ int batrib; /* border atrib */ int watrib; /* window atrib */ char name[15]; /* name */ /* * Set attributes: * * border - blue/white box * window - white background/black letters * */ batrib = (BLUE << 4) | WHITE; /* border atrib */ watrib = (WHITE <<4) | BLACK; /* window atrib */ /* * Open window at 0,0 - 25 cells wide and 10 cells high */ w1 = wn_open(0,0,0,25,10,watrib,batrib); if(!w1) exit(); /* * Print the famous string, prompt and fetch a name, * wait for key to be struck. * Close window on key strike.. exit. */ wn_printf(w1,"Hello World..."); *name = NUL; /* init buffer for name */ wn_gtext(XEQ,NFRM,NFLD,w1,2,1,"Name: ",watrib,'_',15,name,NSTR,NSTR); v_getch(); /* wait for key */ wn_close(w1); /* close the window */ exit(0); /* and exit */ } /* End */ Page: 6 The Window BOSS 4.3. Form Basics Now we will expand a bit further to read a 2 field form. #include "windows.h" /* REQUIRED */ main() { WINDOWPTR w1; /* window handle */ WIFORM f1; /* form handle */ int batrib; /* border atrib */ int watrib; /* window atrib */ char name[15]; /* name */ char city[15]; /* city */ /* * Set attributes: * * border - blue/white box * window - white background/black letters * */ batrib = (BLUE << 4) | WHITE; /* border atrib */ watrib = (WHITE <<4) | BLACK; /* window atrib */ /* * Open window at 0,0 - 25 cells wide and 10 cells high */ w1 = wn_open(0,0,0,25,10,watrib,batrib); if(!w1) exit(); /* * Print the famous string, create, define, and fetch form * wait for key to be struck. * Close window on key strike.. exit. */ wn_printf(w1,"Hello World..."); *name = NUL; /* init buffer for name */ *city = NUL; /* init buffer for city */ f1 = wn_frmopn(3); /* open form 2 + 1 Fields */ wn_gtext(SET,f1,0,w1,2,1,"Name: ",watrib,'_',15,name,NSTR,NSTR); wn_gtext(SET,f1,1,w1,3,1,"City: ",watrib,'_',15,city,NSTR,NSTR); wn_frmget(f1); /* read the form */ v_getch(); /* wait for key */ wn_frmcls(f1); /* first close the form */ wn_close(w1); /* then close the window */ exit(0); /* and exit */ } Page: 7 The Window BOSS 4.4. Mouse Basics The Window BOSS includes a collection of routines that provide the building blocks for developing applications that incorporate Mouse support. As a programmer you will need three things: . The mouse and its associated hardware . The mouse driver software . C and/or Assembly level functions to communicate with the mouse The first two (of the above) are provided by the mouse manufacturer and must be installed as outlined in the manufacture's literature. The last item is provided as part of The Window BOSS. The Window BOSS's mouse functions adhere to the de facto Microsoft standard. However, all of the routines have been extensively tested with both Microsoft and Logitech mice. Mouse Communication The only practical method of communicating with the mouse is through the mouse device driver, which is accessible via software interrupt 33H. This interrupt is not used by DOS and is claimed by the mouse device driver at its invocation. Information is exchanged between the mouse device driver and calling software via the standard 8086/88 registers. As a Window BOSS user you will be pleased to know that the burden of having to deal with the mouse at this level has be replaced by a collection of "C" level routines that handle all of the aforementioned setup, software interrupts and register loading/unloading!! Mouse Usage Once the mouse has been initialized (reset), you can show it, hide it, move it, ask it where it is, check to see if its buttons have been pressed or released, make it emulate a light pen, put a cage around it (set its region), define its shape and associated attribute, or ask it how many buttons it has! Mouse Functions The standard Microsoft mouse supports 16 functions. Logitech's are the same, although some are tweaked a tad to handle the 3rd button. The Window BOSS provides an easy to use interface to the low level mouse functions and several higher level functions to ease your applications level programming. Page: 8 The Window BOSS Mouse Basics - continued. Mouse Functions - continued. The following table summarizes the 16 Microsoft Mouse Functions: Function Description Window BOSS Function 0 Initialize mouse mo_reset() 1 Show mouse mo_show() 2 Hide mouse cursor mo_hide() 3 Get position & status mo_pos() 4 Set mouse position mo_move() 5 Get button press info mo_pbinfo() 6 Get button release info mo_rbinfo() 7 Set min/max columns mo_clim() 8 Set min/max rows mo_rlim() 9 * Define graphics pointer mo_sgcursor() 10 Define text pointer mo_scursor() 11 Read motion counters mo_motion() 12 * Define event handler mo_task() 13 Light pen emulation on mo_lpon() 14 Light pen emulation off mo_lpoff() 15 * Set motion pixel ratio mo_ratio() In addition to the above low level interface routines, the following application's level functions have been implemented to ease the mouse's natural display adapter sensitivity. Without these routines, mouse applications would have to deal with the mouse in a 640x200-pixel plane - even in text mode! mo_rcpos() Return current mouse position (row, col) mo_locate() Locate mouse (row, col) mo_press() Get button pressed info (button, location..) mo_release() Get button released info ( " " " " " " " " ) mo_region() Set mouse hot area (row, col, width, height) mo_setptr() Set mouse pointer (style, attributes) mo_wait() Wait for mouse to settle (de bouncing logic) mo_nbut() Return # of buttons on mouse Most mouse applications will use and generally only need to use: mo_reset(), mo_show(), mo_hide(), and most or all of the application level functions. The low level functions are provided for those who prefer to deal with the mouse on its 640 x 200 pixel plane. All of the above supported functions are documented in the FUNCTION CALL SYNOPSIS section of this manual. * Interfaces to these functions are provided but are not supported by Star Guidance. Page: 9 The Window BOSS Mouse Basics - continued. Mouse Programming Example (Basic) #include "windows.h" /* ALWAYS */ main() { MOUSEPTR m1; /* my mouse ptr */ int mstat, mclik, mrow, mcol; /* mouse stuff */ int i; /* scratch */ v_cls(NORMAL); /* clear the screen */ v_locate(0,0,0); /* locate the cursor */ m1 = mo_reset(); /* init mouse */ if(m1) { /* mouse exists */ printf("Mouse exists with %d buttons.\n", mo_nbutt(m1)); mo_setptr(m1, 0x1E, NORMAL); /* set mouse pointer style */ mo_reigon(m1, 0, 0, 80, 25); /* set mouse "window" */ mo_show(m1); /* show the critter */ v_locate(0,5,0); printf("Roll test... move mouse, click left or right to end.\n"); do { /* rolling test */ mo_rcpos(m1, &mstat, &mrow, &mcol); v_locate(0,6,0); printf("Mouse @ %03d,%03d", mrow, mcol); } while (!mstat); v_cls(NORMAL); /* clear screen */ v_locate(0,0,0); /* home cursor */ mo_hide(m1); /* hide mouse */ m1 = mo_reset(); /* reset mouse */ exit(0); /* finito */ } else { printf("NO MICE HERE!!\n"); /* tell of woe... */ exit(0); /* exit */ } } /* End */ Page: 10 The Window BOSS 4.5. Important Concepts The preceding programming examples serve as the foundation for some fundamental, but very important concepts. 4.5.1. WINDOWS.H The Window BOSS requires the file "windows.h" to be included in any source code files that are going to reference any of the windowing, data entry, or form control functions. Take the time to peruse this file as it contains all of the constants and structures used by both The Window BOSS and Data Clerk. Also, please note that WINDOWS.H includes other standard compiler header files. 4.5.2. Window Handles All windowing functions (any function beginning with "wn_") either explicitly require an associated window pointer to work, or assume one already is, or will be, created. 4.5.3. Mouse Handles All mouse functions (any function beginning with "mo_") either explicitly require an associated mouse pointer to work, or assume one already is, or will be, created. 4.5.4. Window Origin Windows have an origin relative to the upper left hand corner of the screen which is row 0, and column 0. 4.5.5. Text and Data Field Origins Text and data fields have an origin relative to the upper left hand corner of the window, which is always row 0, column 0. 4.5.6. Attributes Attributes (foreground/background colors) must be specified for windows, borders, and data entry fields. Prompts for data entry fields always have the same attributes as the window. The fields themselves can have, but do not require, a different attribute set. Page: 11 The Window BOSS 4.5.7. Fields and Forms Fields are defined by calling the field definition functions (wn_gdate, wn_gtime, wn_gphone, ...) with "SET" as the function code (1st arg), a valid form handle (2nd arg), a field sequence number (3rd arg), and the window handle (4th arg) belonging to the window in which the form is to be displayed. The same functions that are used to retrieve discrete information can be combined to create a form when used in conjunction with wn_frmopn() and wn_frmget(). Note the use of XEQ vs. SET, NFRM vs. f1, and NFLD in the preceding two program examples. XEQ stands for "execute now", while SET stands for "set up for later execution under wn_frmget()". Forms are anchored to a particular window and must be created by wn_frmopn() and defined with field definition functions. Data entry fields can be edited, pre-filled, have validation ranges, and have both help and error messages associated with them. 4.5.8. Return Values Some functions return an indication of success or failure which you can foolishly ignore, or check to determine what action to take. 4.5.9. Closing Forms and Windows Both forms and windows should be closed when they are no longer needed. Although you can close them in any order, it makes sense to close all forms associated with a window before closing the window itself. As a side note - attempting to reference either forms or windows which have been closed can lead to unpredictable results. Page: 12 The Window BOSS Important Concepts - continued. 4.5.10. Overlapping Windows The Window BOSS fully supports the concept of overlapping windows, that is to say that you can have several windows on the screen at the same time and freely access any one of them without having to be concerned with the order in which they were opened or whether or not any other windows overlap the one you wish to access. The Window BOSS employs the "most recently used is active" concept. This concept is based on the following: . The last window referenced is the current active window. . The current active window is always the top window. For example, let us assume that you have opened three overlapping windows in the following order; w1, w2, w3. w3 is considered to be the top window because it was the last window referenced. If you now reference, or explicitly activate w2, The Window BOSS will automatically adjust the screen image to insure that w2 is now the top window with w3 and w1 being partially hidden by w2. Before After +----------+ +----------+ | W1 | | W1 | | +----------+ | +----------+ | | W2 | | | W2 | | | +------------+ | | |----+ | | | W3 | | | | W3 | | | | | | | | | | | +------------+ | | |----+ | | | | | | | +----------+ | +----------+ | | | | +----------+ +----------+ It is extremely important to keep in mind that The Window BOSS will automatically activate (bring to the top) the window being referenced. By keeping your screen layouts attractive and uncluttered there will be a minimum of window thrashing which is both annoying and time consuming. Page: 13 The Window BOSS Important Concepts - continued. 4.5.11. Functions The Window BOSS's functions fall into four major groups: those that manipulate windows, those that deal with data entry, those that deal with the mouse, and those that deal with the video or keyboard interface at a relatively low level. All window and data manipulation functions begin with the prefix "wn_" as in "wn_open". All mouse functions begin with "mo_" as in "mo_reset", while all video and keyboard based functions begin with "v_" or "_" as in "v_getch" and "_putch". This convention makes it easy to remember where to look when you want to do something. Additionally, there are several global functions which begin with "wns_". These functions, although visible to the outside world, are used internally by The Window BOSS. So ends the tale of the basics, you are now ready to add sizzle, bright lights, and artistic touches to all your applications! Page: 14 The Window BOSS 5. Distribution Methods & Media Kits The Window BOSS is distributed on 5 1/4" DSDD diskettes. There are two media kits available: The Shareware diskette kit and The Source diskette kit. This doucument describes both media kits. Neither media kit contains ALL of the files listed. The Shareware diskettes can be freely copied and shared. The Source diskettes can not. In either case you receive a bundled product -- that is to say, we do not require you to order a separate media kit for Microsoft, another for Borland, and so on. All our products include support for all the compilers we support. This makes moving from one compiler to another child's play, and it also helps to protect your software development investment, while at the same time saving you a significant sum of money! 5.1. CompuServe, GENIE & Bulletin Board Files We always upload the latest release of shareware files to GENIE, CompuServe, and selected BBS(s) around the country. These files can be found in the Vendor Support Software Library on the IBM Round Table (M 616) of GENIE and in the "C" Language Section on the IBM Programming Sig (GO IBMPRO) of CompuServe. In both cases we try to name the required files as BOSS01.LZH (code++), BOSS2A.LZH & BOSS2B.LZH (libs), BOSS03.LZH (documentation). Naturally, this naming convention is subject to the approval of the respective service provider. However, it is reasonable to assume that the required files will always conform to a naming convention that begins with "BOSS" or "BOS" and have the keyword "windows" associated with them. If you can not find The Window BOSS files on either GENIE or CompuServe it may be due to a restructuring of the SIGs by the respective service provider. Try looking in the vendor support, systems, or language areas of the SIGS. Bulletin Board files follow the same naming conventions as GENIE and CompuServe files. 5.2. The SHAREWARE Distribution Diskette(s) The SHAREWARE diskette(s) contain the following files: Disk 1 LHARC.DOC <- Archive utility document LHARC.EXE <- Archive utility BOSS_DOC.LZH <- Documentation archive BOSS_SUP.LZH <- Support archive (code, etc.) BOSS_LB1.LZH <- Library archive (Microsoft) READ.ME <- Important notes Page: 15 The Window BOSS The Shareware Distribution Diskette - continued. Disk 2 BOSS_LB2.LZH <- Library archive (Watcom, Zortech) BOSS_LB3.LZH <- Library archive (Mix, Aztec, C86) BOSS_LB4.LZH <- Library archive (Datalight, Lattice, Borland Turbo C) Contents of BOSS_DOC BOSS.MAN <- This manual BOSS.TOC <- Table of Contents Contents of BOSS_SUP AZCS.BAT <- Compiler Driver - Aztec C86.BAT <- Compiler Driver - CI86 DLCS.BAT <- Compiler Driver - Datalight LCS3.BAT <- Compiler Driver - Lattice 3.4 LCS6.BAT <- Compiler Driver - Lattice 6.0 MSC5.BAT <- Compiler Driver - Microsoft C MSQC.BAT <- Compiler Driver - Quick C PCCM.BAT <- Compiler Driver - Mix Power C TCS.BAT <- Compiler Driver - Turbo C WECS.BAT <- Compiler Driver - EXPRESS C WOCS.BAT <- Compiler Driver - Watcom C ZTCS.BAT <- Compiler Driver - Zortech C LOADAZ.BAT <- Link Batch file - Aztec LOADC86.BAT <- Link Batch file - CI86 LOADDLC.BAT <- Link Batch file - Datalight LOADLC3.BAT <- Link Batch file - Lattice 3.4 LOADLC6.BAT <- Link Batch file - Lattice 6.0 LOADMS5.BAT <- Link Batch file - Microsoft C LOADMSQC.BAT <- Link Batch file - Quick C LOADPC.BAT <- Link Batch file - Mix Power C LOADTC.BAT <- Link Batch file - Turbo C LOADWAT.BAT <- Link Batch file - Watcom C LOADWEC.BAT <- Link Batch file - EXPRESS C LOADZTC.BAT <- Link Batch file - Zortech C BOSSDEMO.C <- Source to BOSSDEMO BOSSDEMO.EXE <- DEMO Program BOSSDEMO.MAK <- MAKE file for QuickC BOSSDEMO.PRJ <- PROJECT file for Turbo C GENINDEX.C <- Source to GENINDEX HELLO.C <- The Classic... HELP.C <- Help system source INTELC.HLP <- Demo DATA file INTELC.NDX <- Index for Demo DATA file POPUP.C <- Popup menu source REV.HST <- Revision History REV.LEV <- Revision Level SAMPLE.C <- Data entry sample program Page: 16 The Window BOSS The Shareware Distribution Diskette - continued. Contents of BOSS_SUP - continued. WINDOWS.FN5 <- Type Checking INCLUDE file WINDOWS.FNZ <- Type Checking INCLUDE file WINDOWS.H <- BOSS INCLUDE file WN_FRMGE.C <- Data Entry form reader WN_GDATE.C <- Data Entry function (dates) WN_GFLOA.C <- Data Entry function (floats) WN_GPHON.C <- Data Entry function (phone) WN_GTIME.C <- Data Entry function (time) WN_IEMSG.C <- Data Entry error message handler WN_IHMSG.C <- Data Entry help message hander WN_PUTS.C <- Source to wn_puts() Contents of BOSS_LB1 SMSC5.LIB <- BOSS library - Microsoft C SMSQC.LIB <- BOSS library - Quick C (QCL) Contents of BOSS_LB2 WATEC.LIB <- BOSS library - EXPRESS C WATOC.LIB <- BOSS library - Watcom C ZTECH.LIB <- BOSS library - Zortech C Contents of BOSS_LB3 MWIN.MIX <- BOSS library - Mix Power C SAZTEC.LIB <- BOSS library - Aztec C SC86.LIB <- BOSS library - CI86 Contents of BOSS_LB4 SDLC.LIB <- BOSS library - Datalight SLAT3.LIB <- BOSS library - Lattice C 3.4 SLAT6.LIB <- BOSS library - Lattice C 6.0 STC.LIB <- BOSS library - Turbo C Page: 17 The Window BOSS 5.3. The SOURCE Distribution Diskette(s) The SOURCE diskette(s) contain the following files: DEMO / DOC Disk LHARC.DOC <- Documentation for ARC.EXE LHARC.EXE <- Archive utility DOC.LZH <- Manual DEMO.LZH <- DEMO program & data files READ.ME <- Important notes REVHST.LZH <- Revision History REV.LEV <- Revision Level DISKS.LST <- List of files on source disks Disk 1 CFILES.LZH <- Source to all "C" modules WATCOM.LZH <- Watcom Specific files DLC.LZH <- Datalight Specific files Disk 2 MS5.LZH <- Microsoft C Specific files MSQC.LZH <- Microsoft Quick C Specific files TC2.LZH <- Turbo C Specific files MIX.LZH <- Mix Power C Specific files ZTC.LZH <- Zortech C Specific files Disk 3 ASMFILES.LZH <- Source to all "Assembler" modules LC3.LZH <- Lattice 3.4 Specific files LC6.LZH <- Lattice 6.0 Specific files C86.LZH <- CI86 Specific files AZTEC.LZH <- Aztec Specific files Page: 18 The Window BOSS The SOURCE Distribution Diskette(s) - continued Contents of ASMFILES.LZH (ASM Source Files) AZVLIB.ASM <- ASM routines for Aztec DLVLIB.ASM <- ASM routines for Datalight MSVLIB.ASM <- ASM routines for MSC, Borland, Watcom VLIB.ASM <- ASM routines for Lattice & CI86 PCVLIB.ASM <- ASM routines for Mix Power C Microsoft MASM format WCVLIB.ASM <- ASM routines for WATCOM C !VLIBC.ASM <- ASM routines not found in VLIB.C Contents of AZTEC.LZH ACOMPACT.BAT <- Compact model assembler driver ALARGE.BAT <- Large model assembler driver AMEDIUM.BAT <- Medium model assembler driver ASMALL.BAT <- Small model assembler driver CCC.BAT <- Compact model compiler driver CCL.BAT <- Large model compiler driver CCM.BAT <- Medium model compiler driver CCS.BAT <- Small model compiler driver CCOMPILE.BAT <- Compact model - compile *.c LCOMPILE.BAT <- Large model - compile *.c MCOMPILE.BAT <- Medium model - compile *.c SCOMPILE.BAT <- Small model - compile *.c LOADAZ.BAT <- Link driver for BOSSDEMO MAKELIB.BAT <- Build LIB from O(s) MAKELIB.CMD <- Data file for MAKELIB.BAT SWIN.LIB <- Small model library LWIN.LIB <- Large model library WINDOWS.FNS <- Type checking header file Contents of C86.LZH (Computer Innovations Specific Files) ASMALL.BAT <- Small model assembler driver ALARGE.BAT <- Large model assembler driver CC.BAT <- Small model compiler driver CCBIG.BAT <- Large model compiler driver EPILOGUE.H <- ASM include file LCOMPILE.BAT <- Large model - compile *.c LOADC86.BAT <- Link driver for BOSSDEMO LWIN.LIB <- Large model library MAKELIB.BAT <- Builds LIB file from OBJ(s) MODEL.H <- ASM include file PROLOGUE.H <- ASM include file SCOMPILE.BAT <- Small model - compile *.c SWIN.LIB <- Small model library Page: 19 The Window BOSS The SOURCE Distribution Diskette - continued. Contents of CFILES.LZH (C Source Files) BOSSDEMO.C <- BOSSDEMO Source DOSINT.C <- AZTEC compatibility module. GENINDEX.C <- GENINDEX Source HELP.C <- Help function source HELLO.C <- The classic... POPUP.C <- Popup menu source SCANCODE.C <- Quickie to display KB scancodes SAMPLE.C <- Data entry sample program VLIB.C <- C level versions of most ASM funs. WINDOWS.C <- Globals WINDOWS.H <- Window BOSS header file WN_ACTIV.C <- Window activation, memory mgmt ++ WN_BOXSE.C <- Set box drawing character set WN_CLOSE.C <- Window Close WN_CLR.C <- Clear window WN_COLOR.C <- Set window colors WN_DBORD.C <- Draw window borders WN_DELRO.C <- Delete row in window WN_DMA.C <- Set video access mode WN_SCROL.C <- Set window scrolling method WN_INIT.C <- Initialize window system WN_DMODE.C <- Set window display mode WN_FIXCS.C <- Fix physical cursor location WN_GETS.C <- Get string with validation WN_INSRO.C <- Insert row in window WN_LOCAT.C <- Locate cursor in window WN_MOVE.C <- Move window WN_MOUSE.C <- Mouse interface routines WN_NATRI.C <- Set new attributes NOW WN_OPEN.C <- Window open WN_PRINT.C <- Window printf WN_PUTS.C <- Put string in window WN_RESTO.C <- Restore window image WN_SAVE.C <- Save window image WN_STRING.C <- String (char) functions WN_SUP.C <- Internal support functions WN_SYNC.C <- Set/Clear cursor sync WN_TITLE.C <- Title window WN_WRAP.C <- Set/Clear text wrap WPRINTF.C <- Alternate window printf WINDOWS.FN5 <- Prototype header WINDOWS.FNZ <- Prototype header Page: 20 The Window BOSS The SOURCE Distribution Diskette - continued. Contents of CFILES.LZH (C Source Files - continued.) WN_GDATE.C <- Data entry - get date WN_GDOUBLE.C <- Data entry - get double WN_GTIME.C <- Data entry - get time WN_GTEXT.C <- Data entry - get text WN_GPHONE.C <- Data entry - get phone # WN_GPWORD.C <- Data entry - get password WN_GINT.C <- Data entry - get integer WN_GUINT.C <- Data entry - get unsigned integer WN_GULONG.C <- Data entry - get unsigned long WN_GLONG.C <- Data entry - get long WN_GFLOAT.C <- Data entry - get float WN_GBOOL.C <- Data entry - get logical WN_DTEXT.C <- Data entry - display text WN_FRMOPN.C <- Data entry - FORM open WN_FRMGET.C <- Data entry - FORM read WN_FRMCLS.C <- Data entry - FORM close WN_INPUT.C <- Data entry - common input WN_IEMSG.C <- Data entry - error msg handler WN_IHMSG.C <- Data entry - help msg handler Page: 21 The Window BOSS The SOURCE Distribution Diskette - continued. Contents of MIX.LZH (Mix Power C Specific Files) ** Note: Mix Power C only supports the Medium Memory Model ** AMEDIUM.BAT <- Medium model assembler driver MCOMPILE.BAT <- Medium model - compile *.c LOADPC.BAT <- Link driver for BOSSDEMO MWIN.MIX <- Medium model library MAKELIB.BAT <- Builds MWIN.MIX MAKELIB.CMD <- Data file for MAKELIB.BAT PCCM.BAT <- Medium model compiler driver WINDOWS.FNS <- Type checking header Contents of LC3.LZH & LC6.LZH (Lattice C Specific Files) ASMALL.BAT <- Small model assembler driver ALARGE.BAT <- Large model assembler driver ADMODEL.BAT <- D model assembler driver APMODEL.BAT <- P model assembler driver LCOMPILE.BAT <- Large model - compile *.c SCOMPILE.BAT <- Small model - compile *.c PCOMPILE.BAT <- P model - compile *.c DCOMPILE.BAT <- D model - compile *.c LCS.BAT <- Small model compiler driver LCL.BAT <- Large model compiler driver LCP.BAT <- P model compiler driver LCD.BAT <- D model compiler driver LOADLC.BAT <- Link driver for BOSSDEMO LWIN.LIB <- Large model library SWIN.LIB <- Small model library MAKELIB.BAT <- Build LIB file from OBJ(s) MAKELIB.CMD <- Data file for MAKELIB.BAT WINDOWS.FNS <- Type checking header Page: 22 The Window BOSS The SOURCE Distribution Diskette - continued. Contents of DLC.LZH (Datalight Specific) ASMALL.BAT <- Small model assembler driver ALARGE.BAT <- Large model assembler driver ADMODEL.BAT <- D model assembler driver APMODEL.BAT <- P model assembler driver CCS.BAT <- Small model compiler driver CCL.BAT <- Large model compiler driver CCD.BAT <- D model compiler driver CCP.BAT <- P model compiler driver LCOMPILE.BAT <- Large model - compile *.c SCOMPILE.BAT <- Small model - compile *.c DCOMPILE.BAT <- D model - compile *.c PCOMPILE.BAT <- P model - compile *.c LOADDLC.BAT <- Link driver for BOSSDEMO LWIN.LIB <- Large model library SWIN.LIB <- Small model library MAKELIB.BAT <- Build LIB from OBJ(s) MAKELIB.CMD <- Data file for MAKELIB.BAT WINDOWS.FNS <- Type checking header Contents of TC2.LZH (Borland Turbo C Specific) ALARGE.BAT <- Large model assembler driver ASMALL.BAT <- Small model assembler driver BOSSDEMO.PRJ <- TC Project file for BOSSDEMO LCOMPILE.BAT <- TCC - Large model - compile *.c SCOMPILE.BAT <- TCC - Small model - compile *.c CCOMPILE.BAT <- TCC - Compact model - compile *.c MCOMPILE.BAT <- TCC - Medium model - compile *.c LOADTC.BAT <- Tlink driver for BOSSDEMO LWIN.LIB <- Large model library MAKELIB.BAT <- Build LIB from OBJ(s) MAKELIB.CMD <- Data file for MAKELIB.BAT SWIN.LIB <- Small model library TCCL.BAT <- Large model TCC compiler driver TCCS.BAT <- Small model TCC compiler driver TCCM.BAT <- Medium model TCC compiler driver TCCC.BAT <- Compact model TCC compiler driver WINDOWS.FNS <- Type checking header Page: 23 The Window BOSS The SOURCE Distribution Diskette - continued. Contents of MS5.LZH (Microsoft C Specific Files) ASMALL.BAT <- Small model assembler driver ALARGE.BAT <- Large model assembler driver AMEDUIM.BAT <- Medium model assembler driver ACOMPACT.BAT <- Compact model assembler driver LCOMPILE.BAT <- Large model - compile *.c SCOMPILE.BAT <- Small model - compile *.c MCOMPILE.BAT <- Medium model - compile *.c CCOMPILE.BAT <- Compact model - compile *.c MCCL.BAT <- Large model compiler driver MCCS.BAT <- Small model compiler driver MCCM.BAT <- Medium model compiler driver MCCC.BAT <- Compact model compiler driver LOADMS.BAT <- Link driver for BOSSDEMO LWIN.LIB <- Large model library SWIN.LIB <- Small model library MAKELIB.BAT <- Build LIB from OBJ(s) MAKELIB.CMD <- Data file for MAKELIB.BAT WINDOWS.FNS <- Type checking header Contents of MSQC.LZH (Microsoft QuickC Specific Files) ASMALL.BAT <- Small model assembler driver ALARGE.BAT <- Large model assembler driver AMEDUIM.BAT <- Medium model assembler driver ACOMPACT.BAT <- Compact model assembler driver SCOMPILE.BAT <- Small model - compile *.c LCOMPILE.BAT <- Large model - compile *.c MCOMPILE.BAT <- Medium model - compile *.c CCOMPILE.BAT <- Compact model - compile *.c MCCL.BAT <- Large model compiler driver MCCS.BAT <- Small model compiler driver MCCM.BAT <- Medium model compiler driver MCCC.BAT <- Compact model compiler driver LOADMS.BAT <- Link driver for BOSSDEMO LWIN.LIB <- Large model library SWIN.LIB <- Small model library MAKELIB.BAT <- Build LIB from OBJ(s) MAKELIB.CMD <- Data file for MAKELIB.BAT BOSSDEMO.MAK <- MAKE file for BOSSDEMO WINDOWS.FNS <- Type checking header Page: 24 The Window BOSS The SOURCE Distribution Diskette - continued. Contents of WATCOM.LZH ACOMPACT.BAT <- Compact model assembler driver ALARGE.BAT <- Large model assembler driver ASMALL.BAT <- Small model assembler driver AMEDIUM.BAT <- Medium model assembler driver WCCS.BAT <- Small model compiler driver WCCL.BAT <- Large model compiler driver WCCM.BAT <- Medium model compiler driver WCCC.BAT <- Compact model compiler driver XCC.BAT <- EXPRESS C compiler driver CCOMPILE.BAT <- Compact model - compile *.c LCOMPILE.BAT <- Large model - compile *.c MCOMPILE.BAT <- Medium model - compile *.c SCOMPILE.BAT <- Small model - compile *.c LOADWAT.BAT <- Link driver for BOSSDEMO LOADWEC.BAT <- Link driver for BOSSDEMO (EXPRESS C) MAKELIB.BAT <- Build LIB from OBJ(s) MAKELIB.CMD <- Data file for MAKELIB.BAT SWIN.LIB <- Small model library LWIN.LIB <- Large model library XMWIN.LIB <- EXPRESS C library WINDOWS.FNS <- Type checking header Contents of ZTC.LZH (Zortech C Specific Files) ACOMPACT.BAT <- Compact model assembler driver ALARGE.BAT <- Large model assembler driver ASMALL.BAT <- Small model assembler driver AMEDIUM.BAT <- Medium model assembler driver CCOMPILE.BAT <- Compact model - compile *.c LCOMPILE.BAT <- Large model - compile *.c LOADZTC.BAT <- Link driver for BOSSDEMO LWIN.LIB <- Larger model library MAKELIB.BAT <- Build LIB file from OBJ(s) MAKELIB.CMD <- Data file for makelib.bat MCOMPILE.BAT <- Medium model - compile *.c SCOMPILE.BAT <- Small model - compile *.c SWIN.LIB <- Small model library WINDOWS.FNS <- Type checking header file ZTCC.BAT <- Compact model compiler driver ZTCCB.BAT <- Compact model big compiler driver ZTCL.BAT <- Large model compiler driver ZTCLB.BAT <- Large model big compiler driver ZTCM.BAT <- Medium model compiler driver ZTCMB.BAT <- Medium model big comiler driver ZTCS.BAT <- Small model compiler driver ZTCSB.BAT <- Small model big compiler driver Page: 25 The Window BOSS 6. Installation, Compiling, Linking 6.1. Installation By the numbers: 1) MAKE A BACKUP OF ALL DISKS !!! 2) Shareware diskettes - Use LHARC to unarchive the various LZH files. You will need 900+k of free disk space for all of the files! Alternatively you can extract only those files you need for use with a specific compiler. Simply use LHARC to extract all the files from BOSS_SUP.LZH then the library(s) you will from BOSS_LB?.LZH, for example: B>A:LHARC E A:BOSS_SUP B>A:LHARC E A:BOSS_LB1 SMSC5.LIB ** Shareware Users Note ** - The examples used in the documentation assume the library's name to be SWIN.LIB. You may want to rename the library you extracted to conform to this naming convention to eliminate any possible confusion. Source Code diskettes - Use LHARC to unarchive CFILES.LZH and ASMFILES.LZH. Then, depending upon the compiler you intend to use, unarchive only ONE of the following: LC3.LZH, LC6.LZH, MS5.LZH, MSQC.LZH, DLC.LZH, C86.LZH, TC2.LZH, MIX.LZH, WATCOM.LZH, ZTC.LZH, or AZTEC.LZH. If you plan on unarchiving all of the compiler specific LZH files you will need aproximately 2 megabytes of free disk space! 3) Copy the LIBrary that corresponds to the compiler you are using onto the disk(s) you usually use with your "C" compiler. The LIB file should be on the same disk(s) that the "C" runtime libraries are on. Be sure that the small model library is named "SWIN.LIB". The large model library should be named "LWIN.LIB". The Mix Power C library is MWIN.MIX. The EXPRESS C library is XMWIN.LIB. 4) Copy (or rename) the compiler driver batch file that corresponds to the compiler you are using to: CSM.BAT Page: 26 The Window BOSS Installation - continued. 5) If WINDOWS.FNS is not contained in the archive for your compiler, or is not present after you unarchive the required files, copy (or rename) WINDOWS.FN5 or WINDOWS.FNZ to WINDOWS.FNS. The following table can be used: Compiler File --------- ----- LC3 & LC6 WINDOWS.FN5 Power C WINDOWS.FN5 WATCOM, EXPRESS C WINDOWS.FN5 MSC5, Quick C WINDOWS.FN5 Turbo C WINDOWS.FN5 CI86 -- None -- AZTEC WINDOWS.FNZ DLC WINDOWS.FNZ ZORTECH WINDOWS.FNZ 6) Remember there is no magic to using The Window BOSS. It's simple!! Page: 27 The Window BOSS Installation/Compiling/Linking - continued. 6.2. Compiling Compile your source code in the following manner: C>csm hello ** ALL compilers should be invoked with the compiler driver batch file supplied with The Window BOSS. Some compilers require ".c" to be added to the name of the source file e.g. "csm hello.c" 6.3. Linking Simply specify the ?WIN.LIB file that corresponds to the compiler/memory model you are using. Don't forget to include your compilers runtime library as well. The following examples demonstrate basic linking using the small model library (medium for MIX Power C): Lattice link c+hello,hello,,swin+lcm+lc+lapi+lcr <- 3.41 lmb hello,hello,,swin+lcr; <- 6.XX Computer Innovations link hello,hello,,swin+c86s2s Datalight link c+hello,hello,hello,swin+nl Microsoft (C & Quick C) link hello,hello,,swin Borland tlink /c c0s hello,hello,hello,swin emu maths cs Mix Power C pcl hello;mwin [5k,40k,0] Aztec ln hello swin.lib m.lib c.lib Watcom wlink file hello library swin,maths,clibs EXPRESS C wlink file hello library xmwin,wcexpl ZORTECH blink hello,hello,,swin Page: 28 The Window BOSS 7. General Notes Genindex, Help, and Popup are support programs and functions for the BOSSDEMO program. They can, however, serve as valuable aids to you in the creation of help screens, pulldown menus, and popup menus. The code is provided to demonstrate how the functions in The Window BOSS can be used to create online help screens and popup windows. Please feel free to modify it to suit your needs. Both the C and assembly functions make very heavy use of pointers. The code contains numerous checks to ensure that memory outside of that in use by the program is not corrupted. If you attempt to do something that would cause memory to be corrupted an error message will appear and your program will exit. This message will usually say that a bad handle was passed to some function. This error is normally caused by a stray pointer in the application code! Check all your pointer operations. Doing strcpy's to arrays with insufficient space will always cause this type of problem. Generally speaking, the members of the window control block (refer to windows.h) should not be modified unless you are familiar with how they are used by the various functions. Although the routines appear to support the multi page capabilities of the IBM Color Card, actual support of this feature has not been implemented. Invoking the functions with references to video pages other than 0 might produce interesting, but undesired results. If you are upgrading from a previous version of The Window BOSS be sure to re-compile and re-link your application. This will eliminate the possibility of any "unusual" problems. The distribution libraries were created on an IBMPC/AT under DOS 3.3 using Lattice 3.41, Lattice 6.02, Microsoft 5.1, Microsoft QuickC 2.0, Borland Turbo C 2.0, Datalight 3.10, Aztec 4.10c, Watcom C 7.0, Mix Power C 1.3.0, Zortech 2.0, and Computer Innovations CI86 2.30A. Marion was used to create the LIB files for CI86. Microsoft's LIB was used for the Microsoft variants, Datalight and Zortech. Lattice, Aztec, Watcom and the Mix Power C libraries were created with the library managers shipped with the respective compilers. Test hardware: IBMPC/XT/AT, PS/2, with IBM Monochrome, CGA, EGA, and VGA video adapters. Additionally, a wide variety of clones (8088, 8086, 80186, 80286, 80386) with brand name and noname components were also tested. Page: 29 The Window BOSS General Notes - continued. Several global symbols are used by the various functions: int wn_dmaflg; int wn_sbit; wn_dmaflg when TRUE enables direct writes into video ram. This is the default setting and should work in all cases. Setting wn_dmaflg to FALSE will disable these direct writes. When wn_dmaflg is FALSE the BIOS video routines are used. This results in slower screen updates. However, this method does have the advantage of being considered "well behaved" by IBM's Topview, Microsoft's Windows, and DESQ. wn_sbit controls the window refresh rate on systems with color cards. When set to SLOW (defined in windows.h) window displays will appear to be painted on the screen rather than flash displayed. This is the default value. Setting wn_sbit to FAST enables flash displays. Artistic use of wn_sbit can give your application that extra visual touch. Experiment! The best way to manipulate the method by which windows are updated is via the wn_dmode() function. Calling wn_dmode(PAINT) causes the image to be painted while wn_dmode(FLASH) causes the image to be flash updated. Flash updating is the preferred method. Please keep in mind that windows are always flash updated on monochrome systems. From a performance standpoint, the fastest (flicker & snow free) screen updates will occur with wn_dmaflg=TRUE and wn_sbit=FAST. The key words here are flicker and snow free. Scrolling speed can be increased with, a proportional increase in flicker (perhaps), by using wn_scroll() function to set the scrolling method for the window to BIOS. This technique will provide the fastest screen updates and scrolling on color systems. Several of the compilers support a compile time command line parameter that results in structures being byte aligned instead of word aligned. In all cases, the default (i.e. no command line parameter) option was used to compile the modules in the various libraries. Programs such as Wordstar and Lotus change the video mode when they run. If your system is equipped with a color monitor and your windows are appearing in black and white, issue a call to v_smode to set the video mode to 3. Alternatively, you can use the "MODE CO80" command at DOS level before you run your application. Page: 30 The Window BOSS General Notes - continued. 7.1. Borland Turbo C Borland Turbo C pre version 1.5 users who prefer "The Integrated Environment" over the "Command-Line Version" MUST define the symbol "BORLAND=1". (Select Options, Compiler, Defines and enter "BORLAND=1" in the dialogue box without quotes and in upper case.) Integrated Environment users MUST create PROJECT files in order to be able to create EXEcutable programs from within the Integrated Environment. The PROJECT file must contain the names of all of the programs that comprise the application along with specific entries for all 3rd party libraries being used. In the case of 3rd party libraries, the complete path specification for the library must be provided (e.g. c:\turboc\lib\swin.lib). 7.2. Microsoft C Microsoft Version 5.XX libraries were generated using the "/Zl" command line parameter. This should insure compatability with previous versions of the compiler. Some large model programs may require a stack greater than 4096 bytes. 7.3. Microsoft QuickC Microsoft QuickC - All Programming Environment users MUST create MAKE files in order to be able to create EXEcutable programs from within the Programming Environment. The MAKE file must contain the names of all of the programs that comprise the application along with specific entries for all 3rd party libraries being used. In the case of 3rd party libraries, the complete path specification for the library must be provided (e.g. c:\msc\lib\swin.lib). MAKE files are created by using the SET PROGRAM LIST pick from the OPTIONS, MAKE, menu list. Additionally, MSCV4=1 must be defined in "compiler flags" "defines" dialog box (select OPTIONS, MAKE, COMPILER FLAGS, then fill in DEFINES with MSCV4=1). Some large model programs may require a stack greater than 4096 bytes. Page: 31 The Window BOSS General Notes - continued. 7.4. MIX Power C Mix Power C - (1) Merge files must be created and edited with text editors that do not insert ^Z for end of file. (2) PCO.EXE should be in the default directory (the same directory that your C files are in). (3) The linker should always be told the amount of memory to be assigned to the stack, heap, and far heap. Since The Window BOSS uses both heap and far memory outside of your program, it is imperative that PCL be invoked with reasonable parameters. Typical values are [5k,40k,0] or [5k,40k,100k]. Refer to the chapter on the Mix Linker in the Power C manual. 7.5. Zortech C Zortech C - ZORLIB (as distributed with version 2.0 of Zortech C) can not produce a correctly formatted library of The Window BOSS functions. Microsoft's library manager LIB was used to create the libraries distributed with The Window BOSS. Please do not attempt to recreate or update any of The Window BOSS libraries with ZORLIB. Zortech has been notified of the problem. Page: 32 The Window BOSS General Notes - continued. 7.6. Lattice C Lattice C - Lattice large model programs sometimes require the heap to be set to a minimum value. This can be accomplished by setting _MNEED or specifying the stack and heap size at run time. A minimum heap size of 32k will usually satisfy most applications. REMEMBER: This is for the LARGE model only. Refer to the Lattice reference manuals for further information on setting the stack and heapsize. 7.7. Aztec C Aztec C - Use the following command when recompiling BOSSDEMO.C: csm -Z5000 bossdemo Some large model programs may require a stack greater than 4096 bytes. 7.8. Watcom C Watcom C - Some large model programs may require a stack greater than 4096 bytes. 7.9. Express C Express C - Some programs may require a stack greater than 4096 bytes. 7.10. Feedback PLEASE - Pass along your comments. The Window BOSS is your tool. If you find any logic errors let us know. We are committed to making The Window BOSS the best price performer available. Call, write, or if you prefer, you can reach us via CompuServe or GENIE. Our CompuServe electronic mail ID is [71565,1001], our GENIE mail address is MONGELLUZZO. Remember, there is no reason to sit, steam, or complain to those who can not provide any real form of support. Lastly, if you use The Window BOSS, register your copy. The Shareware System will only work if you support it! Page: 33 The Window BOSS 7.11. Hints on Resolving Common Problems Unresolved Externals - Most common with the programming environments of Turbo C and Quick C. Both of these programming environments require "program lists" or "make files". This type of error can also be caused by not explicitly specifying a Window BOSS library on the link command line. All linkers must have explicit knowledge of what 3rd party libraries are to be linked with the compiler libraries and your applications object files. This problem is usually resolved by creating a program list or make file that includes a explicit reference to one of The Window BOSS libraries, or explicitly specifying the correct Window BOSS library as part of the link command line. Refer to your compiler documentation for further information. Bad Handle Exits - Both the C and assembly functions make very heavy use of pointers. The code contains numerous checks to ensure that memory does not get corrupted or randmomly written over. This error is normally caused by a stray pointer in the application code! Check and recheck all your pointer operations. Doing strcpy's to arrays with insufficient space will always cause this type of problem. Oftentimes switching from the small memory model to large memory model will initially produce these errors in programs that were working fine in the small model. In nearly every case the problem was traced to a stray pointer or improper pointer usage. Fatal Compilation Errors - All command line compilers should be invoked with the compiler driver batch files provided as part of The Window BOSS. This insures the compiler specific compile time parameters are specified correctly. If you elect to use you own method be sure to include ALL of the command line parameters that are specified in the provide batch files. Missing Files - Remember, the documentation covers two media kits (Shareware, Source) and neither kit contains ALL files. If you are missing files that are listed for your media kit then please contact us. Linking Errors - (A) See "Unresolved Externals" above. (B) Most linking errors are the result of; (1) forgetting to specify the library to link, (2) specifying the wrong library, or (3) command line syntax errors. Double check your compiler documentation for the proper way to link "other libraries" or "3rd party libraries". Other Problems - Double check this manual for proper usage, your compile documentation, then contact us. Page: 34 The Window BOSS 8. Making Changes Incorporating local modifications or enhancements is, in part, why you acquired the source code to begin with. Incorporating your modifications or enhancements should be be a relatively straight forward task provided you follow the basic guidelines outlined in the subsequent sections of this manual. If you feel you have developed a significant enhancement that is both well documented and written please let us know. We have, from time to time, incorporated customer supplied enhancements to our products. Contact us for further details. 8.1. General Considerations First, be sure that you are familiar with the existing conventions and compiler specific feature test switches. Refer to the various BATch files for specific examples of compiler specific defines etc. Please note that we assume that you have installed your compiler exactly as suggested in the compiler's manual. This includes suggested sub-directories, PATH specifiers, and environment setup. Check and double check the "include" file requirements - make sure you have the required files and that they have been edited to correspond to the memory model you are writing code for. Creating code that compiles under numerous compilers is not an easy task. If you run into problems review your compilers documentation and browse through the batch files provided. If you still have problems - call! Carefully review the area of code you wish to modify or enhance - be sure to get a complete understanding of what's currently going on before you add your own code. With the exception of the ASM files, compiler and memory model specific feature test switches are specified on the command line. Depending upon the compiler being used, several warning errors will be generated. Warnings created by the unmodified distribution code can be safely ignored - all others should be investigated. A note of caution... PC/MS-DOS Version 2.XX's LINK can complain if you build a new library that takes advantage of later LINK enhancements. If this occurs, you can (1) upgrade to DOS 3.1++ or, (2) get a librarian that isn't so smart!! We suggest going to the later revision of DOS. Page: 35 The Window BOSS Making Changes - continued. 8.2. Specific Changes to Consider Both the Shareware and Source versions of The Window BOSS and Data Clerk are supplied with the source code to the following functions: wn_puts - put string wn_gfloat - get floating point number (data entry) wn_frmget - get form (data entry) wn_iemsg - error message handler (data entry) wn_ihmsg - help message handler (data entry) The above source code was provided to serve as the basis upon which you could develop your own enhancements to the product and to provide you with those modules which may need to be modified for your particular application. The latter is true of wn_frmget, wn_iemsg, and wn_ihmsg. You should consider modifying these routines if you want to change the way in which data entry forms are handled when completed (wn_frmget), the way in which data entry field help messages are displayed (wn_ihmsg), or the way in which data entry field error messages are displayed (wn_iemsg). In the case of wn_frmget, the code to modify is at the tail end of the file and is clearly labeled. Data entry Help messages are displayed by wn_ihmsg whenever F1 is depressed. Data entry error messages are displayed by wn_iemsg whenever validation for a particular field fails. Refer to the source code files and the descriptions of these functions in the function synopsis section of this document. Page: 36 The Window BOSS Making Changes - continued. 8.3. Making Changes - An Overview by The Numbers 1) If applicable, edit the assembler level modules as needed. Be sure to set LPROG and LDATA (if they apply). ASSEMBLE. 2) If Applicable, edit the "C" level modules. COMPILE. 3) Test your changes by linking the new/modified code with the existing libraries. For example to link your modified wn_move.c and v_getch: (Microsoft example) C> link myapp+wn_move+msvlib,,,swin If required, refer to your compiler documentation for explicit instructions on linking. 4) Update the existing Window BOSS libraries with the new "obj" files. This is done with the librarian provided with your compiler. Alternatively, you can use the batch files provided with the source code to recompile the entire library and rebuild, rather than update, The Window BOSS libraries. If required, refer to your compiler documentation for explicit instructions on how to use their librarians to update libraries. Remember, the memory model of the assembly "obj" file must correspond to the memory model of the C "obj" files and the memory model of any existing libraries. 8.4. Assembly Language Object Files The Source Media Kit now includes the object files of the assembly language functions used by The Window BOSS. This will free you from having to acquire, or use, an assembler unless you intend to make changes to those functions written in assembly language! Now, all you have to do is copy and or rename the appropriate object file before running the "MAKELIB" batch file! A object file matrix is provided to assist you in determining which object file should be used with which compiler and memory model. Page: 37 The Window BOSS Making Changes - continued. 8.5. Assembly Language Object File Matrix The matrix that follows identifies the relationship between the object filename, compiler memory model, and the filename used as part of the "MAKELIB" batch utility provided as part of The Window BOSS. Use this matrix to determine what file to rename (or copy) when recreating Window BOSS libraries that DO NOT include any changes or additions to existing assembly language functions. Object File Matrix Compiler SMALL MEDIUM COMPACT LARGE MAKELIB NAME Quick C SMSVLIB MMSVLIB CMSVLIB LMSVLIB MSVLIB.OBJ MSC SMSVLIB MMSVLIB CMSVLIB LMSVLIB MSVLIB.OBJ Turbo C SMSVLIB MMSVLIB CMSVLIB LMSVLIB MSVLIB.OBJ Watcom SWCVLIB MWCVLIB CWCVLIB LWCVLIB WCVLIB.OBJ Express C ------- MWCVLIB ------- ------- WCVLIB.OBJ Datalight SDLVLIB PDLVLIB DDLVLIB LDLVLIB DLVLIB.OBJ Lattice 3 SVLIB PVLIB DVLIB LVLIB VLIB.OBJ Lattice 6 SVLIB PVLIB DVLIB LVLIB VLIB.OBJ Zortech SMSVLIB MMSVLIB CMSVLIB LMSVLIB MSVLIB.OBJ CI86 SVLIB ------- ------- LVLIB VLIB.OBJ MIX ------- PCVLIB ------- ------- PCVLIB.MIX AZTEC SAZVLIB MAZVLIB CAZVLIB LAZVLIB AZVLIB.O Example: Rebuild the Large model libaray for Microsoft C 5.1. You would: (1) Use MCOMPILE to compile all C functions C>MCOMPILE (2) Copy LMSVLIB.OBJ to MSVLIB.OBJ C>COPY LMSVLIB.OBJ MSVLIB.OBJ (3) Rebuild the LARGE model library C>MAKELIB LWIN Page: 38 The Window BOSS Making Changes - continued. 8.6. Assembler Code Selecting the Memory Model: Computer Innovations and Lattice 1) vlib.asm Edit - Set LATTICE to 1 for Lattice DOS.MAC determines the memory model. Set LATTICE to 0 for Computer Innovations. MODEL.H determines the memory model. 2) model.h CI86 only - Set "SMALL" & "LARGE" See MODEL.H for discussion. Microsoft C, QuickC, Borland Turbo C, Watcom C, Zortech 1) msvlib.asm Set LDATA & LPROG to TRUE or FALSE wcvlib.asm LDATA is TRUE for LARGE DATA LPROG is TRUE for LARGE CODE Assemble using: MASM /MX MSVLIB; <- All but WATCOM MASM /MX WCVLIB; <- WATCOM ONLY Datalight 1) dos.mac Edit to reflect memory model. Additionally, MACROS.ASM must be present. Assemble using: MASM /MX dlvlib; MIX Power C 1) pcvlib.asm Set LDATA to FALSE, LPROG to TRUE Assemble using: MASM /ML PCVLIB; Run the MIX utility on PCVLIB.OBJ Aztec C 1) azvlib.asm Set LDATA & LPROG to TRUE or FALSE LDATA is TRUE for LARGE DATA LPROG is TRUE for LARGE CODE Assemble using: AS AZVLIB; Page: 39 The Window BOSS Making Changes - continued. 8.7. C Code Pattern your enhancements after existing code. Both wn_puts.c and wn_gfloat.c were provided explicity for this purpose. The most common mistakes are: (1) failing to call wn_activate, (2) failing to check for error returns, and (3) failing to rebuild the libraries correctly. Incorporating custom data entry functions is a straightforward task if you follow the guidelines below. . Pattern your data entry routine after wn_gfloat. . Study the relationship between wn_gfloat and wn_frmget. . Study the way in which arguments are loaded using the unions v1 through v8. . Edit windows.h and expand the table of data entry function codes to include a new code above 100, for example: #define GCUSTOM 101 The table of data entry function codes is located towards the tail end of "windows.h" and begins with: #define GDONE 0 . Edit wn_frmget.c expanding the large case statement to include a case for your custom data entry function. Pattern the code you are adding after the existing code. . Rebuild the libraries adding your custom function and replacing wn_frmget with the new version. Refer to wn_gfloat and wn_frmget.... The general logic is to call the data entry function with the arguement list corresponding to this occurance of this type of field. The data entry function tests the value of "fun". If it is "XEQ" then control immediately passes to the logic that handles data entry. If fun is "SET" then the data entry function loads the form control block (indexed by "fld") with the arguments being passed. This sets the stage for subsequent calls (in a predetermined order) from wn_frmget! When called, wn_frmget first displays all the prompt fields, and then calls the data entry functions in the order determined by the form control block. Page: 40 The Window BOSS 9. Function Call Synopsis The Window BOSS and Data Clerk Function Library Page: 41 The Window BOSS 9.1. wn_init -- init window system 9.2. wn_exit -- exit window system 9.3. wn_psinit() -- init window system given physical screen size USAGE wn_init() wn_psinit(rows, columns) int rows, columns rows = # of rows on physical screen cols = # of columns on physical screen wn_exit() wn_init() or wn_psinit() and wn_exit(), if used, should be the first and last functions called. Both wn_init() and wn_psinit() save the video state and application entry screen. wn_init() or wn_psinit() is typically the very first function called in the main program. wn_exit() restores the saved video state and screen image. wn_exit() is typically called just prior to calling exit(). wn_init() is the general case of wn_psinit(). It assumes a physical screen size of 25x80 and therefore is the most portable across video adapters. wn_psinit() allows those who need to use either the EGA 43x80 or VGA 50x80 line modes a handy way to save the existing 43 or 50 line screen image. Examples: wn_psinit(43,80); /* saves 43 line EGA screen */ wn_psinit(50,80); /* saves 50 line VGA screen */ RETURNS TRUE if successful, FALSE if error. CAUTIONS and ADDITIONAL NOTES wn_psinit() does not check to see if the parameters passed are valid for the adapter in use. wn_psinit() does not change video modes based on the parameters passed. It is the programmers responsibility to insure that the video adapter is in the correct mode for the application. Calling wn_psinit() with parameters greater than can be handled by the machines video adapter can have interesting but undesirable results. Use of wn_psinit() should be restricted to machines equipped with EGA or VGA adapters only. Page: 42 The Window BOSS 9.4. wn_dmode -- set window display mode USAGE wn_dmode(mode) int mode mode = PAINT for painted windows mode = FLASH for instant windows wn_dmode sets the windows display mode as per mode, PAINT style windows appear to be painted (top to bottom) where FLASH style windows instantly appear. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES CGA, EGA, and VGA only. Updates are made directly to video memory. Page: 43 The Window BOSS 9.5. wn_open -- open window USAGE wn = (WINDOWPTR)wn_open(page, row, col, width, height, atrib, batrib) int page, row, col, width, height, atrib, batrib; page - 0 ,1000, or 800. 1000 opens a borderless page 800 opens an exploding window row - row of upper left hand corner of the window col - column of upper left hand corner of the window width - INSIDE dimension (max value is 78, 80 if page = 1000) height- INSIDE dimension (max value is 23, 25 if page = 1000) atrib - attribute to be used IN the window batrib- attribute to be used for the border wn_open is usually the first function called to create and use a window. wn_open dynamically allocates memory to save the area defined by row, col, width, and height - saves the image, opens the window and homes the logical cursor to row 0, col 0 of the window. The window is now ready to be used by the various window management routines. Attributes are defined in windows.h. RETURNS wn = window handle or NULL if error CAUTIONS and ADDITIONAL NOTES Width and height are inside dimensions. If you want a window with a work area of 10 rows and 5 columns, the width is 7 and the height is 12. The flashing cursor will not be displayed unless wn_sync() has been called with a value of TRUE. The window "wn" automatically becomes the top window tile upon return. TSR programmers note: Exploding windows always use the system BIOS routines. Page: 44 The Window BOSS 9.6. wn_title -- title window USAGE wn_title(wn,title) WINDOWPTR wn; char *title; wn - window handle title - string pointer to title The title is displayed on the top border of the window using the currently defined border attribute. The cursor is positioned off the screen after the title is written. RETURNS TRUE if all is well, NULL if the title is to large to fit on the top border or error. CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. 9.7. wn_titla -- title window with attribute USAGE wn_titla(wn,title,atrib) WINDOWPTR wn; char *title; int atrib; wn - window handle title - string pointer to title atrib - attribute to use for text The title is displayed on the top border of the window using the attribute specified by atrib. The cursor is positioned off the screen after the title is written. RETURNS TRUE if all is well, NULL if the title is to large to fit on the top border or error. CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. Page: 45 The Window BOSS 9.8. wn_close -- close window USAGE wn_close(wn) WINDOWPTR wn; wn - handle of a previously opened window. wn_close removes the window specified by wn and restores the screen area under the window to its previous contents. The memory allocated by wn_open is returned to the free list. The cursor is positioned to where it was located prior to the wn_open call. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES None. 9.9. wn_save -- save screen image USAGE wn = (WINDOWPTR)wn_save(page, row, col, width, height) int page, row, col, width, height; page - always 0. row - row of upper left hand corner of the window col - column of upper left hand corner of the window width - INSIDE dimension (max value is 78) height- INSIDE dimension (max value is 23) wn_save can be used to save areas of the screen for purposes other than windows. Memory for the screen image is dynamically allocated. RETURNS wn = window handle or NULL if error CAUTIONS and ADDITIONAL NOTES The window handle returned by wn_save should only be used with wn_restore. Use with other routines could produce unpredictable results. Page: 46 The Window BOSS 9.10. wn_restore -- restore saved screen image USAGE wn_restore(wn) WINDOWPTR wn; wn - handle of previously wn_save(ed) window. Restores the screen image corresponding to the window handle wn, and allocated memory is returned to the free list. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES This function should only be used with window handles obtained from wn_save. 9.11. wn_move -- move window USAGE wn = (WINDOWPTR)wn_move(wn,row,col) wn - handle of window to be moved row - destination row col - destination column Moves the window corresponding to wn to a new location. The cursor is positioned off the screen after the call. RETURNS Window handle of the window moved or NULL if error. CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. Page: 47 The Window BOSS 9.12. wn_locate -- locate cursor in window USAGE wn_locate(wn, row, col) WINDOWPTR wn; int row, col; wn - window handle row - row to position to (relative to window origin) col - column to position to (relative to window origin) Position the cursor to the row and column specified. Row and Column values are relative to the origin of the window (0,0 locates the cursor in the upper left hand corner of the window referenced by wn). RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES Values of row & col are not checked. The window "wn" automatically becomes the top window tile upon return. Page: 48 The Window BOSS 9.13. wn_printf -- window printf USAGE wn_printf(wn, cs, args) WINDOWPTR wn; char *cs; ?? arg1 ... argn; wn - window handle cs - format control string args - argument list printf function for windows! RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES Output string length is limited to 254 bytes. Registered users can (of course) edit the wn_printf function and set the limit to whatever they wish. Integer only for Microsoft 3.0 and Aztec. This limitation be overcome by using sprintf in conjunction with wn_printf. For example: char buf[256]; .. .. sprintf(buf,"%d %l %x\n", intval, longval, hexval); wn_printf(wn, buf); Full support for all others. The window "wn" automatically becomes the top window tile upon return. Page: 49 The Window BOSS 9.14. wn_puts -- put string (high speed) 9.15. wn_putc -- put character USAGE wn_puts(wn, row, col, string) WINDOWPTR wn; int row, col; char *string; wn_putc(wn, row, col, c) WINDOWPTR wn; int row, col; char c; wn - window handle row - row to print the string at col - column to print the string at string- the string to print c - the character to print Row and Col are relative to the origin of the window. The cursor is displayed only if wn_synflg has been called with a value of TRUE. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES wn_puts writes the string directly to the video ram. Tabs, line feeds, carriage returns and other control characters are not filtered or processed in any way. Range checks are not performed to insure the specified string can be contained in the window. The window "wn" automatically becomes the top window tile upon return. Page: 50 The Window BOSS 9.16. wn_gets -- get string with validation USAGE (char *) wn_gets(wn, buf, va, uva) WINDOWPTR wn; char *buf; int va; char *uva; wn - window handle buf - user buffer for string va - input validation to be used uva - user validation list [optional] va specifies the type of input validation to be performed as data is being entered. Options are: (1) none no restrictions - accept everything (2) integer accept: 0 thru 9 + - (3) floating point accept: 0 thru 9 + - . (4) alpha only accept: a thru z (upper & lower case) (5) upper case only accept: A thru Z (6) validation list accept: only those characters (optional) specified via uva string. ORing va with 0x8000 disables data entry character echo. The following editing functions are supported: . backspace & rubout do the logical things . ^U, ^X, and ^C wipe the field clean . Return and Esc end the input function Data entry takes place at the current logical cursor location. You can, of course, position the cursor to where you wish prior to calling wn_gets. Example: wn_printf(wn,"Enter your name > "); wn_gets(wn,buf,4,0); RETURNS Pointer to buf or NULL if error CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. This function is provided for historical purposes, more complete and flexible functions are included as part of the Data Clerk. Page: 51 The Window BOSS 9.17. wn_putsa -- put string and attribute (high speed) 9.18. wn_putca -- put character and attribute USAGE wn_putsa(wn, row, col, string, atrib) WINDOWPTR wn; int row, col; char *string; int atrib; wn_putca(wn, row, col, c, atrib) WINDOWPTR wn; int row, col; char c; int atrib; wn - window handle row - row to print the string at col - column to print the string at string- the string to print c - the character to print atrib - attribute to be used with string Row and Col are relative to the origin of the window. The cursor is displayed only if wn_synflg has been called with a value of TRUE. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES wn_puts writes the string directly to the video ram. Tabs, line feeds, carriage returns and other control characters are not filtered or processed in any way. Range checks are not performed to insure the specified string can be contained in the window. The window "wn" automatically becomes the top window tile upon return. Page: 52 The Window BOSS 9.19. wn_insrow -- insert row in window USAGE wn_insrow(wn, row) WINDOWPTR wn; int row; wn - window handle row - row at which a line is to be inserted Row is relative to the origin of the window. All lines below the row specified are scrolled down. The currently defined window attribute is used to clear the lines inserted. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. 9.20. wn_delrow -- delete row from window USAGE wn_delrow(wn, row) WINDOWPTR wn; int row; wn - window handle row - row at which a line is to be deleted Row is relative to the origin of the window. All lines below the row specified are scrolled up. The currently defined window attribute is used to clear the lines inserted. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. Page: 53 The Window BOSS 9.21. wn_clr -- clear window USAGE wn_clr(wn) WINDOWPTR wn; wn - window handle The window corresponding to wn is cleared (mini clear screen). The currently defined window attribute is used to clear the interior of the window. The windows virtual cursor is homed. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. 9.22. wn_activate -- activate window USAGE wn_activate(wn) WINDOWPTR wn; wn - window handle Activate a previously opened window. The window specified by "wn" becomes the top window tile. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES None. Page: 54 The Window BOSS 9.23. wn_color -- set window & border attribute USAGE wn_color(wn, atrib, batrib) WINDOWPTR wn; unsigned int atrib, batrib; wn - window handle atrib - attribute to be used for the window batrib- attribute to be used for the border wn_color sets the attribute to be used for all subsequent operations in the window. The attribute byte contains the background specific data in the upper 4 bits and the foreground specific data in the lower 4 bits. Color and bit definitions can be found in windows.h. You can use a statement of the form: atrib = (bground << 4 | fground); to set the attribute to the correct format. Attributes are defined in windows.h. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 55 The Window BOSS 9.24. wn_wrap -- set/clear line wrap flag USAGE wn_wrap(wn, flag) WINDOWPTR wn; int flag; wn - window handle flag - wrap flag (TRUE or FALSE) Sets the line wrap flag for window functions. If line wrap is true, output that exceeds the width of a window is automatically placed on the next line. When the line wrap flag is false, output that exceeds the width of the window is lost. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.25. wn_sync -- set/clear cursor synchronization flag USAGE wn_sync(wn, flag) WINDOWPTR wn; int flag; wn - window handle flag - synchronization flag (TRUE or FALSE) When wn_sync is called with a value of TRUE all subsequent text output to the window will have a flashing (normal) cursor displayed following the last character output. Calling wn_sync with a value of false inhibits the cursor from physically advancing (it is always logically advanced). RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 56 The Window BOSS 9.26. wn_scroll -- set scrolling method for window USAGE wn_scroll(wn,method) WINDOWPTR wn; int method; wn - window handle. method - BIOS or DMAS Set the method to be used to scroll the contents of the window to use either the rom bios (BIOS), or the flicker free DMA logic. BIOS and DMAS are defined in "windows.h". The default scrolling mode is DMAS. The Window BOSS incorporates machine independent logic that ensures that scrolling on color systems is performed in such a way as to totally eliminate snow and flicker. This logic, although bulletproof, can slow scrolling down. Setting the scrolling method to BIOS provides a machine independent way to improve the scrolling speed with a (perhaps) proportional increase in flicker. Keep in mind that recent developments in CGA and EGA technology have, for the most part, eliminated scrolling flicker at the hardware level. If your system is equipped with one of these boards, you may achieve a noticeable improvement in scrolling speed by using wn_scroll() to set the scrolling method to BIOS. Additionally, there are several console device drivers (FANSI and NANSI to mention two) that "patch" the bios routines to achieve the same result. Setting the scrolling method to BIOS when wn_dmaflg=FALSE has no effect. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES Color systems only. Page: 57 The Window BOSS 9.27. wn_dma -- set/clear write ram directly flag USAGE wn_dma(flag) int flag; flag - write to video ram flag (TRUE or FALSE). The windowing routines assume that your video card supports direct access to the video ram (normal for monochrome monitors). RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.28. wn_fixcsr -- update window cursor position USAGE wn_fixcsr(wn) WINDOWPTR wn; wn - window handle wn_fixcsr is a companion routine to wn_sync. Causes the physical cursor to be placed at the logical cursor location. It is typically called after wn_sync has been called to disable cursor synchronization. wn_fixcsr does not alter the state of the windows cursor synchronization flag. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. Page: 58 The Window BOSS 9.29. wn_boxset -- set box drawing character set USAGE wn_boxset(ul, ur, tb, sd, ll, lr); int ul, ur, tb, sd, ll, lr; ul - upper left corner character ur - upper right corner character tb - top/bottom line character sd - left/right side character ll - lower left corner character lr - lower right corner character wn_boxset set the characters to be used to frame all future windows. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.30. wn_natrib -- set new attribute in window NOW! USAGE wn_natrib(wn,atrib) WINDOWPTR wn; int atrib; wn - window handle atrib - attribute to set the window specified by wn to. The attributes of the window are changed immediately. Attributes are defined in window.h The border is not altered. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. Page: 59 The Window BOSS 9.31. wn_dborder -- draw (replace) border on window USAGE wn_dborder(wn, ul, ur, tb, sd, ll, lr); WINDOWPTR wn; int ul, ur, tb, sd, ll, lr; wn - window handle ul - upper left corner character ur - upper right corner character tb - top/bottom line character sd - left/right side character ll - lower left corner character lr - lower right corner character The currently defined border attribute is used when drawing the border. RETURNS TRUE or NULL if error CAUTIONS and ADDITIONAL NOTES The window "wn" automatically becomes the top window tile upon return. Page: 60 The Window BOSS 9.32. wn_input -- general purpose window input USAGE wn_input(wn, row, col, prmpt, mask, fill, atrib, ubuff,hlpmsg) (WINDOWPTR) wn - window pointer int row - row in window where prompt is displayed int col - col in window where prompt is displayed char * prmpt - field prompt char * mask - data entry mask char fill - fill character unsigned atrib - attributes to be used (fground<<4 | background) char * ubuff - user text buffer of MAXSTR size char * hlpmsg- user help message - displayed when HELP is pressed wn_input is the Data Clerk's kernel. It is called by virtually all the higher level data entry functions. RETURNS: NULL if error, else non zero value (scancode of last valid exit key). CAUTIONS and ADDITIONAL NOTES: prmpt - If a prompt message is not to be provided, wn_input should be called with NSTR (null string) in the place of the prompt message text pointer, for example: wn_input(wn,row,col,NSTR,mask,fill,atrib,ubuff,hlpmsg) +--+ #defined in windows.h --^ The prompt is displayed with the current window attributes at the row and column specified in the call. Data entry begins immediately after the prompt. mask - The mask determines what type of data may be entered on a character by character basis. The control characters are as follows: # - Number (0 thru 9, -, +) a - Any ascii character (0x01 thru 0xff excluding 0x08) x - Same as 'a', but without echo (password) t - Any printable ascii char (' ' thru '~') l - lower case character (a thru z) u - upper case character (A thru Z) Page: 61 The Window BOSS wn_input -- continued. Mask Examples: Date Mask "##/##/##" Time Mask "##:##:##" Integer Mask "#######" Float Mask "FFFF.FF" Phone Number "(###) ###-####" Upper Case Mask "uuuuu" or "UUUUU" Lower Case Mask "lllll" or "LLLLL" Ascii Mask "aaaaa" or "AAAAA" No Echo Ascii "xxxxx" or "XXXXX" Text Mask "ttttt" or "TTTTT" fill - The character to be used to fill the field where mask characters appear. The typical choice for fill char is '_'. help - If a HELP message is not to be provided, wn_input should be called with NSTR (null string) in the place of the help message text pointer, for example: wn_input(wn,row,col,NSTR,mask,fill,atrib,ubuff,NSTR) +--+ #defined in windows.h --^ wn_ihmsg is called to display this message whenever the HELP (F1)key is depressed while the cursor is in the field. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Typical size is the length of the mask + 2 bytes (strlen(mask)+2). Maximum length is MAXSTR. On entry the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "Now is the time "). ubuff is returned left justified for non numeric masks. If a completely numeric mask (#) was specified and the mask does not contain any other characters, ubuff is returned right justified. Page: 62 The Window BOSS wn_input -- continued. Editing Keys Pressing the ESCape, RETURN/ENTER, UARROW, or DARROW key terminates input. Since wn_input can be called alone or from any of the custom data entry routines (wn_gint, wn_gfloat) via wn_frmget, wn_input must be able to exit in a variety of ways. If wn_input has been called as the result of a call to wn_frmget, the UARROW and DARROW keys move to the previous and next fields respectively. Backspace and the cursor RIGHT ARROW and LEFT ARROW can be used to position the cursor during entry. The space bar can also be pressed when entering numeric fields provided that no "digits", "+", or "-" has been struck. Naturally, the HOME and END key work in a predictable fashion as do the INSert and DELete keys. The HOME key positions the cursor at the start of the field, END to end of the field. The INSert key inserts a space at the current cursor position (pushing the contents of the field to the right. DELete deletes the character at the cursor location (dragging the contents of the field to the left). When the field fills and RETURN/ENTER has not been struck, the cursor waits at the end of the field for RETURN/ENTER to be pressed. You may also press Backspace, HOME, or LEFT ARROW - these allows the field to be edited again. The cursor shape indicates whether or not data can be entered, or if you are beyond the fields edge. The cursor is half size (bottom half) when data can be entered, and half size (top half) when you are beyond the edge of the field. BELLs automatically ring when you strike an invalid key or attempt to enter data beyond the edge of the field. Miscellaneous Choose your fill character wisely, as you can not enter that character as data in a field. The data entry routines are pointer intensive. Failure to insure that they are called with arguments of the right type, size, and dimension will certainly cause undesired results. Page: 63 The Window BOSS 9.33. wn_frmopn -- open data entry form USAGE wn_frmopn(nfields) int nfields - number of fields in form plus 1. RETURNS: Pointer to an array of field control blocks. (WIFORM) or NULL if error (memory could not be allocated) CAUTIONS and ADDITIONAL NOTES: If wn_frmopn returns NULL, no attempt should be made to use the data entry form in question. NULL indicates that memory could not be allocated for the form! This routine must be called before wn_frmget and wn_frmcls. If your form contains 4 fields the call wn_frmopn as follows: WIFORM frm; frm = wn_frmopn(5); Fields are sequentially numbered starting from 0 ending at nfields-2. The extra field is used for internal purposes. Refer to "sample.c" for example(s) of usage. Page: 64 The Window BOSS 9.34. wn_frmget -- get (read) data entry form USAGE wn_frmget(frm) WIFORM frm - valid field pointer. RETURNS: TRUE - indicating all fields of the form in question have been fetched and verified (where required). (-2) - indicating ESCape was pressed and form processing was terminated. or Never Returns!! CAUTIONS and ADDITIONAL NOTES: As provided, wn_frmget is very usable, however, you may wish to modify it (source has been provided for this purpose) to include some of your own custom forms or the way in which forms are processed when completed. As distributed, wn_frmget first displays all field prompts and then positions to the first field, performs data entry on a field by field basis from the first to the last (allowing editing along the way), asks for a confirmation to accept the fields on the form after the last field is entered, either accepts the form, or drops into edit mode for all the fields on the form starting at the first field. Refer to wn_input for a discussion of editing keys during data entry. wn_frmget will not return unless ESCape is pressed or all data has been entered and verified (where required). This routine must be called after wn_frmopn, and before wn_frmcls. Refer to "sample.c" for example(s) of usage. Page: 65 The Window BOSS 9.35. wn_frmcls -- close data entry form USAGE wn_frmcls(frm) (WIFORM) frm - pointer to an array of field control blocks RETURNS: TRUE CAUTIONS and ADDITIONAL NOTES: This routine should only be called if memory is scarce or there is no further need for the form you wish to close. Once a form is closed, all traces of it vanish, the only way to get it back is to start from scratch with wn_frmopn, wn_frmget and so on. Closing a form has no impact on its visual image, just its logical existence. If you wish to make a form vanish both logically and visually - close the window it is anchored to after, and only after, closing the form. In this release, a form is not automatically closed when the window to which it is anchored is closed. Refer to "sample.c" for example(s) of usage. Page: 66 The Window BOSS 9.36. wn_gdate - input date in window USAGE wn_gdate(fun,frm,fld,wn,row,col,prmpt,atrib,fill,month,day,year, ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NULL) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (int *) month - pointer to int for month (1-12) (int *) day - pointer to int for day (1-31) (int *) year - pointer to int for year (0-99) (char *) ubuff - pointer to char array of 10 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: month, day, and year via pointers. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minimum size is 10. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. Page: 67 The Window BOSS wn_gdate continued. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "12 12 88"). Only basic reasonability checks are made. Therefore, dates like 02/31/88 can be returned. Calls wn_input to perform data entry. Data must satisfy validation checks for function to return. Refer to "sample.c" for example(s) of usage. Page: 68 The Window BOSS 9.37. wn_gtime -- input time in window USAGE wn_gtime(fun,frm,fld,wn,row,col,prmpt,atrib,fill,hrs,mins, secs,ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (int *) hrs - pointer to int for month (0-24) (int *) mins - pointer to int for day (0-59) (int *) secs - pointer to int for year (0-59) (char *) ubuff - pointer to char array of 10 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: hrs, mins, and secs via pointers. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minimum size is 10. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. Page: 69 The Window BOSS wn_gtime - continued. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "23 59 22"). Only basic reasonability checks are made. Therefore, times like 24:59:59 can be returned. Calls wn_input to perform data entry. Data must satisfy validation checks for function to return. Refer to "sample.c" for example(s) of usage. Page: 70 The Window BOSS 9.38. wn_gphone -- input phone number in window USAGE wn_gphone(fun,frm,fld,wn,row,col,prmpt,atrib,fill,acode, nnx,num,ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (int *) acode - pointer to int for area code (3 digits) (int *) nnx - pointer to int for nnx (3 digits) (int *) num - pointer to int for number (4 digits) (char *) ubuff - pointer to char array of 18 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: acode, nnx, and num via pointers. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minimum size is 18 bytes. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. Page: 71 The Window BOSS wn_gphone - continued. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. 800 555 1212). No validation is performed. Leaving the field blank returns 0 for ACODE, NNX, and NUM. Calls wn_input to perform data entry. Refer to "sample.c" for example(s) of usage. Page: 72 The Window BOSS 9.39. wn_gtext -- input text in window 9.40. wn_gutext -- input uppper case text in window 9.41. wn_gltext -- input lower case text in window USAGE wn_gtext(fun,frm,fld,wn,row,col,prmpt,atrib,fill,fwidth, ubuff,hlpmsg,errmsg) wn_gutext(..same as wn_gtext) wn_gltext(..same as wn_gtext) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character int fwidth - width of mask (maximum # of digits is MAXSTR) (char *) ubuff - pointer to char array of fwidth+2 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: ubuff with text data via pointer. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minimum size is fwidth+2. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. Page: 73 The Window BOSS wn_gtext - continued. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "This is a line of text "). Case conversion is automatically performed when wn_gutext() or wn_gltext() are called. Calls wn_input to perform data entry. No validation is performed. Refer to "sample.c" for example(s) of usage. Page: 74 The Window BOSS 9.42. wn_gpword -- input password in window USAGE wn_gpword(fun,frm,fld,wn,row,col,prmpt,atrib,fill,fwidth, ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character int fwidth - width of mask (maximum # of digits is MAXSTR) (char *) ubuff - pointer to char array of fwidth+2 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: ubuff with text data via pointer. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minimum size is fwidth+2. On entry, the first byte of ubuff should be a null. Since this fucntion is for PASSWORD entry, editing is not available. The contents of the edit buffer on entry is ignored. Page: 75 The Window BOSS wn_gpword - continued. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "This is a line of text "). Calls wn_input to perform data entry. No validation is performed. Page: 76 The Window BOSS 9.43. wn_gint -- input integer in window USAGE wn_gint(fun,frm,fld,wn,row,col,prmpt,atrib,fill,value, fwidth,low,high,ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (int *) value - pointer to int for return value (low-high) int fwidth - width of mask (maximum # of digits is 6 with sign) int low - minimum value (lower limit of value) int high - maximum value (upper limit of value) (char *) ubuff - pointer to char array of 10 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: value via pointer. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minimum size is 10 bytes. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. Page: 77 The Window BOSS wn_gint - continued. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces. Calls wn_input to perform data entry. Data must satisfy validation checks for function to return. Calls wn_iemsg(errmsg) when validation fails. Refer to "sample.c" for example(s) of usage. Page: 78 The Window BOSS 9.44. wn_guint - input unsigned integer in window USAGE wn_guint(fun,frm,fld,wn,row,col,prmpt,atrib,fill,v, fwidth,low,high,ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR)wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (unsigned *) v - pointer to int for return value (low-high) int fwidth - width of mask (maximum # of digits is 6 with sign) unsigned low - minimum value (lower limit of value) unsigned high - maximum value (upper limit of value) (char *) ubuff - pointer to char array of 10 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: v via pointer. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minumum size is 10 bytes. Page: 79 The Window BOSS wn_guint - continued. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "-24000"). Calls wn_input to perform data entry. Data must satisfy validation checks for function to return. Calls wn_iemsg(errmsg) when validation fails. Refer to "sample.c" for example(s) of usage. Page: 80 The Window BOSS 9.45. wn_glong -- input long integer in window USAGE wn_glong(fun,frm,fld,wn,row,col,prmpt,atrib,fill,value, fwidth,low,high,ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (long*) value - pointer to long for return value (low-high) int fwidth - width of mask (maximum # of digits is 10 with sign) long low - minimum value (lower limit of value) long high - maximum value (upper limit of value) (char *) ubuff - pointer to char array of fwidth+2 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: v via pointer. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minumun size is fwidth+2. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. Page: 81 The Window BOSS wn_glong - continued. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "-24000"). Calls wn_input to perform data entry. Data must satisfy validation checks for function to return. Calls wn_iemsg(errmsg) when validation fails. Refer to "sample.c" for example(s) of usage. Page: 82 The Window BOSS 9.46. wn_gulong -- input unsigned long integer in window USAGE wn_gulong(fun,frm,fld,wn,row,col,prmpt,atrib,fill,value, fwidth,low,high,ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (unsigned long*) value - pointer to long for return value (low-high) int fwidth - width of mask (maximum # of digits is 10 with sign) unsigned long low - minimum value (lower limit of value) unsigned long high - maximum value (upper limit of value) (char *) ubuff - pointer to char array of fwidth+2 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: v via pointer. NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. Page: 83 The Window BOSS wn_gulong - continued. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minumun size is fwidth+2. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "-24000"). Calls wn_input to perform data entry. Data must satisfy validation checks for function to return. Calls wn_iemsg(errmsg) when validation fails. Page: 84 The Window BOSS 9.47. wn_gfloat -- input float in window USAGE wn_gfloat(fun,frm,fld,wn,row,col,prmpt,atrib,fill,v, fwidth,ndec,low,high,ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (float *) v - pointer to float for return value int fwidth - width of mask (maximum # of digits is 20 with sign) int ndec - # of decimal places float low - minimum value (lower limit of value) float high - maximum value (upper limit of value) (char *) ubuff - pointer to char array of fwidth+2 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: v via pointer. NULL if error, else the non zero value returned from wn_input. NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minumum size is fwidth+2. Page: 85 The Window BOSS wn_gfloat - continued. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. " -1240.20"). Calls wn_input to perform data entry. Data must satisfy validation checks for function to return. Calls wn_iemsg(errmsg) when validation fails. Refer to "sample.c" for example(s) of usage. WN_GFLOAT.C is provided in source form. Page: 86 The Window BOSS 9.48. wn_gdouble -- input double in window USAGE wn_gdouble(fun,frm,fld,wn,row,col,prmpt,atrib,fill,v, fwidth,ndec,low,high,ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (double *) v - pointer to float for return value int fwidth - width of mask (maximum # of digits is 20 with sign) int ndec - # of decimal places double low - minimum value (lower limit of value) double high - maximum value (upper limit of value) (char *) ubuff - pointer to char array of fwidth+2 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: v via pointer. NULL if error, else the non zero value returned from wn_input. CAUTIONS AND ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minumum size is fwidth+2. Page: 87 The Window BOSS wn_gdouble - continued. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. " -1240.20"). Calls wn_input to perform data entry. Data must satisfy validation checks for function to return. Calls wn_iemsg(errmsg) when validation fails. Page: 88 The Window BOSS 9.49. wn_gbool -- input logical in window USAGE wn_gbool(fun,frm,fld,wn,row,col,prmpt,atrib,fill,value, ubuff,hlpmsg,errmsg) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) unsigned atrib - field (not prompt) attributes char fill - field fill character (int *) value - pointer to int for value (0=FALSE, 1=TRUE) (char *) ubuff - pointer to char array of 3 bytes (char *)hlpmsg - pointer to help message (call with NSTR for none) (char *)errmsg - pointer to err message (call with NSTR for none) RETURNS: value via pointer (0=FALSE, 1=TRUE) NULL if error, else the non zero value returned from wn_input. CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. ubuff - Editing buffer. Must be of sufficient size to hold the data as it is entered. Minumum size is 3 bytes. On entry, the first byte of ubuff should be a null, otherwise wn_input assumes there is valid data there and will enter edit mode. This can be handy if there is a need for prefilled, but editable fields. In actual practice, wn_input uses this buffer for both initial character data entry and subsequent editing. Page: 89 The Window BOSS wn_gbool - continued. On return, ubuff contains the actual data entered in character format with fill and mask characters as spaces (e.g. "T"). Calls wn_input to perform data entry. User MUST enter T,F,Y, or N. Data must satisfy validation checks for function to return. Calls wn_iemsg(errmsg) when validation fails. Refer to "sample.c" for example(s) of usage. Page: 90 The Window BOSS 9.50. wn_dtext -- display text on input form USAGE wn_dtext(fun,frm,fld,wn,row,col,prmpt) int fun - function code (SET || XEQ) (WIFORM) frm - form pointer (actual || NFRM) int fld - field # in form (actual || NFLD) (WINDOWPTR) wn - window pointer int row - row in window where data input begins int col - col in window where data input begins (char *) prmpt - field prompt (call with NSTR for none) RETURNS: TRUE if fun==SET or Normal return value of wn_puts if fun==XEQ CAUTIONS and ADDITIONAL NOTES: fun - fun can only be SET for form setup, or XEQ for immediate execution. When called with SET, valid arguments for both "frm" and "fld" must be specified. frm is the field pointer returned from wn_frmopn(), and fld is the field sequence number in the form for this field. When called with XEQ frm must be NFRM and fld must be NFLD. Refer to "sample.c" for example(s) of usage. Page: 91 The Window BOSS 9.51. wn_iemsg -- display input error message USAGE wn_iemsg(msg) (char *) msg - pointer to message to be displayed. RETURNS: NULL if error, else TRUE CAUTIONS and ADDITIONAL NOTES: This routine should be modified or replaced with code to suit your application's specific needs. It hooks to wn_g???? such that whenever the field validation fails wn_g???? calls wn_iemsg to display an error message for the field in question. The hooks in wn_g????? are of the form: if(validation failed) wn_iemsg(msg); This routine displays a single line of text on the 25th line and waits for a key to be struck before returning to accept new data for the field in question. The error message can be a maximum of 80 characters, and must not contain any formatting directives (\n\t...). Some wn_g???? functions (i.e. wn_gtext) have no provision to validate data and therefore never attempt to call this routine. WN_IEMSG.C is provided in source form. Page: 92 The Window BOSS 9.52. wn_ihmsg -- display input help message USAGE wn_ihmsg(msg) (char *) msg - pointer to message to be displayed. RETURNS: NULL if error, else TRUE CAUTIONS and ADDITIONAL NOTES: This routine should be modified or replaced with code to suit your application's specific needs. It hooks to wn_input such that whenever the F1 key is pressed wn_input calls wn_ihmsg to display a help message for the field in question. The hooks in wn_input are of the form: if(key_struck == F1) wn_ihmsg(msg); This routine displays a single line of help on the 25th line and waits for a key to be struck before returning. The help message can be a maximum of 80 characters, and must not contain any formatting directives (\n\t...). WN_IHMSG is provided in source form. Page: 93 The Window BOSS 9.53. wn_sleftj -- (string) left justify USAGE wn_sleftj(str) (char *) str - string to left justify RETURNS: Pointer to str. CAUTIONS and ADDITIONAL NOTES: The string str is left justified in place. This funtion should not be used with literal character strings (e.g. wn_sleft(" left justify this");). Leading white space is converted to trailing white space. 9.54. wn_srightj -- (string) right justify USAGE wn_srightj(str) (char *) str - string to right justify. RETURNS: Pointer to str. CAUTIONS and ADDITIONAL NOTES: The string str is right justified in place. This funtion should not be used with literal character strings (e.g. wn_srightj("right justify this ");). Trailing white space is converted to leading white space. Page: 94 The Window BOSS 9.55. wn_scenter -- (string) center USAGE wn_scenter(sr,tr,w) (char *) sr - the string to center - source (char *) tr - the centered string - target tr contains the results of centering int w - desired width of centered string RETURNS: Pointer to tr. CAUTIONS and ADDITIONAL NOTES: tr must be a pointer to a character array of at least w+1 in size. The source string pointed to by sr is not altered in any way. Both leading and trailing white space of the source string are considered part of the string to be centered. Desired Width (W) |------------------------------------------| source "this is a simple example" target| this is a simple example | source " this is an example toooo" target| this is an example toooo | This fuction is intended to deal with strings that do not have leading or trailing white space. WN_SDELSPC can be called to prepare the string for centering. Page: 95 The Window BOSS 9.56. wn_sdelspc -- (string) delete leading/trailing spaces USAGE wn_sdelspc(str, code) char *str - string to be treated int code - operation code: 1 = delete leading 2 = delete trailing 3 = delete both RETURNS: Pointer to str. CAUTIONS and ADDITIONAL NOTES: All operations are performed in place. This funtion should not be used with literal character strings (e.g. wn_sdelspc(" mumble fratz ", 3);). 9.57. wn_strndx -- (string) return index of s2 in s1 USAGE wn_strndx(s1,s2,off) (char *) s1 - pointer to string s1 (char *) s2 - pointer to string s2 int off - s1 offset for search start RETURNS: The index (aka subscript, aka offset) of where s2 begins in s1, or (-1) if s2 could not be found in s1. CAUTIONS and ADDITIONAL NOTES: A value for "off" must be provided. Page: 96 The Window BOSS 9.58. mo_reset -- reset/init mouse USAGE ms = (MOUSEPTR) mo_reset() MOUSEPTR ms; ms - mouse handle mo_reset() must be the 1st mouse function called. Low level and applications level interface function. RETURNS mo = mouse handle or MOLPTR (null) if error CAUTIONS and ADDITIONAL NOTES Any program that uses a mouse must first initialize it in order to avoid dealing with the mouse in an unknown state. This function clears the mouse status to a "power on" state, places the mouse's cursor in the center of the screen (although hidden) and sets the mouse's active region to the full screen. Requires "windows.h" to be "#include"d. MOUSEPTR is defined in "windows.h" Example: #include "windows.h" main() { MOUSEPTR ms; ms=mo_reset(); /* init mouse */ if(ms) { ..... /* do other things */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Page: 97 The Window BOSS 9.59. mo_show -- show mouse USAGE mo_show(ms) MOUSEPTR ms; ms - mouse handle Display (show, unhide) the mouse cursor. Low level and applications level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES Example: #include "windows.h" main() { MOUSEPTR ms; ms=mo_reset(); /* init mouse */ if(ms) { mo_show(ms); /* show mouse */ ..... /* do other things */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Failure to call mo_show() will cause the mouse to never be displayed. mo_show() is usually called after mo_reset(). Page: 98 The Window BOSS 9.60. mo_hide -- hide mouse USAGE mo_hide(ms) MOUSEPTR ms; ms - mouse handle Hide (unshow, make invisible) the mouse cursor. Low level and applications level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES The only way to display the mouse cursor after it is hidden is by calling mo_show(). Example: #include "windows.h" main() { MOUSEPTR ms; ms=mo_reset(); /* init mouse */ if(ms) { mo_show(ms); /* show mouse */ v_getch(); /* wait for key hit */ mo_hide(ms); /* hide mouse */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Page: 99 The Window BOSS 9.61. mo_pos -- get mouse pixel position & status USAGE mo_pos(ms) MOUSEPTR ms; ms - mouse handle This function updates the mouse control block with current mouse status information - physical location and button status. This information is provided in real time and in the mouse's 640 x 200 pixel array corrdinate system. Low level interface function. RETURNS Nothing. Updates - Members of the mouse control block: ms->bstat - bit 0 set if left button is CURRENTLY down bit 1 set if right button is CURRENTLY down bit 2 set if center button is CURRENTLY down ms->row - mouse pixel row location ms->col - mouse pixel col location CAUTIONS and ADDITIONAL NOTES All information is reported in real time. If the mouse is in the process of being moved, the information returned may not be indicative of the final destination. This funtion is typically used in graphics mode (which The Window BOSS does not support). It is handy for "etch-a- sketch" type pixel drawing programs. Making infrequent calls to this routine can cause your program to miss button clicks. Text (80x25) row and column coordinates can be determined by dividing m->row and m->col by 8. The recommended way to obtain accurate information in a more useful format is by using mo_wait in conjunction with mo_rcpos. Also see "mo_rcpos", "mo_wait". Page: 100 The Window BOSS 9.62. mo_move -- move mouse pixel cursor USAGE mo_move(ms, row, col) MOUSEPTR ms; int row,col; ms - mouse handle row - new pixel row value col - new pixel col value This function moves the mouse to a new physical location in the mouse's 640 x 200 pixel array corrdinate system. Low level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES Pixel row and column coordinates can be determined by multiplying the text (80x25) coordinates by 8. Also see "mo_locate". Page: 101 The Window BOSS 9.63. mo_pbinfo -- get pressed mouse botton status USAGE mo_pbinfo(ms,button) MOUSEPTR ms; int button; ms - mouse handle button - button of interest (MO_LEFT or MO_RIGHT) Low level interface function. RETURNS Nothing. Updates - Members of the mouse control block: ms->bstat - bit 0 set if left button is CURRENTLY down bit 1 set if right button is CURRENTLY down bit 2 set if center button is CURRENTLY down ms->nclick - number of times the requseted button has been pressed since last call. ms->row - mouse pixel row location of last press ms->col - mouse pixel col location of last press CAUTIONS and ADDITIONAL NOTES The mouse device driver is a pretty smart critter. It keeps track of a number of things, one of them being the number of times a particular button has been pressed or released since the last time someone has asked about it. This function returns pressed button information about a specific button (MO_LEFT or MO_RIGHT), and it also returns the real time button status in the same format as mo_pos(). The ms->row and ms->column locations in the mouse control block are from the last press of the specified button. This function, like mo_pos, provides limited value for most applications programs. A better choice is mo_rbinfo (released button information and status), since the mouse device driver waits for the user to RELEASE the specified button before it updates the internal counters. MO_LEFT and MO_RIGHT are defined in "windows.h" Calling mo_pbinfo clears the mouse's pressed button history counters. Also see "mo_press", "mo_release", "mo_rbinfo" Page: 102 The Window BOSS 9.64. mo_rbinfo -- get released mouse button status mo_rbinfo(ms,button) MOUSEPTR ms; int button; ms - mouse handle button - button of interest (MO_LEFT or MO_RIGHT) Low level interface function. RETURNS Nothing. Updates - Members of the mouse control block: ms->bstat - bit 0 set if left has been released bit 1 set if right button has been released bit 2 set if center button " " " ms->nclick - number of times the requseted button has been pressed and released since last call. ms->row - mouse pixel row location of last release ms->col - mouse pixel col location of last release CAUTIONS and ADDITIONAL NOTES The mouse device driver is a pretty smart critter. It keeps track of a number of things, one of them being the number of times a particular button has been pressed or released since the last time someone has asked about it. This function returns released button information about a specific button (MO_LEFT or MO_RIGHT), and it also returns the real time button status in the same format as mo_pos(). The ms->row and ms->column locations in the mouse control block are from the last button release of the specified button. The mouse device driver waits for the user to RELEASE the specified button before it updates the internal counters. MO_LEFT and MO_RIGHT are defined in "windows.h" Calling mo_rbinfo clears the mouse's pressed button history counters. Also see "mo_release", "mo_press", "mo_pbinfo" Page: 103 The Window BOSS 9.65. mo_clim -- set mouse min/max pixel column limits USAGE mo_clim(ms,min,max) MOUSEPTR ms; int min, mix; ms - mouse handle min - column minimum in pixels (0 to 639) max - column maximum in pixels (0 to 639) mo_clim and mo_rlim limit the operational area of the mouse. Together they define the mouse's hot area, or if you prefer, they establish a fence/cage around the mouse. Low level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES min and max are not range checked, 0 is on the left. Also see "mo_reigon" 9.66. mo_rlim -- set mouse min/max pixel row limits USAGE mo_clim(ms,min,max) MOUSEPTR ms; int min, mix; ms - mouse handle min - row minimum in pixels (0 to 199) max - row maximum in pixels (0 to 199) mo_clim and mo_rlim limit the operational area of the mouse. Together they define the mouse's hot area, or if you prefer, they establish a fence/cage around the mouse. Low level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES min and max are not range checked, 0 is at the top. Page: 104 The Window BOSS 9.67. mo_sgcursor -- set mouse graphics cursor USAGE mo_sgcursor(ms, hhot, vhot, seg, off) MOUSEPTR ms; int hhot, vhot; unsigned int seg, off; ms - mouse handle hhot, vhot - X & Y relative coordinates of hot spot seg, off - segment and offset of mask set Low level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES This is an unsupported function that is useful in graphics mode only. This function is not to be used in conjunction with The Window BOSS or Data Clerk. Refer to the Microsoft and/or Logitech API manuals for a complete description of mouse function 9. Use "mo_scursor" or "mo_setptr" to set the mouse cursor. Page: 105 The Window BOSS 9.68. mo_scursor -- set mouse cursor USAGE mo_scursor(ms, type, start, stop) MOUSEPTR ms; int type, start, stop; ms - mouse pointer type - cursor type: MO_HDW for hardware MO_SFT for software start - start scan line stop - stop scan line When using a mouse, you can choose between two types of text cursors, which are hardware or software. The hardware (MO_HDW) cursor puts the video adapters text cursor under control of the mouse. This results in a single cursor appearing on the screen for both the mouse and text. The software cursor (MO_SFT) allows two cursors to appear on the screen, the normal text cursor and a mouse cursor that can take on a user defined shape and attribute. The software cursor is the default and is a simple full-cell inverse video cursor. Using the hardware cursor type MO_HDW: start - start scan line (usually 0) stop - stop scan line: monochrome max = 12 non mon max = 7 Using the software cursor type MO_SFT: Option 1 (user defined): start - 0x00 stop - display attributes in upper 8 bits. ascii character to be used as cursor in lower 8 bits. For example, to set the software cursor to a white happy face on a black background: mo_scursor(ms, MO_SFT, 0x00, 0x0703); continued... Page: 106 The Window BOSS mo_scursor - continued. Option 2 (see through rectangle): start - 0x77ff stop - 0x00 For example, to set the software cursor to a see through block: mo_scursor(ms, MO_SOFT, 0x77ff, 7700); Low level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES See also "mo_setptr". Page: 107 The Window BOSS 9.69. mo_motion -- get mouse motion counters USAGE mo_motion(ms) MOUSEPTR ms; ms - mouse handle Low level interface function. RETURNS Nothing. Updates - Members of the mouse control block: ms->vmove - vertical move counter since last call ms->hmove - horizontal move counter since last call CAUTIONS and ADDITIONAL NOTES The mouse motion counters are reset after each call. Page: 108 The Window BOSS 9.70. mo_task -- define mouse event handler USAGE mo_task(m, mask, seg, off) WINDOWPTR m; unsigned int mask, seg, off; m - mouse handle mask - event mask BIT EVENT 0 Mouse cursor moved 1 Left Button pressed 2 Left button released 3 Right button pressed 4 Right button released 5 Middle button pressed 6 Middle button released seg - segment address of handler routine off - offset portion of handler routine address This function, if properly implemented, can keep your code free of frequent mouse checks. The basic notion is to "attach" a function in your program to the mouse device driver. This function would be invoked whenever any one of the above events took place. Your function would then execute at interrupt level. There are a few shortcomings; however, your function can not perform any I/O, make any calls to DOS or call any of the ROM BIOS routines. What can it do? Actually not much other than record the fact than an event took place and dismiss the interupt. Your program can then process the event at its convenience. The difficulty with using this function is due to the fact that your function MUST look like an interupt service routine in both the way it beings executing and finishes executing. This form of code generation is something most "C" compilers are not very good at, and as a result most of these handler routines have to be written in assembly language. This function is provided as a convenience to those who are familar with writing these types of programs - it is not supported by Star Guidance. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES This is an unsupported function. Refer to the Microsoft and/or Logitech API manuals for a complete description of mouse function 12. Page: 109 The Window BOSS 9.71. mo_lpon -- mouse light pen emulation on 9.72. mo_lpoff -- mouse light pen emulation off USAGE mo_lpon(ms) MOUSEPTR ms; mo_lpoff(ms) MOUSEPTR ms; ms - mouse handle These functions allow software that exepects to find a light pen to respond (or not to respond) to the mouse as if it were a light pen. By default, light pen emluation is enabled - mo_reset() automatically turns on light pen emulation. Low level and applications level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.73. mo_ratio -- set motion to pixel ratio USAGE mo_ratio(ms) MOUSEPTR ms; ms - mouse handle Set the motion to pixel ratio (graphics mode). Low level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES This is an unsupported function. Refer to the Microsoft and/or Logitech API manuals for a complete description of mouse function 15. Page: 110 The Window BOSS 9.74. mo_rcpos -- return current position of mouse USAGE mo_rcpos(ms, status, row, col) MOUSEPTR ms; int *status, *row, *col; ms - mouse handle *status - pointer to int to receive mouse status bit 0 set if left button is CURRENTLY down bit 1 set if right button is CURRENTLY down bit 2 set if center button is CURRENTLY down *row - pointer to int to receive position of mouse row (0-25) *col - pointer to int to receive position of mouse column (0-79) Applications level interface function. RETURNS Nothing. Updates - Members of the mouse control block: ms->bstat - bit 0 set if left button is CURRENTLY down bit 1 set if right button is CURRENTLY down bit 2 set if center button is CURRENTLY down ms->row - mouse pixel row location ms->col - mouse pixel col location continued.... Page: 111 The Window BOSS mo_rcpos - continued. CAUTIONS and ADDITIONAL NOTES Example: #include "windows.h" main() { MOUSEPTR ms; int st, row, col; ms=mo_reset(); /* init mouse */ if(ms) { /* fetch status */ mo_rcpos(ms, &st, &row, &col); mo_show(ms); /* show mouse */ v_getch(); /* wait for key hit */ mo_hide(ms); /* hide mouse */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Note the use of pointers. All information is reported in real time. If the mouse is in the process of being moved the information returned may not be indicative of the final destination. Making infrequent calls to this routine can cause your program to miss button clicks. The recommended way to obtain accurate information is by using mo_wait in conjunction with mo_rcpos. See also mo_pos(), mo_wait() Page: 112 The Window BOSS 9.75. mo_locate -- locate (position) mouse cursor USAGE mo_locate(ms, row, col) MOUSEPTR ms; int row, col; ms - mouse handle row - destination row (0-24) col - destination column (0-79) mo_locate positions the mouse to the row and column specified. Applications level interface function. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES Example: #include "windows.h" main() { MOUSEPTR ms; int st, row, col; ms=mo_reset(); /* init mouse */ if(ms) { /* fetch status */ mo_rcpos(ms, &st, &row, &col); if(row != 0) /* home the mouse ?? */ mo_locate(ms, 0, 0); mo_show(ms); /* show mouse */ v_getch(); /* wait for key hit */ mo_hide(ms); /* hide mouse */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Values are not range checked. Page: 113 The Window BOSS 9.76. mo_press -- get mouse button press status USAGE mo_press(ms, button, status, nclick, row, col) MOUSEPTR ms; int button; int *status, *nclick, *row, *col; ms - mouse handle button - button of interest (MO_LEFT or MO_RIGHT) status - pointer to int to receive status information. bit 0 set if left button is CURRENTLY down bit 1 set if right button is CURRENTLY down bit 2 set if center button is CURRENTLY down nclick - pointer to int to receive number of times the mouse button specified by button has been pressed since last call. Zero indicates the button has not been pressed since the last call. row - pointer to int to receive row (0-24) of last button press. col - pointer to int to receive column (0-79) of last button press. Applications level interface function. RETURNS Nothing. Updates - Members of the mouse control block: ms->bstat - bit 0 set if left button is CURRENTLY down bit 1 set if right button is CURRENTLY down bit 2 set if center button is CURRENTLY down ms->nclick - number of times the requested button has been pressed since last call. ms->row - mouse pixel row location of last press ms->col - mouse pixel col location of last press continued.... Page: 114 The Window BOSS mo_press - continued. CAUTIONS and ADDITIONAL NOTES Example: #include "windows.h" main() { MOUSEPTR ms; int st, row, col; ms=mo_reset(); /* init mouse */ if(ms) { /* fetch status */ mo_rcpos(ms, &st, &row, &col); if(row != 0) /* home the mouse ?? */ mo_locate(ms, 0, 0); mo_show(ms); /* show mouse */ do { /* loop till press */ mo_wait(ms); /* let mouse settle */ mo_press(ms, MO_LEFT, &st, &nc, &row, &col); } while(!nc); mo_hide(ms); /* hide mouse */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Note use of POINTERS. MO_LEFT and MO_RIGHT are defined in "windows.h" Calling mo_press clears the mouse's pressed button history counters. Since mo_release waits for the mouse button to be released before updating the device drivers internal tables, it is a better choice for most applications. Also see "mo_pbinfo" Page: 115 The Window BOSS 9.77. mo_release -- get mouse button release status USAGE mo_release(ms, button, status, nclick, row, col) MOUSEPTR ms; int button; int *status, *nclick, *row, *col; ms - mouse handle button - button of interest (MO_LEFT or MO_RIGHT) status - pointer to int to receive status information. bit 0 set if left button has been pressed and released. bit 1 set if right button has been pressed and released. bit 2 set if center button has been pressed and released. nclick - pointer to int to receive number of times the mouse button specified by button has been pressed and released since last call. Zero indicates the button has not been released since the last call. row - pointer to int to receive row (0-24) of last button release. col - pointer to int to receive column (0-79) of last button release. Applications level interface function. RETURNS Nothing. Updates - Members of the mouse control block: ms->bstat - bit 0 set if left has been released bit 1 set if right button has been released bit 2 set if center button " " " ms->nclick - number of times the requested button has been pressed and released since last call. ms->row - mouse pixel row location of last release ms->col - mouse pixel col location of last release continued.... Page: 116 The Window BOSS mo_release - continued. CAUTIONS and ADDITIONAL NOTES Example: #include "windows.h" main() { MOUSEPTR ms; int st, nc, row, col; ms=mo_reset(); /* init mouse */ if(ms) { /* fetch status */ mo_rcpos(ms, &st, &row, &col); if(row != 0) /* home the mouse ?? */ mo_locate(ms, 0, 0); mo_show(ms); /* show mouse */ do { /* loop till release */ mo_wait(ms); /* let mouse settle */ mo_release(ms, MO_LEFT, &st, &nc, &row, &col); } while(!nc); mo_hide(ms); /* hide mouse */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Note use of POINTERS. The mouse device driver waits for the user to RELEASE the specified button before it updates the internal counters. MO_LEFT and MO_RIGHT are defined in "windows.h" Calling mo_release clears the mouse's pressed button history counters. Also see "mo_rbinfo", "mo_pbinfo", "mo_press" Page: 117 The Window BOSS 9.78. mo_reigon -- set mouse region USAGE mo_reigon(ms, row, col, width, height) MOUSEPTR ms; int row, col, width, height; ms - mouse pointer row - upper left hand corner row col - upper left hand corner column width - width of region (# of columns 1 to 80) height - height of region (# of rows 1 to 25) mo_reigon defines the boundaries of where the mouse may move. Establishes a fence/cage around the mouse. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES Example: #include "windows.h" main() { MOUSEPTR ms; int st, nc, row, col; ms=mo_reset(); /* init mouse */ if(ms) { /* fetch status */ mo_rcpos(ms, &st, &row, &col); if(row != 0) /* home the mouse ?? */ mo_locate(ms, 0, 0); mo_reigon(ms, 0, 0, 40, 12); /* 40x12 */ mo_show(ms); /* show mouse */ do { /* loop till release */ mo_wait(ms); /* let mouse settle */ mo_release(ms, MO_LEFT, &st, &nc, &row, &col); } while(!nc); mo_hide(ms); /* hide mouse */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Page: 118 The Window BOSS 9.79. mo_setptr -- set mouse pointer and attributes USAGE mo_setptr(ms, tchar, atrib) MOUSEPTR ms; unsigned int tchar, atrib; ms - mouse handle tchar - character to be used as the mouse cursor, valid range is 0 to 255 although a value of 0 makes no sense at all! atrib - attribute to be used. The attribute byte contains the background specific data in the upper 4 bits and the foreground specific data in the lower 4 bits. Color and bit definitions can be found in windows.h. You can use a statement as follows to set atrib: atrib = (bground << 4 | fground); RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES To set the mouse cursor to a white happy face on a backgound use the following: atrib = BLACK<<4 | WHITE; mo_setptr(ms, 0x03, atrib); Attributes are defined in windows.h. Page: 119 The Window BOSS 9.80. mo_wait -- wait for mouse to settle USAGE mo_wait(ms) MOUSEPTR ms; ms - mouse handle. Calling mo_wait causes your progam to pause until the mouse has settled - completely stopped and with its buttons up and no activity in progress. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES Example: #include "windows.h" main() { MOUSEPTR ms; int st, nc, row, col; unsigned atrib; ms=mo_reset(); /* init mouse */ if(ms) { /* fetch status */ mo_rcpos(ms, &st, &row, &col); if(row != 0) /* home the mouse ?? */ mo_locate(ms, 0, 0); mo_reigon(ms, 0, 0, 40, 12); /* 40x12 */ atrib = BLACK<<4 | WHITE; mo_setptr(ms, 0x03, atrib); mo_show(ms); /* show mouse */ do { /* loop till release */ mo_wait(ms); /* let mouse settle */ mo_release(ms, MO_LEFT, &st, &nc, &row, &col); } while(!nc); mo_hide(ms); /* hide mouse */ exit(0); /* finito */ } else { ... no mouse } } /* End */ Page: 120 The Window BOSS 9.81. mo_nbutt -- get mouse button count USAGE (int) mo_nbutt(ms) MOUSEPTR ms; ms - mouse handle RETURNS Number of buttons on mouse. CAUTIONS and ADDITIONAL NOTES None. Page: 121 The Window BOSS 9.82. _getca -- get character and attribute USAGE unsigned int _getca(page, row, col) int page, row, col; page - video page # row - row value (0-24) col - column value (0-79) _getca fetches the character and attribute at the screen coordinates defined by row and column. _getca is a general purpose routine and can be used outside of the window environment. RETURNS The character and attribute as an unsigned int. The attribute is in the upper byte, the character is in the lower byte. CAUTIONS and ADDITIONAL NOTES None. 9.83. _putca -- put character and attribute USAGE _putca(page, atch, row, col); int page, row, col; unsigned atch; page - video page # atch - attribute and character attribute in high order byte character in low order byte row - row position for character (0-24) col - column position for character (0-79) _putch is a general purpose routine that can be used outside of the window environment. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 122 The Window BOSS 9.84. _vidblt -- video block transfer USAGE _vidblt(sseg, soff, dseg, doff, n); unsigned sseg, soff, dseg, doff; int n; sseg - source segment soff - source offset dseg - destination segment doff - destination offset n - number of bytes to BLT _vidblt is similar to the lattice movedata() function except that it waits for the video retrace signal before performing the block transfer. _vidblt is a general purpose function that can be used outside of the window environment. RETURNS Nothing CAUTIONS and ADDITIONAL NOTES For use in color systems only. _vidblt references wn_sbit. 9.85. v_spage -- set active display page USAGE v_spage(page) int page; page - video page to switch the display to v_spage is a general purpose routine that can be used outside of the window environment. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES Color card only. Page: 123 The Window BOSS 9.86. v_cls -- clear entire video screen USAGE v_cls(atrib) int atrib; atrib - attribute to be used v_cls clears the entire video screen to the specified attribute and places the cursor in the upper left hand corner of the screen. v_cls is a general purpose routine that can be used outside of the window environment. Attributes are defined in windows.h. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.87. v_smode -- set video mode USAGE v_smode(mode) int mode; mode - mode to set the display to v_smode is a general purpose routine which can be used outside of the window environment. Modes are defined in windows.h. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 124 The Window BOSS 9.88. v_wca -- write character and attribute USAGE v_wca(page, char, atrib, count); int page, char, atrib, count; page - video page # char - character to write atrib - attribute to use count - number of times to repeat v_wca writes the character defined by char count times starting at the current cursor location. v_wca is a general purpose routine that can be used outside of the window environment. Attributes are defined in windows.h. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.89. v_wtty -- write character TTY mode USAGE v_wtty(char); int char; char - character to write v_wtty writes the character defined by char at the current cursor location. v_wtty is a general purpose routine that can be used outside of the window environment. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 125 The Window BOSS 9.90. v_locate -- locate (position) cursor USAGE v_locate(page, row, col); int page, row, col; page - video page # row - row to position to col - column to position to v_locate positions the cursor to the absolute coordinates specified by row and col on the specified page. The upper left hand corner of the screen is (0,0). v_locate is a general purpose routine that can be used outside of the window environment. Row and Col are range checked. You CAN position the cursor slightly (25,80) off the screen. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.91. v_hidec -- hide cursor USAGE v_hidec(); The physical cursor is located off the screen. This function does not affect any virtual cursor coordinates, it simply hides the physical cursor from view. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 126 The Window BOSS 9.92. v_sctype -- set cursor type (style) USAGE v_sctype(type, start, end); int type, start, end; type - cursor style code (0=hidden, 1=normal, 2=slow, 3=fast) start - start scan line end - end scan line As an example, to set a slow flashing block style cursor invoke this function with type=1, start=6, and end=12 (color card). RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES Color and Monochrome adapters only. Not for use on the 3270 PC or Enhanced Graphics Adapters. 9.93. v_sapu -- scroll active display page up USAGE v_sapu(nl, rul, cul, rlr, clr, atrib); int nl, rul, cul, rlr, clr, atrib; nl - number of lines to scroll rul - row of upper left hand corner of scroll area cul - column of upper left hand corner of scroll area rlr - row of lower right corner of scroll area clr - column of lower right corner of scroll area atrib - attribute to be used for blanking A value of 0 for nl scrolls (blanks) the entire area. To clear the entire video screen use v_sapu(0, 0, 0, 24, 79, NORMAL). v_sapu is a general purpose routine that can be used outside of the window environment. Attributes are defined in windows.h. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 127 The Window BOSS 9.94. v_sapd -- scroll active display page down USAGE v_sapd(nl, rul, cul, rlr, clr, atrib); int nl, rul, cul, rlr, clr, atrib; nl - number of lines to scroll rul - row of upper left hand corner of scroll area cul - column of upper left hand corner of scroll area rlr - row of lower right corner of scroll area clr - column of lower right corner of scroll area atrib - attribute to be used for blanking v_sapd is a general purpose routine that can be used outside of the window environment. A value of 0 for nl scrolls (blanks) the entire area. To clear the entire video screen use v_sapd(0, 0, 0, 24, 79, NORMAL). Attributes are defined in windows.h. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.95. v_rcpos -- return current cursor position USAGE v_rcpos(page, row, col); int page; int *row, *col; /* POINTERS */ int page - video page # int *row - pointer to int to receive row value int *col - pointer to int to receive column value v_rcpos is a general purpose routine that can be used outside of the window environment. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 128 The Window BOSS 9.96. v_rcvs -- return current video state USAGE v_rcvs(page, vm, cols); int *page, *vm, *cols; /* POINTERS */ int *page - pointer to int to receive current video page # int *vm - pointer to int to receive current video mode int *cols - pointer to int to receive current screen width v_rcvs is a general purpose routine that can be used outside of the window environment. Modes are defined in windows.h. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.97. v_getch -- get keyboard character and scan code USAGE v_getch(); v_getch is a general purpose routine that can be used outside of the window environment. RETURNS The character and scan code. The character is in the low order byte, the scan code in the high order byte. CAUTIONS and ADDITIONAL NOTES v_getch waits for a key to be struck. Page: 129 The Window BOSS 9.98. v_kstat -- get keyboard status USAGE v_kstat(); v_kstat is a general purpose routine that can be used outside of the window environment. RETURNS TRUE if a character is available, FALSE if not. CAUTIONS and ADDITIONAL NOTES None. 9.99. v_kflush -- flush keyboard buffer USAGE v_kflush(); v_kflush clears the keyboard buffer of any pending input. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. 9.100. v_border -- set border color USAGE v_border(color) int color; Set overscan border to specified color. RETURNS Nothing. CAUTIONS and ADDITIONAL NOTES None. Page: 130 The Window BOSS 10. Registration Form Registration Form Star Guidance Consulting 273 Windy Drive Waterbury, Connecticut 06705 (203) 574-2449 Company Name: _______________________________________ Name: _______________________________________ Address: _______________________________________ _______________________________________ City, State, Zip: _______________________________________ Country: _______________________________________ Phone: _______________________________________ ___ Library Source @ $55.00 USD $________._____ ___ Shareware @ $20.00 USD $________._____ Shipping (Outside USA) $5.00 USD $________._____ Shipping (USA) $3.50 USD $________._____ Connecticut Sales Tax 8.0% $_______4.40___ * (Connecticut residents only) * TOTAL ------>________._____ MasterCard/Visa: ______________________ Exp Date: ____/____ (Circle one) Printed Name: ______________________ (On Card) Signature: ______________________ Date:____/____/____ (Of Card Holder) All funds must be in US Dollars, Call for UPS COD (USA only), Personal and Company Checks Accepted. All checks must be drawn against a US Bank and payable in US Dollars. Page: 131 The Window BOSS A ASMFILES.LZH, 18, 19 Aztec C, 33 AZTEC.LZH, 18, 19 azvlib.asm, 39 B Basics Forms, 4 Mouse, 8 Windows, 4 Borland Turbo C, 31 BOSS_DOC.LZH, 15, 16 BOSS_LB1.LZH, 15, 17, 26 BOSS_LB2.LZH, 15, 17 BOSS_LB3.LZH, 15, 17 BOSS_LB4.LZH, 15, 17 BOSS_SUP.LZH, 15, 16, 17, 26 Bulletin Board Files, 15 Support, 15 C C86.LZH, 18, 19 CFILES.LZH, 18, 20, 21 D Data Entry (Basics), 6 DEMO.LZH, 18 DLC.LZH, 18, 23 dlvlib.asm, 39 DOC.LZH, 18 dos.mac, 39 E Express C, 33 F fields, 12 forms, 12 closing, 12 Forms (Basics), 7 L Lattice C, 33 LC3.LZH, 18, 22 LC6.LZH, 22 LDATA, 39 LHARC.DOC, 18 LHARC.EXE, 18 LPROG, 39 LWIN.LIB, 26 LZH Files, 15 Page: 132 The Window BOSS M macros.asm, 39 Microsoft C, 31 Microsoft Quick C, 31 Mix Power C, 32 MIX.LZH, 18, 22 model.h, 39 Mouse (Basics), 8, 9, 10 mo_clim, 104 mo_hide, 99 mo_locate, 113 mo_lpoff, 110 mo_lpon, 110 mo_motion, 108 mo_move, 101 mo_nbutt, 121 mo_pbinfo, 102 mo_pos, 100 mo_press, 114 mo_ratio, 110 mo_rbinfo, 103 mo_rcpos, 111 mo_reigon, 118 mo_release, 116 mo_reset, 97 mo_rlim, 104 mo_scursor, 106 mo_setptr, 119 mo_sgcursor, 105 mo_show, 98 mo_task, 109 mo_wait, 120 MS5.LZH, 18, 24 MSQC.LZH, 18, 24 msvlib.asm, 39 MWIN.MIX, 26 P pcvlib.asm, 39 R return values, 12 REVHST.LZH, 18 S Shareware Diskette, 15 Source Diskette, 15 Support, 2 Support Services, 2 SWIN.LIB, 26 Page: 133 The Window BOSS T TC2.LZH, 18, 23 V video attributes, 11 vlib.asm, 39 v_border, 130 v_cls, 124 v_getch, 129 v_hidec, 126 v_kflush, 130 v_kstat, 130 v_locate, 126 v_rcpos, 128 v_rcvs, 129 v_sapd, 128 v_sapu, 127 v_sctype, 127 v_smode, 124 v_spage, 123 v_wca, 125 v_wtty, 125 W Watcom C, 33 WATCOM.LZH, 18, 25 wcvlib.asm, 39 window handles, 11 window origin, 11 windows closing, 12 overlapping, 13 tiled, 13 Windows (Basics), 5 WINDOWS.FN5, 27 WINDOWS.FNS, 27 WINDOWS.FNZ, 27 wn_activate, 54 wn_boxset, 59 wn_close, 46 wn_clr, 54 wn_color, 55 wn_dborder, 60 wn_delrow, 53 wn_dma, 58 wn_dmode, 43 wn_dtext, 91 wn_exit, 42 wn_fixcsr, 58 wn_frmcls, 66 wn_frmget, 65 wn_frmopn, 64 wn_gbool, 89 wn_gdate, 67 Page: 134 The Window BOSS wn_gdouble, 87 wn_gets, 51 wn_gfloat, 85 wn_gint, 77 wn_glong, 81 wn_gltext, 73 wn_gphone, 71 wn_gpword, 75 wn_gtext, 73 wn_gtime, 69 wn_guint, 79 wn_gulong, 83 wn_gutext, 73 wn_iemsg, 92 wn_ihmsg, 93 wn_init, 42 wn_psinit, 42 wn_input, 61 wn_insrow, 53 wn_locate, 48 wn_move, 47 wn_natrib, 59 wn_open, 44 wn_printf, 49 wn_psinit, 42 wn_putc, 50 wn_putca, 52 wn_puts, 50 wn_putsa, 52 wn_restore, 47 wn_save, 46 wn_scenter, 95 wn_scroll, 57 wn_sdelspc, 96 wn_sleftj, 94 wn_srightj, 94 wn_strndx, 96 wn_sync, 56 wn_titla, 45 wn_title, 45 wn_wrap, 56 X XMWIN.LIB, 26 Z Zortec C, 32 ZTC.LZH, 18, 25 _ _getca, 122 _putca, 122 _vidblt, 123 Page: 135