Class

Graphics


Description

Graphics class objects are used for drawing text, lines, rectangles, ovals, and pictures.

Methods

Name

Parameters

Returns

Shared

ClearRectangle

X As Double, Y As Double, Width As Double, Height As Double

Clip

X As Double, Y As Double, Width As Double, Height As Double

Graphics

ClipToPath

path As GraphicsPath

ClipToRectangle

x As Double, y As Double, width As Double, height As Double

DrawCautionIcon

X As Double, Y As Double

DrawLine

X1 As Double, Y1 As Double, X2 As Double, Y2 As Double

DrawNoteIcon

X As Double, Y As Double

DrawObject

Object As Object2D, [DeltaX As Double, DeltaY As Double]

DrawOval

X As Double, Y As Double, Width As Double, Height As Double

DrawPath

path As GraphicsPath

DrawPicture

Image As Picture, X As Double, Y As Double, [destWidth As Double], [destHeight As Double], [sourceX As Double], [sourceY As Double], [sourceWidth As Double], [sourceHeight As Double]

DrawRectangle

X As Double, Y As Double, Width As Double, Height As Double

DrawRoundRectangle

X As Double, Y As Double, Width As Double, Height As Double, ArcWidth As Double, ArcHeight As Double

DrawStopIcon

X As Double, Y As Double

DrawText

Text As String, X As Double, Y As Double, [WrapWidth As Double, Condense As Boolean]

FillOval

X As Double, Y As Double, Width As Double, Height As Double

FillPath

path As GraphicsPath, autoClose As Boolean = False

FillRectangle

X As Double, Y As Double, Width As Double, Height As Double

FillRoundRectangle

X As Double, Y As Double, Width As Double, Height As Double, ArcWidth As Double, ArcHeight As Double

Handle

type As HandleTypes

Ptr

LineDash

Assigns values() As Double

Double

NextPage

RestoreState

Rotate

angle As Double

angle As Double, x As Double, y As Double

SaveState

Scale

x As Double, y As Double

TextDirection

Text As String

TextDirections

TextHeight

Double

Text As String, Optional WrapWidth As Double

Double

TextWidth

Text As String

Double

Translate

translateX As Double, translateY As Double

Enumerations

Graphics.AntiAliasModes

AntiAliasModes

Specifies the quality of antialiasing when drawing pictures.

Enum

LowQuality

DefaultQuality

HighQuality

Graphics.LineCapTypes

LineCapTypes

Specifies the various ways the end of a line is drawn.

Enum

Description

Butt

A squared-off ending that ends at the line boundary.

Round

A rounded ending that extends beyond the line boundary. This is the default.

Square

A squared-off ending that extends beyond the line boundary.

Graphics.LineJoinTypes

LineJoinTypes

Specifies the various ways lines can be joined.

Types

Bevel

Miter

Round

Graphics.TextDirections

TextDirections

Specifies in which direction text will be rendered.

Enum

Description

Unknown

The direction in which text will be drawn could not be determined.

LeftToRight

The text is drawn from left to right.

RightToLeft

The text is drawn from right to left.

Graphics.HandleType

HandleType Constants

Specifies the type of OS handle you wish to receive for use with the Handle property.

Enum

Description

CairoContext

Gets a handle to the Cairo Context on Linux.

CGContextRef

Gets the CGContextRef on macOS.

HDC

Gets the HDC on Windows.

Direct2DRenderTarget

Gets the Direct2D render target on Windows.

Property descriptions


Graphics.AntiAliased

AntiAliased As Boolean

Used to draw smooth lines and shapes, including text where applicable. This property is True by default.

The following example is in the Paint event of the main window.

g.AntiAliased = True

Graphics.AntiAliasMode

AntiAliasMode As Boolean

Controls the level of interpolation/quality when drawing scaled Pictures. Valid modes are from the Graphics.AntiAliasModes enumeration: LowQuality, DefaultQuality, and HighQuality. The default is DefaultQuality.

Use High Quality (set in Paint event of a Canvas):

g.AntiAliasMode = Global.Graphics.AntiAliasModes.HighQuality

Graphics.Bold

Bold As Boolean

If True, applies the bold style to the control’s caption and/or its text content if any.

Mac apps can only display font styles that are available. You cannot force a font to display in bold or italic if it does not have bold or italic variations available. In this situation, the Bold property will not affect the font.


Graphics.Brush

Brush As GraphicsBrush

The brush to be used when drawing.

This code in the Paint event, draws an oval with a linear gradient:

Var linearBrush As New LinearGradientBrush
linearBrush.StartPoint = New Point(0, 0)
linearBrush.EndPoint = New Point(g.Width, g.Height)
linearBrush.GradientStops.Add(New Pair(0, Color.Red))
linearBrush.GradientStops.Add(New Pair(0.4, Color.Yellow))
linearBrush.GradientStops.Add(New Pair(0.7, Color.Magenta))
linearBrush.GradientStops.Add(New Pair(1.0, Color.Blue))

