TCanvas.ClipRect Property

Read-only property that specifies the boundaries of the clipping rectangle.

Pascal

property ClipRect: TRect;

C++

__property TRect ClipRect;

Description

Use ClipRect to determine where the canvas needs painting. ClipRect limits the drawing region of the canvas so that any drawing that occurs at coordinates outside the ClipRect is clipped and does not appear in the image.

When handling a form's OnPaint event, the canvas' ClipRect property is set to the rectangle that needs to be painted. Portions of the image that do not overlap the ClipRect do not need to be drawn. Thus, OnPaint routines can use the value of ClipRect to optimize painting, speeding the overall performance of the application.

Note: ClipRect can be modified using the SelectClipRgn Win32 API.

C++ Examples:

Copy Code

/*
This example creates a region and selects this region as the
clipping rectangle for the Image component's canvas. It then
sets the canvas's brush color to red and calls FillRect 
using the ClipRect as the area to fill. Lastly, the ClipRect
is reset to the original value that it contained by calling
SelectClipRect with nil as the second parameter and deletes
the region.  Place a TImage object in the form.
*/
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    HRGN MyRgn;

    MyRgn = ::CreateRectRgn(100,100,200,200);
    ::SelectClipRgn(Image1->Canvas->Handle,MyRgn);
    Image1->Canvas->Brush->Color = clRed;
    Image1->Canvas->FillRect(Image1->Canvas->ClipRect);
    Image1->Invalidate();
    ::SelectClipRgn(Image1->Canvas->Handle,NULL);
    ::DeleteObject(MyRgn);
}

Delphi Examples:

Copy Code

{
This example creates a region and selects this region as the
clipping rectangle for the Image component's canvas. It then
sets the canvas's brush color to red and calls FillRect 
using the ClipRect as the area to fill. Lastly, the ClipRect
is reset to the original value that it contained by calling
SelectClipRect with nil as the second parameter and deletes
the region.  Place a TImage object in the form.
}
procedure TForm1.Button1Click(Sender: TObject);
var
    MyRgn: HRGN;
begin
    MyRgn := CreateRectRgn(100,100,200,200);
    SelectClipRgn(Image1.Canvas.Handle,MyRgn);
    Image1.Canvas.Brush.Color := clRed;
    Image1.Canvas.FillRect(Image1.Canvas.ClipRect);
    Image1.Invalidate;
    SelectClipRgn(Image1.Canvas.Handle, HRGN(nil));
    DeleteObject(MyRgn);
end;