Monster Media 1994 #1/monster.zip/monster/PROG_GEN/TVCOLR.ZIP/TVCOLR.DOC

Text File | 1994-02-08 | 28KB | 516 lines

Notice
======
    The changes described in this file don't necessarily require the source
code to the Turbo Vision class library.  All of Borland's copyrights remain
in effect and I make no claim of ownership or copyright to the modifications
described herein.  It's always a good idea to back up the files to be
modified in case you mess something up and, if you do, I'M NOT RESPONSIBLE.

Files you should have received in TVCOLR.ZIP:
=============================================
        TVCOLR.DOC      -- Document describing extending TV's palette system.
        COLUPDT.DOC     -- Document describing some TV modifications.
        MAPCOLOR.CPP    -- A replacement TView::mapColor().
                           This can be used whether you have the TV source
                           code or not.
        TVCOLR.H        -- A default TVCOLR.H file to get you started.
        TVCOLR.HDC      -- TVCOLR.H fully commented.
        TCOLTEXT.H      -- TColorText header file.
        TCOLTEXT.CPP    -- TColorText class code.  This class is used
                           throughout the demo and has colors in TVCOLR.H.
        DEMOUMOD.EXE    -- Demo using the unmodified TV library.
        DEMOMOD.EXE     -- Demo using the modifications described in the docs.
        DEMO.H          -- Demo header file.
        DEMO.CPP        -- Demo source code.
        DEMO.PRJ        -- Demo program project file.
        DEMNOSRC.PRJ    -- Similar to DEMO.PRJ, but for those with no source
                           code for Turbo Vision.
        LINK.H          -- Resource file __link() definitions for the demo.
        BLDRSC.CPP      -- Resource file builder.
        BLDRSC.PRJ      -- Resource file builder project file.  The included
                           executables have the .RSC file appended to the EXE.

    If your copy is incomplete, you can find a full copy in the BCPPDOS
forum on CompuServe in the Turbo Vision library section.

Foreword
========
    I've seen a number of messages in the BCPPDOS forum on CompuServe asking
how to add new colors to classes in Turbo Vision or modify the application
palettes in a more simplified manner.  Below is a document describing a new,
hopefully easier, method of expanding the default Turbo Vision color
palettes.  I think its more flexible, easier to implement, and all those who
use Turbo Vision could benefit from it eventually when they start playing
around with color options for an application.  There is a lot of text that
follows, but don't let that put you off.  This method is not that hard to
understand or use.  However, I designed it, I coded all the changes, and so
far I alone have the better understanding of what I was trying to do and
what the end result does accomplish.

    With that in mind, I have submitted this to be looked over, kicked
around, tried out, commented on, and hopefully put to good use.  I've
included some sample code in a demo program.  I haven't seen too much on
selecting different palettes, altering colors, or saving the palettes for a
Turbo Vision application so it should also serve as a fairly decent tutorial
on those subjects too.  If you've ever tried using the manual for help on
adding and altering colors, you've probably ended up more confused than when
you started (I did anyway <g>).  Step-by-step instructions for my way can be
found later on in this file.

Background Information
======================
    Most of the time, when a new class is created in Turbo Vision, it can
have its colors mapped into existing colors in the owning view such as a
TDialog or TWindow.  Here, I refer to colors such as normal text,
highlighted text, scrollbar colors, etc.  Occasionally, new additions to the
default application palette are needed.  When I say this, I mean completely
new entries that don't already have an existing equivalent in the normal
application palette.  For example, if you decide to add an error message
color entry for a new TStaticText class you derive, you would add a new
entry to the end of the application's base palettes (cpColor, cpBlackWhite,
and cpMonochrome).
    This document describes a set of modifications (or replacements) to the
Turbo Vision source code and, once they are made, a method to easily expand
the default Turbo Vision application palette by updating and/or including a
single header file.  Using the following method, it is no longer necessary to
derive a new owning class (i.e. TDialog or TWindow) for objects that require
new palette entries.  Also, any new colors you add will be immediately
accessible to existing classes or other new classes you create without
having to derive new owning classes for them as well or adding more colors
specifically for them that may duplicate ones already in existence.

    As an example, suppose you want to derive a class called TColorText from
TStaticText to use different colors for information, notification, warning,
and error messages and each will have a unique entry in the application's
palettes so that the user can modify them with a TColorDialog.  As shown in
the manual and example programs, you would have to create the TColorText
class and its getPalette() member function and then override the
TApplication::getPalette() member function to add the three extra colors to
the end of the base palettes (cpColor, cpBlackWhite, cpMonochrome).

    However, you also have to derive a new TDialog and modify its palette so