g.Brush = linearBrush
g.FillOval(0, 0, g.Width, g.Height)

Graphics.CharacterSpacing

CharacterSpacing As Integer

This property is expressed as a percentage of spacing between characters. Positive and negative values are accepted.


Graphics.Copies

Copies As Integer

The value in the Copies field of the Print dialog box.

This property is read-only.

This property is only meaningful when the Graphics object was created by the ShowPrinterDialog function.

On macOS this always return 1 as macOS takes care of respecting the number of copies the user requested and the app only needs to provide a single copy.


Graphics.DrawingColor

DrawingColor As Color

The currently selected color for the Graphics object. This color is used by the various drawing methods.

This example draws a diagonal line in the current DrawingColor.

g.DrawingColor = &cff0000
g.FillRectangle(10, 10, 100, 100)

Graphics.FirstPage

FirstPage As Integer

The value in the From field of the Print dialog box.

This property is read-only.

This property is meaningful only when the Graphics object was created by the ShowPrinterDialog function.


Graphics.Font

Font As Font

The font used for displaying text.

This in the Paint event draws text using a specific font:

g.Font = Font.BoldSystemFont
g.DrawText("Hello", 5, 20)

Graphics.FontAscent

FontAscent As Double

Returns the ascent of a line of text drawn with the current font.

This property is read-only.

FontAscent is the height of the tallest font letter above the font baseline.

The following example gets the font ascent of the text that was drawn with DrawText.

g.DrawingColor = &cff0000
g.Italic = True
g.DrawText("Hello world", 10, 10)
MessageBox(g.FontAscent.ToString)

Graphics.FontName

FontName As String

Name of the font used to display the caption or text content.

When used with PDFDocument, you can assign font names using the StandardFontNames enumeration.

You can enter any font that is installed on the computer or the names of the two metafonts, “System” and “SmallSystem”.

The System font is the font used by the system software as its default font. Different operating systems use different default fonts. If the system software supports both a large and small System font, you can also specify the “SmallSystem” font as your FontName.

On macOS, “SmallSystem” specifies the smaller system font and may make the control smaller in size as well. On Windows and Linux, “SmallSystem” is the same as “System”.

This code sets the FontName property.

Me.FontName = "Helvetica"

Graphics.FontSize

FontSize As Single

Point size of the font used to display a caption or text content.

If you enter zero as the TextSize, your app will use the font size that works best for the platform on which it is running.

This code sets the font size to 16 points.

Me.FontSize = 16

Graphics.FontUnit

FontUnit As FontUnits

The units in which FontSize is measured.

Note

FontUnit and the FontUnits enumeration are not available for use in Console or Web apps.

The FontUnits enumeration values are shown below:

Value

Default

Pixel

Point

Inch

Millimeter

This example sets the units to points using the class constant.

g.DrawingColor = &cff0000
g.Italic = True
g.FontUnit = FontUnits.Point
g.FontSize = 16
g.DrawText("Hello world", 10, 10)

Graphics.Height

Height As Integer

The height in pixels of the parent object, typically a Canvas control or a Window.

This property is read-only.

For example, if the Graphics class object is in a Canvas control, Height returns the height of the control.

This example in the Canvas.Paint event draws a box the height of the Canvas itself:

g.DrawingColor = &c0000ff
g.FillRectangle(0, 0, g.Width, g.Height)

Graphics.Italic

Italic As Boolean

If True, text will appear in italic when using DrawText.

This example draws “Hello World” in red italic inside a Canvas.

g.DrawingColor = Color.Red
g.Italic = True
g.DrawText("Hello world", 10, 10)

Graphics.LastPage

LastPage As Integer

The value in the “To” field of the Print dialog box.

This property is read-only.

This property is meaningful only when the Graphics object was created by the ShowPrinterDialog function.


Graphics.LineCap

LineCap As LineCapTypes

The way in which the end of the line will be drawn.

Affects only lines drawn when using DrawPath, GraphicsPath and Object2D.

In the Paint event of a Canvas, set the line cap to round:

g.LineCap = Graphics.LineCapTypes.Round

Graphics.LineDashOffset

LineDashOffset As Double

Specifies the starting point of the dash.

An offset of 0.5 would mean the first dash would start at half size.

Draws a line with 2 unit dashes and 2 unit gaps with the first dash offset by 1.

g.LineDash = Array(2.0, 3.0)
g.LineDashOffset = 1.0
g.DrawLine(0, 0, g.Width, g.Height)

Graphics.LineJoin

