TExplorerButton
===============

Freeware
version 2.4 - Nov 17, 1996
Copyright (c) 1996, Fabrice Deville

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

CONTENTS
========

1. Target platforms
2. Description
3. Installation
4. Properties
5. Events
6. Troubleshooting
7. Read this
8. History
9. Known bugs & problems
10. More informations
11. Contact

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

1. Target platforms
===================

Delphi 1.0 (in the 16bits directory)
Delphi 2.0

2. Description
==============

TExplorerButton is a new button created from scratch. It provides the
same functionality and look-and-feel as the buttons found in the
Internet Explorer 3.0 - and that will obviously become a standard,
as it will be used in the next version of Office.

It is great for end-user products or programs designed for children,
as it provides a good feedback on which button will be pressed.

Its main features are:

   - it is transparent. It allows you to put a picture of your mum
     under yours buttons... Great!

   - the outline of the button is shown only when it has the mouse
     focus. It provides thus a clear feedback on which button will
     be activated if the user presses the mouse button;

   - when the button has not the mouse focus, the bitmap is rendered
     in shades based on the system colors which provides a consistent
     whichever color scheme is installed on the system. However,
     you can still provide the non-focus bitmap;

   - you can link a TPopupMenu with the button. This popup will be
     displayed under the button when the user presses on it;

   - you can control the layout of the button.

   - you can provide a non-focus bitmap, if the shading does not
     please you;
  
   - you can control the type of shading (light, medium or dark).

   - you can provide a disabled bitmap, if the default disabling
     does not please you.

NEW IN VERSION 2.4  

   - wordwrapping.

   - checked buttons can have a pattern.

IMPORTANT NOTES TO PREVIOUS USERS: you have to delete your current
buttons, install the new version and remake your buttons, otherwise
strange things will happen :)

3. Installation
===============

TO INSTALL THE COMPONENT
------------------------
A. Choose the Install option from the component menu.
B. Press the Add Button
C. Select EXPLBTN.DCU changing the path if necessary. The 16bits version is in the 16bits
   directory.
D. Press OK twice.
E. The component is now installed in a new 'Freeware' tab.

TO INSTALL THE HELP FILE
------------------------
A. Copy EXPLBTN.KWF to C:\DELPHI\HELP. The 16bits version in in the 16bits directory.
B. Copy EXPLBTN.HLP to C:\DELPHI\BIN. The 16bits version in in the 16bits directory.
C. Run HelpInst from your Delphi folder.
D. Use File|Open to open C:\DELPHI\BIN\DELPHI.HDX.
E. Use Keywords|Add Keyword File to add C:\DELPHI\HELP\EXPLBTN.KWF.
F. Use File|Save to Compile and save the new HDX file.
G. Online help is now installed.

4. Properties
=============

Apart from common properties, it defines:

- Alignment: specifies the alignement of the caption AND the bitmap.

- AllowAllUp: allows all buttons in the same GroupIndex to be up.

- BevelStyle: allows the control of the outline appearance (raised/sunken).

- Bitmap: this is the bitmap that will be drawn in the button. 
          The transparency color is the color of the top-left pixel 
          (coordinates 0,0).

- DisabledBitmap: bitmap used for the disabled state - optional.

- Down: indicates the button in a group that is pressed down.

- DropDownMenu: this is the popup menu that can be activated by the button.
		Simply drop a TPopupMenu on the form, then do the link.

- GroupIndex: specifies a group of buttons acting like radio-buttons. If
              set to a value different of 0, only one button in the same
              group can be down at a time. To define a check button, simply
              assigned a GroupIndex <> 0 but not shared with other buttons.

- Layout: specifies the layout of the button: blBitmapTop, blBitmapDown,
          blBitmapLeft, blBitmapRight.

- Options: boMonoDisplay: if set to true, a shaded version of the bitmap is
                          shown when the mouse is not over.
           boIconOnly: if set to true, only the bitmap is shown, the
                       caption is copied in the Hint field and the ShowHint
                       property is set to True
           boPopupMark: if set to true, a small icon is shown at the right
                        of the bitmap or the text (if no bitmap exists) when
                        a popup menu is linked to the button

- NonFocusBitmap: bitmap used when the mouse pointer is not on the button.
                  If left empty, automatic shading is performed.

- ShadingType: controls the shading (light, medium or dark).

- ShowDownPattern: shows or not a pattern when the button is checked.