that the new colors can be accessed using the getColor() function.  You
would then have to use that new TDialog class whenever you used the
TColorText class.  If any other new classes you create also need to use
these added colors or define more, you have to use the same derived TDialog
or extend its palette again for them so that they can have access to those
colors.  Placing the object in a TWindow or other such object would also
require a new derived class to extended their palettes similar to the
TDialog class.

    I also found that if you decide to add the help colors to your
application at a later date, they have to be added *immediately after* the
normal base palettes because the indices for them are hard coded in
HELPBASE.H.  That means that you will then need to change any color indices
used for your additions because they will have to come *after* the help
colors.  Otherwise, you'll need to include the help window colors from the
very start.  It's not a major problem, but it's still something else you
need to take into account.

How the change works
====================
    I have seen simple work-arounds that involve a color attribute that is
passed to the object in its constructor.  However, that color won't be able
to change at runtime based on the palettes for each monitor type or get
modified in a TColorDialog by the user to suit their preference in colors.
By circumventing the Turbo Vision palette system, you lose the functionality
it offers you.

    After playing around with some ideas for a while, I came up with the
following method.  Some initial changes to the Turbo Vision source code are
required to make my method work (but you don't have to physically change the
library if you don't want to).  In short, you replace TView::mapColor() with
a function that will properly map index references to extended entries (ones
that you add).  Once done, you just modify and/or #include another header
file.  The file, TVCOLR.H, can be placed in the Turbo Vision #include
directory and can be automatically processed by modifying the TV.H file to
include it whenever you #define Uses_TVCOLR.  Until you create another class
requiring more additions to the color palette, you can pretty much forget
about how it works or thinking about what needs changing and just use its
extended application palette definitions.

    The TVCOLR.H header file is where you define a default base palette and
then define any new extensions to it.  The default base palette consists of
the normal colors with the help colors automatically appended to them.  To
add new color entries, you simply add some definitions for the new class and
tack them on the end of the "extended" palette definition.  I have written
it so that there is a standard, simple procedure to follow when doing so.
Once done, any application may use the extended colors by simply including
the TVCOLR.H file and telling its TApplication::getPalette() member function
to use the extended color palette definitions.  If it is already doing so,
then no changes are necessary.  All you have to do is recompile the
application and link in the new class and any processes, dialogs, etc, that
use it.

    Whenever you create a class that needs new color entries added to the
application palette, all you have to modify is TVCOLR.H.  The new classes
you write will have a getPalette() member function that uses defined indices
from TVCOLR.H to reference the new color entries.  After updating it, you
just recompile your application.  In addition to this, any other classes you
create, either related or unrelated, will also have access to these palette
entries.  All you need to do is #include TVCOLR.H and construct their
palette so that they use the proper index values to get to them.

    If you distribute any of your classes to other people either separately
or as a library of classes for use with Turbo Vision, you can refer them to
or include this set of files on how to either add the TVCOLR.H header file
and other modifications to their system or merge your new class color
definitions from your TVCOLR.H into their existing copy.

    Another benefit of this method is that if you distribute a Turbo Vision
class library without source code and your objects use additional colors,
all that the end user has to do is modify their copy of TVCOLR.H and
override getPalette() if and when it comes time to add new entries.  No
changes are required to the source code they don't have.  As long as the
existing entries in TVCOLR.H remain unchanged and they only add stuff to the
end definitions, everything will turn out right.  Also, by conforming to
this color mapping and defintion method, there is little chance of
conflicting color index entries between old and new classes.  You also don't
have to remember to include any additional object palettes in the
TApplication::getPalette() either as long as you use the extended color
#defines from TVCOLR.H.

First, a few code fixes
=======================
    While adding a TColorDialog to my application, I found out that unlike
the compiler's IDE, Turbo Vision had no entries for changing a default
button's shortcut color, a selected button's shortcut color, or a selected
label's shortcut color.  Thus, the hotkeys for them always seem to stand out
in an aesthetically unsatisfactory way (well, they do to me anyway <g>).
Also, you can't use black on black (i.e. for a blank desktop background).
Finally, if you ever use apMonochrome, TColorDialog has defined
TMonoSelector to be one line too long so that the "Inverse" radio button
shows up twice.  I have included notes on fixing these problems too (See
COLUPDT.DOC).  If you want to, put these changes in before proceeding with
the modifications below.  You don't have to add the extra colors for the
TButton and TLabel objects if you don't want to (it does make for a better
looking interface when you use non-standard colors though).  With this
release of the files, TVCOLR.H will work properly whether or not the three
new colors are added to the Turbo Vision source code.  You may want to
put the changes in so that black on black is a valid color selection and/or
to fix the TColorDialog class though.
    For those with no source code for Turbo Vision, you can still implement