LineJoin As LineJoinTypes

The way in which the end of the line will be drawn when connecting to another line.

Affects only lines drawn when using DrawPath, GraphicsPath and Object2D. It will also affect how corners are drawn when using DrawRectangle.

In the Paint event of a Canvas, set the line join to round:

g.LineJoin = Graphics.LineJoinTypes.Round

Graphics.Outline

Outline As Boolean

If True, applies the outline style to the control’s caption and/or its text content if any.

Mac apps can only display font styles that are available. You cannot force a font to display in bold or italic if it does not have bold or italic variations available. In this situation, the bold property will not affect the font.

When using Outline on MacOS and Windows, Underline is not supported.

GraphicsBrush is ignored when using Outline on iOS.

This example sets the text to Outline.

Me.Outline = True

Graphics.PenSize

PenSize As Double

The size in points used when drawing lines, ovals and rectangles.

This example sets the PenSize to 5 point:

g.PenSize = 5
g.DrawRectangle(150, 10, 100, 100)

Graphics.PrintingCancelled

PrintingCancelled As Boolean

If True, the current print job has been cancelled. When used on a non-print Graphics object, it will always return False.

This property is read-only.


Graphics.ScaleX

ScaleX As Double

The scale factor used when converting user space coordinates to backing store coordinates. These can be modified at runtime and must be greater than zero.

When the Graphics object starts out, the scale is set to the the current transform used to convert user space coordinates to backing store coordinates. For example, the Graphics object on a Canvas passed to a paint event might have the ScaleX and ScaleY set to 2 when drawing to a retina screen. For a bitmap Picture, the ScaleX and ScaleY properties are always 1.

The scale properties are not automatically updated if a control’s backing store scale factor changes. They are, however, automatically updated when calling Graphics.NextPage in order to reset back to the state the printing system desires for that page.

Altering these properties will alter the object’s height and width. Specifying a higher scale value will result in a lower size and vice versa. When a new Graphics object is created as the result of calling Clip, the resulting object has the same scale factor as the original. Subsequent modifications to the scale on one object has no bearing on the other, however.


Graphics.ScaleY

ScaleY As Double

The scale factor used when converting user space coordinates to backing store coordinates. These can be modified at runtime and must be greater than zero.

When the Graphics object starts out, the scale is set to the the current transform used to convert user space coordinates to backing store coordinates. For example, the Graphics object on a Canvas passed to a paint event might have the ScaleX and ScaleY set to 2 when drawing to a retina screen. For a bitmap Picture, the ScaleX and ScaleY properties are always 1.

The scale properties are not automatically updated if a control’s backing store scale factor changes. They are, however, automatically updated when calling Graphics.NextPage in order to reset back to the state the printing system desires for that page.

Altering these properties will alter the object’s height and width. Specifying a higher scale value will result in a lower size and vice versa. When a new Graphics object is created as the result of calling Clip, the resulting object has the same scale factor as the original. Subsequent modifications to the scale on one object has no bearing on the other, however.


Graphics.ShadowBrush

ShadowBrush As ShadowBrush

The brush to be used to draw a shadow on the object being drawn.

This code in the Paint event of a Canvas draws a rectangle with a shadow:

g.ShadowBrush = New ShadowBrush
g.DrawingColor = Color.Red
g.FillRectangle 0, 0, 100, 100

Graphics.Transparency

Transparency As Double

The amount of transparency that affects all drawing to the Graphics object done afterwards. The range is from 0.0 (opaque) to 100.0 (fully transparent). Transparency of the Graphics object can be used to obtain “fading” effects (amongst other uses) by setting the transparency to a value greater than 0.0.

When rendering colors or pictures with alpha channel information, the Transparency property is composited with the alpha channel information. This allows you to perform uniform fading operations easily and efficiently.

On Windows, using the Transparency property only works on Graphics if the Picture was created with a depth of 32, or is a Picture with an alpha channel. Attempting to use it on other forms of Pictures will result in an UnsupportedOperationException.

Create a picture with a blue rectangle drawn with 50% transparency:

Var boxPic As New Picture(100, 100)
boxPic.Graphics.DrawingColor = &c0000ff00
boxPic.Graphics.Transparency = 50.0
boxPic.Graphics.FillRectangle(0, 0, 100, 100)

Graphics.Underline

Underline As Boolean

If True, applies the underline style to the control’s caption and/or its text content if any.


Graphics.Width

Width As Integer

The width in pixels of the parent object, typically a Canvas control or a Window.

This property is read-only.

This example in the Canvas.Paint event draws a box the width of the Canvas itself:

g.DrawingColor = &c0000ff
g.FillRectangle(0, 0, g.Width, g.Height)

Method descriptions


Graphics.ClearRectangle

