# GAMBAS BOOK 3.19.2

### Site Tools

k23:k23.3:k23.3.2:start

## 23.3.2 Methods of the Paint class

The Paint class (gb.qt4) only has (static) methods. The many methods are grouped together in the tables below to make it easier to visualise relationships. After the tables you will find notes on the use of selected methods and descriptions of the parameters.

You should definitely take a look at the Painting project from the Gambas examples, as it not only demonstrates drawing with the Paint class, but also shows the (paint) source code used for the 22 lines and areas:

Figure 23.3.2.1: Project Painting - Example 9: Fill style

## 23.3.2.1 Methods

The Paint class has these methods:

MethodDescription
Begin ( Device As Object [ Area As RectF ])Starts drawing on the specified device (drawing area: DrawingArea, Picture, Image, Printer, SVGImage). The call can be nested.
End ( )Ends the drawing. You must call this method just as often as the Paint.Begin(..) method.
NewPath ( )Deletes the current drawing path. After the call, neither a path nor a current (start) point exists.
ClosePath ( )Adds a line segment to the current path, from the current point to the starting point of the current partial path (this is the point that was last passed to Paint.MoveTo()). This closes the current path and the current point becomes the common start and end point of the path.
Scale ( SX As Float, SY As Float )Changes the current transformation matrix (CTM) by scaling the x and y user space axes with the factors SX and SY. SX: Scaling factor for the x-direction, SY: Scaling factor for the y-direction
Translate ( TX As Float, TY As Float )Changes the CTM by shifting the coordinate origin by TX and TY. TX: displacement distance in x-direction, TY: displacement distance in y-direction
Rotate ( Angle As Float )Changes the CTM by rotating the coordinate axes for a given rotation angle Angle (radian measure). The direction of rotation for positive rotation angles corresponds to a rotation from the positive x-axis in the direction of the positive y-axis (mathematically positive).
Clip ( [ Preserve As Boolean ] )Creates a new clip region by cutting the current clip region with the current path - taking into account the current FillRule. After Clip() is applied, the current path is deleted unless the Preserve argument is TRUE. The current clip region affects all drawing operations: all changes outside this region are ignored. A call to Clip() can only make the clip region smaller, never larger, but the current clip is a property of the paint state. You can achieve a temporary clip restriction by clipping within a Paint.Save()/Paint.Restore() pair. Only Paint.ResetClip() enlarges the clip region again.
ResetClip ( )Resets the current clip region to its original, unrestricted state.
Reset()Resets the CTM to the identity matrix (output matrix).
Save ( )Creates a copy of the current paint state and saves it in an internal stack of saved states. If Restore is called, the drawing state is restored from the saved state. Multiple calls for saving and restoring can be nested.
Restore ( )Restores the paint state by calling the saved state. The saved state is then deleted from the stack of saved states.

## 23.3.2.2 Methods - Colour and pattern

MethodDescription
Color ( Color As Integer ) As PaintBrushCreates a new brush corresponding to an opaque or translucent colour. The colour 'Color' is defined as for all GUI components → Chapter 25.3.5 Working with colours
LinearGradient ( X0 As Float, Y0 As Float, X1 As Float, Y1 As Float, Colors As Integer[], Positions As Float[] [ , Extend As Integer ] ) As PaintBrushCreates a new linear gradient brush along the line defined by (X0/Y0) and (X1/Y1) and defines colour stops from the colour and position arguments.
RadialGradient ( CX As Float, CY As Float, Radius As Float, FX As Float, FY As Float, Colors As Integer[], Positions As Float[] [ , Extend As Integer ] ) As PaintBrushCreates a new radial gradient brush, where the colours are interpolated between a focal point (FX/FY) and the end point on a circular area defined by (CX0/CY0, Radius0) and defines colour stops from the colour and position arguments.

## 23.3.2.3 Methods - Lines and areas

