toolwnd.dll - ToolBar/ToolBox creator for Windows 3.0
=====================================================
This is a DLL which allows you to create great looking toolbars and toolboxes
similar to those found in such programs as Microsoft(R) Excel, Microsoft(R) Word,
and Microsoft(R) Visual Basic.  If you can draw a bitmap (or have someone else
draw one), you can use toolwnd.dll to create the nice toolbar or toolbox you've
always wanted for your application.  The only other DLL I've seen which allows
you to do this is almost $300, and that doesn't even include source code!  This
DLL may not be as fancy but it is extremely fast and it's only $35
($75 with source). A demo program with source has been included to show the
power of such a DLL. For those of you who have been waiting for this, sorry
about the wait!

This readme file contains the following information:

   1) A brief description of how to create great looking bitmaps that the
      DLL will use to draw the toolbar/toolbox.

   2) Two methods of accessing the DLL.

   3) Detailed descriptions of DLL functions and structure definitions.

   4) Ordering information.


I. Drawing the bitmap
=====================
The bitmap for a toolbar or toolbox contains pictures for each tool in each of
its possible states.  If your application will run on EGA or monochrome
monitors, you will need a separate bitmap for each monitor type.  The bitmaps
included with the demo application were designed for VGA (color or monochrome).

Toolbar
-------
   The toolbar bitmap consists of (nTools * tool_width) columns and
   (4 * tool_height) rows.  Each tool in the toolbar is represented by 4
   possible states: normal, down, selected and disabled.  For the bitmaps
   included with the demo, the width of each tool is 24 and the height of
   each tool is 22.  This seems to be the optimal dimensions for VGA.

Toolbox
-------
   The toolbox bitmap consists of (nTools * tool_width) columns and
   (3 * tool_height) rows.  Each tool in the toolbox is represented by 3
   possible states: normal, selected and disabled.  For the bitmaps included
   with the demo, the width and height of each tool is 28.  The tools look
   best if they are square.  This is left to your discretion.

The best way to see how the bitmap is drawn is to look at the four bitmaps
which come with the demo program.  They are:

   clr1.bmp    Contains the color bitmap for the toolbox.
   clr2.bmp    Contains the color bitmap for the toolbar.
   bw1.bmp     Contains the black and white bitmap for the toolbox.
   bw2.bmp     Contains the black and white bitmap for the toolbar.

Since you control how each tool looks in each of its states, you can be very
creative in determining how your toolbar or toolbox looks.  Some of the pictures
I used are actually "borrowed" from other applications.  I used the Borland
Resource Workshop to extract them and then "cut" and "paste" them using another
paint program to form one bitmap.  Use whatever tools are available to you.  You
are limited only by what your paint program can do.

II. Two methods of accessing the DLL.
=====================================
There are 2 methods of accessing the functions in toolwnd.dll.

   Method 1
   --------
   Add the file toolwnd.lib to your link line.  This is the easiest method
   but causes the DLL to be loaded as soon as your application starts.  The
   lib file contains all of the exported functions for toolwnd.dll.

   Method 2
   --------
   In you code, make an explicit call to LoadLibrary() to load the DLL.  This
   can be done in the WM_CREATE case for you main window procedure.  The DLL
   must then be unloaded in the WM_DESTROY case for your main window procedure.

      case WM_CREATE:
         hLib = LoadLibrary((LPSTR)"toolwnd.dll");

         if (hLib < 32)
            break;                           /* This means the load failed */

         .
         .
         .

      case WM_DESTROY:
         if (hLib)                           /* If the library was loaded, */
            hLib = FreeLibrary(hLib);        /* free it */
         break;

   Note: The file "toolwnd.dll" must be either in the directory where your
         application is being run from or in some directory where Windows will
         find it. (i.e. c:\windows, c:\windows\system etc.)

III. Function/Structure definitions and descriptions.
================================================
HWND CreateToolbox(hWnd,hbmTools,nTools,x,y,cx,cy,fVisible,lptInfo)

   This function creates a toolbox window.

   Parameter   Type/Description
   ---------   ----------------
   hWnd        HWND-Identifies the parent or owner of the toolbox.
               Note:  The toolbox must have a parent window!

   hbmTools    HBITMAP-Specifies a handle to the bitmap which
               contains the tools.

   nTools      int-Specifies the number of tools in the toolbox.

   x           short-Specifies the starting x position (in
               client coordinates) for the toolbox.

   y           short-Specifies the starting y position (in
               client coordinates) for the toolbox.

   cx          short-Specifies the number of columns in the
               toolbox.

   cy          short-Specifies the numner of rows in the
               toolbox.

   fVisible    BOOL-Specifies whether or not to show the toolbox.

   lptInfo     LPTOOLINFO-Specifies a pointer to a TOOLINFO
               structure.  (See description of TOOLINFO structure below.)

Return Value   The return value identifies the new toolbox window.  It is NULL
               if the window could not be created.

