README.TXT for ToolButton 2.0
December 2, 1992

********************************************************************************
* WARNING *
*
* Users of ToolButton 1.0 or 1.1 must follow these steps to use Version 2.0:
*
*. Load your project(s) into VB 2.0
*. Save all forms with ContextHelp controls as Text
*. Save the project
*. Quit VB
*. Manually edit your .MAK file(s) to change the name of the custom
* control from TOOLBUTT.VBX to TOOLBUTN.VBX
*
* The ContextHelp control had an unavoidable change which is not binary
* compatible with the previous version. If you do not save your forms
* with ContextHelp controls as Text, you will get an "Invalid file format"
* message when you attempt to load the project.
*
* ToolButton 2.0 is *NOT* compatible with VB 1.0.
*
* WARNING *
********************************************************************************

----------------------------------------------------------------
What is ToolButton?
----------------------------------------------------------------
ToolButton is a custom control for Visual Basic that supports
command and attribute buttons in toolbars. You can use the
standard button images supplied, and/or you can "roll your own". A
second custom control, ContextHelp, is bundled with ToolButton to
facilitate implementation of "point and click" style
context-sensitive help.

Standard button images are supplied for Edit Cut, Edit Copy, Edit
Paste, File New, File Open, File Save, File Print, Help, and
Context Sensitive Help.

ToolButton can generate six different button faces from one
supplied bitmap. A command button uses three (Up, Mouse Down, and
Disabled), while an attribute button uses six (former plus Down,
Down Disabled, and Indeterminate). All you have to do is supply
the "Up" bitmap, and ToolButton takes care of the rest.

Another nifty feature of ToolButton is the fact that it generates
MouseDown and MouseUp events, so you can put a help message in a
status bar when the user presses a button. These events are
generated even when the button is disabled.

Microsoft Word for Windows 2.0 was used as a model for the behavior
of ToolButton and ContextHelp. Command buttons behave like Word
toolbar buttons, attribute buttons behave like Word ribbon buttons,
and context-sensitive help behaves in a similar fashion to Shift+F1
in Word.

ToolButton uses the "Buttons & Cursors" (v1.01) code from
Microsoft. This code is currently downloadable as BTNCR2.ZIP from
the WINSDK forum. I do not use the DLL version of this code
because source changes were required to make it compatible with
Windows 3.0.

As mentioned above, ToolButton is compatible with Windows 3.0.
However, the Help Reference requires WinHelp 3.1.

ToolButton is Freeware. You can freely distribute it with your
applications. However, if you distribute source for your
applications, please include an unmodified TOOLBT.ZIP and/or its
component files.

----------------------------------------------------------------
ToolButton Demo
----------------------------------------------------------------
If you would like to see a demonstration of some of ToolButton's
capabilities, load the TOOLDEMO project into Visual Basic. See
"ToolButton Help Reference" below for instructions on how to view
the Help Reference.

TOOLDEMO is a just a dumb Notepad clone. However, it does
demonstrate most of the cool features of ToolButton. Among the
supported features it does *not* demonstrate are:

. Non-standard sized buttons
. Indeterminate attribute button state
. Colorful buttons

----------------------------------------------------------------
ToolButton Help Reference
----------------------------------------------------------------
A complete help reference is provided for ToolButton. You can
access it by double-clicking with the right mouse button on a
ToolButton or ContextHelp control in design mode, by pressing the
help button in TOOLDEMO, or by starting WinHelp manually.

For all standard VB properties, events, and methods, ToolButton
help is linked to the standard VB help file. For this to work,
VB.HLP has to be somewhere on your PATH.

----------------------------------------------------------------
Tips
----------------------------------------------------------------
The ContextHelp control passes the HelpContextID of the control
which the user wants help on. However, if that control doesn't
have a HelpContextID property, or its HelpContextID is 0,
ContextHelp attempts to use its container, then its container's
container, etc. This is similar to the logic used by VB when you
press F1 in your application. You can use this to your advantage
if you have a group of controls which all use the same section of
the help file. For example, if you have a frame containing a bunch
of option buttons, you can assign the HelpContextID of the frame,
and leave the HelpContextID of the option buttons empty. If the
user clicks the frame itself or any of the option buttons, the
result will be the same.

If you want to display a help message in a status bar for each
ToolButton, put the message in the HintMessage property at design
time. Print the help message in the MouseDown event, and clear it
in the MouseUp event. If you have to worry about multiple
languages, load the message at runtime.

Use a control array for all the ToolButtons on a particular toolbar.
This will save you a lot of code. Toolbar buttons are supposed to
just be shortcuts for menu items, so you can put a Select Case on
the index in the Click event, and call the appropriate menu click
subroutine.

Look at the source code for TOOLDEMO. Some tricks are there which
I haven't described above, like sizing and positioning all the
controls based on the display device and the Visual Design Guide;
and interfacing with WinHelp.

----------------------------------------------------------------
Known problems and limitations
----------------------------------------------------------------
No MouseDown or MouseUp events are generated for the middle or
right mouse buttons. This is because I didn't want Click to be
generated for these buttons. I may fix this later by adding a
parameter to the Click and DblClick functions which lets you know
which button was pressed (the standard event functions don't tell
you this).

A few of the links from ToolButton help to VB help aren't quite
right. For example, if you click on Index, you don't get the Index
reference page in VB help. The reason for this is that I am using
a simple JumpKeyword macro, and it just goes to the first topic
containing that keyword (in this case, ListIndex).

----------------------------------------------------------------
Version History
----------------------------------------------------------------

2.0:
. Takes advantage of new VB 2.0 features
. New HelpContextID property for both controls
. ToolButton is now a "graphical" control, to reduce resource
consumption
. ToolButton has new HintMessage property
. ToolButton converts button colors to user preference, based
on Control Panel settings (see Preserve property)
. Contexthelp permits Esc to cancel
. HelpContextID passed instead of Tag in ControlClick event
. ContextHelp now has Index property
. ContextHelp now ignores keystrokes other than Esc, F1
. Bug fix: if multiple applications used Version 1.1 at the
same time, exiting one of them would cause the button faces
on the rest to become blank

1.1:
. ContextHelp custom control added
. Compatible with Windows 3.0
. Sample bitmap for custom buttons supplied
. MouseDown/MouseUp generated for disabled buttons
. Access help reference with double-click of right mouse
button instead of single click
. (About) property
. Over 900 downloads from CompuServe MSBASIC forum

1.0:
. First version
. Over 800 downloads from CompuServe MSBASIC forum

----------------------------------------------------------------
Credits
----------------------------------------------------------------
ToolButton was created by:

Brett Foster [CompuServe: 70444,135]
Fulcrum Technologies, Inc.

Please send comments and questions via Section 6 (VB/Win 3rd Party)
of the CompuServe MSBASIC forum (preferred), or CompuServe mail.

All feedback is GREATLY appreciated!

----------------------------------------------------------------
Supplied Files
----------------------------------------------------------------
TOOLBT.ZIP contains the following files:

. ATTRIBS.BMP- Sample bitmap of custom button faces used in TOOLDEMO
. README.TXT- This file
. TOOLBUTN.HLP- Help reference for ToolButton
. TOOLBUTN.VBX- The ToolButton custom controls
. TOOLCONS.TXT- Global constants
. TOOLDEMO.BAS- BAS file for TOOLDEMO
. TOOLDEMO.FRM- ASCII Form file for TOOLDEMO
. TOOLDEMO.FRX- Binary form info for TOOLDEMO
. TOOLDEMO.MAK- VB project file for TOOLDEMO