MethodDescription
MoveTo ( X As Float, Y As Float )Starts a new (sub)path. After this call, the current point has the coordinates P(x/y).
RelMoveTo(DX, DY)Starts a new (sub)path. After this call, the current point P' has an offset of DX and DY compared to the starting point P. With a starting point P(x/y), the current point has the coordinates P'(x+DX/y+DY) after using RelMoveTo(DX,DY).
LineTo ( X As Float, Y As Float )Adds a distance (straight line segment) from the existing start point P(x0/y0) to the point P'(X/Y) in user space coordinates to the path.
RelLineTo ( DX As Float, DY As Float )Adds a distance (straight line segment) from the start point P(x0/y0) to the current point P'(x0+DX/y0+DY) to the path in user space coordinates.
Rectangle ( X As Float, Y As Float, Width As Float, Height As Float [ , Radius As Float ] )Adds a closed sub-path to the existing path in user-space coordinates for the rectangle of the specified size.
FillRect ( X As Float, Y As Float, Width As Float, Height As Float, Color As Integer )Draws the rectangle defined by the start point, length and height and fills it with the specified colour.
Polygon ( Points As Float[] )Adds a closed sub-path to the existing path for the polygon with the specified points. Points is a float array, where each pair of values describes a point of the polygon. Consequently, the number of elements in the float array must be even. The minimum number is four. The polygon is closed automatically.
Ellipse ( X As Float, Y As Float, Width As Float, Height As Float [ , Angle As Float, Length As Float, Pie As Boolean ] )Adds an elliptical arc to the path. The ellipse is defined by its bounding box (X, Y, width, height). The elliptical arc begins with the start angle 'Angle' and runs anti-clockwise with the angle 'Length'. The reference axis for 0 degrees is the positive x-axis. All angles must be specified in radians. Use the wheel function to convert a degree measurement into radians.
Arc ( XM As Float, YM As Float, Radius As Float [ , Angle As Float, Length As Float, Pie As Boolean ] )Adds an arc with the given radius to the path. The arc is centred at (XM, YM) and begins with the (start) angle Angle and rotates the centre angle anti-clockwise with the angle Length. The reference axis for 0 degrees is the positive x-axis. All angles must be specified in radians. Use the wheel function to convert a degree measurement to radians.
CurveTo ( X1 As Float, Y1 As Float, X2 As Float, Y2 As Float, X3 As Float, Y3 As Float )Adds a cubic Bezier curve (spline) from the current position to the position (X3/Y3) in user space coordinates to the path, where (X1/Y1), (X2/Y2) and (X3/Y3) are support points. After this call, the current point will be (X3/Y3).
RelCurveTo ( X1 As Float, Y1 As Float, X2 As Float, Y2 As Float, X3 As Float, Y3 As Float )Adds, just like CurveTo(), a cubic Bezier curve. Here, however, all arguments are interpreted as offsets relative to the current point.
Stroke ( [ Preserve As Boolean ] )The (line) path is traced with the current line definition (line width, line shape and line end shape). The path is deleted after Paint.Stroke() - unless the Preserve argument is set to the value TRUE.
Fill ( [ Preserve As Boolean ] )Fills the area limited by the current path using the current area definition (FillRule). Each partial path is automatically closed beforehand. After Paint.Fill(), the path is deleted - but only if the optional Preserve argument has not been set to TRUE.

## 23.3.2.4 Methods - Text and images

