================================================
README.TXT FOR LCKOWL.DLL Version 1.5

This product was developed by LCK
Consulting as shareware for general use.
This software and associated
documentation are provided "as-is" and
without any express or implied
warranties whatsoever.  The user is
advised to test the program thoroughly
before relying on it.  The user assumes
the entire risk of using the program.

================================================

Company Information:

     Larry Klein
     Principal
     LCK Consulting
     732 Symphony Woods Drive
     Silver Spring, MD  20901
     Phone: 301-593-2745
     Fax: 301-593-4262


If this program is utilized to your
satisfaction, a $20 shareware fee can be
sent to the above address.  This fee
will go towards upgrading the product.
Your name and address will be placed on
a mailing list for further upgrades.
Where possible, include any bulletin
board address to which notifications can
be sent.

================================================


Introduction
============

LCKOWL is a set of tools that were written to simplify
managing windows that have more than just the basic
Microsoft Windows components.  LCKOWL is an extension of
Borland's OWL library.  In this release, LCKOWL includes
five OWL-derived window classes:

     o    TMDIFrameTools - based on TMDIFrame, this class
          automatically manages a status bar, a tool bar and
          a tool box.  The status bar, tool bar and tool box
          are based on Drover's Toolbox controls.
          TMDIFrameTools also manages groups of child
          windows that have been created using the other
          windows classes that come in this DLL.  When an
          MDI child window is created using one of the
          accompanying TWindow-derived classes, the user can
          easily group similar windows for specific
          functions, including counting and closing a group
          of child windows.
     
     o    TWindowTools - based on TWindow, this class
          extends TWindow in a number of areas.  The class
          provides built-in support for managing a status
          bar, tool bar and toolbox.  As an MDI child
          window, it can be set as a non-resizable window,
          preventing the user from resizing or maximizing
          the window.  Also as an MDI child window the user
          can set a menu associated to it so that when it
          receives focus the frame menu will change to the
          window's menu, and back to the frame menu when it
          looses focus.  Additionally, the class registers
          itself by its title, so that an icon in the
          resource (.RC or .RES) file that shares the title
          name becomes the icon for this window, and any
          other window with an identical name.
     
     o    TMDIChildWindow - based on TWindowTools, this
          class is designed to be used when you need an MDI
          window that includes a dialog box.  The window is
          automatically set not to be resized, and uses a
          parameter that automatically opens a child dialog
          within itself  (using TMDIChildDialog described
          below).  The class automatically manages resizing
          the window at startup, to match that of the dialog
          it contains.  Though the user can't resize the
          window using the keyboard, using the MDI messages
          that cascade and retile child windows a WM_SIZE
          message must be processed, in which case the class
          automatically ensures that the window remains the
          same size as the dialog it contains.
          Additionally, the window manages the focus problem
          inherent in having a dialog box within a MDI child
          window.  NOTE: there is a bug within this version:
          YOU MUST PRESS A KEY FIRST TO START THE TAB KEY
          WORKING IN THE DIALOG BOX.  Because this class is
          derived from TWindowTools, it also supports
          automatic management of status bar, tool bar and
          tool box controls within its window, as well as
          menu management.
     
     o    TMDIChildDialog - based on TDialog, this class is
          used with TMDIChildWindow to manage the focus
          issue of having a dialog within an MDI child
          window.  Additionally, the cancel and OK requests
          within the dialog box automatically close the
          window in which the dialog box is located, in
          addition to the dialog itself.
     
     o    TWindowTable - based on TWindowTools, this class
          manages a table (spreadsheet) that wholly occupies
          the window.  The table control is Protoview's
          Datatable control.  This class manages several
          aspects of the table control, including pure
          virtual functions that can be overloaded for when
          a user double clicks on a row, or when the user
          changes or highlights a row.

Drover's Toolbox can be purchased from FarPoint Technologies
or from any number of software vendors that specialize in
software for developers.  FarPoint can be reached at (614)
765-4333.  If you call FarPoint, please let Tamara Calaway
(Director of Marketing) know that I referred you, and
if there is enough of a response I might be able to get them
to agree that I include more of Drover's toolkit on a review
basis in my next version.

Datatable can be purchased from Protoview Development
Corporation or from any number of software vendors that
specialize in software for developers.  Protoview can be
reached at (908) 329-8588.