ClearRectangle(X As Double, Y As Double, Width As Double, Height As Double)

Clears the rectangle described by the parameters passed by filling it with the background color of the parent window (on Windows/Linux) or by clearing the context so that the background comes through (on Mac).

This code clears the entire drawing area:

g.ClearRectangle(0, 0, g.Width, g.Height)

Graphics.Clip

Clip(X As Double, Y As Double, Width As Double, Height As Double) As Graphics

Creates a new Graphics object in the parent Graphics object. It has the size and shape defined by the passed parameters.

Graphics calls can only draw inside the passed bounds. After creating a clip, you can draw into it, as with any other Graphics object. However the drawing will be contained within the clipping, not the parent object. Use this to prevent objects from overlapping with other objects in the parent object. Whatever is drawn to the clipped region is confined to that region.

Clip allows clipping beyond the bottom and right edges of the source. This ensures the resulting Graphics object will always be the dimensions requested.

When you are drawing a complex image that involves many calls to Graphics methods, you may want to create non-overlapping regions within the area. You then draw into each “child” area, with the assurance that each drawing will not inadvertently overlap another object.

You create a child region within the parent area with the Clip method. You pass it the top-left corner of the child region and its width and height. It returns a new Graphics object that is the specified region inside the parent area. You can then draw into the child area just as with any other Graphics object. The only difference is that the drawing will be confined to the child area. The coordinates of each call are with respect to the top-left corner of the child area. Here is an example of how this works. This code is in the Paint event of a Canvas. Two regions at the top of the Canvas are defined by calls to the Clip method. Subsequent calls to the DrawRectangle method show where the clippings are. Calls to the DrawOval method draw shapes within the clipped areas. Notice that the first call attempts to draw outside the area. If you were drawing from the parent Graphics object, the first oval would bump into the second.

Sub Paint (g As Graphics)
  Var myClip As Graphics = g.Clip(0, 0, 150, 15)
  Var myClip2 As Graphics = g.Clip(150, 0, 150, 15)
  // Draw the border of the Canvas in black
  g.DrawingColor = &c000000
  g.DrawRectangle(0, 0, g.Width, g.Height)
  // Draw into the first area in red
  myClip.DrawingColor = &cff0000
  myClip.DrawRectangle(0, 0, myClip.Width, myClip.Height) // draw the border of the area.
  myClip.DrawOval(0, 0, 200, 15) // try to draw outside its clip.
  // Draw into the second area in blue
  myClip2.DrawingColor = &c0000ff
  myClip2.DrawRectangle(0, 0, myClip2.Width, myClip2.Height) // draw the border
  myClip2.DrawOval(0, 0, 150, 15)
End Sub

Graphics.ClipToPath

ClipToPath(path As GraphicsPath)

Clips the drawing to the specified GraphicsPath.

If you need to clear a Clip after it has been used, call SaveState before calling ClipToRectangle() and then call RestoreState when you no longer want the clipping in effect.

From within an MobileCanvas.Paint event handler:

// Clip to a GraphicsPath
// Path is a triangle
Var p As New GraphicsPath
p.MoveToPoint(0, 0) // Start location
p.AddLineToPoint(20, 44)
p.AddLineToPoint(40, 0)
p.AddLineToPoint(0, 0)

g.SaveState
g.ClipToPath(p)
g.FillOval(0, 0, 50, 50)
g.RestoreState

Graphics.ClipToRectangle

ClipToRectangle(x As Double, y As Double, width As Double, height As Double)

Clips the drawing to the specified rectangle.

If you need to clear a Clip after it has been used, call SaveState before calling ClipToRectangle() and then call RestoreState when you no longer want the clipping in effect.

From within an MobileCanvas.Paint event handler:

// The part of the circle drawn outside the clip area
// is not displayed.
g.SaveState
g.ClipToRectangle(0, 0, 50, 50)

g.DrawingColor = Color.Blue
g.FillOval(25, 25, 50, 50)
g.RestoreState // removes the clipping rectangle

Graphics.DrawCautionIcon

DrawCautionIcon(X As Double, Y As Double)

Draws the operating system’s Caution icon at the coordinates specified.

This code draws the Caution icon at the passed coordinates. The code is in the Paint event.

g.DrawCautionIcon(170.0, 120.0)

Graphics.DrawLine

DrawLine(X1 As Double, Y1 As Double, X2 As Double, Y2 As Double)

Draws a line from X1, y1 to x2, y2 in the current color. The current color is set with the DrawingColor property.


Graphics.DrawNoteIcon

DrawNoteIcon(X As Double, Y As Double)

Draws the operating system’s Note icon at the coordinates specified. X and Y are the coordinates of the top-left corner.

This code draws the Note icon at the passed coordinates. The code is in the Paint event.

