TmpRegionImage readme

-CONTENTS-

title
package
release
target
history
installation
usage
sources
contact
license

_top

TmpRegionImage is a TGraphicControl descendant. It displays a bitmap (like TImage) and contains a list of clickeable regions (e.g. like countries on a map). You can specify different bitmaps for normal, hilited and selected state of a region. The package contains an editor for creating lists of regions (rectangle, ellipse, polygon, fill, combinations). Also included are some utility functions (in rgnpkg.pas) to store/load normal, hilited and selected bitmap and region lists of a TmpRegionImage component in one single compressed file.

_top

TmpRegionImage version 3.0, 10/26/02

added support for multiple selection

TmpRegionImage version 2.0, 01/27/02

renamed, rewritten from scratch, less flicker...

ancestor TMapImage version 1.1, 06/26/98

some additions

ancestor TMapImage version 1.0, 06/04/97

initial release

_top

-INSTALLATION-

copy rgnimg.pas, rgnimg.dcr and rgnpkg.pas to a directory in your delphi library path (e.g. $(DELPHI)\lib).
Add rgnimg.pas to one of the component packages (e.g. dclusr.dpk) and recompile that package.
the new component TmpRegionImage should now appear in the component palette, on the page "mirkes.de".

_top

-USAGE-

place a TmpRegionImage component on the form.
assign a bitmap to the NormalBitmap property. you can also assign different bitmaps to HiliteBitmap and SelectedBitmap (width and height should be equal to the size of the NormalBitmap) to distinguish normal state from hilited state (when the mouse cursor is over a clickeable region) and selected state (a region has been clicked and is now selected).
you can edit the regions in textual form by modifying the Regions property, but i recommend to use the additional regions editor (run the Regions editor, open a bitmap, create the regions and save them to a .map file. now open that .map file in the delphi ide and copy its contents to the Regions property editor window). you can also create a package file in that editor (it contains normal, hilited and selected bitmap and also the regions list) and load it into a TmpRegionImage component at runtime by calling LoadRegionImage from rgnpkg.pas.

TmpRegionImage properties:

NormalBitmap:TBitmap the bitmap to display
HiliteBitmap:TBitmap the bitmap to display when the mouse cursor is over a clickeable region
SelectedBitmap:TBitmap the currently selected region is painted by a part of this bitmap
RegionCursor:TCursor this cursor is displayed when the mouse is over a clickeable region
Regions:TStringList textual representation of all clickeable regions
AutoSelect:Boolean if set to true, a region will be change its state to selected/not selected by clicking on it
ItemIndex: Integer currently selected region (painted by SelectedBitmap)
MultiSelect: Boolean decides whether more than one region can be selected at a time (by shift-clicking)
Selected[Index:Integer]: Boolean decides whether a region is to be drawn in selected state
HiliteCurrent:Boolean if set to true, a hilited region will be painted by HiliteBitmap
Hilited:Integer currently hilited region (where the cursor is, painted by HilitedBitmap)
SingleRegion[Index:Integer]:HRGN returns the windows HRGN object of the specified region
CombinedRegion[Index:Integer]:HRGN returns the windows HRGN object of the xor'd combination of the specified region and all regions on top of it
StrTag[Index:Integer]:string textual Tag property of each region (for user defined purposes, like descriptions...)

TmpRegionImage events:

type TRegionEvent = procedure(Sender: TObject; const AIndex: integer) of object;

OnEnterRegion:TRegionEvent is triggered when the mouse moves over a region
OnLeaveRegion:TRegionEvent is triggered when the mouse leaves a region
OnSelectionChange:TNotifyEvent is triggered when the selection changed (e.g. when a different region has been clicked)

TmpRegionImage methods:

function RegionAtPos(X, Y: integer): integer get the region at the specified cursor position
function RegionAtCursorPos: integer get the region at the current cursor position
procedure OffsetRegion(Index, dX, dY: integer) change the position of a region
function IndexOfStrTag(sName: string): integer find a region by StrTag value
function RegionsCount: integer get the number of regions

utility functions in rgnpkg.pas:

procedure LoadRegionImage(fObj: TmpRegionImage; sFile: TFileName) load the bitmaps and regions list of a TmpRegionImage component from a compressed package file
procedure SaveRegionImage(fObj: TmpRegionImage; sFile: TFileName) save the bitmaps and regions list of a TmpRegionImage component to a compressed package file

_top

    --------------------------------------------------------------------------------
    Author    : markus stephany
    Copyright : (C) 1997-2002 markus stephany
    -

    This source code is freeware. You may use, change, and distribute without
    charge the source code as you like. This unit can be used freely in any
    commercial applications. However, it may not be sold as a standalone product
    and the source code may not be included in a commercial product. This unit
    is provided as is with no warrent or support. Make sure to read relevant
    information and documentation from Microsoft before using this unit.
    --------------------------------------------------------------------------------

_top