C!T ROM 2

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

/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / C / EV_201 / DOCS / USERDOC.TXT < prev

Wrap

Text File | 1993-07-08 | 264KB | 6,435 lines

---------------------------------------------------------------------- TNG SOFT enterprises proudly presents ---------------------------------------------------------------------- EEEEEE AAAAAA SSSSSS YY YY 222222 000000 EE AA AA SS YY YY 22 00 00 EEEE AAAAAA SSSSSS YYYYYY 222222 00 00 EE AA AA SS YY 22 .. 00 00 EEEEEE AA AA SSSSSS YY 222222 .. 000000 VV VV II SSSSSS II OOOOOO NNNNNN --- User's guide --- VV VV II SS II OO OO NN NN VV VV II SSSSSS II OO OO NN NN VVVV II SS II OO OO NN NN VV II SSSSSS II OOOOOO NN NN ---------------------------------------------------------------------- A text mode based user interface ---------------------------------------------------------------------- The easy to use, reliable and powerful C and C++ library of functions, for the DOS environment. This manual may be freely distributed in its original form. Modifications of any kind are prohibited. This manual and software are made available without warranties. TNG SOFT nor the author shall be held liable to the user or any other person or entity regarding any liability, loss, or damage caused or alleged to be caused directly or indirectly by this manual or software. This software is shareware, and must be registered. This library is the property of the author. You are granted the rights to use only. EasyVision is a registered trademark of TNG SOFT. TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- TABLE OF CONTENT Page 2/111 ---------------------------------------------------------------------- C H A P T E R 1 : Overview ........................................7 Why EasyVision? ................................................7 What is EasyVision? ............................................8 Current Version ................................................9 A word about registration ......................................9 What's Next? ..................................................10 About the Author ..............................................11 User support ..................................................11 C H A P T E R 2 : Getting started ................................12 Library specifics .............................................12 Installation ..................................................13 How to use this library .......................................13 How to use this document ......................................14 C H A P T E R 3 : Using EasyVision's templates ...................15 MAIN.C ........................................................15 MAIN.CPP ......................................................16 MODULE.C ......................................................16 MODULE.CPP ....................................................16 MODULE.H ......................................................16 MODULE.HPP ....................................................16 STDMACRO.H ....................................................16 PRJMACRO.H ....................................................17 STDTYPE.H .....................................................17 PRJTYPE.H .....................................................17 PRJMSGS.C .....................................................17 PRJMSGS.H .....................................................18 HEADTEST.C ....................................................18 Examples ......................................................18 C H A P T E R 4 : Using EasyVision's functions ...................19 C H A P T E R 5 : EasyVision's standard functions ................21 ASSERT ........................................................21 ARG_EXIST .....................................................22 ARG_IEXIST ....................................................23 HEAPALLOC .....................................................23 HEAPFREE ......................................................24 TO_UPPER ......................................................24 TO_LOWER ......................................................25 C H A P T E R 6 : EasyVision's keyboard functions ................26 GETKEY ........................................................26 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- TABLE OF CONTENT Page 3/111 ---------------------------------------------------------------------- EXTTOASCII ....................................................27 C H A P T E R 7 : EasyVision's file functions ....................28 FNEWLINE ......................................................28 FSIZE .........................................................28 FCOPY .........................................................29 C H A P T E R 8 : EasyVision's screen functions ..................30 SCR_TEXTATTR ..................................................30 SCR_VSAVE .....................................................31 SCR_VRESTORE ..................................................31 SCR_CSAVE .....................................................32 SCR_CRESTORE ..................................................33 C H A P T E R 9 : EasyVision's string functions ..................34 STR_LEN .......................................................34 STR_CPY .......................................................34 STR_CMP .......................................................35 STR_ICMP ......................................................35 STR_TOUPPER ...................................................36 STR_TOLOWER ...................................................37 STR_PASTOC ....................................................37 STR_CTOPAS ....................................................38 STR_TRIM ......................................................38 STR_INVNAMES ..................................................39 STR_CENTER ....................................................39 C H A P T E R 10 : EasyVision's time functions ...................41 TICKTIMER_INSTALL .............................................41 TICKTIMER_RESET ...............................................41 TICKTIMER_READ ................................................42 DIFFDATE ......................................................42 C H A P T E R 11 : EasyVision's miscellaneous functions ..........44 ANSICOLOR .....................................................44 C H A P T E R 11 : Using EasyVision's classes ....................45 C H A P T E R 12 : EasyVision's tdesktop class ...................47 TDESKTOP::SETTEXTMODE .........................................47 TDESKTOP::GETSIZE .............................................48 TDESKTOP::SETDESKCOLORS .......................................49 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- TABLE OF CONTENT Page 4/111 ---------------------------------------------------------------------- TDESKTOP::SETTEXTURE ..........................................50 TDESKTOP::SETTITLE ............................................50 TDESKTOP::OPEN ................................................51 TDESKTOP::CLOSE ...............................................51 TDESKTOP::REFRESH .............................................52 C H A P T E R 13 : EasyVision's tstatusline class ................53 TSTATUSLINE::SETCOLORS ........................................53 TSTATUSLINE::DISPLAY ..........................................54 TSTATUSLINE::GETMSG ...........................................54 TSTATUSLINE::REFRESH ..........................................55 C H A P T E R 14 : EasyVision's tinput class .....................56 TINPUT::MOUSE_INIT ............................................56 TINPUT::MOUSE_STATUS ..........................................57 TINPUT::MOUSE_SHOW ............................................57 TINPUT::MOUSE_HIDE ............................................58 TINPUT::MOUSE_LB_DOWN .........................................58 TINPUT::MOUSE_POS .............................................58 TINPUT::GET ...................................................59 C H A P T E R 15 : EasyVision's tmenubar class ...................62 TMENUBAR::SETCOLORS ...........................................62 TMENUBAR::SETHLPCTX ...........................................63 TMENUBAR::ADDMENU .............................................64 TMENUBAR::ADDITEM .............................................65 TMENUBAR::ITEMSETAVAIL ........................................66 TMENUBAR::THROUGH .............................................66 TMENUBAR::REFRESH .............................................67 C H A P T E R 16 : EasyVision's twindow class ....................68 TWINDOW::WINSETPOS ............................................69 TWINDOW::WINGETROW ............................................69 TWINDOW::WINGETCOL ............................................70 TWINDOW::WINSETSIZE ...........................................70 TWINDOW::WINGETHEIGHT .........................................71 TWINDOW::WINGETWIDTH ..........................................71 TWINDOW::WINSETCOLORS .........................................71 TWINDOW::WINSETTITLE ..........................................72 TWINDOW::WINSETHLPCTX .........................................73 TWINDOW::WINOPEN ..............................................73 TWINDOW::WINCLOSE .............................................74 TWINDOW::WINCLEAR .............................................74 TWINDOW::WINWRITE .............................................75 TWINDOW::WINTEXT ..............................................77 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- TABLE OF CONTENT Page 5/111 ---------------------------------------------------------------------- TWINDOW::WINTEXTFILE ..........................................78 TWINDOW::WINMOVE ..............................................79 TWINDOW::WINSCROLL ............................................79 TWINDOW::WINONEDGES ...........................................80 TWINDOW::WININSIDE ............................................81 TWINDOW::WININPUT .............................................81 TWINDOW::FIELDSETCOLORS .......................................82 TWINDOW::FIELDCREATE ..........................................83 TWINDOW::FIELDSETASW ..........................................85 TWINDOW::FIELDGETASW ..........................................85 TWINDOW::FIELDINPUT ...........................................86 TWINDOW::BUTTONSETCOLORS ......................................87 TWINDOW::BUTTONCREATE .........................................87 TWINDOW::BUTTONSETAVAIL .......................................89 TWINDOW::BUTTONINPUT ..........................................90 A P P E N D I X A : Keycodes macros ..............................91 A P P E N D I X B : Color codes and symbolic constants ...........95 A P P E N D I X C : Context sensitive help system ................96 What is a context .............................................96 Context numbering .............................................97 Writing the ASCII help file ...................................97 ASCII help file format ........................................98 The help compiler .............................................99 The "*.HLP" and "*.HDX" help files ............................99 A P P E N D I X D : EasyVision's language system variables ......100 Language system variables ....................................100 ev_helpwindowtitle ......................................100 ev_helpwindownohelp .....................................101 ev_helpwindowfileerror ..................................101 ev_wintextdownbutton ....................................101 ev_wintextdown ..........................................101 ev_wintextquitbutton ....................................102 ev_wintextquit ..........................................102 ev_filenotfoundtext .....................................102 ev_filetobig ............................................102 ev_windowmove ...........................................103 ev_statuslinehelp .......................................103 english() and french() functions .............................103 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- TABLE OF CONTENT Page 6/111 ---------------------------------------------------------------------- A P P E N D I X E : EasyVision's demo program ...................104 Things to remember ...........................................104 A P P E N D I X F : How to reach the author .....................106 A P P E N D I X G : Trademarks ..................................107 I N D E X .........................................................108 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 1 : Overview Page 7/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 1 : Overview ---------------------------------------------------------------------- Welcome to EasyVision! This C and C++ library is a collection of routines for the DOS environment that were developed while working on different projects. Because I am big on modularity, I always try to put general purpose code together in a separate function. Therefore, after developing an application, I am often left with many useful functions. Those can be recycled easily and reduce development time of other applications. This package comes in two sections: 1. Day-to-day utility functions, written in C. They can be used in any program. 2. Object-oriented C++ classes, providing an easy to use, reliable and powerful text mode based user interface. I've decided to make this code available to everyone through this library. All those functions were tested thoroughly, and put to work in actual applications. Why EasyVision? ---------------------------------------------------------------------- DOS? Even if the times are to WINDOWS programming, you may be obliged to go with a text mode application if the computers on which they're supposed to run are small machines. However, that doesn't mean that your implementation can't have a professional look! Why reinvent the wheel when someone before you created one that works quite well? One reason would be that professional programmers like to write all of their general purpose functions themselves. They want to know what's inside. But sometimes, you just don't have the time to do it, or simply the need for it. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 1 : Overview Page 8/111 ---------------------------------------------------------------------- This library will give you access to useful routines that will shorten your development time and make your code more reliable. It will effectively free you from having to write many of the common functions your programs might need. EasyVision was first created as a need for a text mode based user interface. After looking at some shareware and commercial user interface packages, and reading comments about them from many C and C++ programmers, it was clear that something was missing. Turbo Vision? When people talked about TURBO VISION from BORLAND, it was their opinion that it was too difficult to use. In my own opinion, I think that TURBO VISION is one of the greatest work of software engineering around. It is the most powerful and professional text mode user interface in existence. It is so well implemented and thought out that it is the standard in text mode interfaces that everyone is following, including EasyVision! (Hope they don't sue me...) But, it is so big that it is a language in itself, and that's what makes people afraid of using it! On the other hand, there are those shareware libraries. Some of them are extraordinarily well done, but are still much too big. I'm thinking about CXL right now. Others are too small and too unreliable to develop serious software. So, what's a C++ programmer's to do? Maybe just what I did, and write all of his interface himself. But what a waste if I'm the only one using it! Why not make it available to everyone? Well, that's what EasyVision is all about! What is EasyVision? ---------------------------------------------------------------------- EasyVision is a collection of short C functions, dealing with the screen, the keyboard, text strings, etc. It is also a text mode based, windowed user interface. It provides a DESKTOP, a STATUSLINE, a MENUBAR, WINDOWS, CONTEXT SENSITIVE ON-LINE HELP, MOUSE SUPPORT and much much more... EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 1 : Overview Page 9/111 ---------------------------------------------------------------------- EasyVision was created with 2 important priorities: 1. It should be EASY to learn and EASY to use. Provide only the big, important functions to the user. Make sure that those functions are REALLY powerful and produce professional looking results! This library hasn't been written to provide every function needed to develop full featured word processors or the likes. It is there to give you a strong and reliable skeleton to build your programs on. It is up to you to come up with the 'meat'. 2. Those functions should be totally bug free and crash proof. EasyVision should validate all parameters to make sure nothing wrong can happen. Don't rely on the programmer's good will to check out its code for out of range or non-initialised parameters. Demo programs That was what EasyVision was supposed to be. Well, EasyVision is still better than that! At this point, if you haven't already done so, you should run the demonstration programs that are in the archives "DEMO1.ZIP" and "HANOI.ZIP", to see the results of not so many lines of C++ codes that uses the EasyVision library... If you find the results interesting, it's up to you to go on. All functions and classes are FULLY documented in the following pages. The source codes of the demonstration programs are also included (and commented) in the archive. It provides you with 'real' examples of how to use this library. Current Version ---------------------------------------------------------------------- The complete history of EasyVision can be found in the "HISTORY.TXT" file, included in the archive. A word about registration ---------------------------------------------------------------------- EasyVision may be freely distributed, without charge except for the media cost. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 1 : Overview Page 10/111 ---------------------------------------------------------------------- EasyVision is made available under the shareware concept. This means that after an evaluation period of 30 days, you should register this software with its author. Furthermore, if you use this software to create your own shareware software, YOU MUST REGISTER EasyVision. Registration grants you a life-time license to use this software, and all following versions or updates. EasyVision is NOT crippled in any way. There is absolutely no difference between the registered or unregistered versions. To register this software, complete the "REGISTER.TXT" registration form included in the archive. Registration is $25 CANADIAN. You will receive through 'snail mail' an official registered user certificate with your registration number. For 35$ CANADIAN, you'll also receive a bonded true type copy of the latest version of the manual. EasyVision and TNG SOFT ENTERPRISES are registered trade marks. What's Next? ---------------------------------------------------------------------- Every time I write a general purpose function, and think it could be used in other project, I will include it in the EasyVision package. Every now and then, a new version of this library will be made public. I will try to improve the functions already there. There won't be many new commands. EasyVision will always remain EASY to use, to leave the programmer at more important tasks. However, I welcome your suggestions to what you think is missing from this package. I will not accept special demands. The purpose of this library is to distribute code that I have in my personal library. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 1 : Overview Page 11/111 ---------------------------------------------------------------------- About the Author ---------------------------------------------------------------------- My name is Remy Gendron . I live in Quebec city, Canada. I'm studying at Laval University in computer sciences (Informatique de genie). I've been programming since I was 14 years old. I started on a Texas Instrument's TI-57 programmable calculator! I then graduated to a Commodore 64. This machine was a breakthrough in computer power, ahead of its time. I've done some BASIC on it, but mostly assembler. Great machine to learn on. The C64 did cost me about as much as you would spend today on a 486! Those of you who really did work with this machine know what could be done with only 64K of memory, when one did put his mind on it (Remember GEOS?). I find it incredible that with the computer power we have today, we don't manage to do something better... I was then away from computers for a couple of years. I returned with a real IBM (AT), then another Commodore (386sx-20), and finally a pieced together (386dx-40). I'm looking forward to a 486dx3-99 or maybe a Pentium? User support ---------------------------------------------------------------------- All of EasyVision's functions and classes have already been tested in real applications. They should behave as indicated. Please take time to carefully read the documentation. The answers to your questions should be in there. The demo programs should also provide a good introduction. I will gladly answer any questions you may have. I'll also welcome any comments or suggestions. I can be reach by netmail/email on FIDONET or INTERNET: FIDONET REMY GENDRON 1:240/1 INTERNET REMY_GENDRON@f1.n240.z1.fidonet.org So, that's about it for now! Have fun and enjoy! Remy Gendron author of EasyVision EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 2 : Getting started Page 12/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 2 : Getting started ---------------------------------------------------------------------- Installing and using the EasyVision library is very simple. Library specifics ---------------------------------------------------------------------- EasyVision's functions are for the DOS environment. They try, but do not always follow the ANSI standard. This software was developed under BORLAND C++ 3.1. --> TURBO VISION's application framework was NOT used in any way to create EasyVision, nor any other 3rd party libraries. It was built from scratch over a period of two years. Memory model The code was compiled under the 'large' memory model. All prototypes were declared as 'far' functions and all pointers were explicitly declared 'huge'. This will provide full compatibility when linking to most memory model sizes. You should consult your compiler documentation about interfacing with different memory models. If you should require that the library be compiled in a different memory model, just get in touch with me. We'll arrange something, if you're a registered user of course! Pointers Unless you REALLY know what you are doing, you should always use 'huge' pointers. 'far' pointers can cause wrap around and comparison problems because they're not normalized. All of EasyVision's functions use 'huge' pointers. Video The video output is done through direct screen writes. This makes for incredibly fast outputs. Going through the BIOS is just to slow. However, under multitaskers like DESKview , who often work in text mode, screen bleeds can occur if the application is running in the background. Use the virtualising options when running under DESKview. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 2 : Getting started Page 13/111 ---------------------------------------------------------------------- Header files All header files use conditional compilation to prevent redeclaration errors at compile time. So, if you're not sure if a header was previously included (possibly by another header file), feel free to include it again. --> They also provide for C++ compilation, using a conditional 'extern "C"' keyword. Installation ---------------------------------------------------------------------- Unpack the archive in a temporary directory. If you haven't done so, you should really print all the USER'S GUIDE for easier reading. It as been formatted to print at 60 lines per pages. And why not take a look at the header files. Put all header files "*.H" and "*.HPP" into an INCLUDE directory. Just to be sure you won't overwrite existing header files, you should make a separate include directory, then include it in the INCLUDE path of your compilator. Then put the EasyVision library "EVISION.LIB" into one of your LIBRARY directories. How to use this library ---------------------------------------------------------------------- To use a library function or class, just include its header file in your source code. YOU MUST NOT write a prototype yourself based on the prototypes written in this manual. The real prototypes may have additional information in them. So, for example: #include <stdio.h> /* A standard header file */ #include "stdfcts.h" /* An EasyVision header file */ void main (void) { ... /* Here you can use the desired functions */ ... return ; } EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 2 : Getting started Page 14/111 ---------------------------------------------------------------------- You then have to link all your modules, including the "EVISION.LIB" library. You do that by including "EVISION.LIB" in your project. That's all there is to it! --> If you get errors, that's probably because you compiled your sources in C and included C++ modules. Another source of errors would be if you tried to linked different memory models. Remember the EasyVision was compiled under the 'large' memory model. Validation All arguments to functions are FULLY validated. An EasyVision function will never let you get away if it is called incorrectly. If something is wrong, the program is stopped and a plain English error message tells you what went wrong, where and why! In the function descriptions, when it says that you SHOULD NOT or CANNOT do something, it means that if you do it, you'll get an error message. Your program will not crash! How to use this document ---------------------------------------------------------------------- The following conventions are used in this document: --> All of EasyVision's functions and methods were declared of type 'far'. The following symbols are used in the text: '' Regular C and C++ keywords {} EasyVision's keywords <> Arguments to functions --> Important remarks (that you MUST read) "" Filenames CAPS Keyboard keys Related functions are grouped together in the same module. A chapter is devoted to each module. At the end, reference information can be found in appendixes. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 3 : Using EasyVision's templates Page 15/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 3 : Using EasyVision's templates ---------------------------------------------------------------------- EasyVision provides you with some starting templates for your programs. Templates are important facilities. They bring consistency and productivity in your programming style. If you already have your own style and templates, stick with them. The included templates are for new programmers, or those of you who are still searching for a better way. Of course, those are just suggestions. For instance, the usage and placement of parenthesis, currently generate many hot debates. Some will follow the 'professional' style and open a block this way: while (condition) { statements ; statements ; } While others (and I), do it this way: while (condition) { statement ; statement ; } Choose your own style! The following files are therefore included for your convenience. MAIN.C ---------------------------------------------------------------------- Template for your main source file. This is the only file with a 'main' function declaration. I'd go further by suggesting that ONLY the 'main' function be included. As a rule, your 'main' should only call other functions in your other modules. It should be as short and as well documented as possible. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 3 : Using EasyVision's templates Page 16/111 ---------------------------------------------------------------------- MAIN.CPP ---------------------------------------------------------------------- C++ version of MAIN.C. MODULE.C ---------------------------------------------------------------------- Template for your secondary modules' code files. You could, for example, put all video related functions in a "VIDEO.C" file. MODULE.CPP ---------------------------------------------------------------------- C++ version of MODULE.C. MODULE.H ---------------------------------------------------------------------- Template for your secondary modules' header files. MODULE.HPP ---------------------------------------------------------------------- C++ version of MODULE.H. STDMACRO.H ---------------------------------------------------------------------- Template for your standard macro definitions. Put in this file your standard macros that can be used with many different projects. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 3 : Using EasyVision's templates Page 17/111 ---------------------------------------------------------------------- --> This file contains declarations for {TRUE} and {FALSE} and for all the keyboard keys (II_* macros). PRJMACRO.H ---------------------------------------------------------------------- Template for macros particular to your current project. Put in this file, macros that will be needed by many modules. You should place macros specific to a module in the module's macro declarations section. STDTYPE.H ---------------------------------------------------------------------- Template for your standard type definitions. Put in this file your standard typedefs that can be used with many different projects. --> This file contains declarations for the {bool}, {byte}, {word} and {dword} types. PRJTYPE.H ---------------------------------------------------------------------- Template for typedefs particular to your current project. Put in this file, typedefs that will be needed by many modules. You should place typedefs specific to a module in the module's typedef declarations section. PRJMSGS.C ---------------------------------------------------------------------- Template for your global output messages . When your program outputs something to the user, put it here as a global variable. Then, reference this variable everywhere in your program when you want to output this message. This will allow easy conversion of your program from one language to another. I suggest that all global message variables begin with 'msg_'. For example, msg_fileselect. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 3 : Using EasyVision's templates Page 18/111 ---------------------------------------------------------------------- PRJMSGS.H ---------------------------------------------------------------------- Template to put 'extern' references to your global message variables. For example: extern char huge *msg_fileselect. HEADTEST.C ---------------------------------------------------------------------- Template to test your header files . Often, they will compile correctly because some other files were included before your header. This could cause problems if you intend to use this header file elsewhere, or make them available to other programmers. Your header files should always compile alone by themselves. Test them with this file. Examples ---------------------------------------------------------------------- Templates promote consistency and free you from tedious tasks. Also, having something to start with, you won't as often be afflicted by the 'blank page' syndrome! Take a look at the demo programs to get a feel at project management. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 4 : Using EasyVision's functions Page 19/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 4 : Using EasyVision's functions ---------------------------------------------------------------------- There are two types of functions in the EasyVision library. Functions available in the standard libraries, and new functions. Because I like to compile in the 'large' memory model, all functions have been written to be of type 'far'. They will also accept 'huge' pointers without the need for a typecast. Those functions don't call the standard run-time library. They were entirely rewritten. There is no overhead and they are fully optimized. New functions have been written because they weren't available in the standard libraries. --> Some conventions have been adopted for the function names. Related functions will have the same name prefix. For instance, all string functions will begin by {str_}. --> Function declarations can use types like {bool}, {byte}, {word} and {dword}. See the file STDTYPE.H for a description of those types. A function's description uses the following format: Summary Short description of this function's behavior. Syntax #include "header.h" ReturnType FonctionName ( <param>, <param> ) ; --> YOU MUST NEVER WRITE A PROTOTYPE FOR A FUNCTION YOURSELF. ALWAYS USE THE PROPER HEADER FILES. THEY HAVE ADDITIONAL INFORMATION IN THEM! Remarks Parameters and usage are described here when needed. Return The returned value of the function is explained here. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 4 : Using EasyVision's functions Page 20/111 ---------------------------------------------------------------------- Example Examples of various calls to this function. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 5 : EasyVision's standard functions Page 21/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 5 : EasyVision's standard functions ---------------------------------------------------------------------- The declarations for EasyVision's standard functions are contained in the "STDFCTS.H" header file. Those are the truly general and often used functions that will be required by most of your modules. ASSERT ---------------------------------------------------------------------- Summary This function will ASSERTain that a <condition> is {TRUE}. If it is, it will return immediately with no effect, and minimum overhead. If the condition is {FALSE}, the program will be terminated in an orderly fashion. {assert} will clear the screen, display an error message for at least five seconds, and terminate the program with a call to 'exit'. This closes all open files, releases any memory allocated on the heap and exits to DOS. Syntax #include "stdfcts.h" void far assert /* Validates an assertion */ ( bool condition, /* FALSE=terminates */ char huge *fctname, /* Current function */ const char huge *errortext, /* Error message */ int exitcode /* Errorlevel */ ) ; Remarks If <condition> evaluates to {FALSE}, the program will be terminated and <fctname> will be displayed. You should set <fctname> to the currently executing function. This will help find the location of the error. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 5 : EasyVision's standard functions Page 22/111 ---------------------------------------------------------------------- The error message <errortext> will be displayed. This can be a string literal, or you can use predefined error messages. These are available from the global variable msg_stderr[]. This is an array of pointers, and here are the messages: 1. "Not enough memory to create an array on the heap." 2. "Not enough memory to create a struct on the heap." 3. "Not enough memory to allocate the requested amount of bytes." 4. "Out of memory." 5. "File not found." 6. "Path not found." 7. "File access denied." 8. "Input/Output error." 9. "Unrecoverable fatal error." {assert} will then return to DOS with an errorlevel of <exitcode>. --> Before calling 'exit', {assert} will set the global variable {assert_err } to {TRUE}. This will allow classes' destructors to know the state of the program when they were called. At any other time, {assert_err} is {FALSE}. Return None. Example assert (nbrecord>0,"datasearch","No data",1); assert (ptr != NULL,"dataprocess",msg_stderr[3],1) ; ARG_EXIST ---------------------------------------------------------------------- Summary This function will check if an argument is present on the command line. Check is case sensitive. Syntax #include "stdfcts.h" int far arg_exist /* Checks for argument */ ( char huge *string /* Argument to search for */ ) ; Remarks The search for the argument is case sensitive. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 5 : EasyVision's standard functions Page 23/111 ---------------------------------------------------------------------- Return If the command line argument <string> exists, its index in the command line argument array will be returned. If the argument does not exist, the function will return 0. See the '_argv' keyword of your compiler for details on accessing command line arguments. Example if (arg_exist ("q")) sound = FALSE ; ARG_IEXIST ---------------------------------------------------------------------- Summary This function will check if an argument is present on the command line. Check is case insensitive. Syntax #include "stdfcts.h" int far arg_iexist /* Checks argument */ ( char huge *string /* Argument to search for */ ) ; Remarks The search for the argument is case insensitive. Return If the command line argument <string> exists, its index in the command line argument array will be returned. If the argument does not exist, the function will return 0. See the '_argv' keyword of your compiler for details on accessing command line arguments. Example if (arg_iexist ("bios")) directvideo = FALSE ; HEAPALLOC ---------------------------------------------------------------------- Summary {heapalloc} replaces 'farmalloc'. Syntax #include "stdfcts.h" void huge * far heapalloc /* Allocates far heap */ ( dword nbytes /* Asks for a block <nbytes> long */ ) ; Remarks Allocates <nbytes> bytes on the far heap. {dword} is an 'unsigned long int' and is declared in "STDTYPE.H". EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 5 : EasyVision's standard functions Page 24/111 ---------------------------------------------------------------------- Return This function returns a 'huge' pointer. Be sure the pointer variable, who will receive the pointer to the allocated memory, is of type 'huge' also. Example char huge *ptr ; ptr = heapalloc (sizeof (object)) ; HEAPFREE ---------------------------------------------------------------------- Summary {heapfree} replaces 'farfree'. Syntax #include "stdfcts.h" void far heapfree /* Deallocates heap */ ( void huge *block /* Ptr to block to free */ ) ; Remarks The only difference from 'farfree' is that this function offers the convenience of accepting a 'huge' pointer as an argument. Return None. Example char huge *ptr ; ptr = heapalloc (sizeof (object)) ; // Allocates memory heapfree (ptr) ; // Frees memory ptr = NULL ; // Always a good idea TO_UPPER ---------------------------------------------------------------------- Summary {to_upper} replaces 'toupper'. Syntax #include "stdfcts.h" int far to_upper /* Converts to uppercase */ ( int ch /* Character to be converted */ ) ; Remarks The standard library 'toupper' function has a problem when you pass an 'int' to it. It considers only the LSB and could wrongly make the conversion. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 5 : EasyVision's standard functions Page 25/111 ---------------------------------------------------------------------- Return An 'int'. The converted letter if it was necessary. Example command = to_upper (command) ; TO_LOWER ---------------------------------------------------------------------- Summary {to_lower} replaces 'tolower'. Syntax #include "stdfcts.h" int far to_lower /* Converts to lowercase */ ( int ch /* Character to be converted */ ) ; Remarks The standard library 'tolower' function has a problem when you pass an 'int' to it. It considers only the LSB and could wrongly make the conversion. Return An 'int'. The converted letter if it was necessary. Example command = to_lower (command) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 6 : EasyVision's keyboard functions Page 26/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 6 : EasyVision's keyboard functions ---------------------------------------------------------------------- The declarations for EasyVision's keyboard functions are contained in the "KEYBFCTS.H" header file. GETKEY ---------------------------------------------------------------------- Summary This is a replacement for the familiar 'getch' function. Syntax #include "keybfcts.h" int far getkey /* Reads a key from keyboard */ ( int filter, /* Filter (0 = all keys) */ bool buffer /* TRUE: Read from keyb buffer */ ) ; Remarks One of 'getch' weakness is its inability to deal with the way extended keys are internally represented. Those are the keys that don't have an ASCII code associated with them. For example, the function, arrow and editing keys all return an extended keycode. This new {getkey} function will deal with these extended keys by adding 256 to the extended keycode. Appendix A lists all the extended keycodes currently available on an extended keyboard. You MUST specify a <filter> to be used by the {getkey} function. A filter of 0 will allow any key to be read and returned by the function. You can also provide the ASCII or extended keycode (remember to add 256 to the real code) of the only key allowed to be returned by the function. This provides an easy way to WAIT FOR a specific key. The function will then return with that keycode, only when that key has been pressed. --> If you set <buffer> to {FALSE}, {getkey} will flush the keyboard buffer before reading a key. Otherwise, it will read from the buffer if keys have been previously pressed. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 6 : EasyVision's keyboard functions Page 27/111 ---------------------------------------------------------------------- --> Beware of NEVER setting <filter> to an impossible key entry, or you will be trapped by the {getkey} function! Return If a normal key was pressed, the returned value is an 'int' representing the ASCII code of that key. (1-255) If an extended key was pressed, the returned value is an 'int' representing the extended keycode plus 256. (256-396) Example getkey (0) ; getkey (13) ; /* Wait for the ENTER key */ EXTTOASCII ---------------------------------------------------------------------- Summary Converts an ALT-(letter or digit) key combination to its equivalent, single letter or digit. Syntax #include "keybfcts.h" int far exttoascii /* Converts 'ALT-letter|digit' */ ( int code /* Code to be converted */ ) ; Remarks <code> is the value as returned by the {getkey} function. For example, {II_A_A} (Alt-A) is returned by {getkey} as 286. Given 286, {exttoascii} will then return 65, the ASCII code for the letter 'A'. Return The ASCII code of the letter or digit in the ALT-key combination. If <code> is not an ALT-(letter or digit) combination, <code> is returned unchanged. --> If the value returned by this function is of a letter, the letter will always be promoted to uppercase. Example in = getkey (0,FALSE) ; in = exttoascii (in) ; /* Checks for Alt-key combi */ EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 7 : EasyVision's file functions Page 28/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 7 : EasyVision's file functions ---------------------------------------------------------------------- The declarations for EasyVision's file functions are contained in the "FILEFCTS.H" header file. FNEWLINE ---------------------------------------------------------------------- Summary Goes to start of next line in a text file. Syntax #include "filefcts.h" int far fnewline /* Goes to next line */ ( FILE *f /* Ptr to opened stream */ ) ; Remarks The end of a text line is marked by the character '\n'. Return If the start of a new line was found, '\n' is returned. If 'EOF' (end of file) was reach before a new line, 'EOF' is returned. Example error = fnewline (text) ; FSIZE ---------------------------------------------------------------------- Summary Returns size of a file in bytes, as displayed from a directory listing. Syntax #include "filefcts.h" dword far fsize /* Returns file size in bytes */ ( FILE *f /* Ptr to opened stream */ ) ; Remarks In a text file, the new line character is in fact two bytes long. DOS stores '\n' as a combination of '\n' and '\r'. So, the length of a text file will not match the number of characters read with 'fgetc'. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 7 : EasyVision's file functions Page 29/111 ---------------------------------------------------------------------- Return {fsize} returns the size of the file in bytes as a {dword}. {dword} is defined in "STDTYPE.H" as an 'unsigned long int'. Example size = fsize (text) ; FCOPY ---------------------------------------------------------------------- Summary Copies a file. Syntax #include "filefcts.h" int far fcopy /* Copies a disk file */ ( char huge *srcpath, /* Path to source file */ char huge *destpath, /* Path to destination file */ bool verify /* TRUE: Verify ON */ ) ; Remarks <srcpath> is copied to <destpath>. Paths are expressed in the form [d:][path]filename.ext. --> No wildcards are allowed. If <verify> is set to {TRUE}, the two files will then be reread and compared. This is different from DOS's 'verify', who doesn't reread the files, and is therefore a little slower. Return If the copy was successful and error free, {fcopy} returns 0. On error, 1 is returned. Example error =fcopy ("autoexec.bat","autoexec.bak",TRUE) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 8 : EasyVision's screen functions Page 30/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 8 : EasyVision's screen functions ---------------------------------------------------------------------- The declarations for EasyVision's screen functions are contained in the "SCRFCTS.H" header file. SCR_TEXTATTR ---------------------------------------------------------------------- Summary This function will set the background and foreground colors used for video outputs by the "CONIO.H" module. It will support bright background colors. Syntax #include "scrfcts.h" void far scr_textattr /* Sets colors of outputs */ ( int back, /* Background color */ int fore /* Foreground color */ ) ; Remarks The normal 'textbackground' function does not allow bright background colors. {scr_textattr} will do so. --> {tdesktop::settextmode] allows you to turn on the ability to use bright background colors. When this is so, all sixteen possible colors can be used when you have to specify a background color anywhere in EasyVision. Therefore, all changes of colors should be done with calls to {scr_textattr}. You will now be able to have 'BLACK' text on a (really) 'WHITE' background. Return None. Example scr_textattr (WHITE,BLACK) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 8 : EasyVision's screen functions Page 31/111 ---------------------------------------------------------------------- SCR_VSAVE ---------------------------------------------------------------------- Summary This function will save the current screen and video attributes in a 'text_info' structure. It has exactly the same effects as a call to 'gettextinfo '. The difference is that it can also save the actual screen content. Syntax #include "scrfcts.h" void far scr_vsave /* Saves all video informations */ ( struct text_info huge *ti, /* Ptr to text_info */ char huge*huge *savedscr /* Ptr to ptr */ ) ; Remarks All members of the 'text_info' structure <ti> are filled with this function. <savedscr> is a huge pointer to a huge char pointer. If this argument is provided, the screen content will also be saved to a buffer in the heap, and the huge pointer to char will be set to point to this buffer. If you don't want to save the screen area, set <savedscr> to 'NULL'. --> The cursor's attributes are saved, but will not be restored by {scr_vrestore}. You must use the {scr_csave} and {scr_crestore}. Return None. Example struct text_info ti ; char huge *scrbfr ; scr_vsave (&ti,&scrbfr) ; SCR_VRESTORE ---------------------------------------------------------------------- Summary This function will restore the screen video mode and the text window size from a 'text_info' structure. It can also restore the screen content if it was saved by a previous call to {scr_vsave}. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 8 : EasyVision's screen functions Page 32/111 ---------------------------------------------------------------------- Syntax #include "scrfcts.h" void far scr_vrestore /* Restores video info */ ( struct text_info huge *ti, /* Ptr to text_info */ char huge*huge *savedscr /* Ptr to ptr */ ) ; Remarks The 'text_info' structure must have been previously filled with {scr_vsave}. The same is true for the previous screen content. --> If the screen area was not previously saved, set <savedscr> to 'NULL'. The memory will be deallocated when the screen content is restored, so you can't restore it more than once. Return None. Example scr_vrestore (&ti,&scrbfr) ; SCR_CSAVE ---------------------------------------------------------------------- Summary This function will save all cursor attributes, INCLUDING THE CURSOR TYPE (shape), in a {cur_info} structure. Those attributes are: colors, x pos, y pos and cursor shape. Syntax #include "scrfcts.h" void far scr_csave /* Saves all cursor attributes */ ( struct cur_info huge *ci /* Ptr to cur_info */ ) ; Remarks The {cur_info} structure is as follows, and is defined in "SCRFCTS.H". struct cur_info { byte attribute ; /* Cursor colors */ byte curx ; /* Cursor X position */ byte cury ; /* Cursor Y position */ word curtype ; /* Cursor type */ } ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 8 : EasyVision's screen functions Page 33/111 ---------------------------------------------------------------------- Return None. Example struct cur_info ci ; scr_csave (&ci) ; SCR_CRESTORE ---------------------------------------------------------------------- Summary This function will restore all cursor attributes, INCLUDING THE CURSOR TYPE (shape), from a {cur_info} structure. Syntax #include "scrfcts.h" void far scr_crestore /* Restores cursor attributes */ ( struct cur_info huge *ci /* Ptr to cur_info */ ) ; Remarks The cursor's attributes must have been previously saved with {scr_csave}. Return None. Example struct cur_info ci ; scr_csave (&ci) ; scr_crestore (&ci) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 9 : EasyVision's string functions Page 34/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 9 : EasyVision's string functions ---------------------------------------------------------------------- The declarations for EasyVision's string functions are contained in the "STRFCTS.H" header file. STR_LEN ---------------------------------------------------------------------- Summary This is a 'huge' version of 'strlen'. It returns the length of a string. Syntax #include "strfcts.h" size_t far str_len /* Returns the length of a string */ ( char huge *string /* Huge ptr to a string */ ) ; Remarks The only difference with 'strlen' is that this function offers the convenience of accepting a 'huge' pointer as argument. Return The length of the string. The type 'size_t' is defined in "STDIO.H" as an 'unsigned int'. Example length = str_len (text) ; STR_CPY ---------------------------------------------------------------------- Summary This is a 'huge' version of 'strcpy'. It copies a string into another, including the terminating '\0' character. Syntax #include "strfcts.h" char huge * far str_cpy /* Copies a string */ ( char huge *dest, /* Destination array */ char huge *src /* Source string */ ) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 9 : EasyVision's string functions Page 35/111 ---------------------------------------------------------------------- Remarks The only difference from 'strcpy' is that this function offers the convenience of accepting 'huge' pointers as arguments. Return A 'huge' pointer to the destination string. Example char huge *string ; string = heapalloc (20) ; str_cpy (string,"Hello there !") ; STR_CMP ---------------------------------------------------------------------- Summary This is a 'huge' version of 'strcmp '. It compares one string to another. Syntax #include "strfcts.h" int far str_cmp /* Compares one string to another */ ( char huge *string1, /* First string */ char huge *string2 /* Second string */ ) ; Remarks The only difference from 'strcmp' is that this function offers the convenience of accepting 'huge' pointers as arguments. Return {str_cmp} returns a value that is : < 0, if <string1> is less than <string2> = 0, if <string1> is the same as <string2> > 0, if <string1> is greater than <string2> Example if (str_cmp (name[i],name[i+1]) > 0) { /* Invert string (bubble sort) */ } STR_ICMP ---------------------------------------------------------------------- Summary This is a 'huge' version of 'stricmp'. It compares one string to another, without case sensitivity. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 9 : EasyVision's string functions Page 36/111 ---------------------------------------------------------------------- Syntax #include "strfcts.h" int far str_icmp /* Case insensitive compares */ ( char huge *string1, /* First string */ char huge *string2 /* Second string */ ) ; Remarks The only difference from 'stricmp' is that this function offers the convenience of accepting 'huge' pointers as arguments. Return {str_icmp} returns a value that is : < 0, if <string1> is less than <string2> = 0, if <string1> is the same as <string2> > 0, if <string1> is greater than <string2> Example if (str_icmp (name[i],name[i+1]) > 0) { /* Invert string (bubble sort) */ } STR_TOUPPER ---------------------------------------------------------------------- Summary This function transposes a string to uppercase. Syntax #include "strfcts.h" void far str_toupper /* Sets string to upper case */ ( char huge *string /* Huge ptr to a string */ ) ; Remarks None. Return None. Example str_toupper (name) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 9 : EasyVision's string functions Page 37/111 ---------------------------------------------------------------------- STR_TOLOWER ---------------------------------------------------------------------- Summary This function transposes a string to lowercase. Syntax #include "strfcts.h" void far str_tolower /* Sets string to lower case */ ( char huge *string /* Huge ptr to a string */ ) ; Remarks None. Return None. Example str_tolower (name) ; STR_PASTOC ---------------------------------------------------------------------- Summary This function translates a string from PASCAL's to C's internal format. Syntax #include "strfcts.h" void far str_pastoc /* Converts a string to c */ ( char huge *string /* Ptr to string */ ) ; Remarks All characters in the string will be shifted left 1 space and a '\0' will be appended at the end of the string. This is useful is you're reading records written in PASCAL format. Return None. Example str_pastoc (name) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 9 : EasyVision's string functions Page 38/111 ---------------------------------------------------------------------- STR_CTOPAS ---------------------------------------------------------------------- Summary This function translates a string from C's to PASCAL's internal format. Syntax #include "strfcts.h" void far str_ctopas /* Converts a string to pascal */ ( char huge *string /* Ptr to string */ ) ; Remarks All characters in the string will be shifted right 1 space, overwriting the terminating '\0'. The length of the string will then be put in the first byte of the array. --> The string MUST be 255 or fewer characters long. This is useful is you're reading records written in PASCAL'S format, converted them to C'S with {str_pastoc}, then reconverting to PASCAL's before writing to disk. Return None. Example str_ctopas (name) ; STR_TRIM ---------------------------------------------------------------------- Summary This function removes leading and trailing spaces from a string. Syntax #include "strfcts.h" void far str_trim /* Normalises string */ ( char huge *string /* Ptr to string */ ) ; Remarks Useful when normalising an input. Return None. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 9 : EasyVision's string functions Page 39/111 ---------------------------------------------------------------------- Example str_trim (name) ; STR_INVNAMES ---------------------------------------------------------------------- Summary This function inverts first and last names in a name string. Syntax #include "strfcts.h" void far str_invnames /* Inverts string */ ( char huge *string /* Ptr to string */ ) ; Remarks A name string is composed of 1 or more clusters of characters. Clusters are packets separated from each other by 1 or more spaces. {str_invnames} will take the first cluster and move it to the end of the string. This could be useful if you're doing a sort by last names then first names, but your name strings are in the form first then last. Return None. Example str_invnames (name) ; "Remy" becomes "Remy" "Remy Gendron" becomes "Gendron Remy" "Remy J. Gendron" becomes "J. Gendron Remy" "This is some string" becomes "is some string This" STR_CENTER ---------------------------------------------------------------------- Summary This function centers a string within a given area. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 9 : EasyVision's string functions Page 40/111 ---------------------------------------------------------------------- Syntax #include "strfcts.h" char huge * far str_center /* Centers a string */ ( char huge *string, /* Ptr to string */ int area_length /* Length of area */ ) ; Remarks The original <string> is not modified. The new string will be padded with blanks, if necessary, to be centered in <area_length>. The function will discard the part of the string that is longer than 255 characters. Return This function will create a new string, and return a ptr to a static string defined in the string module. --> You MUST not try to free this string. Example printf (str_center ("Center of the screen",80)) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 10 : EasyVision's time functions Page 41/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 10 : EasyVision's time functions ---------------------------------------------------------------------- The declarations for EasyVision's time functions are contained in the "TIMEFCTS.H" header file. TICKTIMER_INSTALL ---------------------------------------------------------------------- Summary This function installs or removes a tick counter. Syntax #include "timefcts.h" void far ticktimer_install (void) ;/* Installs timer */ Remarks Ticks are PC's clock units. They are 1/18 second long. The ticktimer routines will allow you to count those ticks. The first call to {ticktimer_install} will install an interrupt, whose purpose is to count ticks. A second call to the {ticktimer_install} will remove the interrupt. Return None. Example ticktimer_install () ; TICKTIMER_RESET ---------------------------------------------------------------------- Summary This function resets the tick count to zero. Syntax #include "timefcts.h" void far ticktimer_reset (void) ; /* Resets counter */ Remarks After installation of the interrupt, the tick count is undefined. You must reset the count before using the {ticktimer_read} function. Also, you can reset the count to zero anytime you like. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 10 : EasyVision's time functions Page 42/111 ---------------------------------------------------------------------- --> Using this function will introduce a random delay of up to 1/18 second. The function will wait for the beginning of the next tick before returning. This will warranty that tick #1 will really be 1 tick long. Return None. Example ticktimer_reset () ; TICKTIMER_READ ---------------------------------------------------------------------- Summary This function returns the current tick count. Syntax #include "timefcts.h" dword far ticktimer_read (void) ; /* Returns count */ Remarks After installation of the interrupt, the tick count is undefined. You must reset the count before using the {ticktimer_read} function. Using this function does not reset the counter. Return The number of ticks since {ticktimer_reset} was last used. {ticktimer_read} returns a {dword}. {dword} is defined in "STDTYPE.H" as an 'unsigned long int'. Example dword count ; ticktimer_install () ; /* Installs timer */ ticktimer_reset () ; /* Resets timer to 0 */ function (argument) ; /* Calls your function */ count = ticktimer_read () ; /* Gets tick count */ ticktimer_install () ; /* De-installs timer */ DIFFDATE ---------------------------------------------------------------------- Summary Calculates absolute number of days between two dates. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 10 : EasyVision's time functions Page 43/111 ---------------------------------------------------------------------- Syntax #include "timefcts.h" dword far diffdate /* Number of days between dates */ ( int day1, /* 1st date: day (1-31) */ int month1, /* 1st date: month (1-12) */ int year1, /* 1st date: year (xxxx) */ int day2, /* 2nd date: day (1-31) */ int month2, /* 2nd date: month (1-12) */ int year2 /* 2nd date: year (xxxx) */ ) ; Remarks day1/day2 : Days of date 1 and 2. (1-31) month1/month2 : Months of date 1 and 2. (1-12) year1/year2 : Years of date 1 and 2. (1583 and after) Return The absolute number of days between the 2 dates. {diffdate} returns a {dword}. {dword} is defined in "STDTYPE.H" as an 'unsigned long int'. Example dword count ; count = diffdate (userday, usermonth, useryear, todayday, todaymonth, todayyear) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 11 : EasyVision's miscellaneous functions Page 44/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 11 : EasyVision's miscellaneous functions ---------------------------------------------------------------------- The declarations for EasyVision's miscellaneous functions are contained in the "MISCFCTS.H" header file. ANSICOLOR ---------------------------------------------------------------------- Summary Converts normal background and foreground color codes to color codes for ANSI escape sequences. Syntax #include "miscfcts.h" void far ansicolor /* Converts color codes to ANSI */ ( int fore, /* Fore and back colors */ int back, int huge *ansbold, /* ESC sequence */ int huge *ansfore, int huge *ansback ) ; Remarks fore, back : Standard screen colors. *ansbold : Ptr to int to return bold value. *ansfore : Ptr to int to return fore value. *ansback : Ptr to int to return back value. To interpret ANSI escape sequences, the ANSI.SYS driver (or its equivalent) must be loaded. Return None. Example int bold, fore, back ; ansicolor (LIGHTGREEN,BLACK,&bold,&fore,&back) ; printf ("\x1b[%d;%d;%dm",bold,fore,back) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 11 : Using EasyVision's classes Page 45/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 11 : Using EasyVision's classes ---------------------------------------------------------------------- The EasyVision library has five classes . They provide a desktop, a statusline, a menubar, windows, user inputs and mouse support. Those classes are fully described in the following pages. --> All classes interact with one another. Don't try to use only one of them. You must work with EasyVision as it was meant to be used. Every method is declared as 'far' and when they take pointers as parameters, those pointers are of type 'huge'. Conventions have been adopted for the methods' names. Related methods will have the same name prefix. For example, all window related functions begin by {win_}. --> Methods declarations can use types like {bool}, {byte}, {word} and {dword}. See the file "STDTYPE.H" for a description of those types. --> Parameters to C++ functions can have default values. If you don't supply a value, the default value will be used. However, rules apply to this usage of default parameters. Refer to your C++ documentations for an explanation of those rules. A classe's description uses the following format: First, the description of the class itself, its behavior, how it is related to the other classes and the interface. Then, each member function of the class is presented as in the following: Summary Short description of this function's behavior. Syntax #include "header.h" ReturnType FunctionName ( <param>, <param> ) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 11 : Using EasyVision's classes Page 46/111 ---------------------------------------------------------------------- --> YOU MUST NEVER WRITE YOURSELF A PROTOTYPE FOR A FUNCTION. ALWAYS USE THE PROPER HEADER FILES. THEY HAVE ADDITIONAL INFORMATION IN THEM! --> C++ functions' header provide for optional arguments. IF YOU WANT TO INCLUDE AN OPTIONAL PARAMETER, ALL PARAMETERS BEFORE THAT ONE MUST BE INCLUDED AS WELL. Refer to your compiler's documentation. Remarks Parameters and usage are described here when needed. Return The returned value of the method is explained here. Example Examples of various calls to this method. Using classes is quite easy! Windows For the {twindow} class, you firsts declare a pointer to this class. Then you instantiate (create) an object of this type with the operator 'new'. Now you can call the classe's member functions with the '->' operator. When you're finished, you free the memory taken by this class instance with 'delete'. The others For the other classes, {tdesktop}, {tstatusline}, {tmenubar} and {tinput}, you can only have one instance of each. To make it easier, they all have been instantiated. You don't need to create them. You just use them right away. You access their member functions with the '.' operator. Many examples are available in the source codes of the EasyVision's demo programs. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 12 : EasyVision's tdesktop class Page 47/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 12 : EasyVision's tdesktop class ---------------------------------------------------------------------- The {tdesktop} class is the first one to be used in a program that uses the EasyVision user interface. This class is responsible for the background on which the statusline, the menubar and windows will be displayed. This class will save the screen content before the program was executed, initialise the video screen to the video mode of your choice, and display the desktop. You will also call this class at the end of your program to restore the previous video mode, restore the previous screen and reset default colors and cursor position. --> An instance has already been globally declared and is called desktop. Only one instance of {tdesktop} can be used in a program. As a result, you will never declare and create another instance. --> The desktop allows your programs to use bright background colors. The desktop has built in default values. Only one call is required to do the work. The desktop will autosize itself to the screen. However, if you would like to change those default behaviors, other functions are provided to do so. On the following pages, you will find each of its member functions. Examples of using the desktop object are given in the source codes of the EasyVision's demo programs. TDESKTOP::SETTEXTMODE ---------------------------------------------------------------------- Summary Sets the textmode in which {open} will draw the desktop. Also sets the availability of bright background colors. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 12 : EasyVision's tdesktop class Page 48/111 ---------------------------------------------------------------------- Syntax #include "tdesktop.hpp" void far tdesktop::settextmode // Sets textmode ( int mode=C80, // Textmode code number bool brightbackground=FALSE // True = bright colors ) ; Remarks This has no effect on the current textmode. It will only take effect when {open} is called. This call is optional. If it is not made before a call to {open}, textmode C80 (3, color 80 columns) is assumed and bright background colors will not be used. Symbolic Value Text mode LASTMODE -1 Previous text mode BW40 0 Black and white, 40 cols C40 1 Color, 40 columns BW80 2 Black and white, 80 cols C80 3 Color, 80 columns MONO 7 Monochrome, 80 columns C4350 64 EGA 43-line, VGA 50-line To use the symbolic constants, "CONIO.H" must be included. --> By setting <brightbackground> to {TRUE}, you will then be able to use all 16 colors for the background. As a drawback, blinking characters won't be available. Return None. Example desktop.settextmode (C4350,TRUE) ; TDESKTOP::GETSIZE ---------------------------------------------------------------------- Summary Returns desktop's current size. Syntax #include "tdesktop.hpp" void far tdesktop::getsize // Returns desktop's size ( int huge *height, // Ptrs to ints to return size int huge *width ) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 12 : EasyVision's tdesktop class Page 49/111 ---------------------------------------------------------------------- Remarks The size returned in <height> and <width> is the ACTUAL desktop's size. If you changed the video mode with {settextmode}, but haven't called {open} yet, the new size won't be returned. --> When other parts of your program need to know the actual desktop's size , they should use this function instead of 'gettextinfo'. Return None. Example int screenheight ; int screenwidth ; desktop.getsize (&screenheight,&screenwidth) ; TDESKTOP::SETDESKCOLORS ---------------------------------------------------------------------- Summary Sets the colors in which {open} or {refresh} will draw the desktop. Also selects the clock's colors. Syntax #include "tdesktop.hpp" void far tdesktop::setdeskcolors // Desktop's colors ( int back=LIGHTGRAY, // Desktop's background color int fore=BLUE, // Desktop's foreground color int clockback=RED, // Clock's color int clockfore=WHITE ) ; Remarks This has no effect on the current colors. It will only be used when {open} or {refresh} will be called. This call is optional. If {setdeskcolors} is not called before a call to {open}, 'BLUE' on 'LIGHTGRAY' is assumed for the desktop and 'WHITE' on 'RED' for the clock. See appendix B for a list of available colors, color codes and symbolic constants. --> The desktop displays an interrupt driven clock in the upper right corner. Return None. Example desktop.setdeskcolors (BLACK,LIGHTGRAY,BLUE,WHITE) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 12 : EasyVision's tdesktop class Page 50/111 ---------------------------------------------------------------------- TDESKTOP::SETTEXTURE ---------------------------------------------------------------------- Summary Sets the character with which {open} or {refresh} will draw the desktop. Syntax #include "tdesktop.hpp" void far tdesktop::settexture // Set's desktop texture ( char asciicode=#176 // ASCII code to use ) ; Remarks You must provide the character used to draw the desktop, in the form of its ASCII code. Only ASCII codes greater or equal to 32 are accepted. This has no effect on the current screen. It will only be used when {open} or {refresh} will be called. This call is optional. If {settexture} is not called before a call to {open}, ASCII code 176 is assumed. Return None. Example desktop.settexture (' ') ; // Plain desktop TDESKTOP::SETTITLE ---------------------------------------------------------------------- Summary Sets the title, and title colors displayed at the very top line of the desktop. Syntax #include "tdesktop.hpp" void far tdesktop::settitle // Sets desktop's title ( char huge *text=NULL, // Desktop's title int back=EV_DEF, // Title's background color int fore=EV_DEF // Title's foreground color ) ; Remarks The title's colors are optional. If they are not provided, the desktop's colors will be used. This is used only if you do not intend to have a menubar, or if you will have something displayed before the menubar is created. This has no effect on the current desktop. It will only be used when {open} or {refresh} will be called. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 12 : EasyVision's tdesktop class Page 51/111 ---------------------------------------------------------------------- This call is optional. If {settitle} is not called before a call to {open}, no title will be displayed. To reset a previously defined title, don't use any argument. You can give a <text> pointer argument that points to a text of any length, but only the part of the title that will fit on the titlebar will be displayed. So don't worry about the length of your title... Return None. Example desktop.settitle ("EasyVision 2.0",RED,BLACK) ; TDESKTOP::OPEN ---------------------------------------------------------------------- Summary Opens the desktop. Syntax #include "tdesktop.hpp" void far tdesktop::open () ; // Opens desktop Remarks This will save the screen before the program was started, initialise the video screen and then display the desktop according to the default values, or those set by the previous functions. This call is NOT optional. --> You cannot reopen an already opened desktop. You must use the {refresh} function for that action, or first close it. If the desktop as been closed, it can then be re- opened. This could be done for instance if you were to shell to DOS or to another program. Return None. Example desktop.open () ; TDESKTOP::CLOSE ---------------------------------------------------------------------- Summary Closes the desktop. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 12 : EasyVision's tdesktop class Page 52/111 ---------------------------------------------------------------------- Syntax #include "tdesktop.hpp" void far tdesktop::close () ; // Restores screen Remarks This will restore the video screen as it was before the desktop was opened. This call is NOT optional. You must first {close} the desktop with this function if you want to re-open it. --> {close} does not reset any of the desktop settings. You can easily re-open it after a shell to DOS for example. Return None. Example desktop.close () ; TDESKTOP::REFRESH ---------------------------------------------------------------------- Summary The desktop has a {refresh} function that will redraw the screen. Using this function can be DANGEROUS... Syntax #include "tdesktop.hpp" void far tdesktop::refresh () ; // Redraws desktop Remarks The refresh function will use the current values for colors, texture, etc... not the values when it was opened. This means that you can change the desktop colors for instance, and then {refresh} it. --> IN EASYVISION, WINDOWS CANNOT BE REFRESHED. YOU MUST MAKE ABSOLUTELY CERTAIN THAT THIS FUNCTION IS NOT AND CANNOT BE CALLED WHEN WINDOWS ARE OPENED, OR YOU WILL BE IN BIG TROUBLE. Return None. Example desktop.refresh () ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 13 : EasyVision's tstatusline class Page 53/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 13 : EasyVision's tstatusline class ---------------------------------------------------------------------- The {tstatusline} class allows your program to easily display information on the last line of the screen. --> An instance has already been globally declared and is called statusline. Only one instance of {tstatusline} can be used in a program. As a result, you will never declare and create another instance. The statusline has built in default values. Only one call is required to do the work. The statusline will autosize itself to the screen. However, if you would like to change those default behaviors, other functions are provided to do so. You can manually use the statusline by calling its {display} member function. Most of the time however, you won't. Each time you create an object in EasyVision, let it be a window, a button or an input field, you assign a short text to it. When this object is selected, this text will be automatically displayed on the statusline. On the following pages, you will find each of its member functions. Examples of using the statusline object are given in the source codes of the EasyVision's demo programs. TSTATUSLINE::SETCOLORS ---------------------------------------------------------------------- Summary Sets the background, foreground and highlight colors used by the {display} member function, when writing to the statusline. Syntax #include "tstatusline.hpp" void far tstatusline::setcolors // Sets colors ( int back=LIGHTGRAY, // Background color int fore=BLACK, // Foreground color int high=RED // Highlight color ) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 13 : EasyVision's tstatusline class Page 54/111 ---------------------------------------------------------------------- Remarks All arguments are optional. If they are not provided, <back> defaults to 'LIGHTGRAY', <fore> to 'BLACK' and <high> to 'RED'. You can use color macros if "CONIO.H" is included. Appendix B gives a description of available color codes and macros. The statusline is not modified by a call to this function. The changes to the colors will be made at the next call to {display}. Return None. Example statusline.setcolors (RED,BLACK,YELLOW) ; TSTATUSLINE::DISPLAY ---------------------------------------------------------------------- Summary Displays a message on the statusline. Syntax #include "tstatusline.hpp" void far tstatusline::display // Displays message ( char huge *text=NULL // Text to be displayed ) ; Remarks The <text> argument can point to a message of any length, including the '~' characters. The message will be truncated to fit on the message area, which length is 68 characters. There is no need to clear the statusline before using this function. You can toggle between normal foreground statusline color and the highlight color with the special character '~' (tilde). To clear the statusline, call this function with no argument. Return None. Example statusline.display ("Welcome to ~EasyVision~") ; statusline.display () ; // Clears statusline TSTATUSLINE::GETMSG ---------------------------------------------------------------------- Summary Returns last displayed message. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 13 : EasyVision's tstatusline class Page 55/111 ---------------------------------------------------------------------- Syntax #include "tstatusline.hpp" char huge* far tstatusline::getmsg () ; // Last message Remarks Lets say you have a function that will modify the statusline. You could save its current content before modifying it, then restore it at the function's end. Return None. Example char lastmsg ; lastmsg = statusline.getmsg () ; TSTATUSLINE::REFRESH ---------------------------------------------------------------------- Summary The statusline object has a {refresh} function that will redraw it on the screen. Syntax #include "tstatusline.hpp" void far tstatusline::refresh () ; // Redraws Remarks {refresh} will redisplay the last message. --> The refresh function will use the current color values. This means that you can change the statusline's colors and then, {refresh} it with the new colors. Return None. Example statusline.refresh () ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 14 : EasyVision's tinput class Page 56/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 14 : EasyVision's tinput class ---------------------------------------------------------------------- The {tinput} class is designed to process input information. It provides mouse support and gives your programs context sensitive help. --> An instance has already been globally declared and is called input. Only one instance of {tinput} can be used in a program. As a result, you will never declare and create another instance. The {tinput} class has built in default values. However, if you would like to change those default behaviors, you can easily do so. On the following pages, you will find each of {tinput}'s member functions. Examples of using the input object are given in the source codes of the EasyVision's demo programs. TINPUT::MOUSE_INIT ---------------------------------------------------------------------- Summary This function will look for a mouse driver and initialise it. Initially, the mouse will be hidden. Syntax #include "tinput.hpp" ; void far tinput::mouse_init () ; // Initialises mouse Remarks This function is called as part of the initialisation routines, before your program starts. You should never have to call it yourself. --> Remember that the mouse's cursor should ALWAYS be off when you make changes to the screen. Many older driver would leave garbage on the screen if you did updates while the cursor is ON. Anyway, the only time the mouse's cursor should be on is when you do user inputs. The {get} function will take care of all this and if you're doing things right, your only inputs will come from {get}. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 14 : EasyVision's tinput class Page 57/111 ---------------------------------------------------------------------- If no mouse is found, calling the other mouse functions won't produce any result. Return None. Example input.mouse_init () ; TINPUT::MOUSE_STATUS ---------------------------------------------------------------------- Summary Returns current mouse's state. Syntax #include "tinput.hpp" ; int far tinput::mouse_status () ; // Mouse's status Remarks None. Return Tree values can be returned: 0: No mouse's driver or mouse was found. 1: A mouse is present and the cursor is on the screen. 2: A mouse is present and the cursor is hidden. Example if (input.mouse_status () == 0) printf ("A mouse is necessary for this program") ; TINPUT::MOUSE_SHOW ---------------------------------------------------------------------- Summary Turns the mouse's cursor on. Syntax #include "tinput.hpp" ; void far tinput::mouse_show () ; // Shows cursor Remarks If a mouse wasn't found, this function doesn't have any effect. Return None. Example input.mouse_show () ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 14 : EasyVision's tinput class Page 58/111 ---------------------------------------------------------------------- TINPUT::MOUSE_HIDE ---------------------------------------------------------------------- Summary Turns the mouse's cursor off. Syntax #include "tinput.hpp" void far tinput::mouse_hide () ; // Hides cursor Remarks If a mouse wasn't found, this function doesn't have any effect. Return None. Example input.mouse_hide () ; TINPUT::MOUSE_LB_DOWN ---------------------------------------------------------------------- Summary Tells if mouse's left button is currently pressed. Syntax #include "tinput.hpp" ; bool far tinput::mouse_lb_down () ; // Tells if down Remarks None. Return {TRUE} if mouse's left button is currently down. {FALSE} otherwise. Example if (input.mouse_lb_down ()) do_something () ; TINPUT::MOUSE_POS ---------------------------------------------------------------------- Summary Returns mouse's screen position. Syntax #include "tinput.hpp" ; void far tinput::mouse_pos // Gets mouse's position ( int huge *row, // To return row position int huge *col // To return col position ) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 14 : EasyVision's tinput class Page 59/111 ---------------------------------------------------------------------- Remarks If a mouse wasn't found, the returned values are not changed. Return <row> returns the cursor's row position, 1 being the top row. <col> returns the cursor's column position, 1 being the leftmost column. Example int row, col ; input.mouse_pos (&row,&col) ; TINPUT::GET ---------------------------------------------------------------------- Summary Gets a user input, be it a keyboard or a mouse event. Provides automatic context sensitive help and mouse support during input. Syntax #include "tinput.hpp" ; int far tinput::get // Gets a keyb or mouse input ( input_info huge *ii=NULL, // Ptr to input_info int filter=0, // Valid key codes int hlpctx=EV_NOHLPCTX, // Context bool buffer=FALSE // Use buffer? ) ; Remarks This function is at the heart of EasyVision's input facilities. --> One important concept is that an EasyVision's input is ALWAYS stored in an {input_info} structure . This structure is as follows: struct input_info { int key_code ; // ASCII code of last character bool key_lshift ; // TRUE if left shift key pressed bool key_rshift ; // TRUE if right shift key pressed bool key_lctrl ; // TRUE if left ctrl key pressed bool key_rctrl ; // TRUE if right ctrl key pressed bool key_lalt ; // TRUE if left alt key pressed bool key_ralt ; // TRUE if right alt key pressed int mouse_row ; // Row position of mouse's cursor int mouse_col ; // Col position of mouse's cursor } EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 14 : EasyVision's tinput class Page 60/111 ---------------------------------------------------------------------- One of 'getch' weaknesses is its inability to deal with the way extended keys are internally represented. Those are the keys that don't have an ASCII code associated with them. For example, the function, arrow and editing keys all return an extended keycode. {tinput::get} will deal with these extended keys by adding 256 to the extended keycode. Appendix A lists all the extended keycodes currently available on an extended keyboard and their associated macros. Always use the macros instead of the real code. The first parameter <ii> is a pointer to an {input_info} structure. Information is returned in this structure. You can set <ii> to a NULL pointer or call {tinput::get} without any parameter. You then specify a <filter> to be used by {tinput::get}. A <filter> of 0 will allow any key to be read and returned by the function. You can also provide the ASCII or extended keycode (remember to add 256 to the real extended code or better yet, use the {II_*} macro) of the only key allowed to be returned by the function. This provides an easy way to WAIT FOR a specific key. The function will then return with that keycode, only when that key has been pressed. --> Beware of NEVER setting <filter> to an impossible key entry, or you will be trapped by the {get} function! Next, you give the current context number <hlpctx> for this input. If the user presses F1 , the right mouse's button or the on screen HELP button, the associated help screen for this context will be displayed. If you don't want to use the help system or if there isn't any help for the current context, set <hlpctx> to {EV_NOHLPCTX}. See appendix C to learn how to build an help file and activate the help facilities. --> If you set <buffer> to {FALSE}, {tinput::get} will flush the keyboard buffer before reading a key. If set to {TRUE}, it will read from the keyboard and mouse buffers if keys have been previously pressed. By default, <buffer> is set to {FALSE}. Return If a normal key was pressed, the returned value is an 'int' representing the ASCII code of that key (1-255). EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 14 : EasyVision's tinput class Page 61/111 ---------------------------------------------------------------------- If an extended key was pressed, the returned value is an 'int' representing the extended keycode plus 256 (256-396). See appendix A for a list of keyboard key macros. If the mouse was pressed, the macro {EV_MOUSE} is returned. The returned value is identical to the {key_code} field in the {input_info} structure. {input_info}'s fields {mouse_row} and {mouse_col} will hold the cursor's coordinates at the moment the left button was pressed. They are undefined if the input wasn't a mouse event. The other fields of the {input_info} structure hold the states of the shift, control and alt keys at the time of the input. Example input_info ii ; if (input.get (&ii) == EV_MOUSE) { // Process mouse input } else { // Process keyboard input } EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 15 : EasyVision's tmenubar class Page 62/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 15 : EasyVision's tmenubar class ---------------------------------------------------------------------- The {tmenubar} class provides a menubar on the first line of the screen, with pull down menus and selection cursor. A menubar acts as a filter. You make the user inputs go {through} the menubar. If the input is the keyboard event {II_F10} (F10), or an ALT-key corresponding to a menu hotkey, the menubar is activated. Otherwise, the input returns unchanged. Items created in the menus are assigned return values. When the user selects an item, his input is changed to this return value and returned from the menubar. --> Keep in mind that all inputs going {through} and returned from the menubar are {input_info } structures. Refer to the chapter on the {tinput} class. --> An instance has already been globally declared and is called menubar. Only one instance of {tmenubar} can be used in a program. As a result, you will never declare and create another instance. The {tmenubar} class has built in default values. However, if you would like to change those default behaviors, you can easily do so. On the following pages, you will find each of {tmenubar}'s member functions. Examples of using the menubar object are given in the source codes of the EasyVision's demo programs. TMENUBAR::SETCOLORS ---------------------------------------------------------------------- Summary Sets the background, foreground, highlight and cursor colors used by the menubar. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 15 : EasyVision's tmenubar class Page 63/111 ---------------------------------------------------------------------- Syntax #include "tmenubar.hpp" void far tmenubar::setcolors // Sets menubar colors ( int back=LIGHTGRAY, // Background color int fore=BLACK, // Foreground color int high=RED, // Highlight color int cursor=GREEN // Cursor color ) ; Remarks You can use color macros if "CONIO.H" is included. Appendix B gives a description of available color codes and macros. If you don't make a call to this function, the previously mentioned default values are assumed. --> When a menu has been created, it is thereafter illegal to change the already selected colors. Furthermore, the color 'DARKGRAY' is unavailable. It is reserved for offline menu items. Return None. Example menubar.setcolors (BLUE,WHITE,RED,MAGENTA) ; TMENUBAR::SETHLPCTX ---------------------------------------------------------------------- Summary Sets the menubar's default help context number. Syntax #include "tmenubar.hpp" void far tmenubar::sethlpctx // Sets default context ( int hlpctx=EV_NOHLPCTX // Help context number ) ; Remarks When created, each menu on the menubar and each item in a menu is given its own context number. If, however, a menu or an item is not given a number and help is requested while this menu or item is highlighted, the menubar default context number will be passed to the help routines. Return None. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 15 : EasyVision's tmenubar class Page 64/111 ---------------------------------------------------------------------- Example menubar.sethlpctx (1000) ; TMENUBAR::ADDMENU ---------------------------------------------------------------------- Summary Adds a menu to the menubar. Syntax #include "tmenubar.hpp" void far tmenubar::addmenu // Creates a new menu ( char huge *name, // Menu's name int hotkey, // Menu's hotkey char huge *sltext=NULL, // Statusline text int hlpctx=EV_NOHLPCTX // Help context number ) ; Remarks <name> is the name of the menu created. It can be of any length, but must fit on the menubar. The first two characters of the menubar are left blank, and the last 10 are reserved for the clock. Two spaces will be inserted between each menu. There can be as many menus on the menubar as will fit. Just don't make the names too long. The <hotkey> is the key that will activate the menu. It must be a letter (A-Z) or a digit (0-9), case insensitive. If the letter is present in the menu name, it will be highlighted. Two menus cannot have the same hotkey. <sltext> is a short help text that will be displayed on the statusline when this menu is selected. It can be of any length. <hlpctx> is the context number corresponding to this menu. The text associated to this context will be displayed if the user asks for help. If you set this argument to {EV_NOHLPCTX}, this menu won't have a help context of its own. Instead, the default menubar context will be use (see tmenubar::sethlpctx). See appendix 3 to learn about the help facilities. Return None. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 15 : EasyVision's tmenubar class Page 65/111 ---------------------------------------------------------------------- Example menubar.addmenu ("Files",'F',"Opens a new file",100) ; TMENUBAR::ADDITEM ---------------------------------------------------------------------- Summary Adds an item to the last created menu. Syntax #include "tmenubar.hpp" void far tmenubar::additem // Adds an item ( char huge *text=NULL, // Item's text int hotkey=II_NUL, // Item's hotkey int returnval=II_NUL, // Return value char huge *sltext=NULL, // Statusline text int hlpctx=EV_NOHLPCTX // Help context number ) ; Remarks <text> is the text displayed for this menu entry. It can be of any length. The menu will autosize itself to accommodate the widest item. There can be as many items in a menu as there is space on the screen. That is always 4 fewer than the total number of screen rows. The <hotkey> is the key that will activate the item. It must be a letter (A-Z) or a digit (0-9), case insensitive. If the hotkey is present in the item's text, it will be highlighted. Two items cannot have the same hotkey. If this item is selected, the user input will be change to <returnval> while in the {through} function. For example, if {II_A_X} (ALT-X) exits the program, you would set the QUIT item in the FILE menu to return the value {II_A_X} (Alt-X). It's a good idea to display those shortcuts in the item's text. --> This return value must be greater than 255. It cannot be {II_F10} (F10) or any of the arrows' keycodes (II_ARROW_*). <sltext> is a short help text that will be displayed on the statusline when this item is selected. It can be of any length. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 15 : EasyVision's tmenubar class Page 66/111 ---------------------------------------------------------------------- <hlpctx> is the context number corresponding to this item. The text associated to this context will be displayed if the user asks for help. If you set this argument to {EV_NOHLPCTX}, this menu won't have a help context of its own. Instead, the default menubar context will be use (see tmenubar::sethlpctx). See appendix 3 to learn about the help facilities. --> If {additem} is called with no arguments, it will insert a separator in the menu. Return None. Example menubar.additem ("Open F3",'O',II_F3,"Open file",103) ; TMENUBAR::ITEMSETAVAIL ---------------------------------------------------------------------- Summary Sets availability of a menu item to {TRUE} or {FALSE}. Syntax #include "tmenubar.hpp" void far tmenubar::itemsetavail // Sets availability ( int menuhotkey, // Hotkey of menu int itemhotkey, // Hotkey of menu item bool state // TRUE: available FALSE: Not ) ; Remarks You must provide the <menuhotkey> of the menu in which the item exists, and the <itemhotkey> of the item itself. Setting a menu item to {TRUE} will make it available, to {FALSE} not available. --> When a menu item is created, it is available by default. Return None. Example menubar.itemsetavail ('F','O',FALSE) ; TMENUBAR::THROUGH -- Summary Makes an input go through the menubar. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 15 : EasyVision's tmenubar class Page 67/111 ---------------------------------------------------------------------- Syntax #include "tmenubar.hpp" input_info far tmenubar::through // Activates menubar ( input_info ii // Input to go through ) ; Remarks If <ii> contains the keyboard event {II_F10} (F10), the menubar is activated, but no menus are opened. If <ii> is a menu hotkey, this menu is opened. Return If <ii> is not {II_F10} or a menu hotkey, {through} returns <ii> unchanged. If the menubar is activated, then if the user enters {II_ESC} (Esc), {through} returns with {II_NUL} in the {key_code} field of the {input_info} structure. Otherwise it returns with the return value of the menu item selected. Example input_info command ; command = menubar.through (input.get (&command)) ; TMENUBAR::REFRESH ---------------------------------------------------------------------- Summary The menubar object has a {refresh} function that will redraw it on the screen. Syntax #include "tmenubar.hpp" void far tmenubar::refresh () ; // Redraws the menubar Remarks You will most likely never call this function. You should call the desktop's own {refresh} function, who will then call this one. Return None. Example menubar.refresh () ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 68/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- C H A P T E R 16 : EasyVision's twindow class ---------------------------------------------------------------------- The {twindow} class provides to your program powerful window facilities. Windows are where all your program's screen inputs and outputs will take place. The {twindow} class comes with many member functions. They allow for manipulating the window position, size and attributes. Text can be easily written to the window. Input fields will give you formatted and secured user inputs. Push buttons will provide options selection. All these and many more features. The {twindow} class has built in default values. However, if you would like to change those default behaviors, you can easily do so. --> Contrary to the other classes, instances of the {twindow} class have NOT been declare. You can use as many instances of {twindow} as you like. As a result, you will have to declare and create your own instances. First, you declare a pointer to a twindow object (twindow huge *win). Then you allocated memory for it (win = new twindow). The object has been initialised with default values and is now ready to be used. --> You can open simultaneously as many windows as you like. When you open a window, what was under it is saved to be restored when you'll close it. --> EasyVision doesn't keep track of the way windows overlap. It doesn't know if a window is over or under another one. Therefore, a window should NEVER be closed if another window covers part of it. Always close the ones that are in the foreground first. --> You CANNOT work with a window if it is under another one. If you do, the integrity of the desktop will be compromised. On the following pages, you will find each of {twindow}'s member functions. Examples of using window objects are given in the source codes of the EasyVision's demo programs. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 69/111 ---------------------------------------------------------------------- TWINDOW::WINSETPOS ---------------------------------------------------------------------- Summary Sets position of the next window to be opened. Syntax #include "twindow.hpp" void far twindow::winsetpos // Sets window's position ( int row, // Top left corner's row int col, // Top left corner's col bool movable=EV_MAYBE // TRUE: Can be moved ) ; Remarks <row> and <col> are the topleft corner of the next window TO BE OPENED. The first and last lines of the desktop are reserved for the menubar and statusline. You can't have part of the window off the screen. Therefore, this function will validate all coordinates and change them to get a valid window position. --> If you set the size of the window before setting its position, this size will be taken into account to calculate the valid range of the <row> and <col> arguments. --> You CANNOT use this function once the window has been opened. Use the {winmove} function instead. Return None. Example win->winsetpos (10,12) ; // Topleft corner at 10,12 TWINDOW::WINGETROW ---------------------------------------------------------------------- Summary Returns row position of its topleft corner. Syntax #include "twindow.hpp" int far twindow::wingetrow () ; // Returns row pos Remarks The top left corner of the screen is (1,1). But row one is unavailable because it is taken by the menubar. Return Row position of window. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 70/111 ---------------------------------------------------------------------- Example row = win->wingetrow () ; TWINDOW::WINGETCOL ---------------------------------------------------------------------- Summary Returns window's column position of its topleft corner. Syntax #include "twindow.hpp" int far twindow::wingetcol () ; // Returns col pos Remarks The top left corner of the screen is (1,1). Return Column position of window. Example col = win->wingetcol () ; TWINDOW::WINSETSIZE ---------------------------------------------------------------------- Summary Sets size of next window to be opened. Syntax #include "twindow.hpp" void far twindow::winsetsize // Sets window's size ( int height=MAXINT,// Window's height including frames int width=MAXINT // Window's width including frames ) ; Remarks <height> and <width> represent the size of the window, frames included. The first and last lines of the desktop are reserved for the menubar and statusline. Also, you can't have part of the window off the screen. --> This function will validate the asked size and change it to get a valid window size. The position that was set with {winsetpos} will be taken into account. --> You CANNOT change the size of a window once it has been opened. Return None. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 71/111 ---------------------------------------------------------------------- Example win->winsetsize (10,60) ; // 10 rows by 60 cols TWINDOW::WINGETHEIGHT ---------------------------------------------------------------------- Summary Returns window's height in lines. Syntax #include "twindow.hpp" int far twindow::wingetheight () ; // Returns height Remarks The top and bottom frames are included in the height. Return The height of the window. Example heigth = win->wingetheight () ; TWINDOW::WINGETWIDTH ---------------------------------------------------------------------- Summary Returns window's width in columns. Syntax #include "twindow.hpp" int far twindow::wingetwidth () ; // Returns width Remarks The left and right frames are included in the width. Return The width of the window. Example width = win->wingetwidth () ; TWINDOW::WINSETCOLORS ---------------------------------------------------------------------- Summary Sets the background and foreground colors of a window. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 72/111 ---------------------------------------------------------------------- Syntax #include "twindow.hpp" void far twindow::winsetcolors // Sets window's colors ( int back=LIGHTGRAY, // Window's background color int fore=WHITE // Window's foreground color ) ; Remarks These are the colors used to draw the window. Those colors will be used by other functions when the color arguments are optional. <back> and <fore> are optional, and will default to 'LIGHTGRAY' and 'WHITE' respectively. --> You CANNOT change the default colors of a window once it has been opened. --> Bright background colors are available. See tdesktop's {settextmode}. Return None. Example win->winsetcolors (BLUE,WHITE) ; TWINDOW::WINSETTITLE ---------------------------------------------------------------------- Summary Sets the title displayed on the top frame of a window. Syntax #include "twindow.hpp" void far twindow::winsettitle // Sets window's title ( char huge *title // Ptr to window's title ) ; Remarks <title> can point to a title of any length, and only the portion that will fit on the top frame will be displayed. If you don't give a title before opening a window, no title will be displayed. --> You CAN'T set a title after a window has been opened. Return None. Example win->winsettitle ("Open file") ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 73/111 ---------------------------------------------------------------------- TWINDOW::WINSETHLPCTX ---------------------------------------------------------------------- Summary Sets the default help context for this window . If input fields or push buttons don't have a context of their own, they'll use this default. Syntax #include "twindow.hpp" void far twindow::winsethlpctx // Sets context's number ( int hlpctx=EV_NOHLPCTX // Help context's number ) ; Remarks See appendix 3 for a description of the help system. Return None. Example win->winsethlpctx (100) ; TWINDOW::WINOPEN ---------------------------------------------------------------------- Summary Opens a window. Syntax #include "twindow.hpp" void far twindow::winopen () ; // Opens window Remarks The window is opened with default attributes, or the ones set by the previous functions. You CANNOT open an already opened window. Default attributes for a window are: Position is (row=2, col=1). Size is (height=3, width=6). Colors are 'WHITE' on 'LIGHTGRAY'. The cursor is on line 1. Return None. Example win->winopen () ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 74/111 ---------------------------------------------------------------------- TWINDOW::WINCLOSE ---------------------------------------------------------------------- Summary Closes a window. Syntax #include "twindow.hpp" void far twindow::winclose () ; // Closes window Remarks You CANNOT close an already closed window. When you close a window, all its attributes are reset to their default values as if you had just declared this object. Your previous settings like size and colors aren't in effect anymore. All memory taken by the window is released. What was under this window when it was opened is restored. --> You should NEVER close a window that has part of itself hidden under another window. Always close the ones in the foreground first. This is your responsibility! EasyVision doesn't know your window's layer position and won't tell you if something goes wrong. Return None. Example win->winclose () ; TWINDOW::WINCLEAR ---------------------------------------------------------------------- Summary Clears part or all the window content. Syntax #include "twindow.hpp" void far twindow::winclear // Clears an area in window ( int left=1, // Top left corner int top=1, int right=MAXINT // Bottom right corner int bottom=MAXINT ) ; Remarks The window must be opened to call this function. All arguments are validated and if incorrect, changed to fall within valid window coordinates. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 75/111 ---------------------------------------------------------------------- All arguments are optional. Calling this function with no arguments will clear the entire window. --> Beware that this function will also clear buttons and input fields, BUT NOT REMOVE THEM. This will make them invisible, until you use them again. It is your responsibility to make sure you don't erase something important! Return None. Example win->winclear (1,1,999,3) ; // Erases first 3 lines TWINDOW::WINWRITE ---------------------------------------------------------------------- Summary Writes text to the window . Many format options are available. Syntax #include "twindow.hpp" void far twindow::winwrite // Writes text to window ( char huge *text, // Ptr to text to be written int row=EV_DEF, // Text's position in window int col=1, int format=0, // Justification int fore=EV_DEF, // Text's color int back=EV_DEF ) ; Remarks The window must be opened. The <text> argument can point to a text string of any length, but only the first 132 characters will be considered. --> This function will only print on 1 line of the window. If the string is longer than an entire line, only what will fit will be printed. NO LINE WRAPPING WILL OCCUR with this function! All arguments are optional, except for <text>. <text> : Pointer to the text to be printed. <row> : The {winwrite} function keeps track of the last line printed to, with an internal cursor. After each {winwrite}, the cursor is positioned on the next line. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 76/111 ---------------------------------------------------------------------- When you use <row>, it tells where the text is to be printed. Row 1 is the first line under the top frame. This argument is optional. If it is not given, or if you use the macro {EV_DEF}, {winwrite} will use it's internal cursor position. Text will be printed on the cursor line, and the cursor will move to the next line. --> If you DON'T give the <row> argument and write to the last window line, all the window will be scrolled up 1 line. YOU MUST MAKE SURE YOU DON'T HAVE ANY BUTTONS OR INPUT FIELDS. THEY WILL BE SCROLLED UP ALSO AND THE WINDOW'S INTEGRITY WILL HAVE BEEN COMPROMISED! --> If you give the <row> argument, you can then write to the last line and no scrolling will occur. The window cursor will stay on the last line. <col> : Column where text will start. This argument is optional. If it is not given, it will default to 1. <format> : Determines how the text string is justified. 0 : No justification. <col> is used. 1 : Left justified. <col> has no effect. 2 : Centered. <col> has no effect. 3 : Right justified. <col> has no effect. This argument is optional. If it is not given, it will default to 0. <fore> : Foreground color used. This argument is optional. If it is not given, or if you use the macro {EV_DEF}, it will default to the window's foreground color. <back> : Background color used. This argument is optional. If it is not given, or if you use the macro {EV_DEF}, it will default to the window's background color. Return None. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 77/111 ---------------------------------------------------------------------- Example // Writes to current line, left justified, current // window's colors, and moves cursor to next line win->winwrite ("Hello") ; // Writes to current line, centered, current window's // colors, and move cursor to next line. Even if // <col> is 1, it has no effect. win->winwrite ("Hello",EV_DEF,1,2) ; // Writes to specific line, specific column, // specific colors win->winwrite ("Hello",5,10,0,YELLOW,RED) ; TWINDOW::WINTEXT ---------------------------------------------------------------------- Summary Displays a text array in current window with word wrapping and 'Ok/Esc' prompts. Syntax #include "twindow.hpp" void far twindow::wintext // Text with wrapping ( char huge *textptr, // Ptr to text to be displayed int fore=EV_DEF, // Normal foreground color int high=YELLOW // Text's highlight color ) ; Remarks The window must be opened to call this function. <textptr> : This points to the text to be displayed. This text can be of any length. This text is an array of characters that need not be formatted in any way. This function will display the array with word wrapping at the window's right edge. Any extra spaces will be removed from the text, leaving only one space between each word. Any leading spaces to a line will also be removed. If you want to begin a line with spaces, or separate some words with more than one space, you must use the underscore (_) character. You can highlight your text by surrounding characters with the tilde (~) character. The array can be of any length. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 78/111 ---------------------------------------------------------------------- An 'Ok' prompt will be created to allow the user to see the remaining text if it couldn't all fit in the window. An 'Esc' prompt will be created to allow the user to stop viewing text at his convenience. --> When you use this function, make sure the window is totally empty. Everything that was in the window is erased when you call this function. <fore> : Foreground color used. This argument is optional. If it is not given, or if you use the macro {EV_DEF}, the default foreground color of the window will be used. <high> : Highlight color used. This argument is optional. If it is not given, the color YELLOW will be used for highlights. Return None. Example win->wintext (instructions) ; TWINDOW::WINTEXTFILE ---------------------------------------------------------------------- Summary Displays a text file from disk in current window with word wrapping and 'Ok/Esc' prompts. Syntax #include "twindow.hpp" void far twindow::wintextfile // Displays a text file ( char huge *path, // Path to file int fore=EV_DEF, // Foreground color to use int high=YELLOW // Highlight color to use ) ; Remarks This function acts exactly the same as {wintext}. The only difference is that it gets it's input text from a disk file. <path> : Complete path to disk file. If the file cannot be found, the string "File not found" is displayed instead. This string is pointed to by the system variable ev_filenotfoundtext. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 79/111 ---------------------------------------------------------------------- <fore> : Foreground color used. This argument is optional. If it is not given, or if you use the macro {EV_DEF}, the default foreground color of the window will be used. <high> : Highlight color used. This argument is optional. If it is not given, the color YELLOW will be used for highlights. Return None. Example win->wintextfile ("C:\\autoexec.bat") ; TWINDOW::WINMOVE ---------------------------------------------------------------------- Summary Moves the windows to a new location. Syntax #include "twindow.hpp" void far twindow::winmove// Moves window to new position ( int row, // Topleft corner's new position int col ) ; Remarks The window must be opened. <row> and <col> are the new position of the topleft corner of the window. The first and last lines of the desktop are reserved for the menubar and statusline and you can't have part of the window off the screen. Therefore, this function will validate all coordinates and change them to get a valid window position. Return None. Example win->winmove (10,12) ; TWINDOW::WINSCROLL ---------------------------------------------------------------------- Summary Moves window in 1 of 4 directions. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 80/111 ---------------------------------------------------------------------- Syntax #include "twindow.hpp" void far twindow::winscroll// Moves window 1 space only ( char direction // U: up D: down L: left R: right ) ; Remarks The entire window will be moved, IF POSSIBLE, one character in the requested direction. The name can be a little confusing. It is not the window content that is scrolled. It's the entire window. The argument is a character, case insensitive: U: Up, D: Down, L: Left, R: Right. Return None. Example win->winscroll ('U') ; // Move window up one line TWINDOW::WINONEDGES ---------------------------------------------------------------------- Summary Checks if position is on window's edges. Syntax #include "twindow.hpp" bool far twindow::winonedges // Checks if on for edges ( int row, // Position int col, int huge *offsetrow=NULL,// Offset to top left corner int huge *offsetcol=NULL ) ; Remarks It will return {TRUE} if this position is on one of this window's edges. This function can also return the offset of the row and col positions to the upper left most corner of the window. If you don't want the offsets, set the return variables to 'NULL'. Return {TRUE} if the position is on one of the edges. Example int off_row, off_col ; if (win->winonedges (10,23,&off_row,&off_col)) DoSomething () ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 81/111 ---------------------------------------------------------------------- TWINDOW::WININSIDE ---------------------------------------------------------------------- Summary Checks if a position is in the window. Syntax #include "twindow.hpp" bool far twindow::wininside // Checks if in window ( int row, // Position int col, int huge *offsetrow=NULL,// Offset to top left corner int huge *offsetcol=NULL ) ; Remarks It will return {TRUE} if this position is inside the window. The frames are NOT considered inside. This function can also return the offset of the row and col positions to the upper left most corner of the window. If you don't want the offsets, set the return variables to 'NULL'. Return {TRUE} if the position is inside window's edges. Example int off_row, off_col ; if (win->wininside (10,23,&off_row,&off_col)) DoSomething () ; TWINDOW::WININPUT ---------------------------------------------------------------------- Summary Makes window alive , allowing inputs to be made in multiple input fields and push buttons selected. Syntax #include "twindow.hpp" input_info far twindow::wininput // Gets input ( input_info ii // input_info struct ) ; Remarks The user will be able to move between input fields and buttons with {II_TAB} (Tab) and {II_S_TAB} (Shift Tab). He will be able to move the window, if allowed, by dragging it by one of its edges. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 82/111 ---------------------------------------------------------------------- --> You should refrain from using the {fieldinput} and {buttoninput} functions. Use this one instead. Return If there are no input fields and no push buttons, the {input_info} structure is returned unchanged. If no push buttons were created, but at least an input field, {wininput} will return with {II_CR} (Enter) or {II_ESC} (Esc). {II_CR} means the user confirmed the inputs by pressing ENTER. {II_ESC} means the user aborted the input by pressing ESC. If buttons were created, {wininput} will return with the identification value of the button pushed. Example userinput = win->wininput (ii) ; TWINDOW::FIELDSETCOLORS ---------------------------------------------------------------------- Summary Sets the colors used in the next input field to be created. Syntax #include "twindow.hpp" void far twindow::fieldsetcolors // Fields' colors ( int back=BLUE, // Fields' background color int foreon=WHITE, // Foreground color when active int foreoff=LIGHTCYAN // Color when inactive ) ; Remarks <back> : Background color used. This argument is optional. If it is not given, 'BLUE' is assumed. If the macro {EV_DEF} is used, it will default to the window default background color. <foreon> : Foreground color used when the field is active. This argument is optional. If it is not given, it will default to 'WHITE'. <foreoff> : Foreground color used when the field is inactive. This argument is optional. If it is not given, it will default to 'DARKGRAY'. Return None. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 83/111 ---------------------------------------------------------------------- Example win->fieldsetcolors (GREEN,WHITE,WHITE) ; TWINDOW::FIELDCREATE ---------------------------------------------------------------------- Summary Creates a new input field in the window. Syntax #include "twindow.hpp" void far twindow::fieldcreate // Creates input field ( int row, // Input field's row int col, // Input field's col int answerlength, // Answers' maximum length int length, // Input field's length in window int ftr, // Input field's filter number (0-4) char huge *xtraftr, // Extra chars for filter bool capsflag, // If TRUE, to uppercase bool nullflag, // If TRUE, can enter null str char huge *defaultasw, // Default answer char huge *sltext, // Statusline text for field int hlpctx // Help context number ) ; Remarks The window must be opened before calling this function. Fields have default built in behaviors when a window is first created. If you don't call any function to set their attributes, buttons will default to 'WHITE' on 'BLUE'. <row> : Row of input field. <col> : Column of input field. <row> and <col> are validated to make sure the input field fits into the window. If the position is incorrect, it will be automatically changed. <answerlength> : The maximum length of the input buffer. The user is allow to enter a string no longer than this limit. The upper limit is 32K. That should be enough! EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 84/111 ---------------------------------------------------------------------- <length> : The length of the input field in the window in characters. The input field cannot be wider than the window. The input field cannot be wider than the answer buffer's length. <ftr> : An input field will allow only certain characters as input. <ftr> will determine what characters are accepted. 0 : All characters are allowed, except control chars. 1 : A-Z and a-z only. *** Space (32) not allowed *** 2 : 0-9 only. 3 : A-Z, a-z and 0-9 only. 4 : No characters allowed. <xtraftr> : Include, between quotes, other characters that you want accepted by the filter. Often used to include the space char (ASCII 32). <capsflag> : If set to {TRUE}, all inputs will be converted to CAPS. <nullflag> : If set to {FALSE}, the user won't be allowed to input an empty string. <defaultasw> : This is the default answer that will be put in the input field. This argument is optional. If you want the field to be initially empty, set to 'NULL'. <sltext> : This is a short help text that will be displayed on the status line when the field is active. If you don't want a help text to be displayed, set to 'NULL'. <hlpctx> : The help context number for this field. If set to {EV_NOHLPCTX}, the field will use the window's default. Return None. Example win->fieldcreate (2, 2, 20, 10, 1, " ", TRUE, FALSE, "Canada", "Enter country", 205) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 85/111 ---------------------------------------------------------------------- TWINDOW::FIELDSETASW ---------------------------------------------------------------------- Summary Sets a field current content. Syntax #include "twindow.hpp" void far twindow::fieldsetasw // Sets default answer ( char huge *answer, // Default answer for this field int fieldnb // Field's ID number ) ; Remarks Even if the content is immediately changed, the field on the screen will be updated only when it is activated. <answer> : String to copy in the field. It can be of any length, but only what will fit in the answer buffer will be copied. <fieldnb> : Number of the field to copy to. Number IDs are given to the field at their creation, starting with one. Return None. Example win->fieldsetasw ("C:\\UTILS\\",5) ; TWINDOW::FIELDGETASW ---------------------------------------------------------------------- Summary Reads the content of the answer buffer of an input field. Syntax #include "twindow.hpp" void far twindow::fieldgetasw // Gets a field's answer ( char huge *dest, // Destination to copy answer's to int fieldnb // Field's ID number ) ; Remarks The answer buffer of field <fieldnb> is copied to <dest>. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 86/111 ---------------------------------------------------------------------- --> There is no way for the function to know if your destination is big enough to hold the content of the answer buffer. YOU MUST MAKE ABSOLUTELY SURE THAT YOUR DESTINATION IS AS BIG AS THE ANSWER BUFFER PLUS ONE CHARACTER for the terminating '\n'. Return None. Example win->fieldgetasw (&response,3) ; TWINDOW::FIELDINPUT ---------------------------------------------------------------------- Summary Gets user input from one input field. Syntax #include "twindow.hpp" input_info far twindow::fieldinput // Activates field ( int fieldnb // Field's number, to get input from ) ; Remarks You must have created at least one input field to use this function. Fields are given numbers when they are created. The first field created is number one. <fieldnb> : This is the field from which you will make the input. This field must exist. --> You should never have to use this function. You should consider using the {wininput} function instead. This is provided to allow for really special cases. --> The user won't be able to move the window. Return {fieldinput} with return with an {input_info} structure containing the ASCII code representing how the user terminated the input. This can be {II_CR}, {II_ESC}, {II_TAB} or {II_S_TAB}. Example name = win->fieldinput (1) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 87/111 ---------------------------------------------------------------------- TWINDOW::BUTTONSETCOLORS ---------------------------------------------------------------------- Summary Sets the colors used for all the window's buttons. Syntax #include "twindow.hpp" void far twindow::buttonsetcolors// Sets buttons's colors ( int back=GREEN, // Button's background color int foreon=WHITE, // Foreground color when active int foreoff=BLACK, // Foreground color when inactive int high=YELLOW // Highlight color (hotkey) ) ; Remarks All buttons use the same color configuration. You can't use this function once a button has been created. <back> : Background color of all buttons. This argument is optional and will default to 'GREEN'. <foreon> : Foreground color of active buttons. This argument is optional and will default to 'WHITE'. <foreoff> : Foreground color of inactive buttons. This argument is optional and will default to 'BLACK'. <high> : Highlight color of all buttons. This argument is optional and will default to 'YELLOW'. Return None. Example win->buttonsetcolors (BLUE,WHITE,BLACK,RED) ; TWINDOW::BUTTONCREATE ---------------------------------------------------------------------- Summary Creates a new button. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 88/111 ---------------------------------------------------------------------- Syntax #include "twindow.hpp" void far twindow::buttoncreate // Creates a button ( int row, // Button's row int col, // Button's col char huge *name, // Button's name int buttonkey, // Button's hotkey char huge *sltext=NULL, // Button's statusline text int hlpctx=EV_NOHLPCTX // Help context number ) ; Remarks The window must be opened to use this function. The window must be big enough to hold the button. It must be at least 4 lines high, and 11 columns wide. You can create as many buttons as you want. There is no upper limit. Buttons have default built in values when a window is first created. You don't need to call the {buttonsetcolors} function. If you don't, buttons will default to a 'GREEN' background, 'WHITE' text when active, 'BLACK' text when inactive, and 'YELLOW' highlight. --> The availability status of a newly created button always defaults to {TRUE} (available). The first button created will be considered the default button. This button will be activated when you request a {buttoninput} or {wininput}. <row> : Row position of the new button. <col> : Column position of the new button. If <row> and <col> are not valid, they will be changed to a correct position. --> You must make sure buttons don't overlap. A button needs an empty line under and to the right of itself. <name> : The name to put on the button. It can be of any length, but only the first 8 characters will be considered. Names aren't automatically centered on the buttons. Center the name manually by inserting leading spaces in the name. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 89/111 ---------------------------------------------------------------------- <buttonkey> : This is the ASCII code that will identify a particular button. Some rules are to be observed: If the identification code of the button matches a character in its name, that character will be highlighted. {II_TAB} (Tab), {II_S_TAB} (Shift Tab) and {II_ARROW_*} (arrow keys) codes cannot be used to identify a button. <sltext> : This is a short help text that will be displayed on the status line when the button is active. This argument is optional. If it is not given, no help text will be displayed. <hlpctx> : The help context number for this button. If set to {EV_NOHLPCTX}, the field will use the window's default. Return None. Example win->buttoncreate (10,2," Save",'S',"Save file",153) ; TWINDOW::BUTTONSETAVAIL ---------------------------------------------------------------------- Summary Sets the availability of a button. Syntax #include "twindow.hpp" void far twindow::buttonsetavail // Sets availability ( int buttonkey, // Button's hotkey bool available=TRUE // TRUE: available ) ; Remarks The button specified MUST exist. <buttonkey> : The button's hotkey that identifies the one you want to change. <available> : {TRUE} means this button is available. {FALSE} means it is not. When a button is created with {buttoncreate}, its availability status is automatically set to {TRUE}. Return None. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- CHAPTER 16 : EasyVision's twindow class Page 90/111 ---------------------------------------------------------------------- Example win->buttonsetavail ('S',FALSE) ; // Save button OFF TWINDOW::BUTTONINPUT ---------------------------------------------------------------------- Summary Makes user go through the buttons with {II_TAB} (Tab), {II_S_TAB} (Shift Tab) and {II_ARROW_*} (arrow keys). Syntax #include "twindow.hpp" input_info far twindow::buttoninput // Waits for button ( input_info userinput, // User's initial input bool first=TRUE // TRUE: Makes 1st alive ) ; Remarks You must have created at least one button to call this function, and there must be at least one button available. <userinput> : The initial user input, as an {input_info} structure. This could come from some previous processing. For instance, the result of an input field. <first> : Determines which button will first be made active during the input. {TRUE} means the first created button, {FALSE} means the last. This argument is optional and will default to {TRUE}. --> You should never have to use this function. You should consider using the {wininput} function instead. This is provided to allow for really special cases. --> The user won't be able to move the window. Return The function returns an 'int'. It is the identification code of the button that was pushed. Example command = win->buttoninput (command) ; EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX A : Keycodes macros Page 91/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- A P P E N D I X A : Keycodes macros ---------------------------------------------------------------------- Extended keycodes are returned when you press a key that doesn't have an associated ASCII code. They are represented by stuffing two codes into the keyboard buffer. A 0 followed by an extended key keycode in the range 0 through 255. The EasyVision's {getkey} function and {tinput} class, deal with these codes by returning values (int) in the range 0 through 511. The standard ASCII codes are returned unchanged (Guess why?). As a convenience, extended keycodes have 256 added to their real value, and are returned as a single number. Macros, always debuting by {II_}, have been assigned to most of the values listed here. Those macros are available in "STDMACRO.H". You should always use the macros instead of the actual codes. Macro Value Comment II_NUL 0 /* No input at all */ II_MOUSE 256 /* {input_info} = mouse */ II_BS 8 /* Back space */ II_TAB 9 /* Tab */ II_CR 13 /* Carriage return */ II_ESC 27 /* Escape */ II_S_TAB 271 /* Shift-Tab */ II_A_Q 272 /* Alt-Q/W/E/R/T/Y/U/I/O/P */ II_A_W 273 II_A_E 274 II_A_R 275 II_A_T 276 II_A_Y 277 II_A_U 278 II_A_I 279 II_A_O 280 II_A_P 281 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX A : Keycodes macros Page 92/111 ---------------------------------------------------------------------- II_A_A 286 /* Alt-A/S/D/F/G/H/J/K/L */ II_A_S 287 II_A_D 288 II_A_F 289 II_A_G 290 II_A_H 291 II_A_J 292 II_A_K 293 II_A_L 294 II_A_Z 300 /* Alt-Z/X/C/V/B/N/M */ II_A_X 301 II_A_C 302 II_A_V 303 II_A_B 304 II_A_N 305 II_A_M 306 II_F1 315 /* F1-F10 */ II_F2 316 II_F3 317 II_F4 318 II_F5 319 II_F6 320 II_F7 321 II_F8 322 II_F9 323 II_F10 324 II_F11 389 /* F11 */ II_F12 390 /* F12 */ II_HOME 327 /* Cursor keys */ II_ARROWUP 328 II_PAGEUP 329 II_ARROWLEFT 331 II_ARROWRIGHT 333 II_END 335 II_ARROWDOWN 336 II_PAGEDOWN 337 II_INS 338 II_DEL 339 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX A : Keycodes macros Page 93/111 ---------------------------------------------------------------------- II_S_F1 340 /* Shift-F1 to Shift-F10 */ II_S_F2 341 II_S_F3 342 II_S_F4 343 II_S_F5 344 II_S_F6 345 II_S_F7 346 II_S_F8 347 II_S_F9 348 II_S_F10 349 II_S_F11 391 /* Shift-F11 */ II_S_F12 392 /* Shift-F12 */ II_C_F1 350 /* Ctrl-F1 to Ctrl-F10 */ II_C_F2 351 II_C_F3 352 II_C_F4 353 II_C_F5 354 II_C_F6 355 II_C_F7 356 II_C_F8 357 II_C_F9 358 II_C_F10 359 II_C_F11 393 /* Ctrl-F11 */ II_C_F12 394 /* Ctrl-F12 */ II_A_F1 360 /* Alt-F1 to Alt-F10 */ II_A_F2 361 II_A_F3 362 II_A_F4 363 II_A_F5 364 II_A_F6 365 II_A_F7 366 II_A_F8 367 II_A_F9 368 II_A_F10 369 II_A_F11 395 /* Alt-F11 */ II_A_F12 396 /* Alt-F12 */ II_C_PRTSCR 370 /* Ctrl-Print Screen */ II_C_ARROWLEFT 371 /* Ctrl- cursor keys */ II_C_ARROWRIGHT 372 II_C_END 373 II_C_PAGEDOWN 374 II_C_HOME 375 II_C_PAGEUP 388 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX A : Keycodes macros Page 94/111 ---------------------------------------------------------------------- II_A_1 376/* Alt-1/2/3/4/5/6/7/8/9/0/-/= */ II_A_2 377 II_A_3 378 II_A_4 379 II_A_5 380 II_A_6 381 II_A_7 382 II_A_8 383 II_A_9 384 II_A_0 385 II_A_MINUS 386 II_A_EQUAL 387 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX B : Color codes and symbolic constants Page 95/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- A P P E N D I X B : Color codes and symbolic constants ---------------------------------------------------------------------- When asked for a color argument, you must provide one of the following values. As an alternative, you can also use special macros, provided "CONIO.H" as been included. --> Functions that require a background color argument can use bright background color. Refer to {tdesktop}'s {settextmode} for more information. Available background colors: 0 BLACK 8 DARKGRAY 1 BLUE 9 LIGHTBLUE 2 GREEN 10 LIGHTGREEN 3 CYAN 11 LIGHTCYAN 4 RED 12 LIGHTRED 5 MAGENTA 13 LIGHTMAGENTA 6 BROWN 14 YELLOW 7 LIGHTGRAY 15 WHITE Available foreground colors: 0 BLACK 8 DARKGRAY 1 BLUE 9 LIGHTBLUE 2 GREEN 10 LIGHTGREEN 3 CYAN 11 LIGHTCYAN 4 RED 12 LIGHTRED 5 MAGENTA 13 LIGHTMAGENTA 6 BROWN 14 YELLOW 7 LIGHTGRAY 15 WHITE EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX C : Context sensitive help system Page 96/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- A P P E N D I X C : Context sensitive help system ---------------------------------------------------------------------- EasyVision provides an easy to use context sensitive help system. If fact, it's so easy you have nothing to do except write up the help text. At startup, the static instance of the {tinput} class (input) will look in the directory of the executable file "*.EXE" for the help files "*.HLP" and "*.HDX". If those files are not found or one is missing, the program simply won't use the help system. When the user requests help by pressing the F1 function key, a message indicating that help is not available will be displayed. If, however, you want your program to use the help system, follow these few simple steps... What is a context ---------------------------------------------------------------------- Menus in the menubar and items within a menu, each have their own context number. Windows, input fields and push buttons also have their own context number. They are given when you create those objects. When one of these objects is active or selected, its context number is in effect. If help is requested by the user, the help text associated with this help context number will be displayed. These objects provide easy input fonctions. You can also get inputs from the {tinput::get} member function. When you do, you also specify a current help context. So, in essence, a context number indicates to the library what the user is currently doing in the interface or in the program. The help routines will thereafter be able to display help relative to the current situation. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX C : Context sensitive help system Page 97/111 ---------------------------------------------------------------------- Context numbering ---------------------------------------------------------------------- You can number your context in any way. A context number is an integer number (int). You should consider, however, using a logical numbering system. You could give a menu the context number 100, and give the items within this menu the numbers 101, 102, 103 and so on... You would do the same with windows. A window would have the number 1000. The input fields would be 1100, 1101, 1102, etc. The push buttons could be 1200, 1201, 1202, etc. You choose the numbering system that's right for you. You'll see in a few moments that there is an easier way to manage these context numbers. Writing the ASCII help file ---------------------------------------------------------------------- The help file is in plain ASCII. You can put comments everywhere in the file. The help compiler "HC.EXE" will consider only the text between the two keywords delimiters {HLPCTX} and {HLPEND}. --> The help text MUST be saved WITHOUT carriage returns or linefeeds at the end of the lines. You put a carriage return only at the end of a paragraph. If you want a blank line between paragraphs, put two returns at the end. I strongly suggest that you write your help file with your favorite word processor and save the file in its native format. You'll also save an ASCII copy of it, without carriage returns at the end of the lines, for the help compiler. You MUST give the ASCII file the same name as your program's executable "*.EXE". For instance, if the program is named "TOTO.EXE", your ASCII help file must be named "TOTO.*". The extension is up to you, but I strongly suggest you use "*.HLT" extensions for the ASCII help file "TOTO.HLT". EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX C : Context sensitive help system Page 98/111 ---------------------------------------------------------------------- ASCII help file format ---------------------------------------------------------------------- The ASCII help file uses the following format. Example: HLPCTX 123 MENU_EDIT_PASTE By using the paste command you'll copy the content of the clipboard back onto the edit page at the cursor's location. HLPEND The help compiler will consider only what you put between the {HLPCTX} and the {HLPEND} keywords. You can put any comments you want elsewhere. 1. The HLPCTX keyword can be anywhere on the line and is case insensitive. 2. Next you put the context number. It must be separated from the {HLPCTX} keyword by at least one white space character (spaces (32) or TABS (9)) and ON THE SAME TEXT LINE. This context number must be a valid string that will evaluate to an integer. 3. After the context number, again separated by at least a white space character, and ON THE SAME LINE, you'll put the context '#define' macro. --> The compiler will produce a file with the name of your program executable and the extension "*.HCM" (Help Context Macros). You can then include this file in your source codes and reference easy to remember macros instead of context number. This macro is optional. If not present, you'll be able to reference this context only by its number. 4. You then start your help text on the next line. Everything you write, up but not including the following {HLPEND} keyword, will be considered by the help compiler as the help text associated with this context number and macro. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX C : Context sensitive help system Page 99/111 ---------------------------------------------------------------------- 5. You then put the terminating {HLPEND} keyword, wich is case insensitive. However, the preceding spaces will be considered part of the help text. Take a look at the included examples that comes with the demo programs. The help compiler ---------------------------------------------------------------------- After your ASCII help file "*.HLT" as been saved, you compile it with EasyVision's help compiler "HC.EXE". The command line is : HC [d:][\path\][filename.ext] The compiler will parse the file checking for errors. If everything goes fine, it will produce two files. One with the extension "*.HLP", the other with "*.HDX". The files will have the same name as your program's executable and be located in the same directory as the "*.HLT" file. As in our example, "TOTO.HLP" and "TOTO.HDX". The "*.HLP" and "*.HDX" help files ---------------------------------------------------------------------- The "*.HLP" and "*.HDX" files must be placed in your program's executable directory. The "*.HLP" file is the compile help text. It stays on disk and is accessed as needed during execution. The "*.HDX" file is an index to the help file that is loaded in memory at program startup. This will provide extremely fast access to the help file, even if it's on floppy disk. That's all there is to it! Your program can enjoy context sensitive help facilities with minimal work on your part. Examples of creating and using the help system are given in the EasyVision's demo programs. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX D : EasyVision's language system variables Page 100/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- A P P E N D I X D : EasyVision's language system variables ---------------------------------------------------------------------- EasyVision makes it easy to implement language files. All the prompts and data strings output by your program should be placed in a separate file as global variables. You then reference them in the other modules with 'extern' declarations. This way, you can have different language versions of your application without rewriting a single line of code. EasyVision displays a few default messages. Those are reference by the following system variables. You can change them manually to display appropriate messages for you country. Two functions are also provided to switch the interface from french to english modes. Language system variables ---------------------------------------------------------------------- --> All the following system variables are huge pointers to characters. The are reference in the header file "EVMSGS.HPP". You must include this file in every module that references these variables. ev_helpwindowtitle String displayed as the title of the help window. English : "Help" French : "Aide" EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX D : EasyVision's language system variables Page 101/111 ---------------------------------------------------------------------- ev_helpwindownohelp String displayed when an object does not have a help context or when the macro {EV_NOHLPCTX} is passed to {input::get}. English : "Sorry, but help is not available at this time..." French : "Desole, mais aucune aide n'est disponible en ce moment..." ev_helpwindowfileerror String displayed when the help system finds an error accessing the help files. English : "There was a disk error while opening the help file. If the help files (*.hlp and *.hdx) are on a floppy disk, make sure it is still in the drive unit." French : "Une erreur de lecture s'est produite en ouvrant le fichier d'aide. Si les fichiers d'aide (*.hlp et *.hdx) se trouvent sur disquette, soyez certain qu'elle est bien dans le lecteur." ev_wintextdownbutton In the {twindow::wintext} function and in the help system, string displayed on the button that will allow seeing the following page. English : " Ok" French : " Ok" ev_wintextdown In the {twindow::wintext} function and in the help system, string displayed on the statusline when the button that will allow seeing the following page is selected. English : "See next page of text" French : "Voir la prochaine page de texte" EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX D : EasyVision's language system variables Page 102/111 ---------------------------------------------------------------------- ev_wintextquitbutton In the {twindow::wintext} function and in the help system, string displayed on the button that will stop the display of text. English : " Esc" French : " Esc" ev_wintextquit In the {twindow::wintext} function and in the help system, string displayed on the statusline when the button that will allow stopping the following page is selected. English : "Quit viewing text" French : "Termine l'affichage du text" ev_filenotfoundtext In the {twindow::wintextfile} function, string displayed when the requested file is not found. English : "File not found!" French : "Fichier non trouve!" ev_filetobig In the {twindow::wintextfile} function, string displayed when the requested file is to big to be loaded in memory. English : "Sorry, not enough memory to load this file..." French : "Desole, pas assez de memoire pour charger ce fichier..." EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX D : EasyVision's language system variables Page 103/111 ---------------------------------------------------------------------- ev_windowmove String displayed when a window is moved by dragging one of its edges. English : "Drag window while holding mouse's left button" French : "Deplacez la fenetre en tenant le boutton gauche de la souris" ev_statuslinehelp String displayed in the left part of the statusline, indicating that the user should press F1 to activate the help system. English : "Help" French : "Help" english() and french() functions ---------------------------------------------------------------------- Two functions will allow you to reset the language system variables to their default values. void language_english () ; // English definitions void language_french () ; // French definitions language_english () is automatically called at program startup. To call one of these functions, "EVMSGS.HPP" must be included. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX E : EasyVision's demo programs Page 104/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- A P P E N D I X E : EasyVision's demo program ---------------------------------------------------------------------- I am a true believer in the motto 'An example will often be simple than its written explanation'. I have included two complete demo programs with EasyVision. They are in the two archives "DEMO1.ZIP" and "HANOI.ZIP". The source codes, BC++ project files and executables are given. I have tried to use as many functions as possible in these short programs. They are fully documented and they illustrate the working relationship between all those functions and classes. I really think that 90% of your questions can be answered by going through these demo programs. You are invited to try some modifications of your own, and see the results. I'll say it again... You should really print all this documentation for easier reading. It's also a good idea to print the header files for quick references. Things to remember ---------------------------------------------------------------------- A couple of things are to be remembered from this demo source code. - You should always use 'huge' POINTERS in your code. You'll be on the safe side and avoid many problems. - You should put all text and prompt strings in a separate resource file. This will make it easy to update prompts or make an alternate language file. - EasyVision won't prevent you from using 'printf' statements. However, you should work within EasyVision's boundaries and use the provided output functions. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX E : EasyVision's demo programs Page 105/111 ---------------------------------------------------------------------- - All classes come with built in default values. Often, only one call is needed to use them if the defaults are to your likings. - Looking at this demo program, you can see that you can make great looking software faster than ever. Take the time to become familiar with EasyVision. The rewards will be fewer frustrations and more enjoyment out of your programming. Have fun! EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX F : How to reach the author Page 106/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- A P P E N D I X F : How to reach the author ---------------------------------------------------------------------- I will gladly answer any questions relating to this software. I can be reach through the FidoNet or the Internet. FidoNet : 1:240/1 (Make message to Remy Gendron) InterNet : REMY_GENDRON@F1.N240.Z1.FIDONET.ORG Phone : (418) 525-6803(TNG SOFT's answering machine) Mail : Remy Gendron 2480 ave de Vitre Quebec, Quebec, Canada G1J 4A6 I can't get back to you on the phone. Be sure to leave an electronic or conventional mail address. I'll get back to you real fast. Any comments, bug reports or suggestions will be appreciated. Thank you for considering this software! Remy Gendron Author of EasyVision EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- APPENDIX G : Trademarks Page 107/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- A P P E N D I X G : Trademarks ---------------------------------------------------------------------- Turbo Vision from Borland. Borland C++ 3.1 from Borland. DeskViev from Quarterdeck. CXL from Mike Smedley. EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- INDEX Page 108/111 ---------------------------------------------------------------------- ---------------------------------------------------------------------- ---------------------------------------------------------------------- I N D E X ---------------------------------------------------------------------- BUTTONSETCOLORS, 87 C - C++ default parameter values, 45 -> operator, 46 classes, 45 clock's colors, 49 . CLOSE, 51 . operator, 46 colors (appendix B), 49 command line arguments, 22 { conditional compilation, 13 {bool}, 17, 19 consistency, 15 {byte}, 17, 19 context number, 60 {dword}, 17, 19 context number (menus), 63 {FALSE}, 17 context sensitive help, 59 {TRUE}, 17 Conventions, 45 {word}, 17, 19 conventions, 14, 19 cur_info, 32 ~ cursor attributes, 32 ~ (highlight), 77 cursor's coordinates, 61 curtype, 32 A curx, 32 ADDITEM, 65 cury, 32 ADDMENU, 64 CXL, 8 ANSI escape sequences, 44 ANSI standard, 12 D ANSI.SYS driver, 44 delete, 46 ANSICOLOR, 44 desktop, 47 ARG_EXIST, 22 desktop's size, 49 ARG_IEXIST, 23 desktop's title, 50 ASSERT, 21 DESKview, 12 assert_err, 22 DIFFDATE, 42 available colors (appendix B), 49 DISPLAY, 54 driver (mouse), 56 B blinking, 48 E Bright background colors, 72 Error (System variable), 22 bright background colors, 30, 47 error messages, 14 buffer (keyb and mouse), 60 EV_MOUSE, 61 button availability, 89 EV_NOHLPCTX, 60, 64 button creation, 88 extended keys, 26, 60 BUTTONCREATE, 87 extern "C", 13 BUTTONINPUT, 90 EXTTOASCII, 27 BUTTONSETAVAIL, 89 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- INDEX Page 109/111 ---------------------------------------------------------------------- F ITEMSETAVAIL, 66 F1 (help), 60 F10, 62, 67 K farfree replacement, 24 key_code, 59, 61 farmalloc replacement, 23 KEYBFCTS.H, 26 FCOPY, 29 keycode, 60 FIDONET (author's address), 11 FIELDCREATE, 83 L FIELDGETASW, 85 license, 10 FIELDINPUT, 86 Linker errors, 14 FIELDSETASW, 85 FIELDSETCOLORS, 82 M FILEFCTS.H, 28 manual (true type version), 10 filter, 60 Memory model, 12 FNEWLINE, 28 menu (adding a), 64 FSIZE, 28 menu (hotkey), 64 function's description, 19 menu creation, 64 menu hotkeys, 62 G menu item separator, 66 GET, 59 menu items (offline), 63 GETKEY, 26 menubar, 62 GETMSG, 54 menus, 62 GETSIZE, 48 mouse driver, 56 gettextinfo replacement, 31 mouse support during input, 59 global output messages, 17 mouse's cursor, 56, 57, 58 mouse's left button, 58 H mouse's position, 58 header files compile error, 18 mouse's right button, 60 HEAPALLOC, 23 MOUSE_HIDE, 58 HEAPFREE, 24, 25 MOUSE_INIT, 56 help, 59 MOUSE_LB_DOWN, 58 help file (see appendix C), 60 MOUSE_POS, 58 Help text format, 77 MOUSE_SHOW, 57 history, 9 MOUSE_STATUS, 57 hotkey, 64 msg_, 17 msg_stderr, 22 I msg_stderr[], 22 input, 56 input facilities, 59 N input field creation, 83 name prefix, 19 input fields colors, 82 new, 46 input_info, 59, 62 new line character, 28 input_info structure, 59 instantiation, 46 O INTERNET (Author's address), 11 OPEN, 51 interrupt clock, 49 optimization, 19 item's availabitity, 66 overhead, 19 item's context number, 66 items (menu), 65 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- INDEX Page 110/111 ---------------------------------------------------------------------- P stricmp replacement, 35 Parameter validation, 9 string inversion, 39 PASCAL to C, 37 string normalisation, 38 Prototypes, 19 string to uppercase, 36 pull down menus, 62 strlen replacement, 34 struct cur_info, 32 R struct input_info, 59 redeclaration errors, 13 REFRESH, 52, 55, 67 T registration, 9 tdesktop, 47 Registration fee, 10 TDESKTOP::CLOSE, 51 Remy Gendron (Who is), 11 TDESKTOP::GETSIZE, 48 rules for C++ default arguments, TDESKTOP::OPEN, 51 45 TDESKTOP::REFRESH, 52 TDESKTOP::SETDESKCOLORS, 49 S TDESKTOP::SETTEXTMODE, 47 SCR_CRESTORE, 33 TDESKTOP::SETTEXTURE, 50 SCR_CSAVE, 32 TDESKTOP::SETTITLE, 50 SCR_TEXTATTR, 30 templates, 15 SCR_VRESTORE, 31 Testing (header files), 18 SCR_VSAVE, 31 text file display, 78 screen background texture, 50 text_info, 31 screen functions, 30 THROUGH, 66 SCRFCTS.H, 30 Ticks, 41 sensitive help, 59 TICKTIMER_INSTALL, 41 SETCOLORS, 62 TICKTIMER_READ, 42 SETDESKCOLORS, 49 TICKTIMER_RESET, 41 SETHLPCTX, 63 tilde, 54 SETLEFTCOLORS, 53 TIMEFCTS.H, 41 SETTEXTMODE, 47 tinput, 56 SETTEXTURE, 50 TINPUT::GET, 59 SETTITLE, 50 TINPUT::MOUSE_HIDE, 58 shell to DOS, 51, 52 TINPUT::MOUSE_INIT, 56 shortcuts key, 65 TINPUT::MOUSE_LB_DOWN, 58 size of a file, 28 TINPUT::MOUSE_POS, 58 size_t, 34 TINPUT::MOUSE_SHOW, 57 statusline, 53 TINPUT::MOUSE_STATUS, 57 STR_CENTER, 39 title (desktop), 50 STR_CMP, 35 tmenubar, 62 STR_CPY, 34 TMENUBAR::ADDITEM, 65 STR_ICMP, 35 TMENUBAR::ADDMENU, 64 STR_INVNAMES, 39 TMENUBAR::ITEMSETAVAIL, 66 STR_LEN, 34 TMENUBAR::SETCOLORS, 62 STR_PASTOC, 37 TMENUBAR::SETHLPCTX, 63 STR_TOLOWER, 37 TMENUBAR::THROUGH, 66 STR_TOUPPER, 36 TO_LOWER, 25 STR_TRIM, 38 TO_UPPER, 24, 25 strcmp replacement, 35 tstatusline, 53 strcpy replacement, 34 TSTATUSLINE::DISPLAY, 54 EV 2.0 User's guide TNG SOFT : The Next Generation Software ---------------------------------------------------------------------- INDEX Page 111/111 ---------------------------------------------------------------------- TSTATUSLINE::GETMSG, 54 window's height, 71 TSTATUSLINE::REFRESH, 55 window's help context, 73 TSTATUSLINE::SETLEFTCOLORS, 53 window's internal cursor, 76 TURBO VISION, 8, 12 window's size, 70 twindow, 68 window's title, 72 TWINDOW::BUTTONCREATE, 87 window's width, 71 TWINDOW::BUTTONINPUT, 90 Windows, 68 TWINDOW::BUTTONSETAVAIL, 89 WINGETCOL, 70 TWINDOW::BUTTONSETCOLORS, 87 WINGETROW, 69 TWINDOW::FIELDCREATE, 83 WINGETWIDTH, 71 TWINDOW::FIELDGETASW, 85 WININPUT, 81 TWINDOW::FIELDINPUT, 86 WININSIDE, 81 TWINDOW::FIELDSETASW, 85 WINMOVE, 79 TWINDOW::FIELDSETCOLORS, 82 WINONEDGES, 80 TWINDOW::WINCLEAR, 74 WINOPEN, 73 TWINDOW::WINCLOSE, 74 WINSCROLL, 79 TWINDOW::WINGETHEIGHT, 71 WINSETHLPCTX, 73 TWINDOW::WININPUT, 81 WINSETSIZE, 70 TWINDOW::WININSIDE, 81 WINSETTITLE, 72 TWINDOW::WINMOVE, 79 WINTEXT, 77 TWINDOW::WINONEDGES, 80 WINTEXTFILE, 78 TWINDOW::WINOPEN, 73 WINWRITE, 75 TWINDOW::WINSCROLL, 79 Word wrapping format, 77 TWINDOW::WINSETCOLORS, 71 TWINDOW::WINSETHLPCTX, 73 TWINDOW::WINSETPOS, 69 TWINDOW::WINSETTITLE, 72 TWINDOW::WINTEXT, 77 TWINDOW::WINTEXTFILE, 78 TWINDOW::WINWRITE, 75 U Updates, 10 V Validation, 14 W WAIT FOR, 60 WINCLEAR, 74 WINCLOSE, 74 window alive, 81 window dragging, 81 window features, 68 window moving, 79 window screen output, 75 window scrolling, 76 window word wrapping, 77 window's colors, 71 EV 2.0 User's guide TNG SOFT : The Next Generation Software