- UnselectedFontColor: sets the font color used when the mouse is not over
                       the button.

5. Events
=========

- OnClick: when the user clicks on the button (strange, no?) This event
           will not be triggered if a popup is attached to the button
	   (see DropDownMenu property above).

- OnDragOver

- OnDragDrop

6. Troubleshooting
==================

Q. My bitmap looks awful!

A. 2 reasons are possible:
 
   - you used a 256 colors bitmap. Be careful with that. Try to
     minimize the number of colors, and to use a common palette for
     all the buttons & bitmaps appearing on the form.
   - do not forget that the transparency color is the color of the
     pixel at coordinates 0,0. It means that all the pixels on the
     bitmap having the same color as the pixel at (0,0) will be
     transparent. Verify your bitmap.

Q. I've created a series of buttons, but the text is not well
   vertically aligned!

A. The bitmap and text are centered in the button. Optimal results are
   obtained when using a series of bitmaps having the same height.

Q. My form takes a lot of time to load !

A. This is certainly due to the fact that you have huge bitmaps in
   your buttons or lots of buttons, and rely on the automatic shading.
   As a solution, you should give your own bitmap for the nonfocus
   state.
   The next version might correct this problem by storing the generated
   shaded bitmap.

Q. The tab, alt-F4 keys and such do not work when the mouse is on a
   TExplorerButton.

A. This is the most important problem. It is due to the capture of the
   mouse. Deep inside the vcl, the key events are not dispatched when
   the capture is done. I succeeded in making the tab key work, but it
   is more a hack than anything else. It might be present in the next
   version, however.

7. Read this
============

WARNING! THE CODE IS PROVIDED AS IS WITH NO GUARANTEES OF ANY KIND!
USE THIS AT YOUR OWN RISK - YOU ARE THE ONLY PERSON RESPONSIBLE FOR
ANY DAMAGE THIS CODE MAY CAUSE - YOU HAVE BEEN WARNED!

8. History
==========

- Nov 17, 1996 - VERSION 2.4 RELEASED
	- enhancements (see present text).
	- bug fixes:
		* drop down menu works as expected: when clicking again
		  on the button, the menu is closed
		* flickering on disabled buttons is eliminated
		* default caption does not come back in design mode
		  when the caption was emptied

- Oct 11, 1996 - VERSION 2.3 RELEASED
        - enhancements (see present text).
        - bug fixes:
                * checkbuttons and radio buttons didn't work properly
                  (bug introduced in version 2.2, shame on me)
                * reduced the number of redraws in case of click

- Oct 5, 1996 - VERSION 2.2 RELEASED
	- enhancements (see present text).
	- bug fixes:
		* incorrect behaviour with Enabled set to False when the
                  mouse is on the button, then Enabled reset to True by
		  other means (it remained focused)
		* Delphi crashed when you deleted a popup linked to a
		  explorer button
		* The Help file is now available for 16-bits users.
		* Demo file fixed for use in 16- and 32-bits.

- Sep 9, 1996 - VERSION 2.1 RELEASED
	- bug fixes:
		* incorrect redraw when a modal window is opened in OnClick
		* incorrect behavior when the mouse goes out of the button
		  with the button still pressed
		* Down property incorrectly initialized at run-time
		* Ampersand not removed when the Caption is moved to the Hint
		* TBevelStyle was already defined by Delphi (grrrr....
		  one never reads the docs enough...)

- Sep  8, 1996 - VERSION 2.0 RELEASED
	- enhancements (see present text).
	- bug fixes: 
		* did not work on MDI forms
		* possibility to specify an empty caption

- Aug 29, 1996 - VERSION 1.0 RELEASED
	- initial revision

9. Known bugs & problems
========================

A. When the mouse pointer is on the button, the accelerators do not work
   (alt-tab, ...). See the troubleshooting section.

10. More informations
====================

This component is FREEWARE. 

Report any problems to: fdev@tornado.be

!! Before submitting any bug found, please take the time to check for
the latest version at http://www.tornado.be/~fdev/

ATTENTION: as I do not want to spend the rest of my life maintaining
this button and have little free time, new suggestions will *not
always* be taken into account. If you have an interesting enhancement,
apply the Nike development method: Just Do It.

11. Contact
===========

Snail-mail: Fabrice DEVILLE
            Sur le Mont, 29
            B-5363 EMPTINNE
            BELGIUM

E-mail:     fdev@tornado.be

Homepage:   http://www.tornado.be/~fdev/

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