


       Ŀ
                                                                            
           
         ۱۱۱۱۱Ŀ  
                                                
                          
         ۱ ۱           
                                                     
              Ĵ   
         ۱     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 <stdio.h>                      // A standard header file
          #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 (<param>, <param>, ...) ;

                    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  <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, 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  <condition> evaluates to FALSE, the program will be
                    terminated  and  <fctname>, the  current  function name
                    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
                    <errortext>.   You can also use predefined error codes.
                    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 <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 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
                    <helptext>.   If no pointer  is supplied, it is assumed
                    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
                    <filter>  is provided, the F1  key will still bring the
                    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 <nbytes> bytes on the far heap.

           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 <stdio.h> as an unsigned int.

           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 <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.

           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 (<param>, <param>, ...) ;

                    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,  <conio.h>  must  be
                    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  <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 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 <fore>  and  <high>  are  optional.   If  they  are not
                    provided,  <fore> defaults to BLACK, and <high> to RED.
                    You  can  use color  macros  if <conio.h>  is included.
                    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 <fore>  and  <high>  are  optional.   If  they  are not
                    provided,  <fore> defaults to BLACK, and <high> to RED.
                    You  can  use color  macros  if <conio.h>  is included.
                    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  <text> argument can point to  a msg of any length,
                    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  <text> argument can point to  a msg of any length,
                    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 <conio.h>  is included.
                    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 <name>  : It  can be of any length, but must fit on the
                              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.

                    <hotkey>: It  must be a letter (A-Z), case insensitive.
                              If the letter is present in the menu name, it
                              will be highlighted.

                    <sltext>: This  is  a  short  help  text  that  will be
                              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 <text>  : This  is  the  text displayed  for  this menu
                              entry.   It can  be of any  length.  The menu
                              will autosize itself to accomadate the widest
                              item.

                    <hotkey>: It  must be a letter (A-Z), case insensitive.
                              If the letter is present in the item text, it
                              will be highlighted.

                    <returnval>:  If this item is  selected, the user input
                              will be change to this value.

                    <sltext>: This  is  a  short  help  text  that  will be
                              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 <key> is F10, the menubar is activated, but no menus
                    are  opened.  If  <key> is a menu  hotkey, this menu is
                    opened.

           Return  If  <key> is not F10 or a menu hotkey, {trough} returns
                    <key>  unchanged.  If the menubar is activated, then 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 <menuhotkey> of the menu in which
                    the  item  exist,  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) ;












          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 <row> and <col> are the topleft corner of the window TO
                    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  <row>  and <col>
                    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 <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.
                    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.     <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.

           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 <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 CANNOT set a title after a window has been opened.

           Return  None

           Example window->winsettitle ("User's file") ;














          EasyVision 1.0           User's Guide                     Page 44




          TWINDOW::WINSETHELP
          

           Summary Sets a pointer to some context sensitive help text that
                    will  be displayed if the F1  help key is pressed while
                    in this window.

           Syntax  #include "twindow.hpp"
                    void winsethelp (char huge *ptrtohelp) ;

            Remarks  The  format of  the  help  text is  described  in the
                    {getkey} function.

           Return  None

           Example window->winsethelp (inputhelp) ;


          TWINDOW::WINSETSLPTR
          

           Summary Sets a pointer to an instantiated {tstatusline} object.

           Syntax  #include "twindow.hpp"
                    void winsetslptr (tstatusline huge *slptr) ;

            Remarks Input fields  and buttons in  a window can  be given a
                    short   help  text  that  will   be  displayed  on  the
                    statusline  when  they are  selected.   To  enable this
                    function,  you  must  give  the window  a  ptr  to your
                    statusline.

           Return  None

           Example window->winsetslptr (statusline) ;



















          EasyVision 1.0           User's Guide                     Page 45




          TWINDOW::WINOPEN
          

           Summary Opens a window.

           Syntax  #include "twindow.hpp"
                    void winopen () ;

            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 window->winopen () ;


          TWINDOW::WINCLOSE
          

           Summary Closes a window.

           Syntax  #include "twindow.hpp"
                    void winclose () ;

            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 responsability !
                    EasyVision  doesn't know your window layer position and
                    won't tell you if something goes wrong.

           Return  None

           Example window->winclose () ;




          EasyVision 1.0           User's Guide                     Page 46




          TWINDOW::WINCLEAR
          

           Summary Clears part or all the window content.

           Syntax  #include "twindow.hpp"
                    void  winclear  ([int  left, int  top,  int  right, int
                    bottom]) ;

            Remarks The window must be opened  to call this function.  All
                    arguments  are validated  and if  incorrect, changed to
                    fall within valide window coordinates.

                    All arguments are optional, and will default to:

                    left = 1 , top = 1,
                    right = rightmost column, bottom = bottom line.

                    So,  calling this function with no arguments will clear
                    the entire window.

               -->  Beware  that this function will also clear static text,
                    buttons  and input fields,  BUT NOT REMOVE  THEM.  This
                    will make them invisible, until you use them again.  It
                    is  your responsability  to make  sure you  don't erase
                    them !

           Return  None

           Example window->winclear (1,1,999,3) ;  // Erases first 3 lines
























          EasyVision 1.0           User's Guide                     Page 47




          TWINDOW::WINWRITE
          

           Summary Writes text to the window.  Many options are available.

           Syntax  #include "twindow.hpp"
                    void  winwrite (char huge *text[, int row, int col, int
                    format, int fore, int back]) ;

            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.

                              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 'WSAME',
                              {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 STATIC TEXT, BUTTONS
                              OR  INPUT FIELDS.   THEY WILL  BE SCROLLED UP
                              ALSO  AND THE WINDOW 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.




          EasyVision 1.0           User's Guide                     Page 48





                    <col>   : Column  where text will start.  This argument
                              is  optional.  If it is  not given, or if you
                              use the macro 'WSAME', it will default to 1.

                    <format>: Determines how the text string is justify.

                              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.   It it is not given, or if you use
                              the  macro  'WSAME', it  will default  to the
                              window foreground color.

                    <back>  : Background  color  used.    This  argument is
                              optional.   If it is not given, or if you use
                              the  macro  'WSAME', it  will default  to the
                              window background color.

           Return  None

           Example // Writes to current line, left justified, current
                    // window colors, and move cursor to next line

                    window->winwrite ("Hello") ;

                    // Writes to current line, centered, current window
                    // colors, and move cursor to next line.  Even if
                    // <col> is 1, it has no effect.

                    window->winwrite ("Hello",WSAME,1,2) ;

                    // Writes to specific line, specific column, specific
                    // colors

                    window->winwrite ("Hello",5,10,0,YELLOW,RED) ;












          EasyVision 1.0           User's Guide                     Page 49




          TWINDOW::WINSWRITE
          

           Summary Writes  STATIC text  to the  window.   Many options are
                    available.

           Syntax  #include "twindow.hpp"
                    void winswrite (char huge *text[, int row, int col, int
                    format, int fore, int back]) ;

           Remarks All   comments  for  {winwrite}   are  still  true  for
                    {winswrite}.

                    Currently, the {twindow} class doesn't have a {refresh}
                    function   like   the  {tdesktop},   {tstatusline}  and
                    {tmenubar}  classes.  The {winswrite} function has been
                    implemented   to  make  possible   a  future  {refresh}
                    function.

                    The {winswrite} function acts exactly as the {winwrite}
                    function.   However,  all the calls  to {winswrite} are
                    saved  in a queue.   Later, when the {refresh} function
                    is implemented, all calls to {winswrite} will be remade
                    to redisplay those static texts.

               -->  All  calls to  this function  allocate memory,  and are
                    much  slower  than a  call  to the  regular {winwrite}.
                    {winswrite}  SHOULD ONLY BE USED for text that will not
                    be erased until the window is closed.  For instance, an
                    identifier   for   an  input   field,  or   some  other
                    identifications.

               -->  You  SOULD  NEVER USE  this function  if you  intend to
                    scroll the window or erase it.  Use it only if you want
                    your text to be available to the {refresh} function.

           Return  None

           Example See the {winwrite} examples















          EasyVision 1.0           User's Guide                     Page 50




          TWINDOW::WINTEXT
          

           Summary Displays  a  text  array in  current  window  with word
                    wrapping and 'PgDown/Esc' prompts.

           Syntax  #include "twindow.hpp"
                    void  wintext (char huge *textptr [,int fore, int high,
                    int helpflag]) ;

           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.  The format
                              of  this  text is  explained in  the {getkey}
                              function.

                              A  'PgDown' 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  'WSAME',  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.

                    <helpflag>:  Determines  if  the F1  help  key  will be
                              available  when  the  text is  displayed.   0
                              means  NO,  1 means  YES.   This  argument is
                              optional  and default to 1.  You should never
                              have  to set this to  0.  It's internaly used
                              to prevent the F1 help routine to call itself
                              from help.

           Return  None

           Example window->wintext (instructions) ;





          EasyVision 1.0           User's Guide                     Page 51




          TWINDOW::WINTEXTFILE
          

           Summary Displays  a text file from  disk in current window with
                    word wrapping and 'PgDown/Esc' prompts.

           Syntax  #include "twindow.hpp"
                    void  wintextfile  (char  huge  *path  [,int  fore, int
                    high]) ;

           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,   'File  not   found'  is
                              displayed instead.

                    <fore>  : Foreground  color  used.    This  argument is
                              optional.   If it is not given, or if you use
                              the  macro  'WSAME',  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.

                         -->  The <helpflag> argument is not used.  Help is
                              always available.

           Return  None

           Example window->wintextfile ("C:\\autoexec.bat") ;





















          EasyVision 1.0           User's Guide                     Page 52




          TWINDOW::WINMOVE
          

           Summary Moves the windows to a new location.

           Syntax  #include "twindow.hpp"
                    void winmove (int row, int col) ;

           Remarks The  window must  be opened.   <row> and  <col> are 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  valide window
                    position.

           Return  None

           Example window->winmove (10,12) ;


          TWINDOW::WINSCROLL
          

           Summary Moves window in 1 of 4 direction.

           Syntax  #include "twindow.hpp"
                    void winscroll (char direction) ;

           Remarks The  entire  window  will  be  moved,  if  possible,  1
                    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 window->winscroll ('U') ;      // Move window up 1 line













          EasyVision 1.0           User's Guide                     Page 53




          TWINDOW::WININPUT
          

           Summary Allow  inputs to be made  in multiple input fields, and
                    push buttons selection.

           Syntax  #include "twindow.hpp"
                    int wininput () ;

           Remarks You  must have created at least  1 input field prior to
                    calling this function.

                    The  user will be able to move between input fields and
                    buttons with TAB and SHIFT-TAB.

           Return  If no push buttons were created, {wininput} will return
                    with  13 or 27.  13 means the user confirmed the inputs
                    by pressing ENTER.  27 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 = window->wininput () ;






























          EasyVision 1.0           User's Guide                     Page 54




          TWINDOW::FIELDSETLENGTHS
          

           Summary Sets  the length of the next  input field to be created
                    and the length of its answer buffer.

           Syntax  #include "twindow.hpp"
                    void fieldsetlengths (int answer, int field) ;

           Remarks <answer>: 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 !

                    <field> : 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
                              length.

           Return  None

           Example window->fieldsetlengths (40,20) ;


          TWINDOW::FIELDSETCOLORS
          

           Summary Sets  the colors  used in  the next  input field  to be
                    created.

           Syntax  #include "twindow.hpp"
                    void   fieldsetcolors  ([int  back,   int  foreon,  int
                    foreoff]) ;

           Remarks <back>  : Background  color  used.    This  argument is
                              optional.    If it  is not  given, or  if the
                              macro 'WSAME' 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

           Example window->fieldsetcolors (GREEN,WHITE,WHITE) ;



          EasyVision 1.0           User's Guide                     Page 55




          TWINDOW::FIELDSETFTR
          

           Summary Sets the filter for the next input field to be created.

           Syntax  #include "twindow.hpp"
                    void fieldsetftr (int ftrtype [,char huge *extra]) ;

           Remarks An  input field  will allow only  certain characters as
                    input.   <ftrtype>  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.

                    <extra> : Include,  between  quotes,  other  characters
                              that  you want accepted by the filter.  Often
                              used to include the space char (ASCII 32).

           Return  None

           Example window->fieldsetftr (3,"\:_") ;   // Enough for a path


          TWINDOW::FIELDSETATTRIB
          

           Summary Sets attributes for the next input field to be created.

           Syntax  #include "twindow.hpp"
                    void   fieldsetattrib  ([int  caps,  int  restore,  int
                    empty]) ;

           Remarks <caps>  : If  set to 1, all inputs will be converted to
                              CAPS.    This argument  is optional  and will
                              default to 0.

                    <restore>:If  set to 1, what was  under a field will be
                              restored  when the  field is  inactive.  This
                              argument is optional and will default to 0.

                    <empty> : If  set to  0, the  user won't  be allowed to
                              input  an  empty  string.   This  argument is
                              optional and will default to 1.

           Return  None

           Example window->fieldsetattrib (1) ;          // Switch to CAPS



          EasyVision 1.0           User's Guide                     Page 56




          TWINDOW::FIELDCREATE
          

           Summary Create a new input field in the window.

           Syntax  #include "twindow.hpp"
                    void   fieldcreate  (int  row,   int  col  [,char  huge
                    *defaultasw, char huge *sltext]) ;

           Remarks The  window  must  be  opened  prior  to  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  the
                    following:

                    The field and the answer buffer will have a length of 1
                    character.

                    The field will be WHITE on BLUE.

                    The default filter will be 1, with no extra characters.

                    CAPS  LOCK  will not  be activated,  what is  under the
                    field won't be restored when the field is inactive, and
                    the user will be permitted to enter an empty string.

                    <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.

                    <defaultasw>:  This is the default  answer that will be
                              put  in the  input field.   This  argument is
                              optional.  If it is not given, the field will
                              be initialy empty.

                    <sltext>: This  is  a  short  help  text  that  will be
                              displayed  on the status  line when the field
                              is  active.  This arguement  is optional.  If
                              it  is  not  given,  no  help  text  will  be
                              displayed.    {winsetslptr}  must  have  been
                              called.

           Return  None

           Example window->fieldcreate (2,2,"Canada","Enter country") ;




          EasyVision 1.0           User's Guide                     Page 57




          TWINDOW::FIELDINPUT
          

           Summary Get user input from one input field.

           Syntax  #include "twindow.hpp"
                    int fieldinput ([int fieldnb]) ;

           Remarks You  must have  created at least  1 input  field to use
                    this  function.  Fields are given numbers when they are
                    created.  The first field created is number 1.

                    <fieldnb>:This  is the  field from which  you will make
                              the  input.   This  field  must exist.   This
                              argument is optional.  If it is not given, it
                              will default to 1.

                    If you want to take inputs from many fields, you should
                    consider using the {wininput} function instead.

           Return  {fieldinput}   with   return   with   an   ASCII   code
                    representing  how the user terminated  the input.  This
                    can be CR, ESC, TAB or SHIFT-TAB.

           Example window->fieldinput (f) ;





























          EasyVision 1.0           User's Guide                     Page 58




          TWINDOW::FIELDSETASW
          

           Summary Sets a field current content.

           Syntax  #include "twindow.hpp"
                    void fieldsetasw (char huge *answer [,int fieldnb]) ;

           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 to  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.    This
                              argument is optional and will default to 1.

           Return  None

           Example window->fieldsetasw ("C:\\UTILS\\",5) ;


          TWINDOW::FIELDGETASW
          

           Summary Reads  the  content of  the answer  buffer of  an input
                    field.

           Syntax  #include "twindow.hpp"
                    void fieldgetasw (char huge *dest [,int fieldnb]) ;

           Remarks The  answer  buffer  of field  <fieldnb>  is  copied to
                    <dest>.  <fieldnb> is optional and will default to 1.

               -->  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.

           Return  None

           Example window->fieldgetasw (response,nb) ;










          EasyVision 1.0           User's Guide                     Page 59




          TWINDOW::BUTTONSETCOLORS
          

           Summary Sets the colors used for all the window's buttons.

           Syntax  #include "twindow.hpp"
                    void   buttonsetcolors  ([int  back,  int  foreon,  int
                    foreoff, int high]) ;

           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 window->buttonsetcolors     (BLUE,WHITE,BLACK,RED)    ;























          EasyVision 1.0           User's Guide                     Page 60




          TWINDOW::BUTTONCREATE
          

           Summary Creates a new button.

           Syntax  #include "twindow.hpp"
                    void  buttoncreate (int row, int  col, char huge *name,
                    int buttonkey [,char huge *sltext]) ;

           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.

                    Button  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 1 (available).

                    The first button created will be considered the default
                    button.  This button will be activated when you request
                    a {buttoninput}.

                    <row>   : Row position of the new button.

                    <col>   : Column  position of the new button.  If <row>
                              and  <col>  are  not  valide,  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 spaces
                              in the name.

                    <buttonkey>:  This is the ASCII code that will identify
                              a  particular button.   Some rules  are to be
                              observed:






          EasyVision 1.0           User's Guide                     Page 61





                              If  the  identification  code  of  the button
                              matches   a  character  in   its  name,  that
                              character will be highlighted.

                              TAB/SHIFT-TAB  and arrow keys codes cannot be
                              used to identify a button. (9, 271, 328, 336,
                              331, 333)

                    <sltext>: This  is  a  short  help  text  that  will be
                              displayed  on the status line when the button
                              is  active.  This arguement  is optional.  If
                              it  is  not  given,  no  help  text  will  be
                              displayed.    {winsetslptr}  must  have  been
                              called.

           Return  None

           Example window->buttoncreate (10,2,"  Save",'S',"Save file") ;



































          EasyVision 1.0           User's Guide                     Page 62




          TWINDOW::BUTTONPUSH
          

           Summary Push a button.

           Syntax  #include "twindow.hpp"
                    void buttonpush (int buttonkey) ;

           Remarks <buttonkey>    is   the   identification   code   (case
                    insensitive)  of the button  you want to  push.  If the
                    button  doesn't  exist,  the  function  has  no effect.
                    Otherwise, the button is pushed in a 3D fashion.

           Return  None

           Example window->buttonpush ('S') ;






































          EasyVision 1.0           User's Guide                     Page 63




          TWINDOW::BUTTONINPUT
          

           Summary Makes user go trough the buttons with TAB/SHIFT-TAB.

           Syntax  #include "twindow.hpp"
                    int buttoninput ([int inchar, int first, int tabexit]);

           Remarks You  must have created  at least 1  button to call this
                    function,  and  there  must  be  at  least  one  button
                    available.

                    <inchar>: The  initial user  input (ASCII  code).  This
                              could  come  from  some  previous processing.
                              For  instance, the result  of an input field.
                              This argument is optional and will default to
                              0.

                    <first> : Determines  which button  will first  be made
                              active  during the input.   1 means the first
                              created  button,  0  means  the  last.   This
                              argument is optional and will default to 1.

                    <tabexit>:0  means the user can't  get out of the input
                              by  going past the first  or last button with
                              TAB  or SHIFT-TAB.  Instead the active button
                              will  wrap around.   1 means it  can get out.
                              This argument is optional and will default to
                              0.

           Return  The  function returns an int.  It is the identification
                    code  of the button  that was pushed.   If the function
                    was permitted to exit (<tabexit> = 1), then it can also
                    return  the TAB or  SHIFT-TAB code.   TAB (9) means the
                    user got past the last button, SHIFT-TAB (271) means he
                    got past the first button.

           Example inchar = window->buttoninput () ; // Can't return until
                                                      // button is pressed















          EasyVision 1.0           User's Guide                     Page 64




          TWINDOW::BUTTONSETAVAIL
          

           Summary Sets the availability of a button.

           Syntax  #include "twindow.hpp"
                    void buttonsetavail (int buttonkey, int state) ;

           Remarks The button specified MUST exist.

                    <buttonkey>: The identification code of the button that
                              you want to change.

                    <state> : 1 means this button is available.  0 means it
                              is  not.    When  a  button  is  created with
                              {buttoncreate},  its  availability  status is
                              automatically set to 1.

           Return  None

           Example window->buttonsetavail ('S',0) ;     // Save button OFF

































          EasyVision 1.0           User's Guide                     Page 65




          
          
          C  H  A  P  T  E  R    9                EasyVision's demo program
          

          I  am  a  true  believer  in  'You  learn  faster  by  looking at
          examples'.   So, I have included  a demo program with EasyVision.
          This  demo  program is  included in  the  archive under  the name
          DEMO.CPP.  The compiled version is available under EVISION.EXE.

          I  have tried to use as many  functions as possible in this short
          source  code.  It  is fully commented  and illustrate the working
          relationship between all those functions and classes.

          I  really think  that 90%  of your  questions can  be answered by
          going  through this  demo program.   You are invited  to try some
          modifications of your own, and see the results.

          I'll  say  it  again...   You  should  really print  all  of this
          documentation  for easier  reading.  It's  always a  good idea to
          have the docs nearby when everything seems to go wrong.


          The Demo Program
          

          A  couple of  things are to  be remembered from  this demo source
          code:

          First,  you should always use HUGE POINTERS in your code.  You'll
          be on the safe side and avoid many problems.

          I  have used a  global variable for  the general help  text.  You
          should  put all texts  and prompts in  a separate ressource 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 the EasyVision boundaries and use
          the provided output functions.

          All  classes come with built in  default values.  Often, only one
          call is needed to use them if the defaults are to your taste.

          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 less frustrations
          and more enjoyment out of your programming.  Have fun !

          Remy Gendron
          author of EasyVision



          EasyVision 1.0           User's Guide                     Page 66




          
          
          C  H  A  P  T  E  R    10                Things you should not do
          

          Here are a couple of things I have found to be hasardeous to your
          health.  I'd like to share them with you...

          Use this library without printing the manual.
          Use this library without looking at the example demo program.
          Use this library without registering !
          Use printf statements.
          Use scanf statements.
          Instantiate more than one {tmenubar} object.
          Smoke.
          Use 3000 {winswrite} statements.
          Use {wintextfile} on really big text files.  It's kindda slow.
          Using BC++ 3.0 on a slow computer.
          Using a function without reading its documentation twice.
          Make fun of your brother in law if he's a karate black belt.

          You  should begin to  get the idea...   Be careful,  that's all I
          ask...































          EasyVision 1.0           User's Guide                     Page 67




          
          
          A  P  P  E  N  D  I  X     A                    Extended keycodes
          

          Extended  keycodes are returned when you press a key that doesn't
          have  an associated ASCII code.  They are represented by stuffing
          2  codes into the keyboard  buffer.  A 0  followed by an extended
          key keycode in the range 0 through 255.

          The  EasyVision  {getkey}  function  deals  with  these  codes by
          returning  values (int) in the range 0 through 511.  The standard
          ASCII  codes  are returned  unchanged  (Guess why  ?).   Extended
          keycodes  are added 256 to their  real value for convenience, and
          are returned as a single number.  Here they are...

          259       NUL
          271       Shift-TAB
          272-281   Alt Q/W/E/R/T/Y/U/I/O/P
          286-294   Alt A/S/D/F/G/H/J/K/L
          300-306   Alt Z/X/C/V/B/N/M
          315-324   F1 to F10
          327       Home
          328       Up arrow key
          329       Page Up
          331       Left arrow key
          333       Right arrow key
          335       End
          336       Down arrow key
          337       Page Down
          338       Ins
          339       Del
          340-349   Shift-F1 to Shift-F10
          350-359   Ctrl-F1 to Ctrl-F10
          360-369   Alt-F1 to Alt-F10
          370       Ctrl-Print Screen
          371       Ctrl-Left arrow key
          372       Ctrl-Right arrow key
          373       Ctrl-End
          374       Ctrl-Page Down
          375       Ctrl-Home
          376-387   Alt 1/2/3/4/5/6/7/8/9/0/-/=
          388       Ctrl-Page Up
          389       F11
          390       F12
          391       Shift-F11
          392       Shift-F12
          393       Ctrl-F11
          394       Ctrl-F12
          395       Alt-F11
          396       Alt-F12



          EasyVision 1.0           User's Guide                     Page 68





          
          
          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.



          Available background colors:

                    0  BLACK
                    1  BLUE
                    2  GREEN
                    3  CYAN
                    4  RED
                    5  MAGENTA
                    6  BROWN
                    7  LIGHTGRAY



          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



















          EasyVision 1.0           User's Guide                     Page 69





          
          
          A  P  P  E  N  D  I  X     C                           Trademarks
          

          Turbo vision from Borland

          DeskView from Quarterdeck

          EasyVision from TNG SOFT ENTERPRISES

          CXL from Mike Smedley









































          EasyVision 1.0           User's Guide                     Page 70





          
          
          A  P  P  E  N  D  I  X     D         Common Questions and Answers
          

          As  this is the first release of  this software, I don't have any
          questions or answers.  Doesn't make for a big appendix D...

          I  will gladly answer any questions relating to this software.  I
          can  be reach via  the C++ FidoNet  echomail conference.  Address
          your message to 'Remy Gendron'.  Don't make a mistake in the name
          because  I don't read  the echo.   The name must  be correct if I
          want to be alerted to your message.

          I  will not send  answers through Netmail.   It costs something !
          But the real reason is that it won't benefit anyone else.

          Any comments, bug reports or suggestions will be appreciated.




                                STARFLEET COMMAND BBS
                              (418)  525-6899/4740/6803
                                 FidoNet: 1:240/1701



                                         or



                                TNG SOFT ENTERPRISES
                                  2480 Ave de Vitre
                                   Quebec, Quebec
                                       Canada
                                       G1J 4A6



          Thank you for using this software !

          Remy Gendron
          Author of EasyVision







