Class TRegion (unit region)

Inherits from

TComponent

Constructors


constructor Create (AOwner: TComponent);



Functions

procedure Apply;

Make the region active; see Remove; equivalent to Active:=true;

try // need to call clear when destroying, but Clear // form is destroyed first, problem except end;


procedure BeginPath;

Start a drawing path (see EndPath below

procedure BeginUpdate;

Call when making multiple changes to an active path, this is more efficient than just calling the individual changes that you need.

function Bounds : TRect;

Returns the rectangle which bounds the current region

alternative? // The advantage of the Begin.


procedure Clear;

Clear the current region back to a full form.

function Clone : TRegion;

Returns a copy of the current region (guaranteed inactive

Produces a copy of the TRegion and returns a new TRegion.


procedure Combine (Region : TRegion);

Combine the given TRegion with this one

Combines this TRegion with another TRegion modifying this TRegion.


function Complexity: integer;

Returns a code representing the complexity of the region (see rgXXXXX above

returns a code indicating the complexity of the region - see rgXXXXX codes above


function ContainsPt (Pt : TPoint) : boolean;


function ContainsRect (Rect : TRect) : boolean;

True if any part of Rect is in the region

see Bounds for alternative method using Clone


function ContainsXY (X, Y : integer) : boolean;

True if region contains the point (X, Y) - Form relative!

see Bounds for alternative method using Clone


destructor Destroy;

default fill mode

procedure Ellipse (X1, Y1, X2, Y2 : integer);

Draw an ellipse

create an elliptical region based on X, Y coordinates of the top left corner and X, Y coordinates of bottom right corner of the bounding box


procedure EllipseFromRect (Rect: TRect);


procedure EndPath;

End the drawing path and combine the resultant Region - see BeginPath above

procedure EndUpdate;

End changes

function Equal (Region : TRegion) : boolean;

True if the supplied region has same size and shape

procedure Fill;

Fill region with FBrush

procedure Frame (Width, Height : integer);

Frame region with FBrush setting width and height of the brush strokes

need to invalidate controls as well?


procedure Invalidate;

Cause the region to be repainted (I think

procedure Invert;

Invert the colours in the region - effect depends on colour capabilities of the display adapter you are using

procedure LoadFromFile (const Filename : string);

Load a region data file previously saved using SaveToFile

procedure LoadFromStream (Stream : TStream);


procedure Move (dX, dY : integer);

Move the region by dX, dY (may be negative for left and up

no transform on load


procedure MoveTo (X, Y : integer);

Move to absolute top left coords

procedure Polygon (const points: array of TPoint);

Draw a polygon based on a series on points

procedure Rectangle (X1, Y1, X2, Y2 : integer);

Draw a rectangle

procedure RectangleFromRect (Rect: TRect);


procedure Remove;

Makes a Region inactive, opposite of Apply, equivalent to Active:=false;

procedure RoundRect (X1, Y1, X2, Y2, X3, Y3 : integer);

Draw a rectangle with rounded corners - see TCanvas.

procedure SaveToFile (const Filename : string);

Save a region data file to disc/stream

procedure SaveToStream (Stream : TStream);


procedure TextOut (X, Y : integer; Text: string);

Create's a region based on the outline of a text string

Text is only possible by using a path.


procedure Transform (XEffect, YEffect : single; dX, dY : integer);

Apply a transform matrix to a region, only scaling and move possible with win 95

procedure TransformBy (const XForm : TXForm);

under win 95

procedure TransformNT (XEffect, YEffect, XYEffect, YXEffect : single; dX, dY : integer);


function CheckRegion (Region : hRgn) : hRgn;

Passes through a valid region handle or complexity value but causes an Exception if zero passed (= RGN_ERROR

checks a region handle or other integer value or boolean, if RGN_ERROR (=0) then produces an exception by calling Error


procedure CombineDelete (Rgn : hRgn);

Like CombinesHandles except the supplied Rgn is deleted after use

Calls CombineHandles and then delete the supplied region handle (guaranteed


procedure CombineHandles (Rgn : hRgn);

Combines the given Rgn into FRegion using FCombineMode, if the region is Currently active, ie in use then it is obtained from the form, combined and Then made active again.

procedure CreateRegion;

Creates a small but valid dummy region in FRegion

Creates a small but valid region in the region handle.


procedure FormInvalidate;

Causes the owner form to be wholey invalidated and redraw

function GetRegionData (var Size: integer) : PRgnData;

Returns a pointer to a TRgnData structure and the size of the structure in Size.

function XlatCombineMode (Mode: TRegionCombine) : integer;

Translates a rcXXXXX into a windows integer constant

Combine regions translation - note the multiple definitions to offer different identifiers eg rcOr = rcUnion


function XlatFillMode (Mode: TRegionFillMode) : integer;

Translates a fmXXXXX into a windows integer constant

function GetIsNotUpdating : boolean;

region fill mode (see fmXXXXXX above

procedure SetActive (Value: boolean);


Properties

property Active : boolean


property AutoInvalidate : boolean


property Brush : TBrush


property CombineMode : TRegionCombine


property FillMode : TRegionFillMode


property Font : TFont


property Handle : hRgn

Read only Region handle

property IsNotUpdating : boolean

Read only

property Path : TPath

NB Path is only valid between BeginPath and EndPath, otherwise nil

Events

Variables

FActive : boolean;

if true causes form redraw on region move/xform

FBrush : TBrush;

handle to an inactive region or zero when active

FCombineMode : TRegionCombine;

true if region is in use

FFillMode : TRegionFillMode;

our font

FFont : TFont;

our brush

FForm : TForm;


FInvalidate : boolean;

used to prevent screen redraws when making several changes (see BeginUpdate

FPath : TPath;

local copy of owner form

FRegion : hRgn;

region combining mode (see rcXXXXXX above

FUpdating : integer;

path (if it exists, otherwise nil


Constructors


constructor Create (AOwner: TComponent);


Functions


procedure Apply;

Make the region active; see Remove; equivalent to Active:=true;

try // need to call clear when destroying, but Clear // form is destroyed first, problem except end;


procedure BeginPath;

Start a drawing path (see EndPath below


procedure BeginUpdate;

Call when making multiple changes to an active path, this is more efficient than just calling the individual changes that you need. Calls to BeginUpdate can be nested and each paired with an EndUpdate. FUpdating counts the number of calls to BeginUpdate and only redraws the form when it returns to zero.


function Bounds : TRect;

Returns the rectangle which bounds the current region

alternative? // The advantage of the Begin..EndUpdate method is it looks like fewer resources // are used. The advantage of the Clone method is that the region is not made // inactive and therefore looks easier to make thread-safe. This alternative // way of obtaining a region handle should apply to many of the methods. function TRegion.Bounds : TRect; var Region : TRegion; begin Region := Clone; // clone obtains an inactive region try GetRgnBox (Region.FRegion, Result) finally Region.Free end end;


procedure Clear;

Clear the current region back to a full form.

Clears the region whether active by removing it or if not active by deleting it. Region handle is set to zero.


function Clone : TRegion;

Returns a copy of the current region (guaranteed inactive

Produces a copy of the TRegion and returns a new TRegion. If active it simply uses GetWindowRgn if not active uses RGN_COPY


procedure Combine (Region : TRegion);

Combine the given TRegion with this one

Combines this TRegion with another TRegion modifying this TRegion.


function Complexity: integer;

Returns a code representing the complexity of the region (see rgXXXXX above

returns a code indicating the complexity of the region - see rgXXXXX codes above


function ContainsPt (Pt : TPoint) : boolean;


function ContainsRect (Rect : TRect) : boolean;

True if any part of Rect is in the region

see Bounds for alternative method using Clone


function ContainsXY (X, Y : integer) : boolean;

True if region contains the point (X, Y) - Form relative!

see Bounds for alternative method using Clone


destructor Destroy;

default fill mode


procedure Ellipse (X1, Y1, X2, Y2 : integer);

Draw an ellipse

create an elliptical region based on X, Y coordinates of the top left corner and X, Y coordinates of bottom right corner of the bounding box


procedure EllipseFromRect (Rect: TRect);


procedure EndPath;

End the drawing path and combine the resultant Region - see BeginPath above


procedure EndUpdate;

End changes


function Equal (Region : TRegion) : boolean;

True if the supplied region has same size and shape


procedure Fill;

Fill region with FBrush


procedure Frame (Width, Height : integer);

Frame region with FBrush setting width and height of the brush strokes

need to invalidate controls as well?


procedure Invalidate;

Cause the region to be repainted (I think


procedure Invert;

Invert the colours in the region - effect depends on colour capabilities of the display adapter you are using


procedure LoadFromFile (const Filename : string);

Load a region data file previously saved using SaveToFile


procedure LoadFromStream (Stream : TStream);


procedure Move (dX, dY : integer);

Move the region by dX, dY (may be negative for left and up

no transform on load


procedure MoveTo (X, Y : integer);

Move to absolute top left coords


procedure Polygon (const points: array of TPoint);

Draw a polygon based on a series on points


procedure Rectangle (X1, Y1, X2, Y2 : integer);

Draw a rectangle


procedure RectangleFromRect (Rect: TRect);


procedure Remove;

Makes a Region inactive, opposite of Apply, equivalent to Active:=false;


procedure RoundRect (X1, Y1, X2, Y2, X3, Y3 : integer);

Draw a rectangle with rounded corners - see TCanvas.RoundRect


procedure SaveToFile (const Filename : string);

Save a region data file to disc/stream


procedure SaveToStream (Stream : TStream);


procedure TextOut (X, Y : integer; Text: string);

Create's a region based on the outline of a text string

Text is only possible by using a path. This method is a shortcut as it provides for the path begin and end and combining the text region. This is Ok for one text string, but for multiple text strings you should begin the path "manually", do your stuff on the path (multiple strings or whatever) and then end the path.


procedure Transform (XEffect, YEffect : single; dX, dY : integer);

Apply a transform matrix to a region, only scaling and move possible with win 95


procedure TransformBy (const XForm : TXForm);

under win 95


procedure TransformNT (XEffect, YEffect, XYEffect, YXEffect : single; dX, dY : integer);


function CheckRegion (Region : hRgn) : hRgn;

Passes through a valid region handle or complexity value but causes an Exception if zero passed (= RGN_ERROR

checks a region handle or other integer value or boolean, if RGN_ERROR (=0) then produces an exception by calling Error


procedure CombineDelete (Rgn : hRgn);

Like CombinesHandles except the supplied Rgn is deleted after use

Calls CombineHandles and then delete the supplied region handle (guaranteed


procedure CombineHandles (Rgn : hRgn);

Combines the given Rgn into FRegion using FCombineMode, if the region is Currently active, ie in use then it is obtained from the form, combined and Then made active again. The Rgn handle is not deleted.

Combine a new region into the existing region. Need to check if currently active and if so make it inactive first (re-activating it later). The supplied region handle is not deleted by this method.


procedure CreateRegion;

Creates a small but valid dummy region in FRegion

Creates a small but valid region in the region handle. Some function calls require the region to exist before replacing it.


procedure FormInvalidate;

Causes the owner form to be wholey invalidated and redraw


function GetRegionData (var Size: integer) : PRgnData;

Returns a pointer to a TRgnData structure and the size of the structure in Size. It is the callers duty to use FreeMem (?Data?, Size) when done.


function XlatCombineMode (Mode: TRegionCombine) : integer;

Translates a rcXXXXX into a windows integer constant

Combine regions translation - note the multiple definitions to offer different identifiers eg rcOr = rcUnion


function XlatFillMode (Mode: TRegionFillMode) : integer;

Translates a fmXXXXX into a windows integer constant


function GetIsNotUpdating : boolean;

region fill mode (see fmXXXXXX above


procedure SetActive (Value: boolean);


Properties


property Active : boolean


property AutoInvalidate : boolean


property Brush : TBrush


property CombineMode : TRegionCombine


property FillMode : TRegionFillMode


property Font : TFont


property Handle : hRgn

Read only Region handle


property IsNotUpdating : boolean

Read only


property Path : TPath

NB Path is only valid between BeginPath and EndPath, otherwise nil


Events


Variables


FActive : boolean;

if true causes form redraw on region move/xform


FBrush : TBrush;

handle to an inactive region or zero when active


FCombineMode : TRegionCombine;

true if region is in use


FFillMode : TRegionFillMode;

our font


FFont : TFont;

our brush


FForm : TForm;


FInvalidate : boolean;

used to prevent screen redraws when making several changes (see BeginUpdate


FPath : TPath;

local copy of owner form


FRegion : hRgn;

region combining mode (see rcXXXXXX above


FUpdating : integer;

path (if it exists, otherwise nil