MethodDescription
Text ( Text As String [ , X As Float, Y As Float, Width As Float, Height As Float, Alignment As Integer ] )Adds the specified text to the path. The current font is used, which is set via the font property.
TextSize ( Text As String ) As RectFReturns the bounding box (data type RectF (with coordinates of type Float)) that is required by the text string. In contrast to TextExtents, the font size is used - not the height of the text actually drawn.
TextExtents ( Text As String ) As PaintExtentsDetermines the dimensions (data type PaintExtents) for the text string. The extents describe a user-space rectangle that encloses the actual drawn text as it would have been created by Paint.Text and Paint.Fill without a transformation matrix.
TrimText ( Text As String, W As Float [ , H As Float ] ) As StringReturns a trimmed text that fits into the specified rectangle. If the text fits into the rectangle from the outset, it is returned unchanged. Otherwise, it is shortened and supplemented with an ellipsis so that it fits.
RichText ( Text As String [ , X As Float, Y As Float, Width As Float, Height As Float, Alignment As Integer ] )Adds the specified RichText to the path. The current font is used, which is set via the font property.
RichTextSize ( Text As String [ , Width As Float ] ) As RectFReturns the bounding box (data type RectF (with coordinates of type Float)) that is required by the RichText string. In contrast to RichTextExtents, the font size is used - not the actual text drawn.
RichTextExtents ( Text As String [ , Width As Float ] ) As PaintExtentsDetermines the dimensions (data type PaintExtents) for the RichText string. Die Ausmaße beschreiben ein User-Space-Rechteck, das den tatsächlich gezeichneten Text umschließt, wie es von Paint.RichText und Paint.Fill ohne Transformationsmatrix erstellt worden wäre. Da nur ein Pfad erstellt wird, werden durch die <font>-Auszeichnung definierte Schrift-Farben nicht berücksichtigt!
TrimRichText ( RichText As String, W As Float [ , H As Float ] ) As StringReturns a shortened version of the given RichText that fits into the given rectangle. If the RichText fits in, it is returned unchanged. Otherwise, it is shortened and an ellipsis is added so that it fits.
DrawImage ( Image As Image, X As Float, Y As Float [ , Width As Float, Height As Float, Opacity As Float, Source As Rect ] ) Draws an image or part of an image. The X, Y, Width and Height arguments specify the position and maximum extent of the image on the drawing area. The desired partial image from the transferred image can be specified as a rectangle in the source argument.
DrawPicture ( Picture As Picture, X As Float, Y As Float [ , Width As Float, Height As Float, Source As Rect ] )Draws a picture or part of a picture. The X, Y, Width and Height arguments specify the position and maximum extent of the image on the drawing area. The desired partial image from the transferred picture can be specified as a rectangle in the source argument.
DrawText ( Text As String [ , X As Float, Y As Float, Width As Float, Height As Float, Alignment As Integer ] )Draws the specified text. If you specify the optional parameters, the text is limited by the specified rectangle and aligned according to the alignment parameter. This method is faster than drawing the text with Paint.Text and then Paint.Fill.
DrawTextShadow ( Text As String, X As Float, Y As Float, W As Float, H As Float [ , Alignment As Integer, Radius As Integer, Opacity As Float ] )Draws the shadow of a text.
DrawRichText ( Text As String [ , X As Float, Y As Float, Width As Float, Height As Float, Alignment As Integer ] )Draws the specified rich text. If you specify the optional parameters, the text is limited by the specified rectangle and aligned according to the alignment parameter. This method is faster than drawing the text with Paint.RichText and then Paint.Fill.
DrawRichTextShadow ( Text As String, X As Float, Y As Float, W As Float, H As Float [ , Alignment As Integer, Radius As Integer, Opacity As Float ] )Draws the shadow of a RichText.
Image ( Image As Image [ , X As Float, Y As Float ] ) As PaintBrushCreates a new brush from an image. Image is the image object and X and Y are the (optional) values (data type float) from the brush matrix and specify the initial translation of the image.

Tables 23.3.2.4.1 : Methods of the Paint class

## 23.3.2.5 Notes

The following notes supplement the contents of the tables. Arguments are described in more detail and special features are pointed out. Examples and complete projects can be found in the following two → chapters 23.3.3 Paint projects 1 and 23.3.4 Paint projects 2.

ClosePath

• ClosePath() is different from a LineTo() with the appropriate coordinates.
• If a closed path (with the first method) is drawn with Stroke(), there are no caps (Paint.LineCap) at the line ends, but the lines are joined (Paint.LineJoin).
• If there is no current point when ClosePath() is called, this method has no effect.

Circle and arc

The notes for an arc are very extensive on the one hand and only valid in certain combinations on the other:

