VERMONT VIEWS (tm) v3.05 ORGANIZATION OF READ_ME.VV 1. About This Release 2. Installation 3. Compiler-Specific Information 3.1 Only Large and Medium Memory Model Libraries Distributed 3.2 Compatibility with Other Compilers 3.3 Compatibility with Microsoft C v6.0 and v7.0 3.4 Compatibility with C++ Libraries 3.5 Running Out of Compiler Space 3.6 Increasing Stack Size 4. Problems and Solutions 4.1 Maximum Number of Files that Can Be Opened by the System 4.2 Compatibility with Monochrome Monitors that Display Shades of Gray 4.3 Selection Characters on Monochrome Displays in the Designer 4.4 Conflicts with Other Products' Header Files 5. Mouse Related Information 5.1 Using ki() in a Mouse-enabled Application 5.2 Enabling Mouse Support for Vermont Views Tutorials 1. ABOUT THIS RELEASE VERSION: 3.05 RELEASED: March 30, 1992 OS: PCDOS Compiler: Microsoft C v6.0 or v7.0 Borland Turbo C v2.x Borland Turboc C++ v3.0 Borland C++ v2.0 or v3.0 Watcom v8.0, v8.5, or v9.0 2. INSTALLATION The system disk contains an installation program that will automatically copy and de-archive the necessary files. See the "Read Me First" booklet for complete installation information. 3. COMPILER-SPECIFIC INFORMATION 3.1 Only Large and Medium Memory Model Libraries Distributed Vermont Views v3.05 is being distributed with the large and medium memory model libraries only. Shrouded (encrypted) source code is provided for those who want to use other memory models. A set of batch files for building libraries is provided in the /shrsrc sub-directory. Please review the comments in the batch file buildvv.bat in that directory for more information. You may also want to look at the other batch files in that sub-directory to review and/or modify the compiler options used. The distributed libraries have been compiled using the same options as the batch files provided. WARNING: Only libraries built with the compiler options used in the batch files we provide have been tested at Vermont Creative Software. Other compiler options may cause the libraries to malfunction. In particular, we do not recommend using the optimization option that relaxes alias checking. Exercise caution! 3.2 Compatibility with Other Compilers While the use of other versions of the compilers is not recommended, it may be possible to use other compiler versions if you build Vermont Views libraries from the shrouded source using that version of the compiler. The assembly modules have been assembled using MASM 5.1 or TASM 2.5. The assembly code is MASM 5.0 and TASM compatible. Porting to compilers other than Microsoft C, Watcom, and Borland would most likely involve source code changes. Fully commented Vermont Views source code would probably be necessary for such a port. 3.3 Compatibility with Microsoft C v6.0 and v7.0 Microsoft C has a new optimization available. It offers the ability to pass parameters in registers rather than on the stack. Our experience has been that this reduces code size by about 8% and increases execution speed. The Vermont Views libraries as shipped do not take advantage of this optimization. In order to use register parameter passing, you must rebuild the Vermont Views libraries. You can use the batch files provided with Vermont Views, if you modify them properly. You must change the compile line to include the following switch: /DFASTCALL /Gr In addition, all your functions must be declared with the FASTCALL keyword, i.e.: int FASTCALL my_func(); If you do not do this, you will get a warning from the compiler that the functions have different attributes. We recommend that you use stack passing during development and register passing for production versions of your application. Because FASTCALL is defined in vv_sys.h as '_cdecl' (stack passing), if you do not define FASTCALL on the compile line stack, passing is done by default. MS C 6.0 optimizations, other than the ones that are ON by default, sometimes generate bad code. When compiling Vermont Views, do not specify any optimizations at all. This implies no -O option of any kind on the compile line. The MS C 6.0 compiler is pickier than 5.1, especially at the new warning level W4. There will be warning messages about signed/unsigned mismatches in numeric assignment and comparison statements. Ignore these warnings. The code produced is fine. 3.4 Compatibility with C++ Libraries The Vermont Views v3.05 libraries for Borland C++, Turbo C++, and Microsoft 7.0 are standard C libraries (i.e., the -P option was not used when compiling). You may link the Vermont Views standard C libraries to a C++ application, provided you keep the following information mind. vv_main.h: vv_main.h initializes certain structures to function pointers. These functions are defined as PFI (Pointer to function returning an int). Because C++ does more rigorous type checking, these functions will produce the error "Cannot assign ident1 to ident2". To correct this problem, you need to create a new module. This module should contain the Vermont Views header files you would normally place in main(). You must compile this new module as a standard C function. Tutorials: The Vermont Views tutorials are standard C applications. To turn a tutorial into a C++ application, you must make the following changes (wn_basic.c is used as an example here). You must modify all other tutorials in the same fashion: 1. When you try to compile wn_basic.c, you will get an error message, "Cannot overload main". This error occurs because of the prototype we have set up for main(). To avoid this problem, only set up the prototype for main() if the C++ global __cplusplus is not defined. Replace #ifdef LINT_ARGS /* ANSI prototyping enabled */ int CDECL main(void); #else int CDECL main(); #endif With #ifdef LINT_ARGS /* ANSI prototyping enabled */ #ifndef __cplusplus int CDECL main(void); #endif #else #ifndef __cplusplus int CDECL main(); #endif #endif 2. When you try to link wn_basic.c as a C++ application against the libraries we provide, you will get an error "Cannot assign ident1 to ident2", as explained above. To solve this problem, you need to place vv_main.h and vv_key.h in a separate module. Compile the new module as a standard C module. In this case, we are placing them in vv_glob.c. In wn_basic.c, you will not need to include vv_main.h if you are using C++. Set up the following module called vv_glob.c /* vv_glob.c */ #include #include In wn_basic.c, replace #include #include /* Main module header file */ With #include #ifndef __cplusplus #include #endif 4. When you link wn_basic.c, you must link vv_glob.c in as well. 3.5 Running Out of Compiler Space When using Vermont Views with the Microsoft C compiler, you may be able to create files that are too large to be compiled. You will receive an "out of near/far heap space" error. Microsoft provides an alternate form of compiler pass 1 named C1L.EXE to work around this problem. See the Microsoft C compiler readme files and documentation for more information. 3.6 Increasing Stack Size When using the large memory model, you may have to increase the size of the stack for your application. You can do this at link time with the /STACK:xxxx option where xxxx is the size of the stack. The default stack is 2048 bytes. Increasing the stack to 4096 bytes should be sufficient. Microsoft also provides the exemod utility to change the size of the stack for an .exe file. 4. PROBLEMS AND SOLUTIONS 4.1 Maximum Number of Files that Can Be Opened by the System Because of the deeply nested header file system used in Vermont Views, it may be necessary to change the maximum number of files that can be opened at the same time. To do this, modify your config.sys file and change the value assigned to FILES. You will then have to reboot. If FILES is not present in config.sys, it defaults to 8. We set ours to 20 and have never had any problems. The problem usually shows up during compile time and is reported in an obscure way (e.g., "Unable to find vv_sys.h header file"). 4.2 Compatibility with Monochrome Monitors that Display Shades of Gray Some IBM PC compatibles have a monochrome monitor that will duplicate the function of the IBM PC monochrome card and the color/graphics card. This enables the monitor to work in either the monochrome or color mode. When in color mode, the colors are mapped to various shades of gray. For systems like this, the monochrome video attribute UNDERLINE is not supported. The computer maps this video attribute to a shade of gray. Compaq computers, AT&T 6300s, and possibly other brands have this problem as well. There are two ways to work around this problem: 1. Call vid_setmode(BW80) to set the video mode to BW80. This forces the application to always run in mode BW80. 2. Set the video mode to BW80 from DOS before executing the application. This will also force Vermont Views to work in monochrome mode. 4.3 Selection Characters on Monochrome Displays in the Designer The Designer uses high intensity on reverse video to highlight the selection character and unavailable items in its menu system. You may have to adjust the brightness and contrast to show the selection character and unavailable menu items. However, this video attribute combination may not be distinguishable on some monochrome monitors regardless of the brightness and contrast settings. 4.4 Conflicts with Other Products Header Files There are some name conflicts between Vermont Views and certain other products. In Vermont Views, we do the following: #define ULONG unsigned long #define UCHAR unsigned char etc... Header files provided with certain other products have typedefs for some or all of the same things, like: typedef unsigned long ULONG; So far we know that db_Vista and the OS/2 header files in Microsoft C 5.1 do this. Regrettably, there is very little we can do about this. We cannot check to see if the types have already been typedef'd, because C does not provide a way to do that. And if we change our #defines to typedefs, the compiler will issue a warning. To work around the problem #include Vermont Views header files AFTER the conflicting header files from other products. If Vermont Views header files are #included before the other header files where ULONG (or whatever) has already been defined, the typedef expands to typedef unsigned long unsigned long; which cannot be handled by the compiler. If you #include Vermont Views header files last, no macro expansion occurs, and the typedef just gets priority. The only disadvantage here is that if a function is prototyped as taking ULONG, parameters passed to it must be declared as ULONG. Using the Vermont Views approach, the parameters could be declared as either ULONG or unsigned long. The compilers would not issue a warning unless the definitions were different - which would indicate a real problem. 5. MOUSE INFORMATION 5.1 Using ki() in a Mouse-enabled Application ki() waits for a keyboard input. It does not account for the presence or absence of a mouse. In general, any application that will be using a mouse should not use ki(). A while loop should be done in which evnt_get() and et_proc() are called such as: while(!done) { if (evnt_get(&event) et_proc(&event, SYSETP, fmp); } This allows for both keyboard and mouse events to be processed. ki() can be used in a program with a mouse where you only want the keyboard to be used. In this case, disable the mouse events so that they do not "stack up" in the event queue. This is not done automatically by Vermont Views because all applications will be using a mouse and to disable it would bring in mouse overhead to non-mouse applications. To disable the mouse during ki(), recompile ki.c with KI_DISABLE_MOUSE defined. (You can do this on the command line by using a /DKI_DISABLE_MOUSE switch.) 5.2 Enabling Mouse Support for Vermont Views Tutorials None of the Vermont Views tutorials as shipped enable mouse support. To enable mouse support in any of the tutorials, add #include before vv_main.h. If you want to drag or resize windows in the tutorial you should set the necessary window options by using sw_opt(MOU_DRAG | MOU_RESIZE, ON, wnp); after the window has been brought into memory. END read_me.vv