readme.txt

BmpRgn is a *FREEWARE* unit that allows you to create forms with transparent areas based on a bitm

TABLE OF CONTENTS
-----------------

1. Copyright
2. What it does
3. License Agreement
4. Installation
5. How to use BmpRgn
6. Setting up your code
7. Using your own bitmaps
8. Re Popup Menus
9. Support (or lack of it)


COPYRIGHT
---------

  BmpRgn copyright Gunter Richter, 2001
                   [e-mail]


WHAT IT DOES
------------

BmpRgn is a *FREEWARE* unit that allows you to create forms 
with transparent areas based on a bitmap that you provide.
The bitmap is converted to a  form region, where only the
interior pixels are displayed. The transparent border remains
transparent.



LICENSE AGREEMENT
-----------------

  Permission to use, copy, modify, and distribute this software and its
  documentation for any purpose and without fee is hereby granted,
  provided that my name may not be used in advertising or publicity
  pertaining to distribution of this software without specific, written
  prior permission, and that this LICENSE AGREEMENT is distributed with
  all copies.

  This software is made available "as is", and I DISCLAIM ALL WARRANTIES,
  EXPRESS OR IMPLIED, WITH REGARD TO THIS SOFTWARE, INCLUDING WITHOUT
  LIMITATION ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  PARTICULAR PURPOSE, AND IN NO EVENT SHALL I BE HELD LIABLE FOR ANY
  SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
  RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
  CONTRACT, TORT (INCLUDING NEGLIGENCE) OR STRICT LIABILITY, ARISING OUT
  OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

  If you do not agree to these terms, you may not use this software.


INSTALLATION
------------

  This is not a component, so there's no need to install it. Just make sure
  that BmpRgn.pas is included in your form's USES clause and available to the
  compiler. The easiest way to do so is to copy BmpRgn.pas into the folder 
  containing your application's DPR file or into a folder accessible to the 
  Units path in Delphi.
  

HOW TO USE BmpRgn
-----------------

  There is only one function in BmpRgn that you need to use, declared as
  follows:

    function BmpToRegion( Form: TForm; Bmp: tbitmap): HRGN;
  

  You would typically call it in your program's OnCreate event handler
  as shown:
  
    procedure TForm1.FormCreate(Sender: TObject);
    var rgn: HRGN;
    ....
    begin
      ....    
      rgn := BmpToRegion( Self, Image1.Picture.Bitmap);
      SetWindowRgn( handle, rgn, true);
      ....
    end;  

  If BmpToRegion can successfully convert your bitmap to a region, the
  return value is a handle to the created region. If it's not successful
  the return value is zero, which in the code example above, simply
  draws the full form without any region, the way you would see it if
  you weren't using BmpRgn.
  

SETTING UP YOUR CODE
--------------------

  Working with custom forms means that you are working outside of some
  of the protection offered by standard windows. In other words, you
  have to provide mechanisms that do the following:
  
  1.  Paint the form background.
  2.  Allow users to move the form on the desktop.
  3.  Close the form.
  
  It also helps if you can see the bitmap you'll be using (at leastt
  the default one) while your working in the Delphi IDE. And finally,
  you obviously have to add BmpRgn to your unit's USES clause. All
  in all there are five steps you need to take. Here they are:

  Step 1: Add BmpRgn to your unit's USES clause.
  
    This step's fairly easy so I won't bother to explain it any more.
    If you don't know how to do it you're using the wrong development
    tool.


  Step 2: Make sure you can see the bitmap in the Delphi IDE.
  
    The easiest way to do this is simply to add a TImage component
    at location 0,0 in your form. Set the following properties:

    Left = 0
    Top  = 0
    AutoSize = true
    Center = false
    Transparent = false
    Visible = false
    Picture = the bitmap you want to use
    
    Setting the visible property to false is important because
    you can see the TImage while in the IDE, but not at runtime.
    At runtime, the handler that paints the form's background
    takes over. That's step 3.

  
  Step 3: Add a handler to paint the form's background with your bitmap
  
    You can override the default drawing of a form's background by
    trapping the WM_ERASEBKGND message. To do so, first copy the
    following line and paste it into your form's PRIVATE declarations.
    
    procedure WMEraseBkGnd( Var Msg: TWMEraseBkGnd ); message WM_ERASEBKGND;

    The handler is also easy. Just copy the following and paste it into
    the implementation section of your unit.
    
    procedure TForm1.WMEraseBkGnd(var Msg: TWMEraseBkGnd);
    var Brush: TBrush;
    begin
      // the following four lines are only needed if you want
      // to allow toggling between the normal form and your "skinned"
      // version.
      Brush := TBrush.Create;
      Brush.Color := Color;
      FillRect( Msg.DC, ClientRect, Brush.Handle);
      Brush.Free;
      // the following two lines are mandatory
      with Image1.Picture.Bitmap do
        BitBlt( Msg.DC, 0, 0, Width, Height, Canvas.Handle, 0, 0, SRCCOPY);
      Msg.Result := 1;
    end;


  Step 4: Add a handler to allow moving the form.
  
    Windows allows you to move forms by dragging the title bar. 
    Unfortunately your form won't have a title bar any more, but you can 
    still drag it by adding the following. First, copy the following line
    and paste it into the PRIVATE section of your form's declarations:
    
    procedure WMNCHitTest( Var msg: TWMNCHitTest ); message WM_NCHITTEST;
    
    Then copy and paste the following procedure into your unit's
    implementation section:
    
    procedure TForm1.WMNCHitTest( var msg: TWMNCHitTest );
    var
      i: integer;
      p: TPoint;
      AControl: TControl;
      MouseOnControl: boolean;
    begin
      inherited;
      if msg.result = HTCLIENT then begin
        p.x := msg.XPos;
        p.y := msg.YPos;
        p := ScreenToClient( p);
        MouseOnControl := false;
        for i := 0 to ControlCount-1 do begin
          if not MouseOnControl
          then begin
            AControl := Controls[i];
            if ((AControl is TWinControl) or (AControl is TGraphicControl))
              and (AControl.Visible)
            then MouseOnControl := PtInRect( AControl.BoundsRect, p);
          end
          else
            break;
        end;
        if (not MouseOnControl) then msg.Result := HTCAPTION;
      end;
    end;

    If you've seem similar examples on the Internet you may be wondering
    why this one has so much code. The reason is simple. If you forget to
    include code to detect if the mouse was clicked on a control, then 
    the controls are effectively disabled since Windows will always think
    you're clicking on the form's title bar.


  Step 5: Call BmpToRegion in your form's OnCreate handler.
  
    BmpToRegion takes 2 parameters - your form and the bitmap. It returns
    a handle to a region. Here's the code that you need to add to your form's
    OnCreate handler:
    
    procedure TForm1.FormCreate(Sender: TObject);
    var rgn: HRGN;
    .... your other declarations
    begin
      .... other code
      rgn := BmpToRegion( Self, Image1.Picture.Bitmap);
      SetWindowRgn( handle, rgn, true);
      .... other code
    end;  


  That's all there is to it. You may be wondering why I didn't make this a
  component. The simple reason is that I don't like cluttering up the 
  component palette with things that I'll only use for a small handful of
  apps. However, if you want to add it to your palette, you have the source
  code, so by all means make the changes necessary and do it. You can even
  claim that you wrote it from scratch. It's okay by me.

   