NOTE: BOTH FARPOINT TECHNOLOGIES AND PROTOVIEW HAVE AGREED
TO ALLOW THEIR DLL'S AND A PORTION OF THEIR HEADER AND
LIBRARY FILES TO BE INCLUDED IN THIS PACKAGE.  THIS IS NOT
TO BE TAKEN AS A SALE OF THEIR PRODUCT.  THE ENCLOSED
PACKAGE DOES NOT INCLUDE PORTIONS OF THEIR PRODUCT THAT ARE
NECESSARY TO EXTEND THE TOOLS PROVIDED.  IT IS EXPECTED THAT
ANYONE WHO USES EITHER OR BOTH OF THESE PRODUCTS WILL
PURCHASE THEM AS REQUIRED.

NOTE:  There are other toolkits available for the types of
controls that are implemented in this toolkit.  Because of
the way in which the classes are set up, it should be
relatively straightforward to swap toolkits for the controls
used.


Installation
============

Copy the enclosed .ZIP file to a first-level directory and
unzip.  If this has already been unzipped and is not in a
first-level directory, copy the files into a first-level
directory.

COPY ALL DLLs INTO A DIRECTORY ON YOUR PATH, OR PREFERABLY
INTO THE WINDOWS (typically \windows\) DIRECTORY OR THE
WINDOWS SYSTEM (typically \windows\system\) DIRECTORY.  IF
THE DLLs ARE NOT COPIED INTO ONE OF THESE DIRECTORIES,
LCKOWL.DLL AND GENMDIX.EXE WILL NOT KNOW WHERE TO FIND
SUPPORTING DLLS.

NOTE: If the files are not in a first level directory, the
project will have to be edited so that the references to the
project files match the directories in which they are
located.

NOTE: If Borland's C++ files were not installed in the
default \borlandc\ directory, you will have to update the
Options | Directories in the IDE so that the header and
library files point to the correct locations.


Quick Explanation
==================

To start, I suggest you first run the enclosed GENMDIX.EXE
application.  It contains the features that demonstrate the
functionality available in LCKOWL.DLL.  GENMDIX.EXE also
serves as a shell MDI application, and can therefore be used
as a basis for creating an OWL-based MDI applications with
status bar, toolbar and toolbox, and any or all of the
enclosed OWL-derived windows.


Description of Menu Options in GENMDIX.EXE
------------------------------------------

     File | New Window   - Creates a new child window.  The
               purpose of this menu option is to demonstrate
               TWindowTools.  The window supports a child
               window that manages a status bar, tool bar
               and tool box of its own.  Also, it supports
               its own menu (AlternateMenu1 in the resource
               file).
     
     File | New Window With Dialog - Creates a new child
               window that contains an embedded dialog box.
               Demonstrates TMDIChildWindow working with
               TMDIChildDialog.
     
     File | New Window With Table - Creates a new child
               window that contains an embedded spreadsheet
               control.  Demonstrates TWindowTable.
     
     File | How Many Windows of Type - allows user to
               display in a dialog box the number of windows
               that the user designated with a certain ID.
     
     File | Close All Windows of Type - allows user to close
               all windows that the user designated with a
               certain ID.
     
     File | Enter Status Bar Text  - Accepts any character
               string that will be displayed in the first
               status bar field.  This option is only tied
               to the frame window status bar.
     
     File | Enter Status Bar Progress   - Accepts any
               numeric value that will show as a percentage
               progress on the second status bar field.
               This option is only tied to the frame window
               status bar.
     
     Options | Create... - Creates appropriate control.  If
               the focus is on the frame, then the control
               is created in the frame.  Otherwise, it is
               created in the child window that has the
               current focus.
     
     Options | Destroy...     - Destroys appropriate
               control.  If the focus is on the frame, then
               the control is destroyed in the frame.
               Otherwise, it is destroyed in the child
               window that has the current focus.
     
     Options | Toggle... - Toggles appropriate control.  If
               the focus is on the frame, then the control
               is toggled in the frame.  Otherwise, it is
               toggled in the child window that has the
               current focus.
     
     Windows...     - Standard MDI windows routines


     Explanation of TMDIFrameTools Functions
     ---------------------------------------

OWL has certain menu IDs that are reserved so that OWL can
automatically manage certain functions, without the
developer having to code anything.  For example,
CM_CASCADECHILDREN automatically cascades child MDI windows
without having to code a line in the header or source file.
Simply add this as a menu option, derive your MDI window
from TMDIFrame and OWL will take care of cascading children.
(NOTE:  You must add OWLRC.H to your resource so that the
Resource Workshop will recognize these menu IDs).