===============================================================================
HWND CreateToolbar(hWnd,hbmTools,nTools,fVisible,lptInfo)

   This function creates a toolbar window.

   Parameter   Type/Description
   ---------   ----------------
   hWnd        HWND-Identifies the parent or owner of the toolbar.
               Note:  The toolbar must have a parent window!

   hbmTools    HBITMAP-Specifies a handle to the bitmap which
               contains the tools.

   nTools      int-Specifies the number of tools in the toolbar.

   fVisible    BOOL-Specifies whether or not to show the toolbar.

   lptInfo     LPTOOLINFO-Specifies a pointer to a TOOLINFO
               structure.  (See description of TOOLINFO structure below.)

Return Value   The return value identifies the new toolbar window.  It is NULL
               if the window could not be created.

===============================================================================
BOOL IsToolSelected(hWnd,wId)

   This function determines if the tool specified by the wId parameter is
   selected or not.

   Parameter   Type/Description
   ---------   ----------------
   hWnd        HWND-Identifies a toolbar or toolbox window.

   wId         WORD-Specifies the command id of the desired tool.

Return Value   The return value is TRUE if the given tool is selected, otherwise
               it is FALSE.

===============================================================================
void EnableTool(hWnd,wId,fEnable)

   This function enables or disables the tool specified by the wId parameter.

   Parameter   Type/Description
   ---------   ----------------
   hWnd        HWND-Identifies a toolbar or toolbox window.

   wId         WORD-Specifies the command id of the desired tool.

   fEnable     BOOL-Specifies whether to enable or disable the
               tool.

Return Value   None.

===============================================================================
void ToggleTools(hWnd,wIdFirstTool,wIdLastTool,wIdCheckTool)
                                                        
   This function selects the tool specified by the wIdCheckTool parameter.
   It removes the selection from all other tools in the group of tools
   specified by the wIdFirstTool and wIdLastTool parameters.

   Parameter      Type/Description
   ---------      ----------------
   hWnd           HWND-Identifies a toolbar or toolbox window.

   wIdFirstTool   WORD-Specifies the id of the first tool in a
                  group.

   wIdLastTool    WORD-Specifies the id of the last tool in a
                  group.

   wIdCheckTool   WORD-Specifies the id of the tool to be checked.

Return Value   None.

===============================================================================
void CheckTool(hWnd,wIdCheck,fCheck)

   This function selects or de-selects the tool specified by the wIdCheck
   parameter.

   Parameter   Type/Description
   ---------   ----------------
   hWnd        HWND-Identifies a toolbar window.

   wIdCheck    WORD-Specifies the id of the tool to be checked.

   fCheck      BOOL-Specifies whether to check or uncheck the
               tool.

Return Value   None.

===============================================================================
TOOLINFO    Structure Description

   The TOOINFO structure provides information to CreateToolbox() or
   CreateToolbar() functions for creating a toolbox or toolbar.

   typedef struct
   {
      WORD wId;
      DWORD dwStyle;
      WORD wState;
      RECT rc;
   } TOOLINFO;

   The TOOLINFO structure has the following fields:

   Field       Description
   -----       -----------
   wId         Specifies the command id for a tool.  The parent window will
               receive a WM_COMMAND message with wParam as this id, whenever
               the tool is clicked or selected.

   dwStyle     This field is used for the toolbar window only.  It specifies
               whether to start a new group with this tool.  It is either
               WS_GROUP or NULL.  A tool with the style of WS_GROUP will
               start 10 pixels from the previous tool.  A tool without this
               style will be placed right next to the previous tool.

   wState      This is used internally by the toolwnd.dll and should be set to
               0.


   rc          This contains the bounding rectangle for each tool.  This field
               is calculated internally by toolwnd.dll and should be set to 0.

===============================================================================
Example:

   The following is an example of how to initialize a TOOLINFO structure and
   call the function CreateToolbar() to create a toolbar window:

   TOOLINFO tInfo[nTools]=
   {
      IDM_TOOL1,WS_GROUP,0,{0,0,0,0},        /* First group of tools */
      IDM_TOOL2,NULL,0,{0,0,0,0},
      IDM_TOOL3,NULL,0,{0,0,0,0},
      IDM_TOOL4,WS_GROUP,0,{0,0,0,0},        /* Start new group */
      .
      .
      .
      IDM_TOOLN,NULL,0,{0,0,0,0}
   };

   hWndToolbar = CreateToolbar(hWnd,hbmTools,nTools,TRUE,(LPTOOLINFO)&tInfo);

IV.  Ordering Information
==========================
To register your royalty free copy of toolwnd.dll send $35.00 check or money
order (sorry no credit cards) to the following address:

   Ray Donahue
   365 Mather Street Unit 125
   Hamden, CT 06514

   Home Phone: (203) 230-9877
   Work Phone: (203) 399-7111

For inquiries or bug reports send Email to the following CompuServe address:

   Ray Donahue [70324,1204]

The source code for toolwnd.dll is also available for $75.00

By registering, you are entitled to any upgrades which become available and
also information on other useful Windows tools.

Currently, the only other tool which is available is three_d.dll which
makes a dialog box have a nice "3-dimensional" look.  A demo of this program
can be found in the WINADV section of CompuServe LIB 1 (New Uploads) or
LIB 12 (Utilities).  Search for keyword 3-D.

Package deals are also available!

Thanks,
Ray Donahue

         ----------------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 4,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