• XM : x-coordinate of the centre of the arc
• YM : y-coordinate of the centre of the arc
• Angle : Starting angle - measured against the positive x-axis
• Length : Measure for the centre angle
• Pie : For True, this results in a closed sector ('pie slice'). Standard is an open arc.
• If Length is negative, the arc is drawn in a clockwise direction.
• If Angle and Length are not specified, a full circle is drawn.
• If the Angle value is specified but not Length, nothing is drawn. The current position is set to the (end) point on the arc.
• To draw an elliptical arc instead of a circular arc, you must use the Ellipse method with suitable arguments.

Figure 23.3.2.4.1: Circular arc - circle sectors

Source code:

```Public Sub DrawArcs()
Paint.AntiAlias = True
Paint.LineWidth = 1
Paint.Brush = Paint.Color(Color.Red)
Paint.Arc(100, 140, 70, Rad(45), 3 * Pi / 2, False)
Paint.Stroke()
Paint.Arc(260, 140, 70, Pi / 4, Rad(270), True)
Paint.Stroke()
Paint.Arc(420, 140, 70, Pi / 4, 3 * Pi / 2, True)
Paint.Fill()
Paint.Dash = [2, 2]
Paint.Arc(420, 140, 70, Pi / 4 + 3 * Pi / 2, Rad(90), False)
Paint.Stroke()
Paint.Dash = []  '-- Null
Paint.AntiAlias = False
End```

Rounded rectangles

If the optional radius argument is defined, the rectangle will have rounded 'corners'. The radius argument determines the radius of the rounding. The radius must not be greater than half of the shortest side of the rectangle.

Polygon - special case triangle

This source code is used to draw a light blue triangle ABC:

```Paint.LineWidth = 1
Paint.Brush = Paint.Color(&C3DDFF)
Paint.Polygon([20, 20, 30, 160, 200, 70]) '-- A(20|20), B(30|160) and C(200|70)
Paint.Fill()```

Ellipses

`Ellipse ( X As Float, Y As Float, Width As Float, Height As Float [ , Angle As Float, Length As Float, Pie As Boolean ] )`
• X, Y, Width, Height : bounding box of the ellipse
• Angle : Start angle
• Lenght : Swept angle
• Pie : A closed sector results for True. Standard is an open arc.
• If Length is negative, the elliptical arc is drawn in a clockwise direction.
• If Angle and Length are not specified, a complete ellipse is drawn.
• If the Angle value is specified - but not Length - then nothing is drawn. The current position is set to the (end) point on the ellipse arc.

Cubic Bezier curve

`CurveTo ( X1 As Float, Y1 As Float, X2 As Float, Y2 As Float, X3 As Float, Y3 As Float )`
• X1 : x-coordinate of the first support point (start point)
• Y1 : y-coordinate of the first support point
• X2 : x-coordinate of the second support point
• Y2 : y-coordinate of the second support point
• X3 : x-coordinate of the third support point (end point)
• Y3 : y-coordinate of the third support point

If there was no current point before the call of Paint.CurveTo(..), the function will behave as if the call was preceded by the Paint.MoveTo(X1|Y1) method to ensure a defined start.

Cubic Bezier curve with relative coordinates - version of CurveTo(..)

`RelCurveTo ( X1 As Float, Y1 As Float, X2 As Float, Y2 As Float, X3 As Float, Y3 As Float )`
• DX1 : x-offset of the first support point (start point)
• DY1 : y offset of the first support point
• DX2 : x-offset of the second support point
• DY2 : y-offset of the second support point
• DX3 : x-offset of the third support point (end point)
• DY3 : y-offset of the third support point

Paint.CurveTo(X+DX1, Y+DY1, X+DX2, Y+DY2, X+DX3, Y+DY3) is logically equivalent to the call Paint.RelCurveTo (DX1, DY1, DX2, DY2, DX3, DY3) at a current point (X|Y).

Text

`Text(Text As String [, X As Float,Y As Float,Width As Float,Height As Float,Alignment As Integer ] )`
• X, Y, Width, Height : A rectangle in which the text is drawn
• Alignment : Alignment of the text in the rectangle