Similarly, TMDIFrameTools has several menu options that
automatically manage status bar, toolbar and toolbox
functionality.  To get these menu IDs to work in your
resource (.RC) file, add the header file LCKOWL2.H to your
resource (File | Add To Project from the Resource Workshop
menu).  By deriving your MDI window from TMDIFrameTools
(which is itself derived from TMDIFrame), the following menu
IDs will automatically work:

     IDM_CREATESTATUSBAR
     IDM_CREATETOOLBAR
     IDM_CREATETOOLBOX
     IDM_DESTROYSTATUSBAR
     IDM_DESTROYTOOLBAR
     IDM_DESTROYTOOLBOX
     IDM_TOGGLESTATUSBAR
     IDM_TOGGLETOOLBAR
     IDM_TOGGLETOOLBOX

Also, these menu IDs will work on any MDI child windows
derived from one of the window classes in this toolkit.

The management of the status bar, tool bar and tool box is
demonstrated in the GENMDIX.EXE application that is
enclosed.  GENMDIX.EXE does not actually have any code
associated with managing these MDI features, except to
initialize them.

TMDIFrameTools also manages its child windows as groups, by
providing two functions that count and close child windows
as a group.  By using the other window classes in this
toolkit that automatically stamp a window with an ID,
TMDIFrameTools can count or close all windows that are
stamped with identical IDs.  An ID is any number assigned by
the developer.  GENMDIX.EXE demonstrates this feature by
allowing a user to open a window and assigning it an ID of
the user's choice, and then offering the user menu options
to count or close all windows with identical IDs.  In this
way a developer can manage groups of child windows easily
within an MDI application.  An additional useful function
gets the first child window that matches an ID.



     Explanation of TWindowTools Functions
     -------------------------------------

TWindowTools is designed to supply the status bar, tool bar
and tool box functionality found in TMDIFrameTools.  It can
also be set so that the user cannot resize or maximize the
window.  The user can also register a menu to attach to the
window.  When the window gets the focus, the MDI frame will
change to this menu, and then back to the original frame
menu when the window looses focus.


     Explanation of TMDIChildWindow Functions
     ----------------------------------------

TMDIChildWindow is used if you want to use an MDI child
window with a dialog in it.  This class greatly simplifies
creating MDI child windows using dialog resources that can
easily be painted using Resource Workshop or a similar tool,
rather than painting the window directly.  This class
automatically manages the sizing of the window to match that
of the dialog box.  NOTE:  by default this class expects a
TMDIChildDialog-base dialog, and the dialog should be
created using the Child and No Border options in the
Resource Workshop.  This class also manages focus, so that
focus passes to the controls of the dialog within the
window.  Since TMDIChildWindow is based on TWindowTools, it
supports status bar, tool bar and tool box controls, as well
as menu management.


     Explanation of TMDIChildDialog Functions
     ----------------------------------------

TMDIChildDialog is designed to work with TMDIChildWindow so
that focus is properly passed to the controls of the dialog
when the dialog resides in a MDI window.  This class also
manages the cancel and OK buttons, so that they properly
close the window when the dialog is closed.


     Explanation of TWindowTable Functions
     -------------------------------------

TWindowTable creates and manages a spreadsheet control that
wholly occupies the window.  It has two pure virtual
functions that are called when the user double clicks on a
row, or when the user changes the row or selection.  Since
TWindowTable is based on TWindowTools, it supports status
bar, tool bar and tool box controls, as well as menu
management.



     Explanation of Tying Buttons to Menu Commands
     ----------------------------------------------

This is automatic, so long as the ID used for a button is
the same as the ID for a menu option.  This relieves the
programmer from any extra coding.  In GENMDIX.EXE, I used
BM1 to represent the File | Enter Status Bar Text, and BM2
to represent File | Enter Status Bar Progress.  The only
requirement was that BM1 and BM2 have the same ID as the
menu options they represent.  You set the ID of a button in
the source file when creating the structure that represents
the toolbar and toolbox.  GENMDIX.CPP contains an example.


Brief Technical Directions on Using LCKOWL.DLL
===============================================

1.   Copy ALL the files of this package into a first level
     directory.  Copy ALL DLLs into the \windows or
     \windows\system directory.
2.   Add the header file TDROVER.H to your source file.  The
     reason this is necessary is because you need some
     identifiers to use the LCKOWL.H file, which in turn
     uses identifiers from toolbox.h, which I could not
     include in this package.  I have therefore included
     only the relevant identifiers in TDROVER.H.  If you
     purchase Drover's toolbox, replace this file with
     toolbox.h (make sure to use the expression extern "C"
     {toolbox.h } when compiling in C++)
