                  Custom Control Library Documentation

This file contains information useful to you if you intend to use the
file CtrlDLL.DLL and the Percent Complete control included in it in your
own programs.  You should read file this before you use the code.  If
you use this code for any of your own programs and find any bugs in it,
please let me know.

FILES IN THE ARCHIVE
====================

The following files should have been included in the archive when you
downloaded it:

CUSTCTRL.TXT                             This file.
PERCENT  BMP      406  11-09-91   9:40a  Bitmap for RW tool bar
PERCENT  CUR      326  11-09-91  10:23a  Cursor for RW
CTRLCOMM INC     1133  11-10-91   7:35p  Include file for RW & programs
CTLDLLIM PAS      126   9-15-91   6:40p  Unit to use with TESTIT.PAS
CTRLCOMM PAS     1504  11-09-91  11:59a  DLL common declarations unit
CTRLDLGS PAS     3193  11-10-91  11:28p  Control style dialog unit
CTRLDLL  PAS    13761  11-10-91  11:28p  Main DLL source file
CTRLFLAG PAS     1514  11-10-91  11:30p  Control flag proc unit
CTRLINFO PAS     2874  11-10-91  11:28p  Control information unit
CTRLINIT PAS     3833  11-10-91  11:28p  DLL initialization unit
CUSTCNTL PAS     2248  11-10-91  11:29p  Custom Control definitions
PERCENTC PAS     1891  11-10-91   9:52p  WObjects compatible unit
TESTIT   PAS     7919  11-07-91   9:10p  Test program for the % control
WNDFNPER PAS    16477  11-10-91  11:29p  Percent control window proc
CTRLDLL  RC      2334  11-10-91   7:35p  Resource script for DLL
TESTIT   RC      1766  11-07-91   7:26p  Resource script for test prog.


INSTALLING THE SOURCE CODE
==========================

After unzipping the archive, should place all the source files for the
DLL into the same directory.  Development was done in the directory
C:\PROGRAMS\UNITS, but you may place the code in any directory that
suits your working habits.  Just be sure that TPW is configured properly
to find and place all .PAS, .INC, .TPU, and .DLL files.

COMPILING THE LIBRARY
=====================

When you compile the library, be sure to MAKE or BUILD the file
CTRLDLL.PAS within the TPW Integrated Development Environment.  The
compiler will then automatically compile all source files and build a
.DLL file.  Once this is done, you can now write programs that use the
control class defined in the DLL.

This code is intended for use with Borland International's Turbo Pascal
for Windows compiler.  It was specifically written for use with the
version 1.0 product.  Compatibility with future versions of the compiler
is not guaranteed by the author.  Attempting to compile this code for
any other environment is not recommended.

Make sure you place the compiled DLL file in a directory on your path.
This will make it easier for a program that uses the DLL to find it and
load it.  Remember, if Windows can't find the DLL file, it will prompt
you to place a disk in A:, which probably won't be of much help!

USING THE PERCENT COMPLETE CONTROL
==================================

The discussion of using the Percent Complete Control is divided into
three parts, as follows:

1. Control styles defined & their effects on an instance
2. User interface considerations
3. Programming considerations


1. Control Styles
-----------------

A Percent Complete Control is composed of several parts.  The control
draws them from the top down.  The parts, in order from top to bottom,
are:  an optional caption, a bar showing the current percent setting of
the control, an optional digital display of the current percent setting
in the middle of the bar, optional tickmarks in either 10%, 25%, or 50%
gradations, and an optional axis labeling each of the tickmarks.

The control defines 5 different style identifiers, which may be used in
various combinations.  These identifiers and their effects are:

Pct_10Grads     Draws percentage tickmarks at 10% gradations
Pct_25Grads     Draws percentage tickmarks at 25% gradations
Pct_50Grads     Draws percentage tickmarks at 50% gradations
Pct_DrawAxis    Draws an axis under the tickmarks.
Pct_DrawPct     Draws the percentage as "x^" in the center of the bar

Note that Pct_10Grads, Pct_25Grads, and Pct_50Grads are all mutually
exlusive styles.  You can use one or none of these identifiers in the
window style of an instance of the control.  Not using any of them
causes the control to not draw any tickmarks, while using one of them
causes it to draw tick marks in the gradations indicated.

You should also not use Pct_DrawAxis if you do not also use one of the
tickmark styles.  It makes no sense to draw an axis if you don't also
draw tickmarks!

Finally, Pct_DrawPct may be freely mixed with any of the other styles.

The control always has a percentage complete bar, whose height is
dependent on whether or not there is a caption, and on which styles have
been set for the control.  The following paragraphs detail the effects
of certain combinations on the height of the bar.

Specifying a caption:  Specifying a caption causes the control to leave
                       space above it for the caption plus some white
                       space to separate the caption from the top of the
                       control's area & from the percent complete bar.

No styles specified :  Not specifying any of the styles will cause the
                       control to draw itself as a solid bar across the
                       entire width of the control.  The bar's height
                       will be the height of the control minus any space
                       required by the control's caption and any white
                       space needed to separate it from the bar.

Pct_XXGrads:           Specifying one of these three styles causes the
                       control to leave room beneath the bar for
                       tickmarks four dialog units high.