g.DrawNoteIcon(170.0, 120.0)

Graphics.DrawObject

DrawObject(Object As Object2D, [DeltaX As Double, DeltaY As Double])

Draws the passed Object2D object into the Graphics object. The optional parameters DeltaX and DeltaY are offsets from the top-left corner of the Graphics object to the top-left corner of the Object.

If Object is an OvalShape, then the offsets are from the top-left corner of the Graphics object to the center of the OvalShape.

The following method is in the Paint event of a DesktopWindow. It draws a simple curve. The negative value of ControlY(0) places the control point above the imaginary straight line from x,y to x2,y2.

Var c As New CurveShape
c.ControlX(0) = 120
c.ControlY(0) = -40
c.Order = 1
c.X = 10
c.Y = 100
c.X2 = 250
c.Y2 = 100

g.DrawObject(c, c.X, c.Y)

Graphics.DrawOval

DrawOval(X As Double, Y As Double, Width As Double, Height As Double)

Draws the outline of an oval in the current color. The current color is set with the DrawingColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the oval.

The following example sets the PenSize and draws an oval. The code is in the Paint event of a Canvas.

g.PenSize = 5
g.DrawOval(10, 10, 100, 60)

Graphics.DrawPath

DrawPath(path As GraphicsPath)

Draws a bezier line along the path designated.

When autoClose is True (not available on iOS), the path will be automatically closed so that there are no gaps in it.


Graphics.DrawPicture

DrawPicture(Image As Picture, X As Double, Y As Double, [destWidth As Double], [destHeight As Double], [sourceX As Double], [sourceY As Double], [sourceWidth As Double], [sourceHeight As Double])

Draws the picture at the specified location. The picture can be shown at full size, cropped, or scaled. All units are pixels.

X and Y are the distances from the top-left corner of the control or window from which the 0,0 point of the image will be drawn. The optional parameters are used to copy a portion of the picture (cropping) and for scaling the picture.

If you are cropping, then DestWidth and DestHeight are also required. If you are doing scaling, then all of the optional parameters are required. You scale an image by making the destination width and height different from the source width and height.

The parameters SourceX, SourceY, SourceWidth, and SourceHeight describe the portion of the image that will be scaled. DestWidth and DestHeight are used to change the scaling of the picture when SourceWidth and SourceHeight are provided. SourceX and SourceY default to 0 and are used to determine the upper-left coordinate you wish to copy from.

Note

Negative values for DestWidth, DestHeight, SourceWidth and SourceHeight are not supported so the behavior is undefined.

The following example scales an image by 50%. The image, MyImage, has been added to the project. Its size is 600 x 915. Note that the destination width and height are half the original width and height. The code is in the Paint event of a Canvas. A call to DrawRect adds a black border around the Canvas.

g.DrawingColor = &c000000
g.DrawRectangle(0, 0, Me.Width, Me.Height)
Var scale As Double = 0.50
g.DrawPicture(MyImage, 0, 0, MyImage.Width * scale, MyImage.Height * scale, 0, 0, MyImage.Width, MyImage.Height)

The following code crops the image. It copies only the top 150 pixels of the original image at full size:

g.DrawPicture(MyImage, 0, 0, 600, 150)

The following code crops and scales the image. The top half of the image is retained and the DestWidth and DestHeight parameters specify a 50% reduction.

g.DrawPicture(MyImage, 0, 0, 300, 228, 0, 0, 600, 457)

If you don’t want to scale or crop the image, you can leave off the last six parameters. In this case, it will appear full-size.

g.DrawPicture(MyImage, 0, 0)

Graphics.DrawRectangle

DrawRectangle(X As Double, Y As Double, Width As Double, Height As Double)

Draws the outline of a rectangle in the current color. The current color is set with the DrawingColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the rectangle.

This example draws two squares with a 5-point red border.

g.DrawingColor = &cff0000
g.PenSize = 5
g.DrawRectangle(10, 10, 100, 100)
g.DrawRectangle(130, 10, 100, 100)

Graphics.DrawRoundRectangle

DrawRoundRectangle(X As Double, Y As Double, Width As Double, Height As Double, ArcWidth As Double, ArcHeight As Double)

Draws the outline of a rounded rectangle in the current color. The current color is set with the DrawingColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the round rectangle. ArcWidth and ArcHeight control the shape of the corners in the horizontal and vertical axes, respectively. They are the distance (in pixels) from the corner at which the arc begins. Setting them to zero results in a rectangle with sharp corners.

This example draws two squares with a 5-pixel red border. The left square sets the arcs to 10 and the right one to 25.

g.DrawingColor = &cff0000
g.PenSize = 5
g.DrawRoundRectangle(10, 10, 100, 100, 10, 10)
g.DrawRoundRectangle(130, 10, 100, 100, 25, 25)