the changes below for extended colors.  Simply include the new MAPCOLOR.CPP
in your project file or compile it and simply replace it in the TV.LIB (make
a back-up of the original!) with:

        bcc -c -P -O1 -ml -I\bc\include;\bc\tvision\include;. mapcolor.cpp
        tlib \bc\tvision\lib\tv.lib /0 -+mapcolor.obj

Substitute your path to the include and library directories as needed.  If
you choose to add it to your projects instead of replacing it in the
library, be sure it gets linked in *before* TV.LIB (or TVNO.LIB and TVO.LIB
when using the overlay versions if you created them) so that the new copy is
used.  You'll know if it hasn't worked because the colors will be messed up.
This is usually only a problem when using MAKE files instead of the IDE's
.PRJ files.  Placing MAPCOLOR.CPP anywhere in an IDE's .PRJ file is usually
enough to make it get linked in before TV.LIB.

How to make the changes
=======================

Files Affected:
===============
    COLORSEL.CPP ──┐
    DRIVERS.CPP    ├─  See COLUPDT.DOC for allowing black on black,
    MAPCOLOR.CPP ──┘   fixing TMonoSelector, etc.

    MAPCOLOR.CPP -- See below.
    TV.H

Files Added:
============
    TVCOLR.H     -- Place this file in the Turbo Vision #include directory
                    (\BC\TVISION\INCLUDE for example).

Files Changed:
==============

MAPCOLOR.CPP
============
    Simply replace the existing MAPCOLOR.CPP with the supplied MAPCOLOR.CPP
or include it in your project file to replace the existing library copy when
your application is compiled and linked.

TV.H
====
    Add the following lines around line 608 before the '#pragma option -Vo'
statement:

#if defined( Uses_TVCOLR )
#include <tvcolr.h>
#endif

*******************************************************************************

Implementation
==============
    That's all there is to it.  If you made the modifications described in
COLUPDT.DOC, change directories to \BC\TVISION\SOURCE (substitute your path
as necessary) and issue the command:  make -fmakefile

    I think it's best to rebuild the library because by doing the MAKE, you
can insure that everthing that needs updating gets recompiled.  But, if all
you've done is replace MAPCOLOR.CPP and left out the changes in COLUPDT.DOC,
you can use the method described above in the "First, a few code fixes"
section to recompile and replace MAPCOLOR.OBJ.  It doesn't require a total
rebuild of the library to replace MAPCOLOR.OBJ in the TV.LIB file.

    I have included a demo program with comments that explain using extended
colors along with the TColorText class described in the comments of the
TVCOLR.HDC file.  I created TVCOLR.HDC with full documentation to describe
how to do things and TVCOLR.H without all the comments so that you could see
the whole picture without all the clutter.  Read those comments because they
will tell you all you need to know for adding more colors to it.  Additional
comments can be found in the TColorText source files and the demo program
files.

*******************************************************************************

    The following notes cover adding a class's extended colors to TVCOLR.H.
I will use the TColorText class already in the header file as an example.
It might be helpful to print it out and follow along.

Step 1.  Define the additional color attributes for each palette.
=================================================================
    This step refers to the actual color attributes that will appear in the
application's base palettes (cpColor, cpBlackWhite, cpMonochrome, and any
user defined palettes).  I've also defined an Alternate Color palette
(cpAltColor) that can be used for your own default color preferences as
opposed to the default Turbo Vision color preferences (I'm not a big fan of
green buttons <g>).  For the example TColorText class, we will add four new
entries to each palette: one for information messages, one for notification
messages, one for warning messages, and the last one for error messages.
It would be done as follows:

// TColorText additional color attributes.
#define cpColorTextAltColor   "\x1B\x1F\x4F\x4E"    // Alt color palette
#define cpColorTextColor      "\x1B\x1F\x4F\x4E"    // Color palette
#define cpColorTextBlackWhite "\x70\x7F\x07\x0F"    // B&W palette
#define cpColorTextMonochrome "\x70\x01\x0F\x0F"    // Monochrome palette

These will become the default colors for the object at start-up. To get a
default color, use the digits below and join them together to form a hex
value in the format \x[background][foreground].  Thus for the error color in
the cpColorTextColor palette it is \x4E or *yellow text (E)* on a *red
background (4)*.

