Borland Programmer's Resource/Borland_Programmers_Resource_CD_1995.iso/code/bcpp/file18/xpwindlg.doc

Text File | 1995-05-19 | 16.4 KB | 382 lines

               TExplodeWindow and TExplodeDialog Classes

                             Eric Woodruff
                          16719 Lakeside Drive
                         Medical Lake WA 99022

                           CIS ID: 72134,1150

         Copyright (c) 1993, Eric Woodruff, All rights reserved

                         Released: Wed 08/25/93
-------------------------------------------------------------------------------

Description
===========
    These two classes will allow you to add exploding windows and dialog
boxes to your applications.  They are used exactly like normal TWindow
and TDialog objects at instantiation with the exception of their names:
TExplodeWindow and TExplodeDialog.  Once inserted into the desktop, they
will explode when opened (or shown with the show() function) and implode
when closed (or hidden with the hide() function).  This is all done
automatically by the required overridden functions within each class.
Both classes are fully streamable and can reside in a resource file
until needed if you want them to.

    IF YOU USE THESE CLASSES IN YOUR OWN PROGRAMS AND APPLICATIONS,
PLEASE SEND $10 TO ERIC WOODRUFF AT THE ABOVE ADDRESS.  It would be very
much appreciated and I'll try and keep you informed of any bug fixes or
updates.
    Feel free to distribute these files to anyone but, if you do, please
distribute ALL files received in their original UNMODIFIED form
including all source, documentation, executables, and copyright notices.
You may distribute and/or sell any executable which results from using
this code but you may NOT include any source code or library of this
software in part on in whole with any product that is distributed and/or
sold by you.
    If you DO modify the source, make any interesting modifications or
additions, or find any bugs, PLEASE notify me and let me know what you
changed so that I can maintain these classes and distribute the updates.
I can be reached by mail or on CompuServe at the above noted addresses.
Again, if you distribute this set of files, please do so in their original,
unmodified form including all source files and documentation.  Thank
you.
    THIS CODE IS PROVIDED AS-IS AND WITHOUT ANY WARRANTY.  I WILL NOT BE
RESPONSIBLE FOR ANY DAMAGE OR LOSS YOU INCUR THROUGH USE OF THE CODE IN
THESE CLASSES.

Files you should receive in XPWNDG.ZIP
======================================
XPWINDLG.DOC        -  This document containing the instructions.
BLDRSC.CPP          -  Source file for the demo program resource file builder.
BLDRSC.PRJ          -  Project file for the demo program resource file builder.
BLDRSC.EXE          -  Executable for BLDRSC.CPP.
EXPDEMO.H           -  Header file for the demo.
EXPDEMO.CPP         -  Source file for the demo program.
EXPDEMO.PRJ         -  Project file for the demo.
EXPDEMO.EXE         -  Executable for EXPDEMO.CPP.
EXPDEMO.RSC         -  Resource file for the demo.
TEXPLODE.H          -  Header file for TExplodeWindow and TExplodeDialog.
TEXPWIN.CPP         -  Source file for TExplodeWindow.
TEXPDLG.CPP         -  Source file for TExplodeDialog.
TEXPLODE.PRJ        -  Project file used to make TEXPLODE.LIB.
TEXPLODE.LIB        -  Library for inclusion in your Turbo Vision projects.

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

-------------------------------------------------------------------------------

Class Descriptions
==================
    Both classes are basically the same and both have the same member
functions.  The only differences are that one class is a window and the
other is a dialog box, and the underlying code for each does differ
slightly in some cases.  However, the member functions and variables are
identical in usage so one description will do for both classes.

    The following section describes the constructors and inline
functions used to instantiate and manipulate the exploding windows and
dialog boxes.  These are the only functions you need to know about in
order to use these classes.  As stated above, all the internal details
automatically handle the explosion and implosion processes.


TExplodeWindow(const TRect &r, const char *aTitle, short aNumber)
TExplodeDialog(const TRect &r, const char *aTitle)
=================================================================
    These are the constructors for the exploding window and dialog
classes respectively.  Each will invoke the constructor for its base
classes with the given parameters and set themselves to explode and
implode with a default rate of 20ms between draws.

inline void MakeItNormal(void)
==============================
    Call this inline function to suppress the explode/implode process.
If called before being inserted into the desktop or calling the show()
function when hidden, the object will not explode into view and will not
implode on closing.  If called before the window is closed or hidden,
the window will not implode on closing (it won't explode if shown after
a hide() either).  In either case, the window or dialog box will act
like its base class again.

inline void MakeItExplode(short ms)
===================================
    This function is the opposite of the MakeItNormal() function.  It
