
                                TVToyc
                              Prerelease
                             January 1994

                         Far Niente Productions



    Prerelease Information  
  
    This is the current status of the TVToyc project, a port of the
    TVToys (for Pascal) package.  I dislike BC a lot, and I don't know
    enough C or C++ to do this justice.  Without your help, TVToyc will
    be buried and forgotten for good, so try to improve it, volunteer to
    port more code (it's dead boring, but very easy) or at least let me
    know if you liked it.

    Without user support this project is dead.



    Contents  
  
    Introduction
    Copyright
    Short Description
    Package File List

    Instructions
    Compatibility Testing
    Coding Style
    Protected Mode Information
    Overlay Information
    PC Video Modes
    Video 7

    The Improved Help File
    Extended Video Mode Support Code

    Credits
    Author, Support, Info, Bugs etc
    To Do List



    Introduction  
  
    Welcome to TVToyc!

    This is a collection of useful stuff that should be available to all
    Turbo Vision programmers. It is intended for Borland C++ 3.x with
    Turbo Vision but the [font, palette] and video mode code can be used
    in plain text mode without Turbo Vision.

    THE SOURCE IS FREE AND COMES WITH NO WARRANTIES WHATSOEVER.

    I hope that you will find this package useful. Have fun with it!



    Copyright  
  
    You may use this package for free and pass it on to other persons as
    long as you clearly state, in the header as well as in the code, all
    changes made to the original code.

    You may not pass along compiled versions of the source, except as
    executable files.

    You may also upload this package, unmodified, to bulletin boards or
    other public access places.

    There must be no charge associated with this package, though you may
    include the unmodified package as a whole in shareware/freeware
    compilations if only a nominal amount is charged for the compilation
    disk.

    I strongly urge people with money to spare to donate a small token
    of appreciation in the $20 range. That's 5 campus meals for me.



    Short Description  
  
    This package includes:

    An improved Help viewer with back tracking and the possibility to
    add Contents and Index pages or whatever without recompiling
    the help engine.

    Extended video mode support. Code that determines what video modes
    are available and presents a list for the user to choose from.
    Video7 and VESA support included.


    WHAT THIS PACKAGE COULD INCLUDE:

    Custom fonts. Support for three different font file formats.

    Palette routines. Change the EGA/VGA palette.

    A mouse unit that limits the effects of buggy mouse drivers in
    extended video modes.

    Three demonstration programs, personal configuration files.



    Package File List  
  
    The package consists of the following files:

    TEST.CPP      Main test program
    TEST.MAK      Attempt at make file for TEST.CPP

    HELP.H
    HELP.CPP
    HELPBASE.H
    HELPBASE.CPP  Improved HelpFile with back tracking and external commands

    HELPCTX.H     Help contexts generated by TVHC
    HELPTEST.HLP  Demo help text compiled with TVHC
    HELPTEST.TXT  The Help text source

    VIDEO.H
    VIDEO.CPP     A unit supporting extended video mode setting and searching

    MODEDLG.H
    MODEDLG.CPP   Dialog for presenting and selecting video modes

    TVVIDEO.H
    TVVIDEO.CPP   TV support for all the new video modes

    TOYCFG.H      Your personal configuration file

    VESA.H
    VESA.CPP      VESA support routines

    README.TXT    This text.



    Instructions  
  
    The demonstration program relies on the improved help code included
    in this package, so you should make sure it gets used instead of
    Turbo Vision's normal help engine.

    The program called TEST is a very simple demonstration of the help
    and the video mode detection. Run it for a quick demonstration.

    If your mouse behaves oddly at times when running TEST, you need
    NEWMOUSE, a not yet ported mouse remedy against bug ridden mouse
    drivers.

    The mouse cursor also jumps around when you change video modes, but
    that's because the cursor stays at the same position relative to the
    upper left corner.

    Convention:  Uppercase words are file names, like TEST and TOYCFG. A
                 "section" is a paragraph in this file, having the
                 section name for header.



    Compatibility Testing  
  
    This code has mainly been tested on three machines:

       A 286 with with a Chips VGA card and an EGA monitor. Also tested
        with a Video7 card which provided 132 column output on the EGA
        monitor. No protected mode. First development machine.

       An IBM PS/1 486/33 with Tseng VGA chips. VERY slow at scanning.
        First protected mode attempts.

       A Dual monitor Compaq 386 Portable with a Video7 VGA card and
        Super VGA monitor. Current development platform.

    I have tested three mouse drivers on the Video 7 equipped 386:
    Microsoft Mouse driver version 8.20 and earlier does not work with
    extended text modes, it assumes them to be graphics modes. All
    Logitech mouse drivers should work with all text modes, I have only
    tested version 6.20. Genius mouse driver version 10.20 does not
    work, it doesn't realize what width the screen is. NewMouse fixes
    all this, but if the mouse driver is buggy (like Genius) there might
    be minor annoyances like the cursor jumping or temporarily
    disappearing at mode switches. I suggest that you check what mouse
    driver you are using, there are usually several on every hard disk.
    I use Microsoft's driver version 8.20 even though it's buggy, but
    you know what you get.

    VESA compatibility was tested using a PD Video7 TSR on the 386.

    UNIVESA.EXE by Kendall Bennett is NOT a full VESA implementation, it
    focuses solely on graphics video modes and will not provide the
    necessary information to avoid having to physically test every video
    mode.

    If you promptly have to use UNIVESA or UNIVBE release 4.2 or earlier
    on a Video 7 video card, make sure you define V7UniVesaKludge, since
    there is a Video 7 specific bug in UNIVESA. Future versions of
    UNIVESA will probably not suffer from this.



    Coding Style  
  
    I'm a C++ novice, and the source is a Pascal port with some changes
    on the way.  If you have suggestions or even better rewritten code
    I'll be happy to see it.  I admit the current version could be a lot
    better.



    Protected Mode Information  
  
    All the code has been tested in protected mode, especially the
    Video7, Vesa and NewMouse code, but only in the Pascal version.

    I have not ported the protected mode code since I lack information
    on BC Dos extenders, and I don't have a Dos extender for BC++, so I
    couldn't test it anyway. I've left the Pascal DPMI implementation if
    you feel inclined.



    Overlay Information  
  
    You can overlay all units EXCEPT NewMouse, which contains an
    interrupt handler. It's a very small unit anyway, about 530 bytes.



    PC Video Modes  
  
    Turbo Vision only knows about three video modes, and there is a
    reason for that. These three are the only "standard" 80 column text
    modes, all other video modes are manufacturer specific. All modes
    are referred to by number, and the three Turbo Vision knows about
    are number 2, 3 and 7. Numbers range from 0 to 127, where most of
    the first 19 are used by VGA cards. Numbers above 19 are used for
    extended video modes.

    Naturally, all manufacturers number their video modes differently,
    even if the screen size is the same. This means that you can't
    easily set a 80x60 video mode, for instance, since you wouldn't know
    what mode number to refer to unless you know the brand of the video
    card. You might not even know if the video card supports 80x60, but
    your program could find out. The monitor might not like 80x60
    either, but a program cannot detect if a VGA monitor is suited for
    Super VGA video modes.

    There is a function, TVideoList::findSimilarVideoMode(Cols,Rows),
    that will return the number of a video mode which is about Cols wide
    and Rows high. You can pass the mode number to setSpecialVideoMode
    directly. Remember to use scanVideoModes first. findSimilarVideoMode
    uses a simple approach, but you can write your own algorithm.



    Video 7  
  
    This package supports Video 7 video cards. Certain design decisions
    were made with Video 7 in mind (overly complicating things).

    Video 7 cards do not recognize any text video mode numbers above 19
    (see above) if you use the normal BIOS interrupt call, you must use
    a special Video 7 call. On the other hand, video mode 1 corresponds
    to the last Video 7 specific video mode set with such a Video 7
    call. That is, if you set a 80x60 video mode with a Video 7
    interrupt (the only way), you can use a normal BIOS call setting
    mode 1 and get the last Video 7 specific mode set.

    This also means that if you ask a Video 7 BIOS in the normal way
    what video mode is set, the answer will be 1 for all extended video
    modes. This creates problems as mode 1 is a standard 40x25 mode.
    Sometimes you will get a 40x25 mode when you least expect it,
    usually when you terminate your program abnormally inside the IDE.
    This only happens if you have a Video 7 video card.



    The Improved Help File  
  
    HELPFILE is an improved help file with back tracking and custom key
    help screens. See TEST for a demonstration.

    The help code is a modified TV 1.03 help with some bugs removed.

    There should be no difficulty upgrading your programs to use the
    improved help engine, just make your application object inherit
    TToyApp and define a status line. Make sure you set helpFileName to
    your application's help file name and everything will be taken care
    of for you.



    Extended Video Mode Support Code  
  
    The units Video, ModeDlg, TVVideo and VESA provide extended video
    mode support. See TEST for a demonstration.

    You CANNOT use smFont8x8 with TVToys any more. REMOVE all references
    to it.

    Video7 and VESA support are defined automatically. Modify TOYCFG to
    your liking.

    VESA function calls take priority. checkVideoType will still look
    for all video types supported, though. You can check for only some
    video types by changing the videoTypesToCheck variable. checkEVGA
    will always be called, this works with most computers, but not the
    Vesa and Video 7 checks. This is a Video BIOS problem on some
    machines. The Vesa implementation might also be so buggy that the
    user rather lived without it. videoTypesToCheck lets you configure
    video support at run time.


    How it all works: (This is a very long description! If you inherit
    TToyApp all you have to do is copy the uses list, some HandleEvent
    lines, the cmXXXX list and some menu code from TEST to make things
    work)

    First call checkVideoType. This will set videoType, video7 and
    vesaVersion to appropriate values. If vesaVersion is zero, no Vesa
    support was detected. (TToyApp::Init does this for you). You can call
    checkVesa, checkVideo7 and checkEVGA yourself if you want greater
    control, or use videoTypesToCheck.

    Call TVideoList::setup to construct a list of available video modes.
    If a VESA video card is detected, attempts will be made to directly
    inquire about available video modes. This might not be supported by
    the video card since it is not mandatory in the VESA standard.

    If the VESA test fails, scanEVGAModes will be used to determine
    video modes.

    scanEVGAModes takes a somewhat simple and stupid approach to
    determine what video modes are available: It tries to set every
    video mode from 0 to 127 to see if the BIOS responds by setting more
    or less legal values in the BIOS data segment. This might not work
    all that well all the time, see TEST for a list of caveats.
    The only other way (apart from VESA) of determining available video
    modes is to use lists of all video modes for all cards manufactured.

    Use selectVideoModeDialog to put up a TV dialog that lets the user
    choose from available modes.


    To avoid unnecessary scanning, you can save and restore the scanning
    results to/from disk.

    If you don't like the format of the information (not very easy to
    read, maybe?) presented in the selection dialog, make changes in the
    addMode procedure in MODEDLG.


    To use the video mode routines, use this as a checklist:

    1)  Always start out by determining the current video system.
        (TToyApp::TToyApp handles all this automatically)

        checkVideoType;  (* Always start with this command *)

    2)  Check that we're in fact dealing with a EGA/VGA before using
        scanEVGAModes. You can simply shut off the command:

        if videoType=OTHER then disableCommands([cmVideoMode,
          cmVideoLines, cm14p, cm16p]);

    3)  Put up some sort of warnings before we start scanning...
        TVideoList::hasToScan is false if we already know what video
        modes are available. vesaScanningPossible is true if we don't
        have to physically set every video mode to see if it is
        supported. You might want to put up different warnings depending
        on what will actually happen.

    4)  To scan and then select video mode:

          TVideoList::setup();
          selectVideoModeDialog();

        If you use resources, try this:

          TVideoList::setup();
          selectVideoMode(
            (TSelectVideoModeDialog*) rezFile.get('VideoModeDialog'));

    5)  To save the video modes found during scanning, use
        StoreVideoModes:

        var
          S : TDosStream;

        RegisterObjects;
        S.Init('VIDEOTST.INI', stCreate);
        StoreVideoModes(S);
        S.Done;

        Use LoadVideoModes to restore them. See RESTEST for an advanced
        example.

    6)  Remember to change all your old references to setScreenMode to
        setSpecialScreenMode, but...

    7)  YOU CANNOT USE smFont8x8! TVToys does not support this any
        longer, there is now a toggleVideoLines procedure. You can also
        use the setInternalFont(internal8x8Font) procedure.

    8)  This code has to trash Turbo Vision's startUpMode to get by
        "internal security". Since Video7 cards use video mode 1 to
        signify the last extended video mode used, special care must be
        taken to provide intelligent startupMode behaviour if
        TOYVIDEO7SUPPORT is defined. TToyApp uses TVideoState objects
        and handles everything transparently for you.



    Credits  
  
    All dialogs designed and generated with Dialog Design 4.0 available
    on Compuserve and by anonymous ftp to garbo.uwasa.fi in directory
    /pc/turbovis and oak.oakland.edu in /pub/msdos/turbovis. Thanks to
    David Baldwin, who also contributed the original ColorTxt unit and
    an ATI fix.

    NewMouse, VESA and DPMI bug fixes and lots of other suggestions from
    Marek Bojarski without whom TVToys would be buggier than a mouse
    driver.

    I finally found a VESA TSR for Video7 that contained TEXT mode
    support. Thanks to Gary Lorenson.

    All Video7 and VESA information derived from Ralf Brown's famous
    interrupt listing.

    DPMI information from Borland source and the official DPMI
    specifications.

    This project would have been utterly impossible without the help of
    Borland's run time source, or for that matter, Borland Pascal 7.0...



    Author, Support, Info, Bugs etc  
  
    If you would like to see further enhancements to this code, write me
    a letter telling me what you like and don't like, what works and
    what doesn't, and what improvements you want to see.

    Since I am a computer science student with no income, I would very
    much appreciate a financial contribution. Get in touch with me if
    you feel that you want to support this package financially.
    Unfortunately a check costs me SEK 70 (almost $10) to cash in, so
    cash or wire is best for me!

    I accept orders for the latest version and will send invoices by
    arrangement.

    Bug reports, enhancements, contributions, credits, postcards and
    money are always welcome!

      My internet address:

        d91-pbr@nada.kth.se

      You can reach me from CompuServe by sending mail to:

        INTERNET:d91-pbr@nada.kth.se

      Mail:

        Peter Brandstrm          (Peter Brandstrom)
        Roslagsgatan 10
        S-113 55 Stockholm
        Sweden, Europe



    To Do List  
  

    A TToyApp class that overrides TApplications getEvent and getPalette
    Putting the VESA code into an object More objects, less global
    symbol litter

    Some sort of way (make file) to get the modified help code into the
    TV.LIB file without fuss.