Graphics.DrawStopIcon

DrawStopIcon(X As Double, Y As Double)

Draws the operating system’s Stop icon at the coordinates specified. x and y are the coordinates of the top-left corner.

This code draws the Stop icon at the passed coordinates. The code is in the Paint event.

g.DrawStopIcon(170, 120)

Graphics.DrawText

DrawText(Text As String, X As Double, Y As Double, [WrapWidth As Double, Condense As Boolean])

Draws the text at the specified location and in the current color. The current color is set with the DrawingColor property.

The X parameter specifies the distance from the left of the Graphics object in pixels. The Y parameter specifies the baseline for the text. The optional WrapWidth parameter specifies the width at which text should wrap. The text will wrap if WrapWidth is provided and Condense is False (The default is False). If WrapWidth is omitted, then text will print on one line, even if the drawing area is too narrow to contain the text. If the optional Condense property is True, DrawText truncates the text to fit into the space specified by WrapWidth and uses an ellipsis (“…”) to indicate that there is additional text that is not shown. The default values of WrapWidth and Condense are zero and False, respectively. The default behavior is to print the text on one line.

This code draws text in red Helvetica 16-point:

g.DrawingColor = &cff0000
g.FontName = "Helvetica"
g.FontUnit = FontUnits.Point
g.FontSize = 16
g.DrawText("Hello world", 10, 130)

Graphics.FillOval

FillOval(X As Double, Y As Double, Width As Double, Height As Double)

Draws an oval filled with the current color. The current color is set with the DrawingColor property.

x and y are the coordinates of the top-left corner. width and height specify the size of the oval.

g.DrawingColor = &cff0000
g.FillOval(10, 10, 100, 60)

Graphics.FillPath

FillPath(path As GraphicsPath, autoClose As Boolean = False)

Draws a bezier line along the path designated and fills the region with the current DrawingColor value.

When autoClose is True (not available on iOS), the path will be automatically closed so that there are no gaps in it.


Graphics.FillRectangle

FillRectangle(X As Double, Y As Double, Width As Double, Height As Double)

Draws a rectangle filled with the current color. The current color is set with the DrawingColor property.

X and Y are the coordinates of the top-left corner. Width and Height specify the size of the rectangle.

This example (in the Paint event of a Canvas control) draws a rectangle with a red interior.

g.DrawingColor = &cff0000 // Red
g.FillRectangle(10, 10, 100, 60)

Graphics.FillRoundRectangle

FillRoundRectangle(X As Double, Y As Double, Width As Double, Height As Double, ArcWidth As Double, ArcHeight As Double)

Draws a rounded rectangle filled with the current color. The current color is set with the DrawingColor property.

x and y are the coordinates of the top-left corner. width and height specify the size of the round rectangle. arcWidth and arcHeight control the shape of the corners in the horizontal and vertical axes, respectively. They are the distance (in points) from the corner at which the arc begins. Setting them to zero results in a rectangle with sharp corners.

This example (in the Paint event of a Canvas control) draws a rounded rectangle with a red fill and 30 pixel rounded corners.

g.DrawingColor = &cff0000
g.FillRoundRectangle(10, 10, 100, 60, 30, 30)

Graphics.Handle

Handle(type As HandleTypes) As Ptr

Gets the OS Handle for the passed Type. Pass the appropriate HandleTypes value to specify the Type.

Handle will return nil if the requested handle type is not available or is not supported.

This code gets a handle to the port of the Graphics object on Mac and iOS.

Var h As Ptr = g.Handle(Graphics.HandleTypes.CGContextRef)

Graphics.LineDash

LineDash(Assigns values() As Double)

Specifies the on/off dash pattern.


Graphics.LineDash

LineDash As Double

Specifies the on/off dash pattern.

Passing an array with the values 1.0, 2.0 means a dash of 1 unit with a spacing of 2 units per dash.

Setting LineDash to Nil restores drawing to solid lines.

LineDash affects DrawLine, DrawOval, DrawPath, DrawPath, DrawRectangle, and DrawRoundRectangle.

LineCap and LineJoin will affect how the dashes are drawn.

Draw a diagonal line with 2 unit dashes and 3 unit gaps

g.PenSize = 5
g.LineDash = Array(2.0, 3.0)
g.DrawLine(0, 0, g.Width, g.Height)

Graphics.NextPage

NextPage

When printing a Graphics object, this method will cause the current page to be printed and a new page to be created.

For mobile projects, this method is only supported for PDFGraphics since printing is not currently supported for mobile.


Graphics.RestoreState

RestoreState

Restores Graphics context previously saved with SaveState.

Support for RestoreState in Desktop and Console applications was added in 2021r1.