Color                    Digit          Can be used for:
==================================================================
Black                      0               Both
Blue                       1               Both
Green                      2               Both
Cyan                       3               Both
Red                        4               Both
Magenta                    5               Both
Brown                      6               Both
Light Gray                 7               Both
Dark Gray                  8               Foreground only
Light Blue                 9               Foreground only
Light Green                A               Foreground only
Light Cyan                 B               Foreground only
Light Red                  C               Foreground only
Light Magenta              D               Foreground only
Yellow                     E               Foreground only
White                      F               Foreground only

2. Define the indices that go into the extended application palettes.
=====================================================================
    For each of the added colors above, you will need to define an index
into the application palettes so that the color can be accessed.  This is
just the offset (position) within the application palette as a whole.  Just
add a #define for each new color that equates to the offset.  This is done
by taking the last defined offset from the class prior to the one being
defined and adding an offset to it for the new class.  Don't worry!  It's
simpler than it sounds.  Here are the indices for the TColorText class:

#define cCTxtInfoColor      cpDefSize + 1       // Information color
#define cCTxtNotifyColor    cpDefSize + 2       // Notification color
#define cCTxtWarnColor      cpDefSize + 3       // Warning color
#define cCTxtErrorColor     cpDefSize + 4       // Error color

    Because TColorText is the *first* class added to TVCOLR.H, we have to
use cpDefSize as the sum of all palette entries up to this point.  We can
now just add our offsets into the TColorText attributes.  For the
information color, we add 1 because it is the first entry in TColorText's
extra colors.  The notification color is the second entry so it is cpDefSize
+ 2. The warning color is the third entry so it is cpDefSize + 3, and the
error color is the fourth entry so it is cpDefSize + 4.  Because all of the
application palettes (cpColor, cpBlackWhite, etc) are the same size, these
indices work for any of them.

Now, lets suppose we add another class to TVCOLR.H after TColorText.

// Another class's attributes   #1  #2 ...#nnn
#define cpAnyClassAltColor    "\x71\x6E...etc"
#define cpAnyClassColor       "\x71\x6E...etc"
#define cpAnyClassBlackWhite  "\x0F\x0E...etc"
#define cpAnyClassMonochrome  "\x0F\x0E...etc"

// As described, cCTxtErrorColor will be the *last* offset of the palettes,
// so it will give us the size up to that point.

#define cAnyClassExtra1   cCTxtErrorColor + 1   // Extra Color 1
#define cAnyClassExtra2   cCTxtErrorColor + 2   // Extra Color 2
  .                                              .
  .                                              .
  etc.                                          // Extra Color nnn

So where does that get me?
==========================
    Because you are adding colors for the object, it will need an overridden
getPalette() member function.  You will use these indices to form the
palette for the object.  These point to the new colors in the application's
base palettes (cpColor, etc).  You will also use these indices so that
TColorDialog can modify the object's colors.

Creating the Object's getPalette() Member Function
--------------------------------------------------
    For colors that will match the owning view's color for a particular item
(i.e. normal text), just use an index such as '\x06' to access the n'th
element of the owners palette just like you normally would.  In such cases,
the new mapColor() function will follow the normal procedure of mapping the
index on to the owning view's palette and so on down the line.  For colors
added to the TVCOLR.H file, you will use the index so that mapColor() goes
directly to the base palette and retrieves the attribute.