If only the text is specified, the text is drawn at the current point. The y-coordinate of the current point determines the BaseLine for the text. The term 'BaseLine' can be described very simply using the word annoyance. Mentally draw a line from the base point of the letter A to the base point of the small r - this is the BaseLine. If only the arguments X and Y are specified next to the text, the text is drawn at the point P(X|Y). The y-coordinate of P determines the BaseLine for the text. Otherwise, the text is drawn within the specified rectangle. Please note that the rectangle does not cut off the text!

RichText

`RichText ( Text As String [ , X As Float, Y As Float, Width As Float, Height As Float, Alignment As Integer ] )`
• The same notes apply to the optional arguments as for the Text() method.
• As only one path is created, font colours defined by the <font> markup are not taken into account!

TrimText – TrimRichText

```TrimText ( Text As String, W As Float [ , H As Float ] ) As String
TrimRichText ( RichText As String, W As Float [ , H As Float ] ) As String```
• Text : Text to be customised
• W : Length of the (enclosing) rectangle
• H : optional height of the (enclosing) rectangle. If it is not specified, the font size is assumed. In other words: The text should fit into a single line.

DrawImage

`DrawImage ( Image As Image, X As Float, Y As Float [ , Width As Float, Height As Float, Opacity As Float, Source As Rect ] )`
• Image : Image to be drawn
• X, Y : Coordinates of the starting point (top left)
• Width, Height : If specified, the image is scaled to width and height
• Opacity : The opacity used to create the image is between 0 (completely transparent) and 1.0 (completely opaque). The default value is 1.
• Source : If specified (data type Rect), only the part of the image described by the rectangle is taken into account.

DrawPicture

`DrawPicture ( Picture As Picture, X As Float, Y As Float [ , Width As Float, Height As Float, Source As Rect ] )`
• Picture : Picture to be drawn
• X, Y : Coordinates of the starting point
• Width, Height : If specified, the image is scaled to width and height
• Source : If specified (data type Rect), only the part of the image described by the rectangle is taken into account.

```DrawTextShadow ( Text As String, X As Float, Y As Float, W As Float, H As Float [ , Alignment As Integer, Radius As Integer, Opacity As Float ] )
DrawRichTextShadow ( Text As String, X As Float, Y As Float, W As Float, H As Float [ , Alignment As Integer, Radius As Integer, Opacity As Float ] )```
• X, Y, W, H : Define the rectangle in which the drawing takes place
• Alignment : Determines the alignment of the text, default is Align.Left
• Radius : Blending radius in pixels. By default, the value is 1/8 of the font height
• Opacity : The opacity is between 0.0 and 1.0. The default value is 0.5 (50% transparent)
• You must call Paint.DrawText() or Paint.RichText() to draw the actual text for the shadow.

`LinearGradient ( X0 As Float, Y0 As Float, X1 As Float, Y1 As Float, Colors As Integer[], Positions As Float[] [ , Extend As Integer ] ) As PaintBrush`
• X0 : x-coordinate starting point
• Y0 : y-coordinate starting point
• X1 : x-coordinate end point
• Y1 : y-coordinate end point
• The points (X0, Y0) and (X1, Y1) define a line of length L that connects the two points.
• Colors : Array of colour values
• Positions : Array of colour positions; 0 for gradient start and 1 for gradient end. A position q (float) between 0 and 1 corresponds to the point Q on the defined path that is q*L away from the start point and (1-q)*L away from the end point. A position in the position array is also called a stopper. The colour with the same index from the colours array belongs to a stopper. This colour has the greatest intensity at the stopper.
• The following illustration shows a linear gradient from (0|0) to (200|70) across the colours black, yellow and blue. The stoppers are shown as red dots at 0 and 0.3 as well as 1.0.

`RadialGradient (CX As Float,CY As Float,Radius As Float,FX As Float,FY As Float,Colors As Integer[],Positions As Float[] [,Extend As Integer ]) As PaintBrush`