DELPHI Component TCMBtn version 1.0
Copyright (c) 1997 Christian Maas
                   chmaas@hit.sb.sub.de
All Rights Reserved


CONTENTS
========
I.   Summary
II.  Requirements
III. Installation
IV.  Documentation of unit interface
V.   License agreement
VI.  Disclaimer agreement


I. SUMMARY
==========

a) Note
   You can evaluate this component *BEFORE* installing:

   1. Try the demo CMB_DEMO.EXE which is supplied with this archive.
   2. You can compile and modify the demo source *WITHOUT* having
      installed TCMBtn, because of dynamically creating within
      this project. Note that you will not see the TCMBtn components
      on the form at design time.

b) About TCMBtn
   TCMBtn is a button like in MS Internet Explorer 3.0.

   Why just another Internet Explorer button component?
   I've examined three existing versions, but none of them met my
   requirements. So I created this component with the following main
   advantages:

   - inherited property Caption (is therefore automatically supplied
     at design time with CMBtn1, CMBtn2 and so on)
   - caption can contain an ampersand ("&") followed by accelerator char
   - WordWrap property for Caption
   - automatic cutting of Caption with trailing '...' if needed
   - HelpContext property
   - PopupMenu property with selectable mouse button (left like in
     Internet Explorer or right like in other DELPHI components)
   - no problems when calling windows help at OnClick event
   - no problems when help window is active and mouse leaves button
   - can be positioned on TPanel
   - ALT F4 (to close window) works
   - button layout control as known from TBitBtn
   - uses three glyphs for the three possible states
     1. enabled with mouse over button
     2. disabled (with or without mouse)
     3. enabled without mouse
     You can assign a single glyph bitmap to the glyph property, the two additional
     glyphs are created *AND* stored automatically! You can save the created 3-glyph-
     bitmap and edit it!


c) Properties
   The following new properties are defined for TCMBtn:

   Glyph: TBitmap
     An optional bitmap displayed in the button (see below for details)

   Margin: TMargin = (2..25)
     Distance in pixels: border - glyph, border - text (default: 2)

   BtnLayout: TButtonLayout = (blGlyphLeft, blGlyphRight, blGlyphTop, blGlyphBottom)
     Position of glyph in button (same type as in TBitBtn; default: blGlyphTop)

   BevelWidth: TBevelW = (1..5)
     Like property for TPanel (default: 1)
     BTW: I defined this new type because TBevelWidth = (1..MaxInt) defined for
     TPanel is weird (create Panel1 and try to increment BevelWidth, but
     save your work before...)

   WordWrap: boolean
     If true, caption is wrapped over multiple lines (default: false)

   PopupButton: TMouseButton (mbRight, mbLeft, mbMiddle)
     Determines which button opens an assigned popup menu (default: mbLeft like
     in Internet Explorer 3.0)
     If set to mbRight, you can assign an OnClick event for left button
     as well as popup menu.

   PopupMenu: TPopupMenu
     An optional popup menu; if assigned, a popup mark (triangle in color of the
     assigned font) appears in the upper right corner.
     When assigning a popup menu, its property AutoPopup is automatically set to
     false. This is necessary for TCMBtn to have the complete control over the mouse
     up and down events.


d) About using glyphs for TCMBtn
   TCMBtn uses three glyphs for the three possible states
   1. enabled with mouse over button
   2. disabled (with or without mouse)
   3. enabled without mouse

   Usually you assign a square bitmap (e.g. width 20 x height 20 which contains
   a single glyph) to the glyph property. This glyph is used for state 1.

   If TCMBtn detects such a single glyph bitmap, it creates the two additional
   glyphs automatically and stores it in one bitmap with the following structure:

   - Height is the same as the assigned bitmap
   - Width is 3 * width of assigned bitmap
   - the order of glyphs from left to right is 1-2-3 (enabled with mouse, 
     disabled, enabled without mouse)

   You can easily examine and/or change the automatically created glyphs.
   Proceed as follows:

   1. Select or create a square bitmap containing one glyph.
   2. Load it in glyph property via object inspector. TCMBtn creates now two
      additional bitmaps.
   3. Save the glyph property using object inspector (giving it a different
      file name as a security measure). In the save window, you'll see already
      three glyphs!
   4. Edit the saved bitmap. You'll see three glyphs in the above mentioned order.
   5. Change the bitmap if needed and load it again in glyph property. You can also
      use three completely different glyphs for the three states (like THREE.BMP
      contained in this archive).

   The ratio width/height is used to determine the count of glyphs contained
   in a assigned bitmap:
   Width = height    : 1 glyph  (enabled with mouse)
   Width = 2 * height: 2 glyphs (enabled with mouse, disabled)
   Width = 3 * height: 3 glyphs (enabled with mouse, disabled, enabled without mouse)

   If TCMBtn detects a bitmap containing less than three glyphs, one or two additional
   glyhs are created.

   If you edit the bitmaps provided with DELPHI for TSpeedButton or TBitBtn, you'll
   see that they contain normally 2 glyphs (enabled and disabled). This is the
   explanation for the above mentioned order (1-2-3) of the three glyphs.

   When assigning a bitmap to the glyph property programatically, use
   Bitmap1.LoadFromFile ('C:\DATA\BMP\TEST.BMP');
   CMBtn1.Glyph := Bitmap1;

   { the following code prevents detection of glyph count and generating! }
   CMBtn1.Glyph.LoadFromFile ('C:\DATA\BMP\TEST.BMP');


II. REQUIREMENTS
================

TCMBtn is a component for DELPHI 2.0. The component unit CMBUTTON.DCU can't be
installed under DELPHI 1.0.


III. INSTALLATION
=================

