Class
Graphics
Graphics
Description
Graphics class objects are used for drawing text, lines, rectangles, ovals, and pictures.
Note
Many of these operations are GPU-accelerated on macOS and Windows.
Properties
Name |
Type |
Read-Only |
Shared |
|---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
|---|---|---|---|
Graphics |
|||
path As GraphicsPath |
|||
object2D As Object2D, deltaX As Double = 0.0, deltaY As Double = 0.0 |
|||
path As GraphicsPath, autoClose As Boolean = False |
|||
image As Picture, x As Double, y As Double, destWidth As Double = -10000.0, destHeight As Double = -10000.0, sourceX As Double = 0.0, sourceY As Double = 0.0, sourceWidth As Double = -10000.0, sourceHeight As Double = -10000.0 |
|||
x As Double, y As Double, width As Double, height As Double, arcWidth As Double, arcHeight As Double |
|||
str As String, x As Double, y As Double, width As Double = 0.0, condense As Boolean = False |
|||
value As String, x As Double, y As Double, maxWidth As Double = -1.0, maxHeight As Double = -1.0, alignment As MobileTextControl.Alignments = MobileTextControl.Alignments.Left, truncateLastLine As Boolean = False |
|||
path As GraphicsPath, autoClose As Boolean = False |
|||
x As Double, y As Double, width As Double, height As Double, arcWidth As Double, arcHeight As Double |
|||
type As HandleTypes |
|||
angle As Double |
|||
value As String, maxWidth As Double = -1.0, maxHeight As Double = -1.0, alignment As MobileTextControl.Alignments = MobileTextControl.Alignments.Left, truncateLastLine As Boolean = False |
|||
value As String |
|||
text As String |
|||
Enumerations
Graphics.AntiAliasModes
AntiAliasModes
Specifies the quality of antialiasing when drawing pictures.
Enum |
|---|
LowQuality |
DefaultQuality |
HighQuality |
Graphics.HandleTypes
HandleTypes
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. |
AndroidCanvas |
Provides access to the underlying drawing Canvas. |
AndroidPaint |
Provides access to the underlying drawing style information. |
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. |
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 Graphics.AntiAliasModes
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.
Important
This property is not supported for iOS and Android.
Use High Quality (set in Paint event of a DesktopCanvas):
g.AntiAliasMode = Graphics.AntiAliasModes.HighQuality
Graphics.Bold
Bold As Boolean
If True, text will appear in bold when using DrawText.
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.
Important
This property is not supported for iOS and Android.
Graphics.Brush
Brush As GraphicsBrush
The brush to be used when drawing.
Important
This property is not currently supported for Android.
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.
Important
This property is only supported for desktop projects.
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.DrawLine(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.
Important
This property is only supported for desktop projects.
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)
Note
This property is only available for Mobile projects. To assign a font in other project types, use the FontName property.
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.
Important
This property is not supported for iOS and Android. Use Font.Ascent instead.
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".
Important
This property is not supported for iOS and Android. Use Font instead.
This code sets the FontName property.
g.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 FontSize, your app will use the font size that works best for the platform on which it is running.
Important
This property is not supported for iOS and Android. Font.Size.
This code sets the font size to 16 points.
g.FontSize = 16
Graphics.FontUnit
FontUnit As FontUnits
The units in which FontSize is measured.
Important
This property is only supported for desktop projects.
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 DesktopCanvas control or a Window.
This property is read-only.
For example, if the Graphics class object is in a DesktopCanvas control, Height returns the height of the control.
This example in the DesktopCanvas.Paint event draws a box the height of the DesktopCanvas 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.
Important
This property is not supported for iOS and Android.
This example draws "Hello world" in red italic inside a DesktopCanvas.
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.
Important
This property is only supported for desktop projects.
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 DesktopCanvas, 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 DesktopCanvas, set the line join to round:
g.LineJoin = Graphics.LineJoinTypes.Round
Graphics.MiterLimit
MiterLimit As Double
The maximum length of a miter which is the distance between the inner corner and the outer corner where two lines meet.
Graphics.Outline
Outline As Boolean
If True, text will appear outlined when using DrawText.
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.
g.Outline = True
g.DrawText("Hello world", 50, 50)
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.
Important
This property is only supported for desktop projects.
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 DesktopCanvas 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 DesktopCanvas 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 DesktopCanvas draws a rectangle with a shadow:
g.ShadowBrush = New ShadowBrush
g.DrawingColor = Color.Red
g.FillRectangle(0, 0, 100, 100)
Important
The color value of ShadowBrush when used with DrawPicture is not currently supported on Android.
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, text will appear underlined when using DrawText.
Graphics.Width
Width As Integer
The width in pixels of the parent object, typically a DesktopCanvas control or a Window.
This property is read-only.
This example in the DesktopCanvas.Paint event draws a box the width of the DesktopCanvas 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.
Important
This method is not supported for iOS and Android.
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 DesktopCanvas. Two regions at the top of the DesktopCanvas 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.
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)
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.
Important
This method is not supported for console or web projects.
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.
Important
This method is not supported for iOS and Android.
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.
Important
This method is not supported for iOS and Android.
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(object2D As Object2D, deltaX As Double = 0.0, deltaY As Double = 0.0)
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 object2D.
Important
This method is not supported for iOS and Android.
If object2D 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 DesktopCanvas.
g.PenSize = 5
g.DrawOval(10, 10, 100, 60)
Graphics.DrawPath
DrawPath(path As GraphicsPath, autoClose As Boolean = False)
Draws a bezier line along the path designated.
When autoClose is True, the path will be automatically closed so that there are no gaps in it.
Important
This method is not supported for console or web projects.
Graphics.DrawPicture
DrawPicture(image As Picture, x As Double, y As Double, destWidth As Double = -10000.0, destHeight As Double = -10000.0, sourceX As Double = 0.0, sourceY As Double = 0.0, sourceWidth As Double = -10000.0, sourceHeight As Double = -10000.0)
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 DesktopCanvas. A call to DrawRect adds a black border around the DesktopCanvas.
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.
Important
This method is not supported for iOS and Android.
This code draws the Stop icon at the passed coordinates. The code is in the Paint event.
g.DrawStopIcon(170, 120)
Graphics.DrawText
DrawText(str As String, x As Double, y As Double, width As Double = 0.0, condense As Boolean = False)
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 width parameter specifies the width at which str should wrap. The str will wrap if width is provided and Condense is False (The default is False). If width is omitted, then str 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 width and uses an ellipsis ("...") to indicate that there is additional text that is not shown. The default values of width and condense are zero and False, respectively. The default behavior is to print the text on one line.
Graphics.DrawText with Outline enabled, now properly outlines the text using fonts that are weighted (i.e. the boldness level) more heavily, like Arial Black.
In specific cases where you need to draw the outline of the text on top of already rendered text, we've added the ability to opt into this specific way of rendering text by setting up the XOJO_GRAPHICS_DRAWTEXT_MODE environment variable. A value of "1" will enable Graphics.DrawText to render the text with similar metrics, regardless of whether Outline is enabled or not. This environment variable must be setup before the Graphics object is instantiated.
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.DrawTextBlock
DrawTextBlock(value As String, x As Double, y As Double, maxWidth As Double = -1.0, maxHeight As Double = -1.0, alignment As MobileTextControl.Alignments = MobileTextControl.Alignments.Left, truncateLastLine As Boolean = False)
Draws a block of text.
Important
This method is only supported for iOS.
From within an MobileCanvas event handler:
g.FillColor = Color.Blue
Var s As String
s = "How much wood would a woodchuck chuck if a woodchuck could chuck wood?"
g.DrawTextBlock(s, 0, 10, g.Width, g.Height, MobileTextControl.Alignments.Left, False)
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, the path will be automatically closed so that there are no gaps in it.
Important
This method is not supported for console or web projects.
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 DesktopCanvas 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 DesktopCanvas 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 HandleTypes 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, DrawRoundRectangle and DrawText (if Outline = True).
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.
Important
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.
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.
Note
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)
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.
Note
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.TextBlockSize
TextBlockSize(value As String, maxWidth As Double = -1.0, maxHeight As Double = -1.0, alignment As MobileTextControl.Alignments = MobileTextControl.Alignments.Left, truncateLastLine As Boolean = False) As Size
Calculates the size of a text as it would appear using DrawTextBlock.
Important
This method is only supported for iOS.
Get the text block size of left-aligned text:
Var tbs As Size
tbs = g.TextBlockSize("Hello, world!", -1, -1, MobileTextControl.Alignments.Left, False)
Graphics.TextDirection
TextDirection(value 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, 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(x As Double, y As Double)
Translates the origin point by the specified x and y values. Useful with Rotate.
Note
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 DesktopCanvas.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 DesktopCanvas 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 project types on all supported operating systems.
See also
Object parent class; DesktopCanvas, MobileCanvas control; DesktopWindow, DesktopContainer, Group2D classes.