From within an MobileCanvas.Paint event handler:

g.DrawingColor = Color.Blue
g.FillRectangle(10, 10, 20, 20)

g.SaveState
g.DrawingColor = Color.Red
g.FillRectangle(50, 50, 20, 20)

// Restore to state where FillColor is Blue
g.RestoreState
g.FillRectangle(10, 50, 20, 20)

Graphics.Rotate

Rotate(angle As Double)

Rotates the drawing context at the x and y coordinates by the specified angle (in radians). This only affects subsequent drawing. Any drawing done before the Rotate method called is not rotated.


Graphics.Rotate

Rotate(angle As Double, x As Double, y As Double)

Rotates the drawing context at the x and y coordinates by the specified angle (in radians). This only affects subsequent drawing. Any drawing done before the Rotate method called is not rotated.

Use Translate to move the origin.

Support for Rotate in Desktop and Console applications was added in 2021r1.

When used in combination with Scale and/or Translate to draw into a PDFDocument, Rotate may behave differently than it does when drawing to normal Graphics object because the rotation is being handled by the PDF engine itself.

From within an MobileCanvas.Paint event handler:

// Rotate square in center of graphics area
Const Pi = 3.14159
g.Translate(g.Width / 2, g.Height / 2)
g.Rotate(Pi / 4) // 45 degrees or 1/8 of a circle
g.DrawingColor = Color.Blue
g.FillRectangle(10, 10, 50, 50)
// Rotate the entire drawing area around its center
// and draw a rectangle
Const Pi = 3.14159
g.Rotate(Pi / 4, g.Width / 2, g.Height / 2) // 45 degrees or 1/8 of a circle
g.DrawingColor = Color.Blue
g.FillRectangle(g.Width / 2 - 20, g.Height / 2 - 20, 20, 20)

Graphics.SaveState

SaveState

Saves Graphics state of the Graphics context so that it can be restored later.

These values are saved with SaveState and are restored when you call RestoreState.

  • Translate

  • Clip region

  • PenSize

  • AntiAliased

  • DrawingColor

  • Font

  • Underline

  • Rotate (rotation)

Support for SaveState in Desktop and Console applications was added in 2021r1.

From within an MobileCanvas.Paint event handler:

g.DrawingColor = Color.Blue
g.FillRectangle(10, 10, 20, 20)

g.SaveState
g.DrawingColor = Color.Red
g.FillRectangle(50, 50, 20, 20)

// Restore to state where FillColor is Blue
g.RestoreState
g.FillRectangle(10, 50, 20, 20)

Graphics.Scale

Scale(x As Double, y As Double)

Sets the scale for the Graphics context as specified scaleX and scaleY. This only affects subsequent drawing. Any drawing done before the Scale method is called is not scaled.

When used in combination with Rotate and/or Translate to draw into a PDFDocument, Scale may behave differently than it does when drawing to normal Graphics object because the scaling is being handled by the PDF engine itself.

From within the MobileCanvas.Paint event handler:

g.Scale(2.0, 4.0)
g.DrawingColor = Color.Blue
g.FillRectangle(10, 10, 10, 10) // The squares scales to a rectangle

Graphics.TextDirection

TextDirection(Text As String) As TextDirections

Returns an Enumeration that indicates the direction in which the text is written.

This is useful for non-Roman systems, especially Middle-Eastern languages. If you pass an empty string, it returns the system default string direction. If this function is not supported on the user’s system, the TextDirections value will be Unknown.

This example gets the string direction.

If g.TextDirection("Hello world") = Graphics.TextDirections.RightToLeft then
  MessageBox("We are on a right to left system.")
End If

Graphics.TextHeight

TextHeight As Double

Gets the height of a line of text drawn with the current font.

TextHeight(Text As String, Optional WrapWidth As Double) As Double

Used to calculate the height of a line of text passed (given the wrap width passed) drawn with the current font.

TextHeight is calculated as the maximum height for the font itself and not the actual height of the text. For example, with “a” vs. “A”, both return the same TextHeight even though “A” has a greater height than “a”.

g.FontName = "Helvetica"
g.FontUnit = FontUnits.Points
g.FontSize = 32

Var height As Double
height = g.TextHeight("Hello world", 150)

This example reports the TextHeight of the current text.

g.DrawingColor = &cff0000
g.Italic = True
g.DrawText("Hello world", 10, 10)
MessageBox(g.TextHeight.ToString)

Graphics.TextWidth

TextWidth(Text As String) As Double

Returns as a Double the width of Text in points, based on the current text properties of the Graphics object.