Pct_DrawAxis:          Specifying this style causes the control to leave
                       additional room beneath the control to draw an
                       axis 8 dialog units high, plus some additional
                       white space to separate the axis text from the
                       bottom of the control's space.  The bar's width
                       is decreased by 20 dialog units to allow the axis
                       to fit within the control's space.

Pct_DrawPct:           Specifying this style has no effect on the height
                       of the percentage complete bar.

The following paragraphs briefly describe the algorithms used by the
control when it draws itself on the screen.

The control responds to the wm_EraseBackground message.  When this
message is processed, the control sends the wm_CtlColor message to its
parent.  This allows your dialog boxes to exert control over the
appearance of the control by specifying the brush the control will use
to erase its background.  In addition, if the control's background is
not to use the stock white brush, the control will draw a 3D depression
around itself before it draws itself.  This allows the control to be
used BorDlg dialogs without using a group shade box to enclose the
control.

The appearance of the percentage bar is modeled after that of the same
type of control used in the Norton Desktop for Windows.  When it is
drawn, the bar has a 3D button-like appearance.  The global system
colors COLOR_BUTTON, COLOR_WINDOW, & COLOR_BTNSHADOW are used to
determine the face color of the button and the colors to use for the
button shadow & highlight.  At 0 percent, the control appears to be a
trough in the dialog display; as the percentage approaches 100%, the bar
comes closer to appearing as a complete button.

Any caption, percentage complete digits, tickmarks, and axis labels are
drawn using the pen currently selected in the window's DC.  That is, the
pen that's specified in the DC when the BeginPaint procedure returns.  I
believe this pen may be set by the control's parent, which is why the
control does not change the pen at this time.


2. User Interface
-----------------

The Percent Complete Control is a passive control window class that is
intended to only display data.  As such, the control does not respond to
any mouse or keyboard messages, and should never receive the input
focus.


3. Programming Considerations
-----------------------------

When an instance of the control is created, it will show 0% complete.
Since the control does not accept keyboard or mouse input, a problem
presents itself.  That is, how do you change the percentage displayed?

To change the percentage value currently displayed by the control, you
use one of 4 different messages the control recognizes.  These messages
and their meanings are:

pcm_ResetPercent:       Reset percentage displayed to 0.
pcm_AddPercent:         Add wParam (signed) percent to the value displayed.
pcm_GetPercent:         Control returns value displayed.
pcm_SetPercent:         Set value displayed to an arbitrary value.

Note that the percentage displayed may never be below 0 or above 100.
Also, the percentage is stored as an integer value, so the control is
not capable of displaying 50.5% complete, as an example.

Two units are provided in the archive which enable your programs to use
the percentage control.  One is in the file PERCENTC.PAS, and the other
is in CTRLDLLIM.PAS.  Both of these files are provided for two different
purposes, as explained below.

Using CTRLDLLIM.PAS
-------------------

The CTRLDLLIM.PAS unit is intended to be used by programs like RW that
must import the DLL and gain direct access to the routines in the DLL.
Note that this is probably not very useful in most circumstances, since
RW & the MS SDK program DIALOG.EXE don't need or use this interface!  It
is provided to allow TESTIT.EXE to run, and can be used if you find you
need it for a program.

Note that the CenterPopup routine exported by the DLL may come in handy
in your own programs.  It is intended to be used by popup windows, such
as dialog boxes, either modal or modeless.  The procedure takes the
handle to a window and a handle to that window's device context (DC) as
parameters.  The routine automatically centers the dialog box either
within the borders of its parent/owner window (if the parent is big
enough to completely contain the popup window), or within the screen in
the event the parent/owner window does not completely contain the popup.

The code included in CenterPopup is a Pascal translation of a C routine
written by Kevin P. Welch & included in an article he wrote in the July
1990 issue of MSJ.

Using PERCENTC.PAS
------------------

The PERCENTC.PAS unit implements an ObjectWindows class called
TPercentCtrl.  This control is a descendant of TControl and allows any
OWL program to use this control.  The class defines methods
corresponding to the 4 custom messages the control implements.


COPYRIGHT INFORMATION
=====================

All code in this unit is the property of Anthony M. Vitabile, Copyright
1991.  You may use this code in your own programs provided you include
the above copyright notice.

Please note that the code included in the files that make up the DLL is
provided "as-is."  I'll gladly allow anyone to use this code, but I
don't make any warranties or guarantees about its fitness for anything.


         ----------------end-of-author's-documentation---------------

                         Software Library Information:

                    This disk copy provided as a service of

                           Public (software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  PsL cannot debug pro-
         programs over the telephone, though we can answer questions.

         Disks in the PsL are updated  monthly,  so if you did not get
         this disk directly from the PsL, you should be aware that the
         files in this set may no longer be the current versions. Also,
         if you got this disk from another vendor and are having prob-
         lems,  be aware that  some files may have become corrupted or
         lost by that vendor. Get a current, working disk from PsL.

         For a copy of the latest monthly software library newsletter
         and a list of the 3,000+ disks in the library, call or write

                           Public (software) Library
                               P.O.Box 35705 - F
                            Houston, TX 77235-5705

                                 Orders only:
                                1-800-2424-PSL
                              MC/Visa/AmEx/Discover

                          Outside of U.S. or in Texas
                          or for general information,
                              Call 1-713-524-6394

                          PsL also has an outstanding
                          catalog for the Macintosh.