1. Extract CMB10UF.ZIP into a directory on your hard disk.
2. The archive contains the following files:
   README.TXT   (this file)
   CMBUTTON.DCU (the installable unit containing TCMBtn)
   CMBUTTON.DCR (DELPHI component resource for TCMBtn)
   CMB_DEMO.EXE (demo for TCMBtn; try before you install it!)
   CMB_DEMO.DPR (demo project source)
   CMB_DEMO.HLP (help file for demonstrating HelpContext property)
   CMB_W1.PAS   (first form of demo project source)
   CMB_W1.DFM   (.dfm for first form of demo project)
   CMB_W2.PAS   (second form of demo project source)
   CMB_W2.DFM   (.dfm for second form of demo project)
   BLITZ.BMP    (a bitmap containing 1 glyph)
   BULB.BMP     (a bitmap containing 1 glyph)
   EXIT.BMP     (a bitmap containing 2 glyphs)
   THREE.BMP    (a bitmap containing 3 glyphs)

3. Copy CMBUTTON.DCU and CMBUTTON.DCR in the directory which contains your own component
   units. Then install the component unit CMBUTTON.DCU from DELPHI IDE (don't forget to
   change the filter from *.pas to *.dcu!). The new component TCMBtn is added to the
   page "CM".


IV. DOCUMENTATION OF UNIT INTERFACE
===================================

type
  TMargin = 2..10;
  TBevelW = 1..5;

type
  TCMBtn = class(TCustomPanel)
  private
    { NOT the inherited property in order to get notification about assigning
      a popup menu (important especially at design time) }
    FPopupMenu: TPopupMenu;
    FPopupButton: TMouseButton;

    FBevelWidth: TBevelW;
    FBtnLayout: TButtonLayout;
    FGlyph: TBitmap;
    FMargin: TMargin;
    FButtonLayout: TButtonLayout;
    FWordWrap: Boolean;

    procedure SetPopupMenu (Value: TPopupMenu);
    function  GetPopupMenu: TPopupMenu; dynamic;
    procedure SetPopupButton (Value: TMouseButton);

    procedure SetBevelWidth (Value: TBevelW);
    procedure SetBtnLayout (Value: TButtonLayout);
    procedure SetGlyph (Value: TBitmap);
    procedure SetMargin (Value: TMargin);
    procedure SetWordWrap (value: boolean);

    procedure CMMouseEnter (var Message: TMessage); message CM_MOUSEENTER;
    procedure CMMouseLeave (var Message: TMessage); message CM_MOUSELEAVE;
    procedure CMDialogChar (var Message: TCMDialogChar); message CM_DIALOGCHAR;
    procedure CMEnabledChanged (var Message: TCMDialogChar); message CM_ENABLEDCHANGED;
    procedure CMTextChanged (var Message: TMessage); message CM_TEXTCHANGED;

    procedure InitBtnRect;
    procedure GlyphChanged (Sender: TObject);
    function  CutCaption (Cap: string; var TxtRect: TRect): PChar;
    procedure DrawCaption (Cap: PChar; TxtRect: TRect);
    procedure DrawPopupMark (x, y: integer; C: TColor);

    function  NGlyphs (B: TBitmap): integer;
    procedure CalculateTxtRect (var TxtRect: TRect; GlyphRect: TRect);
    procedure CalculateGlyphRect (GlyphW: integer; var GlyphRect: TRect);

  protected
    FHasMouse: boolean;
    FBtnRect: TRect;
    FPrevMouseDown: boolean;
    procedure Notification (AComponent: TComponent; Operation: TOperation); override;
    procedure MouseDown (Button: TMouseButton; Shift: TShiftState; X, Y: Integer); override;
    procedure MouseUp (Button: TMouseButton; Shift: TShiftState; X, Y: Integer); override;
    procedure Paint; override;

  public
    Constructor Create( AOwner: TComponent ); override;
    destructor Destroy; override;

  published
    property Glyph: TBitmap read FGlyph write SetGlyph;
    property Margin: TMargin read FMargin write SetMargin default 2;
    property BtnLayout: TButtonLayout read FBtnLayout write SetBtnLayout default blGlyphTop;
    property BevelWidth: TBevelW read FBevelWidth write SetBevelWidth default 1;
    property WordWrap: boolean read FWordWrap write SetWordWrap default False;
    property PopupButton: TMouseButton read FPopupButton
      write SetPopupButton default mbLeft;

    property Caption;
    property Color;
    property Enabled;
    property Font;
    property ParentFont;
    property ParentShowHint;
    property ShowHint;
    property Visible;
    property onClick;
    property onDblClick;
    property onMouseDown;
    property onMouseUp;
    property onMouseMove;
    property PopupMenu: TPopupMenu read FPopupMenu write SetPopupMenu;
  end;

procedure Register;


V. LICENSE AGREEMENT
====================

This component is freeware. You can freely distribute copies of the main archive
CMB10UF.ZIP as long as no alterations are made to the contents and no charge is
raised except a reasonable fee for distributing costs.

You are hereby granted the permission to use TCMBtn in your own programs for private
or commercial purposes, provided your software contains the copyright notice
"TCMBtn Copyright (c) 1997 Christian Maas".

If you find this component useful, I would appreciate to hear from you.
Send e-mail to
               chmaas@hit.sb.sub.de


VI. DISCLAIMER AGREEMENT
========================

This software has been thoroughly tested. Nevertheless it is provided "as is" and
without any warranties expressed or implied, including, but not limited to, implied
warranties of fitness for a particlar purpose.

In no event shall the author be liable for any damages whatsoever (including, without
limitation, damages for loss of business profits, business interruption, loss of
business information, or other pecuniary loss) arising out of the use of or inability
to use this software or documentation, even if the author has been advised of the
possibility of such damages.