To be precise, TextWidth returns the width of the string’s baseline, which is to say that it returns the position that the next character would be drawn at, if the string were to be extended. For example, if Bold is True, then each character would have a larger width when drawn, so TextWidth will return a larger value than otherwise. On the other hand, if Italic is True, then the last character of the text would lean to the right when drawn, increasing the visual width of the text slightly. However, the baseline of the rendered string would not have changed, so TextWidth will generally not return a different value in this case.

TextWidth does not handle multiple lines in the way that one might expect. Essentially, the multi-line nature of the text is ignored, and newline sequences are treated as if they were space characters. For example, it returns the same value for the text “A B” as for the text “A”+EndOfLine+”B”. To take multiple lines into account, you’ll need to String.Split the text into multiple lines yourself, and calculate the width of each line separately, handling leading or trailing whitespace in whatever way makes sense for your situation.

This example creates a Picture and uses its Graphics object to calculate the TextWidth and display it in a TextField on a window:

Var d As Double
Var p As New Picture(100, 100, 32)
d = p.Graphics.TextWidth("Hello World!")
TextField1.Text = d.ToString

Graphics.Translate

Translate(translateX As Double, translateY As Double)

Translates the origin point by the specified translateX and translateY values. Useful with Rotate.

Support for Translate in Desktop and Console applications was added in 2021r1.

When used in combination with Rotate and/or Scale to draw into a PDFDocument, Translate may behave differently than it does when drawing to normal Graphics object because the translation is being handled by the PDF engine itself.

From within an MobileCanvas.Paint event handler:

// Rotate square in center of graphics area
Const Pi = 3.14159
g.Translate(g.Width / 2, g.Height / 2)
g.Rotate(Pi / 4) // 45 degrees or 1/8 of a circle
g.DrawingColor = Color.Blue
g.FillRectangle(10, 10, 50, 50)

Notes

Normally you use a Graphics object in response to a Canvas.Paint event, but you can also perform direct drawing by using the Graphics property of a Picture. Alternatively, you can create vector Graphics using the subclasses of the Object2D class.

Note

You cannot create a meaningful Graphics object via the New command.


Graphics Coordinates

The x and y parameters of the methods are the horizontal and vertical coordinates of the left-top corner of the object being drawn or cleared. The origin (0,0) is the top-left corner of the control or window in which the drawing is being done.

For example, 50,50 is 50 points to the right and 50 points down from the top-left of the window or control.


Alpha channel support

The Transparency property takes a value between 0.0 (opaque) and 100.0 (transparent) that can be used to obtain “fading” effects (amongst other uses) by setting the transparency to a value greater than 0.0.

When rendering colors or pictures with alpha channel information, the Transparency property is composited with the alpha channel information. This allows you to perform uniform fading operations easily and efficiently.

On Windows, using the Transparency property only works on Picture.Graphics if the Picture was created with a depth of 32, or is a Picture with an alpha channel. Attempting to use it on other forms of Pictures will result in an UnsupportedOperationException.

Sample code

This example uses the Paint event handler of a Canvas control to draw the text “The quick brown fox” in Helvetica bold, italic, 18 point, 50 pixels from the top of and 10 pixels from the left side of the control.

Sub Paint(g As Graphics)
 g.Bold = True
 g.Italic = True
 g.FontName = "Helvetica"
 g.FontSize = 18
 g.DrawText("The quick brown fox", 10, 50)
End Sub

This example draws a triangle in a Canvas control. It is placed in the Paint event. The parameter g as Graphics is passed into this event.

g.DrawingColor = Color.Red
Var path As New GraphicsPath
path.MoveToPoint(10, 10)
path.AddLineToPoint(100, 50)
path.AddLineToPoint(10, 200)
g.FillPath(path)

This example uses the Clip method to define child Graphics items within the parent Canvas. The code is in the Paint event of a Canvas. The two clippings define regions at the top of the canvas and the DrawOval method draws object in each one. Notice that the first call tries to draw an oval that is wider than the region. It is truncated in the drawing.

Var myClip As Graphics = g.Clip(0, 0, 150, 15)
Var myClip2 As Graphics = g.Clip(150, 0, 150, 15)

// draw the border of the Canvas..
g.DrawingColor = &c000000
g.DrawRectangle(0, 0, g.Width, g.Height)

// draw into the first area...
myClip.DrawingColor = &cff0000
myClip.DrawRectangle(0, 0, myClip.Width, myClip.Height) // draw the border of the area..
myClip.DrawOval(0, 0, 200, 15) // the oval does not appear outside the region despite the call

// draw into the second area...
myClip2.DrawingColor = &c0000ff
myClip2.DrawRectangle(0, 0, myClip2.Width, myClip2.Height) // draw the border of the area
myClip2.DrawOval(0, 0, 150, 15)

Compatibility

All projects types on all supported operating systems.

See also

Object parent class; DesktopCanvas control; DesktopWindow, DesktopContainer, Group2D classes.