Thus the TColorText palette is layed out as follows:
        1 = Normal Text       (from owner's 6th palette entry)
        2 = Information Text  (custom added color)
        3 = Notification Text (custom added color)
        4 = Warning Text      (custom added color)
        5 = Error Text        (custom added color)

    One thing I will point out right now:  When possible, try to find an
entry in the owner's palette that will fill the need for your class's
colors.  An example of this is TColorText's Normal Text entry.  Instead of
adding another new color for it, the class looks to the owner and gets it's
Normal Text color attribute.  That way, you don't waste space or time
defining entries for colors that already exist.  Also, normal text will now
be drawn in the proper color whether it is inserted into a TDialog or a
TWindow.

All of the getPalette() functions will look similar to this one:

// Create a character array where each element is a color index.
// This forms the palette for the object.
char cpColorText[] = { '\x06', cCTxtInfoColor, cCTxtNotifyColor,
                               cCTxtWarnColor, cCTxtErrorColor };

TPalette& TColorText::getPalette() const
{
    // Note the lack of a "- 1" after the sizeof().  There is no NULL on
    // this type of palette because it is a simple array, not a string.
    // Don't account for one!
    static TPalette palette( cpColorText, sizeof( cpColorText) );
    return palette;
}

    The first entry is '\x06' to map onto the owning view's sixth palette
entry, but the rest are the custom index values added to TVCOLR.H.  When
mapColor() sees an index value greater than cpDefSize, it goes directly to
the base palette and retrieves the attribute instead of mapping colors onto
the owning views.

3. Add your new color attribute definitions to the full extended palette.
=========================================================================
    You do this by taking the #defines from step 1 and putting them on the
*end* of the cpExtXXX #defines at the bottom of TVCOLR.H.  Always add your
new colors to the *end* of the palettes so that the indices you created
before it will stay the same.  That way you don't have to recompile any of
them when you add new colors.  The new information goes on the end where it
doesn't affect anything.

#define cpExtAltColor       cpDefAltColor cpColorTextAltColor
#define cpExtColor          cpDefColor cpColorTextColor
#define cpExtBlackWhite     cpDefBlackWhite cpColorTextBlackWhite
#define cpExtMonochrome     cpDefMonochrome cpColorTextMonochrome

    Once you've gone through the above steps, you are free to use the new
colors however you want.  To use them, make sure the TVCOLR.H file gets
included in all the files that need it:

    .
    .
    .
#define  Uses_TVCOLR
#include <tv.h>

Or, if you didn't modify the TV.H file, make sure it can be found somewhere
in the default #include path and add the following line:

#include <tvcolr.h>

For your application class, override the normal getPalette() with something
like:

// This is where the palettes for the application are defined.
TPalette &TDemoApp::getPalette() const
{
    // The Color and Alternate Color attribute maps are swapped in these
    // definitions so that my color preferences are used by default for
    // color monitors.

    static TPalette color( cpExtAltColor, sizeof( cpExtAltColor)-1 );
    static TPalette blackwhite( cpExtBlackWhite, sizeof( cpExtBlackWhite)-1 );
    static TPalette monochrome( cpExtMonochrome, sizeof( cpExtMonochrome)-1 );
    static TPalette altcolor( cpExtColor, sizeof( cpExtColor)-1 );

    static TPalette *palettes[] =
    {
        &color,
        &blackwhite,
        &monochrome,
        &altcolor        // Additional palettes must come after standard ones
                         // in this array.
    };
    return *(palettes[appPalette]);
}

Look at the demo source code included with these instruction files for
further examples.

Distributing Your Own Classes
=============================
    If you distribute your own Turbo Vision classes that make use of the
TVCOLR.H methods, you will need to include a copy of your TVCOLR.H and a
copy of MAPCOLOR.CPP so that people who don't already have this set of
documented changes can use them.  To use them in that manner, all you need
to do is put a copy of MAPCOLOR.CPP in the project and have TVCOLR.H
#included in such a way that it can be found.  You could also point them to
this set of files for complete instructions on implementing their classes in
a similar fashion.  This is all public domain, so you can also include
TVCOLR.ZIP as part of the registered/distributable version of your files if
you wanted to.

Maintenance of TVCOLR.H
=======================
    A thought occured to me after I uploaded these files the first time.
That is, if everyone adds their own colors to TVCOLR.H and distributes their
classes as shareware or freeware, there will be a number of conflicting
headers.  If the source code to those files is provided, it is easy enough
to resolve any conflicts between the color indices.  However, if no source
code is provided, as is the case with shareware classes, there may be
problems.
    I am now volunteering to maintain a standard TVCOLR.H file.  If you are
planning to distribute a new set of classes which add colors to TVCOLR.H,
notify me of your additions and I will update these files, send you the most
recent copy of TVCOLR.H with those changes, and notify anyone else who is
interested that a new version is available.  I am currently planning to
upload two of my own creations within the next couple of weeks.  That is the
main reason for this update.  The TVCOLR.H contained in this release has new
colors for a message viewer class and an editor indicator class that are a
part of one of these pending uploads (if you've been waiting for a
replacement of the TEditor classes, watch for TVE1B3.ZIP/TVE1B4.ZIP...).

*******************************************************************************

    Well, I hope you find this useful.  I'd appreciate any feedback,
comments, suggestions, questions, etc that you may have on the changes I
implemented.  I can be reached on CompuServe E-Mail at 72134,1150 or by
posting a message in Section 11 (Turbo Vision) of the BCPPDOS forum.
Thanks.

Eric Woodruff,  CIS ID: 72134,1150
Tue 02/08/94 14:51:40