[Overview][Constants][Types][Classes][Procedures and functions][Variables][Index] | Reference for unit 'Graphics' (#lcl)

# TCanvas

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

Implements a drawing surface for a visual control or bitmap image.

## Declaration

Source position: graphics.pp line 996

`type TCanvas = class(TFPCustomCanvas)`
`protected`
`function DoCreateDefaultFont; override;` |  | Creates the TFont instance used as the default font for the canvas.
`function DoCreateDefaultPen; override;` |  | DoCreateDefaultPen - calls TPen.Create to create a default pen.
`function DoCreateDefaultBrush; override;` |  | DoCreateDefaultBrush - calls TBrush.Create to create a default brush.
`procedure SetColor(); override;` |  | Sets the value for the indexed Colors property.
`function GetColor(); override;` |  | Gets the Color for the pixel at the given coordinates as a TFPColor value.
`procedure SetHeight(); override;` |  | SetHeight should never be called for Canvas: raises an exception if it is called.
`function GetHeight; override;` |  | GetHeight - if a handle has been allocated, returns the height from the device size.
`procedure SetWidth(); override;` |  | SetWidth - should never be called; raises an exception if it is called.
`function GetWidth; override;` |  | Gets the value for the Width property.
`procedure SetPenPos(); override;` |  | Moves the pen to the specified position.
`procedure DoLockCanvas; override;` |  | Enters the critical section used to lock the canvas, and calls the inherited method.
`procedure DoUnlockCanvas; override;` |  | Leaves the critical section used to lock the canvas, and calls the inherited method.
`procedure DoTextOut(); override;` |  | DoTextOut calls TextOut for the specified coordinates and string.
`procedure DoGetTextSize(); override;` |  | Calls TextExtent to find the width and height of the specified text.
`function DoGetTextHeight(); override;` |  | DoGetTextHeight calls TextHeight to return the height of the text.
`function DoGetTextWidth(); override;` |  | DoGetTextWidth calls TextWidth to return the width of the given text string.
`procedure DoRectangle(); override;` |  | DoRectangle calls Frame to draw a rectangle in the given bounds.
`procedure DoRectangleFill(); override;` |  | DoRectangleFill calls FillRect to draw a filled rectangle with the given bounds.
`procedure DoRectangleAndFill(); override;` |  | DoRectangleAndFill - calls Rectangle to draw a rectangle and fill it.
`procedure DoEllipse(); override;` |  | Draws an Arc of 360 degrees within the specified Bounds.
`procedure DoEllipseFill(); override;` |  | DoEllipseFill calls Ellipse.
`procedure DoEllipseAndFill(); override;` |  | DoEllipseAndFill calls the inherited DoEllipseAndFill.
`procedure DoPolygon(); override;` |  | DoPolygon calls PolyLine to draw a series of lines through the points.
`procedure DoPolygonFill(); override;` |  | DoPolygonFill calls Polygon for the supplied points.
`procedure DoPolygonAndFill(); override;` |  | DoPolygonAndFill calls inherited method.
`procedure DoPolyline(); override;` |  | DoPolyline calls PolyLine.
`procedure DoPolyBezier(); override;` |  | Performs actions needed to draw a Bézier curve using the specified control points.
`procedure DoFloodFill(); override;` |  | DoFloodFill calls the FloodFill method.
`procedure DoMoveTo(); override;` |  | DoMoveTo calls the MoveTo method.
`procedure DoLineTo(); override;` |  | DoLineTo calls the LineTo method.
`procedure DoLine(); override;` |  | DoLine calls Line to draw from x1, y1 to x2, y2.
`procedure DoCopyRect(); override;` |  | Verifies and copies the source canvas.
`procedure DoDraw(); override;` |  | DoDraw checks that Image is of the right type, makes a local copy, creates the necessary handles and bitmaps for drawing.
`procedure CheckHelper(); override;` |  | Ignored in the current implementation of the class.
`function GetDefaultColor(); virtual;` |  | Gets the default color value for the canvas.
`function GetClipRect; override;` |  | GetClipRect - if an error is encountered in finding the Clipping Rectangle dimensions, sets some defaults anyway.
`procedure SetClipRect(); override;` |  | Sets the value for the ClipRect property.
`function GetClipping; override;` |  | GetClipping returns True if clipping is being performed.
`procedure SetClipping(); override;` |  | SetClipping specifies whether clipping is to be performed.
`function GetPixel(); virtual;` |  | Gets the value for the indexed Pixels property.
`procedure CreateBrush; virtual;` |  | Ensures that the handle for the Brush is valid and configured with the Brush settings.
`procedure CreateFont; virtual;` |  | Ensures that the Font for the canvas is valid and uses the correct color.
`procedure CreateHandle; virtual;` |  | Creates a new Handle for the Canvas.
`procedure CreatePen; virtual;` |  | Ensures that the Pen for the canvas is valid, configured, and positioned.
`procedure CreateRegion; virtual;` |  | Ensures that the handle for the canvas Region is valid.
`procedure DeselectHandles; virtual;` |  | Deselects all sub-handles in the current device context.
`procedure PenChanging(); virtual;` |  | Implements the default OnChanging event handler used for the Pen in the canvas.
`procedure FontChanging(); virtual;` |  | Implements the OnChanging event handler for the Font used on the canvas.
`procedure BrushChanging(); virtual;` |  | Implements the OnChanging event handler for the Brush on the canvas.
`procedure RegionChanging(); virtual;` |  | Implements the OnChanging event handler for the Region on the canvas.
`procedure RealizeAutoRedraw; virtual;` |  | Implements the AutoRedraw feature when enabled.
`procedure RealizeAntialiasing; virtual;` |  | Implements the Anti-aliasing feature for the canvas.
`procedure RequiredState(); virtual;` |  | Ensures that all handles needed for the canvas are valid.
`procedure SetHandle(); virtual;` |  | Sets the value for the Handle property.
`procedure SetInternalPenPos(); virtual;` |  | SetInternalPenPos - specify position for the Pen.
`procedure SetPixel(); virtual;` |  | Sets a value in the indexed Pixels property.
`procedure FreeHandle; virtual;` |  | Frees the Handle for the canvas.
`public`
`constructor Create;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`procedure Lock; virtual;` |  | Lock the canvas, making it unavailable for drawing.
`function TryLock;` |  | TryLock - examines the Lock state, and performs Lock if necessary.
`procedure Unlock; virtual;` |  | Unlock or release a previously locked Canvas.
`procedure Refresh; virtual;` |  | Sets Pen, Brush, and Font handles to their default values.
`procedure Changing; virtual;` |  | Signals the OnChanging event handler (when assigned).
`procedure Changed; virtual;` |  | Signals the OnChange event handler (when assigned).
`procedure SaveHandleState; virtual;` |  | Stores the state for the Handle in the canvas.
`procedure RestoreHandleState; virtual;` |  | Restores the previous Handle state for the canvas.
`procedure Arc();` |  | Use Arc to draw an elliptically curved line with the current Pen.
`procedure ArcTo(); virtual;` |  | Draws an elliptically curved line and updates the Pen position.
`procedure AngleArc();` |  | Draws an arc over a specified angle along the circumference of a circle.
`procedure BrushCopy(); virtual;` |  | Copies part of a bitmap to a rectangle on the canvas and replaces the transparent color with the canvas Brush color.
`procedure Chord();` |  | Draw a filled chord shape starting and finishing at the specified angular positions on the circumference.
`procedure CopyRect(); virtual;` |  | Copies the rectangle found at Source in SrcCanvas to the destination position in Dest.
`procedure Draw(); virtual;` |  | Draws the image content in SrcGraphic on the canvas at the specified position.
`procedure DrawFocusRect(); virtual;` |  | Draws a focus rectangle around the specified rectangle on the canvas.
`procedure StretchDraw(); virtual;` |  | Expands or contracts the specific graphic content to fit the specified destination rectangle on the canvas.
`procedure Ellipse();` |  | Draws a filled ellipse (or circle) on the canvas.
`procedure FillRect();` |  | Fills a rectangular area on the canvas using the current Brush settings.
`procedure FloodFill(); virtual;` |  | Fills an area at the specified coordinates with the current Brush for the canvas.
`procedure Frame3d();` |  | Draws a frame for the specified rectangle with a 3-dimensional appearance.
`procedure Frame();` |  | Draws a frame or border around the specified rectangle using the Pen for the canvas.
`procedure FrameRect();` |  | Draws a border around the specified rectangle with the Brush for the canvas.
`function GetTextMetrics(); virtual;` |  | Gets text metrics for the canvas font.
`procedure GradientFill();` |  | Fills a rectangle with a color gradient using the specified colors in a given direction.
`procedure RadialPie(); virtual;` |  | RadialPie draws a filled pie-shaped wedge on the canvas with specified start and end coordinates, and starting and ending angular positions.
`procedure Pie(); virtual;` |  | Pie draws a filled Pie-shaped wedge on the canvas.
`procedure PolyBezier();` |  | Polybezier draws cubic Bézier curves.
`procedure Polygon();` |  | Draws a closed, many-sided shape using the Pen for the canvas.
`procedure Polyline();` |  | Draws a line which connects a set of points on the canvas.
`procedure Rectangle();` |  | Draws a Rectangle with the specified coordinates.
`procedure RoundRect();` |  | Draws a rectangle with rounded corners at the specified position.
`procedure TextOut(); virtual;` |  | Writes text at the specified position on the canvas.
`procedure TextRect();` |  | Draws text on the canvas at the specified location using the given style.
`function TextExtent(); virtual;` |  | Calculates the width and height for the specified Text using the Font for the canvas.
`function TextHeight(); virtual;` |  | Gets the height for the specified text using the canvas Font.
`function TextWidth(); virtual;` |  | Gets the width for the specified text using the canvas Font.
`function TextFitInfo();` |  | Gets the number of characters that fit in the specified maximum width.
`function HandleAllocated; virtual;` |  | Checks whether the Handle has been allocated for the canvas.
`function GetUpdatedHandle(); virtual;` |  | Checks the required canvas states and gets the updated Handle for the canvas.
`property Pixels []: TColor; [rw]` |  | The color of the Pixels located at the specified position.
`property Handle: HDC; [rw]` |  | Handle (or device context) for the drawing surface.
`property TextStyle: TTextStyle; [rw]` |  | Text style attributes used to draw text on the canvas.
`published`
`property AntialiasingMode: TAntialiasingMode; [rw]` |  | Controls anti-aliasing for canvas drawing operations.
`property AutoRedraw: Boolean; [rw]` |  | AutoRedraw - if True, the Canvas is to be redrawn automatically after each change or update.
`property Brush: TBrush; [rw]` |  | The Brush used to paint on the Canvas.
`property CopyMode: TCopymode; [rw]` |  | Indicates the raster operation used to combine pixel colors on the drawing surface.
`property Font: TFont; [rw]` |  | Contains the Font used to render text on the drawing surface.
`property Height: Integer; [r]` |  | Height of the canvas.
`property Pen: TPen; [rw]` |  | The Pen to be used for writing in this canvas.
`property Region: TRegion; [rw]` |  | The Region where the Canvas is located.
`property Width: Integer; [r]` |  | The Width of the Canvas.
`property OnChange: TNotifyEvent; [rw]` |  | Event handler signalled after a change to the canvas.
`property OnChanging: TNotifyEvent; [rw]` |  | Event handler signalled prior to changing the canvas.
`end;`

## Inheritance

`TCanvas` |  | Implements a drawing surface for a visual control or bitmap image.
`TFPCustomCanvas`
?
`TObject`

## Description

TCanvas is a descendant of the TFPCustomCanvas class in the FCL (Free Pascal Component Library). TCanvas implements a drawing surface which can be used to display a visual control or render output to a bitmap. TCanvas provides drawing tools like Brush, Pen, and Font needed to draw on the surface. Events are provided to respond to change notifications and progress events. Methods are provided to implement common drawing operations, such as:

- Pen, Brush, and Color selection
- Drawing lines or shapes
- Filling shapes with colors or patterns
- Rendering text to the drawing surface
- Rendering image content to the drawing surface
- Direct manipulation of pixels on the drawing surface

A TCanvas instance (or a specialized descendant) is used in visual controls which are responsible for rendering their own content. It is also used in non-visual components like TPrinter, and in class that provide support for drawing operations using bitmap data.

## See also

TSharedRasterImage |  | Implements a reference counted raster image that may be shared between controls.
TGraphicControl.Canvas |  | A clipped window into the parent Canvas.
TCustomControl.Canvas |  | The drawing surface for the control.
TControlCanvas |  | Base class which provides a canvas property used in graphic controls.