3.   Add the header file LCKOWL.H to your source
4.   Add the header file LCKOWL2.H to your resource file
5.   Derive your MDI Frame from TMDIFrameTools
6.   Derive your MDI child window from either TLCKWindow,
     TMDIChildWindow, or TWindowTable, depending on the
     required functionality
7.   Initialize the status bar, tool bar or tool box
     controls in the window constructor of your
     TMDIFrameTools class or any of the TWindow-based
     classes using the Init... functions (see GENMDIX.EXE
     for an example).  Follow the format that's found in
     GENMDIX.CPP for creating structures for a status bar,
     tool bar and tool box to be used in the Init...
     functions.  Set any menus using the format found in the
     TMyWindowTools constructor.
8.   Add LCKOWL.LIB to your project
9.   If you use Borland-style dialogs, add BWCC.LIB to your
     project and call BWCCGetVersion() at the start of your
     program
10.  Add the menu options for status bar, toolbar and
     toolbox creation and destruction that are relevant to
     your application
11.  Compile and have fun running your application!



What Is Included
================

This version includes two projects: LCKOWL.PRJ and
GENMDIX.EXE.

The LCKOWL project includes all the source code and other
files to create LCKOWL.DLL, except for the Drover's Toolbox
header and library files.  In order to revise and recompile
LCKOWL.PRJ, you will need to purchase the Drover's Toolbox.
However, because the Drover Toolbox DLLs are distributable,
LCKOWL.DLL can be used as-is since all the necessary
Drover's Toolbox DLLs are included.

The GENMDIX.PRJ includes all the files necessary to compile
a general purpose Windows program that includes a status
bar, a tool bar and a toolbox.  The executable, GENMDIX.EXE,
is a fully functional MDI application that makes use of all
the functions available in LCKOWL.DLL.  You can use
GENMDIX.PRJ directly, adding the necessary functionality to
complete an application of your own.  I suggest that you
copy GENMDIX.PRJ (all files beginning with GENMDIX*.*) to
another directory, so that you can have a clean version for
a second application.  Note that the Options | Directories
expect Borland files to be in the default \borlandc\
directory.  Also note that the project expects to be in a
first-level subdirectory, which means that if you copy this
to another level directory, you will have to change the
locations of the project files.

This version includes LCKUTIL.DLL, which is used by
LCKOWL.DLL to centrally process standard messages, and to
provide a central location for commonly used functions that
are not available in standard libraries or Windows (such as
word-, rather than string-, oriented functions, and some
file and directory functions).


Further Description of the TMDIFrameTools in LCKOWL.DLL and
its Associated Project
============================================================
===

To use TMDIFrameTools, simply specify TMDIFrameTools instead
of TMDIFrame when you derive your own MDI Frame class.
Then, to use any of the controls, simply initialize
whichever or all the three controls using the InitStatusBar,
InitToolBar or InitToolBox functions functions.  A good
example of how to do this can be found in the GENMDIX.PRJ
project.  The rest is managed automatically.

What exactly is being managed?  When a statusbar or toolbar
is created, the client area must be adjusted so that a new
window does not overlap the statusbar or toolbar.  In other
words, the statusbar and toolbar must be the topmost window
within the MDI frame.  Further, when the frame is resized
the statusbar and toolbar must be resized accordingly, along
with the client area.  If the user clicks on any of the
buttons on the toolbar or toolbox, then if the ID of the
button matches that of a menu item the menu option should be
initiated.  There should be an easy way of updating text in
the status bar, or if the status bar has a progress line,
then the percentage filled should be easily updated.
Finally, there should be an easy way to have these controls
created, destroyed and toggled on or off using a menu
option.  All this is managed by TMDIFrameTools!

To accomplish the last task, that of creating, destroying
and toggling these controls, I have designated menu IDs to
accomplish this along with their identifiers in LCKOWL2.H.
To get these effects with no programming effort, include
LCKOWL2.H in your resource file, and use those IDs for their
appropriate menu items (refer to GENMDIX.RC for an example).
Once these menu IDs are used, TMDIFrameTools manages the
rest automatically.


More Questions, Suggestions, Criticisms
=======================================

Please call me at (301) 593-2745, or fax me at (301) 593-
2745, or send me a message on Compuserve at 76330,2525.