USING YOUR OWN BITMAPS
----------------------

  You can use any bitmap you want with BmpRgn. What BmpToRegion does, is
  look at the pixel in the top left corner. It takes that as the transparent
  color and then begins a minorly complex conversion of the edge surrounding
  the non-transparent pixels into a series of TPoints. The points are converted
  to a path and the path is converted to a region.  You must use regions to 
  define irregularly shaped forms when running under Windows.
  
  The main limitation of BmpRgn is that it doesn't handle forms with cutouts.
  It WILL trace the outer edges, but if you have transparent pixels in the
  center that are surrounded by a closed frame of non-transparent pixels,
  the pixels in the center will not be converted to transparent. I may address
  this in a future release (if anybody likes this unit).
  
  I also wouldn't recommend using JPG files. The loss of color information
  that results from compression, may just render pixels that are supposed to
  be transparent into opaque. That could result in a mess. If you do need
  compressed images, you can work with PNG or GIF files, provided that you
  still pass their expanded bitmaps to BmpToRegion.
  

Re: POPUP MENUS
---------------

  One thing that I haven't been able to get working are popup menus. It seems
  that when you add the code to trap the WM_NCHITTEST message, you lose the
  ability to detect right mouse clicks. I don't believe this is actually the
  case, but I don't know the solution. If you know it, I'd be happy to hear
  from you.
  
  Fortunately this phenomenon only happens to popup menus that you assign to
  the entire form. Popup menus that are assigned to controls still work the
  way they should. So while it's a bit of a nuisance, it's not severe enough
  to keep this code out of circulation.
  
  One workaround that I have found, is to place a TPaintBox on the form and
  assign the menu to the PaintBox. By default, Paintboxes are invisible, so
  that's okay. You just have to be careful where you place them, because once
  the mouse is on the PaintBox control, you can't drag the form any more.
  You also have to be careful that they don't overlap controls that you want
  to keep enabled. You can do this with the Send To Back / Bring to Front
  positioning. Controls that you want to work should be at the front.
  


SUPPORT (or lack of it)
-----------------------

  If you have any comments, criticisms, questions or bug reports, you can
  get in touch with me by email.
  
  [e-mail]
  
  However, be forewarned, I'm one of those people who tends to ignore email
  and voice mail messages. I apologize, but I haven't been able to change
  it in the last ten years, so it's unlikely I'll do so in the near future.
  Once I get into doing something, I tend to get absorbed by it to the
  exclusion of everything else. 
  
  In any case, BmpRgn shouldn't need much support. You have the source code.
  It's fairly easy to follow for a programmer with late-beginner level skills
  and if you want to change it, you have my blessing to enhance it in any
  way that you need to.
  
  I really hope you like BmpRgn. I've downloaded tons of really neat stuff
  from DSP and similar sites, and just want to give something equally cool
  back. I hope you enjoy it.
  

  Thanks
  Gunter Richter