also has the added feature of allowing you to change the default delay
rate from 20ms to your own desired value.  A valid range is from 0 to
32767, but usually a number less than 100 will suffice.
    By default, the windows and dialog boxes will explode and implode
automatically with a default rate of 20ms.  If this is sufficient, you
will not need to call this function at all.

inline short GetDelay(void)
===========================
    As its name implies, this inline function returns the current draw
delay rate.



    The following section describes the overridden functions that allow
the the windows and dialog boxes to explode and implode correctly.  It
is included for information only and none of the variables or functions
should be used or called directly under normal circumstances with the
exception of the setState(), sizeLimits(), and maybe the changeBounds()
functions.

Private:
========

Boolean  WillExplode, WillImplode, Is_Exploding_Imploding
=========================================================
    These private variables indicate whether or not the window or dialog
will explode or implode and also whether or not the object is currently
in the process of doing one or the other.  They are all used internally
by the classes.

short msDelay
=============
    This private variable controls the delay used between draws when the
object explodes or implodes.  It is set in millisecond increments by the
constructor or the MakeItExplode() member function.  The constructor
defaults it to 20 ms.

void Explode(void)
void Implode(void)
void ExpImpDraw(void)
=====================
    These three private functions control the explode and implode process.
They are controlled totally from within the class and will be invoked at
the proper times when required.  They should never be called directly
except ExpImpDraw() which has a special case described below.


Public:
=======

virtual void setState(ushort aState, Boolean enable)
====================================================
    This virtual function is overridden to catch requests to hide the
window or dialog box.  If such a request is received and the object is
set to implode on closing, it will do so.  It is also set up to explode
when shown again.
    This function is not normally overridden in derived classes, but if
you do derive your own specialized TExplodeWindow class with a new
setState() function, you will at least need to call
TExplodeWindow::setState() before leaving yours or base it on the
existing code.

virtual void changeBounds(const TRect &bounds)
==============================================
    This virtual function is overridden to catch requests to change the
bounds of the object.  During explosion or implosion, this will prevent
calls that would change the bounds of all sub-views.  If this were not
done, their positions would be all messed up when the process finally
completed (this is because their growMode flags may or may not be set).
The only exception to this is the frame of the window or dialog box.
Its size and position are adjusted and drawn along with the window or
dialog.  The effect you get is that as it opens, all the sub-views are
dragged into position.  It's pretty neat to watch.
    This function is not normally overridden in derived classes, but if
you do derive your own specialized TExplodeWindow class with a new
changeBounds() function, you will at least need to call
TExplodeWindow::changeBounds() before leaving yours or, more likely,
base it on the existing code.

void sizeLimits(TPoint &min, TPoint &max)
=========================================
    This virtual function is overridden so that when the window or
dialog box is in the process of exploding or imploding, size limits are
suppressed.  If they were not, the object would never start exploding
below or shrink beyond its minimum view size.

*** NOTE: If you derive a specialized TExplodeWindow class that requires
it's own overridden sizeLimits() function, you *MUST* place your code in
the "else" section of the "if(Is_Exploding_Imploding)" if() block.  If
you don't, your derived exploding window will not work as it should!
The same applies to TExplodeDialog, although overridden sizeLimits()
functions in that case would be rare.

Example:
void TMyOwnExplodeWindow::sizeLimits(TPoint &min, TPoint &max)
{
    // Ignore limits when imploding or exploding.
    if(Is_Exploding_Imploding)
    {
        min.x = min.y = 0;
        max.x = max.y = MAXINT;
    }
    else
    {
        Your size limit code here.
        .
        .
        .
    }
}

virtual void draw(void)
=======================
    Upon opening, the first call to the overridden draw() function will
check the WillExplode flag.  If set to True, the window or dialog box is
exploded to its normal size before the draw resumes.

*** NOTE: If you derive a specialized TExplodeWindow class that requires
it's own overridden draw() function, you *MUST* place your code in the
"else" section of the "if(Is_Exploding_Imploding)" if() block. If you
don't, your derived exploding window will not work as it should!
Usually, it's better to leave the window's draw function alone and
simply insert an interior object.  The same applies to TExplodeDialog,
although overridden draw() functions in that case would be rare.

Example:
void TMyOwnExplodeWindow::draw(void)
{
    // Check for the need to explode.  This will generally only be
    // true just after construction when the window is inserted into
    // the desktop.
    if(WillExplode)
        Explode();

    if(Is_Exploding_Imploding)
        ExpImpDraw();           // Explode or implode draw.
    else
    {
        Your draw code here.
        .
        .
        .
    }
}

