Category : C Source Code
Archive : EVISION1.ZIP
Filename : USERDOC.TXT
Output of file : USERDOC.TXT contained in archive : EVISION1.ZIP
ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ ³
³ ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ³
³ ±±ÛÛÛÛÛÛÛÛÛ±±ÛÛÛÛÛÛÛÛÛ±±ÛÛÛÛÛÛÛÛÛ±±ÛÛ±±±±±±ÛÛ±±±±ÚÄÄÄÄÄÄÄÄÄÄÄÄ¿±± ³
³ ±±ÛÛ ±ÛÛ ÛÛ ±ÛÛ ±ÛÛ ±±±±±ÛÛ ±±±³ ³ ± ³
³ ±±ÛÛ ±±±±±±±±ÛÛ ±±±±ÛÛ ±ÛÛ ±±±±±±±±ÛÛ ±±±±±ÛÛ ±±±³ Û ÛßÛ ³ ± ³
³ ±±ÛÛÛÛÛÛÛÛÛ±±ÛÛÛÛÛÛÛÛÛ ±ÛÛÛÛÛÛÛÛÛ±±ÛÛÛÛÛÛÛÛÛÛ ±±±³ Û Ü ÛÜÛ ³ ± ³
³ ±±ÛÛ ±ÛÛ ÛÛ ±± ÛÛ ±± ÛÛ ±±±³ ³ ± ³
³ ±±ÛÛ ±±±±±±±±ÛÛ ±±±±ÛÛ ±±±±±±±±ÛÛ ±±±±±ÛÛ ±±±±±±±ÃÄÄÄÄÄÄÄÄÄÄÄÄ´ ± ³
³ ±±ÛÛÛÛÛÛÛÛÛ±±ÛÛ ±±±±ÛÛ ±ÛÛÛÛÛÛÛÛÛ ±±±±±ÛÛ ±±±±±±±³ User Guide ³ ± ³
³ ±±± ±± ±±±±± ±± ±±±±±± ±±±±±±±ÀÄÄÄÄÄÄÄÄÄÄÄÄÙ ± ³
³ ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ± ³
³ ±±ÛÛ±±±±±ÛÛ±±ÛÛ±±ÛÛÛÛÛÛÛÛÛ±±ÛÛ±±ÛÛÛÛÛÛÛÛÛ±±ÛÛÛÛÛÛÛÛÛ±±±±±±±±±±±±± ³
³ ±±ÛÛ ±±±±ÛÛ ±ÛÛ ±ÛÛ ±ÛÛ ±ÛÛ ÛÛ ±ÛÛ ÛÛ ±±±±±±±±±±±± ³
³ ±±ÛÛ ±±±±ÛÛ ±ÛÛ ±ÛÛ ±±±±±±±±ÛÛ ±ÛÛ ±±±±ÛÛ ±ÛÛ ±±±±ÛÛ ±±±±±±±±±±±± ³
³ ±±ÛÛ ±±±±ÛÛ ±ÛÛ ±ÛÛÛÛÛÛÛÛÛ±±ÛÛ ±ÛÛ ±±±±ÛÛ ±ÛÛ ±±±±ÛÛ ±±±±±±±±±±±± ³
³ ±±ÛÛ ±±±±ÛÛ ±ÛÛ ±± ÛÛ ±ÛÛ ±ÛÛ ±±±±ÛÛ ±ÛÛ ±±±±ÛÛ ±±±±±±±±±±±± ³
³ ±±±ÛÛ ±±ÛÛ ±±ÛÛ ±±±±±±±±ÛÛ ±ÛÛ ±ÛÛ ±±±±ÛÛ ±ÛÛ ±±±±ÛÛ ±±±±±±±±±±±± ³
³ ±±±±ÛÛÛÛÛ ±±±ÛÛ ±ÛÛÛÛÛÛÛÛÛ ±ÛÛ ±ÛÛÛÛÛÛÛÛÛ ±ÛÛ ±±±±ÛÛ ±±±±±±±±±±±± ³
³ ±±±±± ±±±± ±± ±± ±± ±± ±±±±± ±±±±±±±±±±±± ³
³ ±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±±± ³
³ ³
³ The easy to use, reliable and powerful library for a textmode ³
³ based user interface. ³
³ ³
³ 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 with respect to 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. ³
³ ³
³ The original manual and software may be obtained from ³
³ ³
³ STARFLEET COMMAND BBS ³
³ (418) 525-6899/4740/6803 ³
³ FidoNet: 1:240/1701 ³
³ F'req magic name > EVISION ³
³ ³
³ ³
³ ßÛß ÛßÛ Ûßß Ûßß ÛßÛ Ûßß ßÛß ³
³ Û Û Û ÛÜÛ ÜÜÛ ÛÜÛ Ûß Û The Next Generation Software ³
³ ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
EasyVision 1.0 User's Guide Page 2
Chapter 1: Overview ..................................... 7
Why EasyVision .......................... 7
What is EasyVision ...................... 7
Current version ......................... 8
A word about registration ............... 8
What's next ? ........................... 9
Chapter 2: Getting started .............................. 10
Library specifics ....................... 10
Installation ............................ 10
How to use this library ................. 11
How to use this document ................ 11
Chapter 3: Using EasyVision's functions ................. 13
assert .................................. 14
getkey .................................. 15
getheap ................................. 17
freeheap ................................ 17
hstrlen ................................. 18
hstrcpy ................................. 18
savevideo ............................... 19
restorevideo ............................ 19
savecursor .............................. 20
restorecursor ........................... 20
Chapter 4: Using EasyVision's classes ................... 21
Chapter 5: EasyVision's TDesktop class .................. 22
settextmode ............................. 23
setdeskcolors ........................... 23
settexture .............................. 24
settitle ................................ 24
open .................................... 25
close ................................... 25
insert .................................. 26
refresh ................................. 26
Chapter 6: EasyVision's TStatusline class ............... 27
setleftcolors ........................... 28
setrightcolors .......................... 28
displayleft ............................. 29
displayright ............................ 29
refresh ................................. 30
EasyVision 1.0 User's Guide Page 3
Chapter 7: EasyVision's TMenubar class .................. 31
setcolors ............................... 32
sethelp ................................. 33
setslptr ................................ 33
addmenu ................................. 34
additem ................................. 35
trough .................................. 36
itemavail ............................... 36
refresh ................................. 37
Chapter 8: EasyVision's TWindow class ................... 38
wingetscreenheight ...................... 39
wingetscreenwidth ....................... 39
winsetpos ............................... 40
wingetrow ............................... 41
wingetcol ............................... 41
winsetsize .............................. 42
wingetheight ............................ 42
wingetwidth ............................. 42
winsetcolors ............................ 43
winsettitle ............................. 43
winsethelp .............................. 44
winsetslptr ............................. 44
winopen ................................. 45
winclose ................................ 45
winclear ................................ 46
winwrite ................................ 47
winswrite ............................... 49
wintext ................................. 50
wintextfile ............................. 51
winmove ................................. 52
winscroll ............................... 52
wininput ................................ 53
fieldsetlengths ......................... 54
fieldsetcolors .......................... 54
fieldsetftr ............................. 55
fieldsetattrib .......................... 55
fieldcreate ............................. 56
fieldinput .............................. 57
fieldsetasw ............................. 58
fieldgetasw ............................. 58
buttonsetcolors ......................... 59
buttoncreate ............................ 60
buttonpush .............................. 62
buttoninput ............................. 63
buttonsetavail .......................... 64
EasyVision 1.0 User's Guide Page 4
Chapter 9: EasyVision's Demo Program .................... 65
The demo program ........................ 65
Chapter 10: Things you should not do ..................... 66
Appendix A: Extended keycodes ............................ 67
Appendix B: Color codes and Symbolic constants ........... 68
Appendix C: Trademarks ................................... 69
Appendix D: Common Questions and Answers ................. 70
EasyVision 1.0 User's Guide Page 5
This page intentionally left blank
EasyVision 1.0 User's Guide Page 6
This page intentionally left blank
EasyVision 1.0 User's Guide Page 7
ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
C H A P T E R 1 Overview
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
Welcome to EasyVision 1.0 ! This C++ library provides an easy to
use, reliable and powerful textmode based user interface.
Why EasyVision ?
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
After looking at some shareware and commercial user interface
packages, and reading comments about them from a lot of C and C++
programmers, it was clear that something was missing. 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
user interface in existence. It is so well implemented and
thought out that it is the standard in textmode interfaces that
everyone is following, including EasyVison ! (Hope they don't
sue me...) But, it is so big that it is a language in itself,
and that is 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 to big.
I'm thinking about CXL right now. Others are to small and to
unreliable to develop serious software.
So, what's a C++ programmer 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 textmode based, windowed user interface. It
provides a DESKTOP, a STATUSLINE, a MENUBAR, WINDOWS, CONTEXT
SENSITIVE ONLINE HELP, and much much more...
EasyVision was created with 2 important priorities.
EasyVision 1.0 User's Guide Page 8
First, it should be EASY to learn and EASY to use. Provide only
the big, important functions to the user. A user doesn't need a
library function if he can write it himself in less than 25 lines
of code. But make sure that those big functions are REALLY
powerful and produce professional looking results ! This library
hasn't been written to provide every fonctions needed to
developpe full featured word processors or the likes. It is
there to give you a strong and reliable skeleton for your
programs. It is up to you to come up with the 'meat'.
Second, 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 good will of the
programmer to check out is code for out of range or
non-initialised parameters.
That was what EasyVision was suppose to be. Well, EasyVision is
still better than that ! At this point, if you haven't already
done so, you should run the demonstation program 'EVISION.EXE' to
see the results of about 200 lines of C++ codes that uses the
EasyVision library...
If you find the results interesting, it is up to you to go on.
All functions and classes are FULLY documented in the following
pages. The source code of the demonstration program is 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 1.0 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 absolutly no
differences between the registered or unregistered version.
EasyVision 1.0 User's Guide Page 9
To register this software, fill in the REGISTER.TXT registration
form included in the archive. Registration is $25 CANADIAN. You
will receive via 'snail mail' an official registered user
certificate with your registration number. For $35 CANADIAN,
you'll also receive a bonded printed copy of the latest version
of this manual.
EasyVision and TNG SOFT ENTERPRISES are registered trade marks.
What's Next ?
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
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. Remember though, that I will never include
functions that are not directly related to the user interface.
I will try to improve the functions and classes already there.
I'd like to add an integrator for the windows, allowing
background windows to be brought in the foreground, a window
refresh function, better text output facilities and mouse
support.
So, that's about it for now ! Have fun and enjoy !
Rmy Gendron
author of EasyVision
EasyVision 1.0 User's Guide Page 10
ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
C H A P T E R 2 Getting started
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
Installing and using the EasyVision library is very simple.
Library specifics
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
EasyVision was developped under TURBO C++ 1.01, then later
transfered to BORLAND C++ 3.0.
The code was compiled under the HUGE memory model. All
prototypes were declared as FAR functions and all pointers were
explicitely declared HUGE. This will provide full compatibility
when linking to any memory model size.
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 are not normalised. All EasyVision's
functions use huge pointers.
The video output is done through direct screen writes. This
makes for incredibly fast output. Going through the BIOS is just
to slow. However, under multitaskers like Deskview, who often
work in textmode, screen bleeds can occur if the application is
running in the background. Use the virtualising options when
running under DeskView.
All EasyVision's 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.
Installation
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
Unpack the archive in a temporary directory. If you haven't done
so, you should really print all of the USER'S GUIDE for easier
reading. It as been formatted to print at 60 lines per pages.
Put all header files (.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.
EasyVision 1.0 User's Guide Page 11
How to use this library
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
To use an EasyVision function or class, just include its header
file in your source code. YOU MUST NOT write a prototype
yourself based on the prototype written in this manual. The real
prototypes have additional informations in them. So, for
example:
#include
#include "getkey.hpp" // An EasyVision header file
void main ()
{
...
// Here you can use the 'getkey' function
...
return ;
}
You then have to link all your modules together, including the
EVISION.LIB library. You do that by including EVISION.LIB in
your project. EVISION.LIB must be in one of your LIBRARY
directories. That's all there is to it !
If you get linker errors, that's probably because you compiled
your sources in C ANSI. You must compile in C++, or else make
interfaces with the 'extern C' keyword.
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
EasyVision error message. Your program will not crash !
See the chapter THINGS YOU SHOULD NOT DO for hints on things to
watch out for.
How to use this document
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
The following conventions are used in the document:
All of EasyVision's functions were declared of type
far, but the far modifier was left out of the
prototypes in this manual.
EasyVision 1.0 User's Guide Page 12
The following symbols were used in the text:
'' Regular C and C++ keywords
{} EasyVision keywords
<> Arguments to functions
[] Optional arguments are enclosed in brakets
--> Important remarks (that you MUST read)
CAPS Keyboard keys
Chapter 3 describes all EasyVision's functions. Chapter 4
introduces you to the basics of using a class object. Then
chapters 5 to 8 describe the 4 EasyVision's classes.
At the end, reference informations can be found in appendixes.
I will gladly answer any questions. I WILL NOT ANSWER THROUGH
NETMAIL. YOU MUST REACH ME VIA THE C++ FIDONET ECHOMAIL
CONFERENCE. I think that most questions can be answered by
looking at the included demo program (DEMO.CPP).
EasyVision 1.0 User's Guide Page 13
ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
C H A P T E R 3 Using EasyVision's Functions
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
This version of the EasyVision library has 10 functions. They
provide for parameter validations, fatal errors handling,
keyboard inputs, automatic F1 online help. Also, some frequently
used functions have been rewritten to accept huge parameters
without the need for typecasting. All these functions are fully
described in the following pages.
A function description uses the following format:
FUNCTION NAME
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Short description of this function behavior.
þ Syntax #include "header.h"
ReturnType FonctionName (, , ...) ;
YOU MUST NEVER WRITE A PROTOTYPE FOR A FUNCTION
YOURSELF. ALWAYS USE THE PROPER HEADER FILES. THEY
HAVE ADDITIONAL INFORMATIONS IN THEM !
--> When parameters are in brakets ([]), they are optional.
IF YOU WANT TO INCLUDE AN OPTIONAL PARAMETER, ALL
PARAMETERS BEFORE THAT ONE MUST BE INCLUDED AS WELL.
þ Remarks Parameters and usage are described here when needed.
þ Return The returned value of the function is explained here.
þ Example Examples of various calls to this function.
So, here are the EasyVision's functions...
EasyVision 1.0 User's Guide Page 14
ASSERT
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary This function will ASSERTain that a
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, print an error message, and terminate the
program with a call to 'exit'. This closes all open
files, releases any memory allocated on the heap and
exit to DOS with an ERROR LEVEL of 1.
þ Syntax #include "assert.hpp"
void assert (int condition [,char huge *fctname, int
errorcode, char huge *errortext]) ;
þ Remarks If
terminated and
will be displayed. This will help find the location of
the error. You can specify an error code. If 0, you
must provide an error message with the parameter
In this case, you don't need to specify an error
message.
1: "Not enough memory to instantiate a class 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."
þ Return None
þ Example assert (nbrecord>0,"datasearch",0,"Database empty !") ;
EasyVision 1.0 User's Guide Page 15
GETKEY
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary This is a replacement for the familiar 'getch'
function.
þ Syntax #include "getkey.hpp"
int getkey (int filter [,char *helptext]) ;
þ Remarks One of 'getch' weakness is its inability to deal with
the way extended keys are internaly represented. Those
are the keys that don't have an ASCII code associated
with them. For exemple, 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 key code.
Appendix A lists all of the extended keycodes currently
available on an extended keyboard.
You MUST specify a
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 key code (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.
--> When you call {getkey}, it will first flush the
keyboard buffer of any keys already present. When
waiting for a key, if the F1 key is pressed, an help
window will pop up automatically ! You can optionaly
give {getkey} a pointer to some context sensitive
that no help is available at this time, and the help
window pops up saying so. This help window will take
care of itself. You don't have to worry about screen
coordinates, colors, key input or anything.
The help text is an array of chars, that need not be
formated in any way. The help window will read the
array and display it with word wrapping at the end of
the lines. It can also be of any length. If the text
cannot fit in one window, a more prompt will be
showned. At any time, the user can leave help with the
ESC key.
EasyVision 1.0 User's Guide Page 16
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 you text by surrounding characters
with the tilde (~) character.
--> If the F1 key is pressed, the help window is showned
and closed, then the function waits for another key.
F1 will never be returned by that function ! If a
help window. Beware of NEVER setting the filter to an
impossible key entry or to the F1 keycode (315), 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 key code plus 256.
(256-396)
þ Example getkey (0) ; // Returns the first key pressed
// No help is available
getkey (13,edithelp) ; // Wait for the ENTER key
// With help available
EasyVision 1.0 User's Guide Page 17
GETHEAP
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Getheap replaces 'farmalloc'.
þ Syntax #include "farheap.hpp"
char huge *getheap (unsigned long nbytes) ;
þ Remarks Allocates
þ Return In C++ you cannot assign a void pointer to a typed
pointer without a typecast. As you will most often
want a huge pointer to char, this is what this function
returns. If you want to assign this pointer to a
pointer to a different type, just use a typecast.
þ Example char huge *ptr1 ;
int huge *ptr2 ;
ptr1 = getheap (1024) ;
ptr2 = (int huge*) getheap (100) ;
FREEHEAP
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Freeheap replaces 'farfree'.
þ Syntax #include "farheap.hpp"
void freeheap (void huge *heapptr) ;
þ Remarks The only difference from 'farfree' is that this
function offers the convenience of accepting a huge
pointer as argument.
þ Return None
þ Example char huge *ptr ;
ptr = getheap (sizeof (object)) ; // Allocate memory
freeheap (ptr) ; // Free memory
ptr = NULL ; // Always a good idea
EasyVision 1.0 User's Guide Page 18
HSTRLEN
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary This is a huge version of 'strlen'. It returns the
length of a string.
þ Syntax #include "hugefcts.hpp"
size_t hstrlen (char huge *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
þ Example length = hstrlen (text) ;
HSTRCPY
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary This is a huge version of 'strcpy'. It copies a string
into another.
þ Syntax #include "hugefcts.hpp"
char huge *hstrcpy (char huge *dest, char huge *src) ;
þ 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 = getheap (20) ;
hstrcpy (string,"Hello there !") ;
EasyVision 1.0 User's Guide Page 19
SAVEVIDEO
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary This will save the current screen 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 "screen.hpp"
void savevideo (text_info huge *ti[, char huge*huge
*savedscr]) ;
þ Remarks All members of the text_info structure
with this function.
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.
þ Return None
þ Example text_info ti ;
char huge *scrbfr ;
savevideo (&ti,&scrbfr) ;
RESTOREVIDEO
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ 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 {savevideo}.
þ Syntax #include "screen.hpp"
void restorevideo (text_info huge *ti[, char huge*huge
*savedscr]) ;
þ Remarks The text_info structure must have been previously
filled with {savevideo}. The same is true for the
previous screen content.
þ Return None
þ Example restorevideo (&ti,&scrbfr) ;
EasyVision 1.0 User's Guide Page 20
SAVECURSOR
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary This function will save all cursor attributes,
INCLUDING THE CURSOR TYPE, in a {cur_info} structure.
Those attributes are: colors, x pos, y pos and
cursorshape. It will not save the other screen
attributes, and is therefore faster than {savevideo}.
þ Syntax #include "screen.hpp"
void savecursor (cur_info huge *ci) ;
þ Remarks The cur_info structure is as follow, and is defined in
"screen.hpp".
struct cur_info
{
unsigned char attribute ; // Cursor colors
unsigned char curx ; // Cursor X position
unsigned char cury ; // Cursor Y position
unsigned int curtype ; // Cursor type
} ;
þ Return None
þ Example cur_info ci ;
savecursor (&ci) ;
RESTORECURSOR
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary This function will restore all cursor attributes,
INCLUDING THE CURSOR TYPE, from a cur_info structure.
þ Syntax #include "screen.hpp"
void restorecursor (cur_info huge *ci) ;
þ Remarks The cursor attributes must have been previously saved
with {savecursor}.
þ Return None
þ Example cur_info ci ;
savecursor (&ci) ;
...
restorecursor (&ci) ;
EasyVision 1.0 User's Guide Page 21
ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
C H A P T E R 4 Using EasyVision's Classes
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
The EasyVision library has 4 classes. They provide a desktop, a
statusline, a menubar and windows. Those classes are fully
described in the following pages.
A classe 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 in the following
format:
MEMBER FUNCTION NAME
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Short description of this function behavior.
þ Syntax #include "header.h"
ReturnType FonctionName (, , ...) ;
YOU MUST NEVER WRITE A PROTOTYPE FOR A FUNCTION
YOURSELF. ALWAYS USE THE PROPER HEADER FILES. THEY
HAVE ADDITIONAL INFORMATIONS IN THEM !
--> When parameters are in brakets ([]), they are optional.
IF YOU WANT TO INCLUDE AN OPTIONAL PARAMETER, ALL
PARAMETERS BEFORE THAT ONE MUST BE INCLUDED AS WELL.
þ Remarks Parameters and usage are described here when needed.
þ Return The returned value of the function is explained here.
þ Example Examples of various calls to this function.
Using classes is quite easy ! First you declare a pointer to
this class. Then you instantiate (create) an object of this
class 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'.
Many examples are available in the source code of the EasyVision
demo program (DEMO.CPP).
EasyVision 1.0 User's Guide Page 22
ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
C H A P T E R 5 EasyVision's TDESKTOP class
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
The {tdesktop} class is the first one to be instantiated in a
program that uses the EasyVision user interface.
This class will save the current screen, initialise the video
screen to the video mode of your choice, and display the desktop.
The desktop is the background on which the menubar, the
statusline and your windows will be displayed. 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.
The {tdesktop} class as 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.
The {tdesktop} class can be used alone by itself. That is, it
can be the only class you will use in your application.
On the following pages, you will find each of tdesktop's member
functions.
An example of instantiating a {tdesktop} object is given in the
source code of the EasyVision's demo program (DEMO.CPP).
EasyVision 1.0 User's Guide Page 23
TDESKTOP::SETTEXTMODE
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the textmode in which {open} will draw the
desktop. This has no effect on the current textmode.
It will only take effect when {open} will be called.
The {refresh} function uses the current textmode. This
call is optional. If it is not made before a call to
{open}, textmode C80 (3) is assumed.
þ Syntax #include "tdesktop.hpp"
void settextmode (int mode) ;
þ Remarks Symbolic constant | 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,
included.
þ Return None
þ Example desktop->settextmode (C80) ;
TDESKTOP::SETDESKCOLORS
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the colors in which {open} or {refresh} will draw
the desktop.
þ Syntax #include "tdesktop.hpp"
void setdeskcolors (int back, int fore) ;
þ 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.
See appendix B for a list of available colors, color
codes and symbolic constants.
þ Return None
þ Example desktop->setdeskcolors (RED,LIGHTGRAY) ;
EasyVision 1.0 User's Guide Page 24
TDESKTOP::SETTEXTURE
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the character with which {open} or {refresh} will
draw the desktop.
þ Syntax #include "tdesktop.hpp"
void settexture (char asciicode) ;
þ Remarks You must provide the character used to draw the
desktop, in the form of its ASCII code. Only ASCII
code 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}, '°' 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 settitle (char huge *text[, int back, int fore]) ;
þ Remarks The colors for the title 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. 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, use ""
as argument. You can give a
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 1.0",RED,BLACK) ;
EasyVision 1.0 User's Guide Page 25
TDESKTOP::OPEN
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Opens the desktop.
þ Syntax #include "tdesktop.hpp"
void open () ;
þ 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.
þ Syntax #include "tdesktop.hpp"
void close () ;
þ Remarks This will restore the video screen as it were 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 () ;
EasyVision 1.0 User's Guide Page 26
TDESKTOP::INSERT
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Insert a {tstatusline} or {tmenubar} object into the
desktop.
þ Syntax #include "tdesktop.hpp"
void insert (tstatusline huge *sl) ;
void insert (tmenubar huge *mb) ;
þ Remarks The desktop has a {refresh} function that will redraw
the screen. Initialy, it will only redraw the desktop.
If you want it to be able to redraw the statusline and
menubar, you must {insert} them into the desktop.
This function is overloaded. You use the same function
to insert the statusline or the menubar.
--> You cannot insert more than one object of the same type
in the desktop, or the previous one will be lost.
þ Return None
þ Example desktop->insert (statusline) ;
DESKTOP::REFRESH
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary The desktop has a {refresh} function that will redraw
the screen. Using this function can be DANGEROUS...
þ Syntax #include "tdesktop.hpp"
void refresh () ;
þ Remarks If you want it to be able to redraw the statusline and
menubar, you must first {insert} them into the desktop.
--> 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 1.0, WINDOWS CANNOT BE REFRESHED. YOU
MUST MAKE ABSOLUTELY CERTAIN THAT THIS FUNCTION CANNOT
BE CALLED WHEN WINDOWS ARE OPENED, OR YOU WILL BE IN
BIG TROUBLE.
þ Return None
þ Example desktop->refresh () ;
EasyVision 1.0 User's Guide Page 27
ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
C H A P T E R 6 EasyVision's TSTATUSLINE class
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
The {tstatusline} class provides a standard statusline on the
last line of the screen. It is divided into 2 areas, each one
completely independent.
The left area is 10 spaces wide, including the dividing character
'|'. You have 8 spaces to display a message in this area. The
suggested message for this area is '~F1~ Help'. The right area
occupies the remainder of the line.
The {tstatusline} class as built in default values. The
statusline will autosize itself to the screen. However, if you
would like to change those default beheviors, other functions
will allow you to do so.
The {tstatusline} class can be used alone by itself. That is, it
can be the only class you will use in your application.
On the following pages, you will find each of the tstatusline's
member functions.
Examples of instantiating a {tstatusline} object are given in the
source code of the EasyVision's demo program (DEMO.CPP).
EasyVision 1.0 User's Guide Page 28
TSTATUSLINE::SETLEFTCOLORS
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the background, foreground and highlight colors
used by the {displayleft} function, when writing to the
left statusline.
þ Syntax #include "tstatusline.hpp"
void setleftcolors (int back[, int fore, int high]) ;
þ Remarks
provided,
You can use color macros if
Appendix B gives a descrition of available color codes
and macros.
þ Return None
þ Example statusline->setleftcolors (LIGHTGRAY,BLACK,RED) ;
TSTATUSLINE::SETRIGHTCOLORS
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the background, foreground and highlight colors
used by the {displayright} function, when writing to
the right statusline.
þ Syntax #include "tstatusline.hpp"
void setrightcolors (int back[, int fore, int high]) ;
þ Remarks
provided,
You can use color macros if
Appendix B gives a descrition of available color codes
and macros.
þ Return None
þ Example statusline->setrightcolors (LIGHTGRAY,BLACK,RED) ;
EasyVision 1.0 User's Guide Page 29
TSTATUSLINE::DISPLAYLEFT
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Displays a message on the statusline, in the left area.
þ Syntax #include "tstatusline.hpp"
void displayleft ([char huge *text]) ;
þ Remarks The
including the '~' characters. If the message is too
long to fit in the area, only the first 8 characters
will be displayed. 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
parameter.
þ Return None
þ Example statusline->displayleft ("~F1~ Help") ; // Display text
statusline->displayleft () ; // Clear left statusline
TSTATUSLINE::DISPLAYRIGHT
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Displays a message on the statusline, in the right
area.
þ Syntax #include "tstatusline.hpp"
void displayright ([char huge *text]) ;
þ Remarks The
including the '~' characters. If the message is too
long to fit in the area, only the first 'n-2'
characters will be displayed, assuming the right area
is n characters wide. 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
parameter.
þ Return None
þ Example statusline->displayright ("This is ~EasyVision~ !") ;
statusline->displayright () ; // Clear right area
EasyVision 1.0 User's Guide Page 30
TSTATUSLINE::REFRESH
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary The statusline object has a {refresh} function that
will redraw it on the screen.
þ Syntax #include "tstatusline.hpp"
void refresh () ;
þ Remarks It will redraw the statusline and redisplay the last
message.
--> The refresh function will use the current values for
colors. This means that you can change the statusline
colors and then, {refresh} it with the new colors.
þ Return None
þ Example statusline->refresh () ;
EasyVision 1.0 User's Guide Page 31
ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
C H A P T E R 7 EasyVision's TMENUBAR class
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
The {tmenubar} class provides a menubar on the first line of the
screen, with pull down menus and scrolling selection cursor. It
also activates an interrupt driven clock displayed at the end of
the menubar.
A menubar acts as a filter. You make the user inputs go 'trough'
the menubar. If the input is the F10 key, or an ALT-key
corresponding to a menu hotkey, the menubar is activated. If
not, 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.
The {tmenubar} class as built in default values. The menubar
will autosize itself to the screen. However, if you would like
to change those default beheviors, functions will allow you to do
so.
The {tmenubar} class can be used alone by itself. That is, it
can be the only class you will use in your application.
YOU SHOULD NEVER INSTANTIATE MORE THAN ONE MENUBAR. RESULTS
COULD BE DANGEROUS.
On the following pages, you will find each of {tmenubar}'s member
functions.
Examples of instantiating and using a {tmenubar} object are given
in the source code of the EasyVision's demo program (DEMO.CPP).
EasyVision 1.0 User's Guide Page 32
TMENUBAR::SETCOLORS
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the background, foreground, highlight, cursor and
clock colors used by the {tmenubar} object.
þ Syntax #include "tmenubar.hpp"
void setcolors ([int back, int fore, int high, int
cursor, int clockback, int clockfore]) ;
þ Remarks All arguments are optional. If they are not provided,
they will default to the following values:
back = LIGHTGRAY
fore = BLACK
high = RED
cursor = GREEN
clockback = RED
clockfore = WHITE
You can use color macros if
Appendix B gives a descrition 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 allready selected colors.
þ Return None
þ Example menubar->setcolors (BLUE,WHITE,RED,MAGENTA) ;
EasyVision 1.0 User's Guide Page 33
TMENUBAR::SETHELP
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the pointer to some help text that will be
displayed when F1 is pressed while in the menubar.
þ Syntax #include "tmenubar.hpp"
void sethelp (char huge *helptext) ;
þ Remarks The help text format is explained in the {getkey}
function description.
þ Return None
þ Example menubar->sethelp (menuhelp) ;
TMENUBAR::SETSLPTR
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the pointer to the statusline.
þ Syntax #include "tmenubar.hpp"
void setslptr (tstatusline huge *slptr) ;
þ Remarks When you create menus and menu items, you can optionaly
give them a short help text that will be displayed on
the statusline when the menu cursor is on them. You
therefore need to tell the menubar where is the
statusline object. This is optional. If this pointer
is not set, the statusline help texts will not be
displayed.
þ Return None
þ Example menubar->setslptr (statusline) ;
EasyVision 1.0 User's Guide Page 34
TMENUBAR::ADDMENU
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Adds a menu on the menubar.
þ Syntax #include "tmenubar.hpp"
void addmenu (char huge *name, int hotkey[, char huge
*sltext]) ;
þ Remarks
menubar. The first 2 characters of the
menubar are left blank, and the 10 lasts are
reserved for the menubar clock. 2 spaces
will be inserted between each menu.
If the letter is present in the menu name, it
will be highlighted.
displayed on the statusline when this menu is
selected. It can be of any length.
{setslptr} must have been previously called.
þ Return None
þ Example menubar->addmenu ("Files",'F',"Create, open files") ;
EasyVision 1.0 User's Guide Page 35
TMENUBAR::ADDITEM
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Adds an item in the last created menu.
þ Syntax #include "tmenubar.hpp"
void additem ([char huge *text, int hotkey, int
returnval, char huge *sltext]) ;
þ Remarks
entry. It can be of any length. The menu
will autosize itself to accomadate the widest
item.
If the letter is present in the item text, it
will be highlighted.
will be change to this value.
displayed on the statusline when this item is
selected. It can be of any length.
{setslptr} must have been previously called.
--> If {additem} is called with no arguments, it will
insert a separator in the menu.
þ Return None
þ Example menubar->additem ("Open F3",'O',317,"Open file") ;
EasyVision 1.0 User's Guide Page 36
TMENUBAR::TROUGH
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Makes an input go trough the menubar.
þ Syntax #include "tmenubar.hpp"
int trough (int key) ;
þ Remarks If
are opened. If
opened.
þ Return If
the user enters ESC, {trough} returns with 0.
Otherwise it returns with the return value of the menu
item selected.
þ Example int inchar ;
inchar = menubar->trough (getkey (0)) ;
TMENUBAR::ITEMSETAVAIL
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets availability of a menu item to TRUE or FALSE.
þ Syntax #include "tmenubar.hpp"
void itemsetavail (int menuhotkey, int itemhotkey, int
state) ;
þ Remarks You must provide the
the item exist, and the
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) ;
EasyVision 1.0 User's Guide Page 37
TMENUBAR::REFRESH
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary The menubar object has a {refresh} function that will
redraw it on the screen.
þ Syntax #include "tmenubar.hpp"
void refresh () ;
þ Remarks None
þ Return None
þ Example menubar->refresh () ;
EasyVision 1.0 User's Guide Page 38
ÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛÛ
ÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜÜ
C H A P T E R 8 EasyVision's TWINDOW class
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
The {twindow} class provides powerful window functions to your
programs. A window is where all your program's screen
inputs/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 this and many more features.
The {twindow} class as built in default values. However, if you
would like to change those default beheviors, functions will
allow you to do so.
The {twindow} class can be used alone by itself. That is, it can
be the only class you will use in your application.
--> You can open simultanously 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, you should NEVER close a window
if another window covers part of it. Always close the
ones that are in the foreground first.
--> You must NEVER work with a window that is under another
one. If you do so, the integrity of the desktop will
be compromised.
On the following pages, you will find each of {twindow}'s member
functions.
Examples of instantiating and using a {twindow} object are given
in the source code of the EasyVision's demo program (DEMO.CPP).
EasyVision 1.0 User's Guide Page 39
TWINDOW::WINGETSCREENHEIGHT
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Returns the video screen height in lines.
þ Syntax #include "twindow.hpp"
int wingetscreenheight () ;
þ Remarks This could be needed if you wanted to center a window.
þ Return An 'int', the height of the screen.
þ Example lines = window->wingetscreenheight () ;
TWINDOW::WINGETSCREENWIDTH
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Returns the video screen width in columns.
þ Syntax #include "twindow.hpp"
int wingetscreenwidth () ;
þ Remarks This could be needed if you wanted to center a window.
þ Return An 'int', the width of the screen.
þ Example Cols = window->wingetscreenwidth () ;
EasyVision 1.0 User's Guide Page 40
TWINDOW::WINSETPOS
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the position of the window on the desktop.
þ Syntax #include "twindow.hpp"
void winsetpos (int row, int col) ;
þ Remarks
BE OPENED. 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 valide window position.
--> If you set the size of the window before setting its
position, this size will be taken into account to
calculate the valide range of the
arguments.
--> You CANNOT use this function once the window has been
opened. Use the {winmove} function instead.
þ Return None
þ Example window->winsetpos (10,12) ; // Topleft corner at 10,12
EasyVision 1.0 User's Guide Page 41
TWINDOW::WINGETROW
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Returns the window row position of its topleft corner.
þ Syntax #include "twindow.hpp"
int wingetrow () ;
þ Remarks The top left corner of the screen is (1,1).
þ Return Row position of window.
þ Example row = window->wingetrow () ;
TWINDOW::WINGETCOL
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Returns the window column position, topleft corner.
þ Syntax #include "twindow.hpp"
int wingetcol () ;
þ Remarks The top left corner of the screen is (1,1).
þ Return Column position of window.
þ Example col = window->wingetcol () ;
EasyVision 1.0 User's Guide Page 42
TWINDOW::WINSETSIZE
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the size of the window.
þ Syntax #include "twindow.hpp"
void winsetsize (int height, int width) ;
þ Remarks
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.
Therefore, this function will validate the asked size
and change it to get a valide window size.
--> You CANNOT change the size of a window once it has been
opened.
þ Return None
þ Example window->winsetsize (10,60) ; // 10 rows by 60 cols
TWINDOW::WINGETHEIGHT
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Returns the window's height in lines.
þ Syntax #include "twindow.hpp"
int wingetheight () ;
þ Remarks The top and bottom frames are included in the height.
þ Return An 'int', the height of the window.
þ Example heigth = window->wingetheight () ;
TWINDOW::WINGETWIDTH
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Returns the window's width in columns.
þ Syntax #include "twindow.hpp"
int wingetwidth () ;
þ Remarks The left and right frames are included in the width.
þ Return An 'int', the width of the window.
þ Example width = window->wingetwidth () ;
EasyVision 1.0 User's Guide Page 43
TWINDOW::WINSETCOLORS
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the background and foreground colors of a window.
þ Syntax #include "twindow.hpp"
void winsetcolors ([int back, int fore]) ;
þ Remarks These are the colors used to draw the window. Those
colors will be used by other functions when the color
arguments are optional.
optional, and will default to LIGHTGRAY and WHITE
respectively.
--> You CANNOT change the default colors of a window once
it has been opened.
þ Return None
þ Example window->winsetcolors (BLUE,WHITE) ;
TWINDOW::WINSETTITLE
ßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßßß
þ Summary Sets the title displayed on the top frame of a window.
þ Syntax #include "twindow.hpp"
void winsettitle (char huge *title) ;
þ Remarks