virtual void close(void)
========================
    This virtual function is overridden to implode the window or dialog
box upon closing.  If the object's valid() member function says it is
okay to do so, the window or dialog box will implode and destroy itself.
    This function is not normally overridden in derived classes, but if
you do derive your own specialized TExplodeWindow class with a new
close() function, you will at least need to call TExplodeWindow::close()
before leaving yours or base it on the existing code.


Streamable Options
==================
    All of the necessary functions and variables are defined and/or
overridden to allow both classes to be streamed.  When deriving your own
specialize TExplodeWindow and TExplodeDialog classes, don't forget to
override them if you need to save additional variables to the resource
file.  The subject of streams and resource files is too complex to cover
fully in this document.  Refer to the manuals and other tutorials for
more information on them.

-------------------------------------------------------------------------------

Implementation
==============
    To use the TExplodeWindow and TExplodeDialog classes in your own
application, include the following lines at the top of your program
source files where necessary (usually after #include <tv.h>):

    .
    .
    .
#include <tv.h>

#define Uses_TExplodeWindow         // Define if using TExplodeWindow
#define Uses_TExplodeDialog         // Define if using TExplodeDialog
#include <texplode.h>               // Make sure it's in your #include
                                    // path somethere!

// NOTE: Always be sure to include these two lines once somewhere in your
//       program if you are using streamed TExplodeWindow and/or
//       TExplodeDialog objects (i.e. loading them from a resource file)!
__link(RExplodeWindow)
__link(RExplodeDialog)

    If not using a TExplodeWindow or a TExplodeDialog in the current file,
you may exclude the associated #define Uses_XXX line.

    You are then free to use the objects as needed.  Simply instantiate
them as you would any other TWindow or TDialog object but use the
appropriate TExplodeXXXX name instead.

    The last step is to insure that TEXPLODE.LIB is included in your
project and can be found along the default search path for library
files.  Once that's done, just compile your application.

IMPROVING SCREEN UPDATE SPEED
=============================
    This isn't a necessary change, but if you have the Turbo Vision
source code and you haven't already done so, go into TSCREEN.CPP and
change:

Boolean near TScreen::checkSnow = True;

to

Boolean near TScreen::checkSnow = False;

    Recompile this module and replace the TSCREEN.OBJ file in TV.LIB
with the new one.  If you don't have the source or don't want to modify
it, you can always put "TScreen::checkSnow = False" in your
application's constructor so that it is turned off.
    A TI document from Borland noted that this was left as True by
accident and that it will improve screen update performance when set to
False.  IT DOES.  The explode and implode processes are much smoother
and quicker when snow checking is turned OFF.  Not only that, all other
screen updates are faster and smoother too.  Normally, this only gets
set to False if you change screen modes (i.e. to 43/50 line mode) or
you have a monochrome monitor.
    The demos are compiled with my copy of the library that contains
this change.  If you haven't made the change and have an EGA/VGA
monitor, recompile the demo programs, explode a few windows in 25 line
mode, use the Toggle Screen Size option on the Window Menu to go into
43/50 line mode and back to 25 line mode, then explode some more.
You'll see the speed difference the most when exploding the bigger
windows and dialog boxes.

Modeless THelpWindow Fix
========================
    While fixing a bug in the TExplodeWindow class being used as a base
class for THelpWindow, I found the following bug in the Turbo Vision
source code.  If created as a modeless window, THelpWindow can sometimes
cause a program crash.  To fix it, make the following change:

In HELP.CPP around line 266 in THelpViewer::handleEvent() is the case:

case evCommand:
    if ((event.message.command == cmClose) && (owner->state && sfModal != 0))
        {
        endModal(cmClose);
        clearEvent(event);
        }
    break;

The if() statement incorrectly checks for a modal window.  Change it to:

    if((event.message.command == cmClose) && (owner->state & sfModal))
                                                           |
                                                           |
                                                    USE ONLY 1 '&' HERE!!

    Recompile this module and replace the HELP.OBJ file in TV.LIB
with the new one.

-------------------------------------------------------------------------------

Final Notes
===========
    I have included a demo program that uses both the TExplodeWindow and
TExplodeDialog classes in normal form and resource file form.  It's
pretty simplistic, but should give you enough information on using these
classes in an application.

    If you like these classes and have any comments, questions, or
suggestions, I'd like to hear from you.  My mail and CompuServe
addresses can be found at the top of this document.  Thanks for your
interest.

Eric Woodruff,  CIS ID: 72134,1150
Wed 08/25/93 20:21:20