PdfCanvas Object

Overview

PdfCanvas encapsulates AspPDF's drawing functionality. PdfCanvas is returned by PdfPage's Canvas and Background properties, as well as by PdfGraphics' Canvas property. For more information about drawing, see Chapter 4: Drawing.

Member List

Properties

HtmlTag As String (Read-only)

Returns an HTML tag reflecting the current font state when using AspPDF's HTML tag support. This property is populated by a call to the DrawText method with the HTML parameter set to True and a text string too long to fit in the allocated space. Use it to correctly display HTML text spanning multiple pages. For more information, see Section 6.4 - HTML Support.

LineCap As Short (Read/Write)

Returns or specifies the current line cap style. Valid values are 0 (Butt cap), 1 (Round cap) and 2 (Projecting square cap) described in Section 4.4.2 - Line Width and Cap Style.

LineJoin As Short (Read/Write)

Returns or specifies the current line join style. Valid values are 0 (Miter join), 1 (Round join) and 2 (Bevel join) described in Section 4.4.3 - Line Join Style and Miter Limit.

LineWidth As Single (Read/Write)

Returns or specifies the current line width. Line width is 1 by default (in user units).

For more information, see Section 4.4.2 - Line Width and Cap Style.

MiterLimit As Single (Read/Write)

Returns or specifies the current miter limit described in Section 4.4.3 - Line Join Style and Miter Limit.

Value As String (Read-only)

Returns the current canvas contents as a sequence of operators in a language similar to PostScript. This property is only useful for trouble-shooting or debugging purposes.

Methods

Sub AbandonPath()
This method cancels all previous path-construction operators. For more information on path construction, see Section 4.1 - Introduction to PDF Drawing
Sub AddCurve(X1 As Single, Y1 As Single, X2 As Single, Y2 As Single, X3 As Single, Y3 As Single)
Adds a Bezier curve to the current path using the current point as the beginning, point (X3, Y3) as the ending, and points (X1, Y1) and (X2, Y2) as control points. For more information on paths and Bezier curves, see Section 4.1 - Introduction to PDF Drawing.
Sub AddEllipse(X As Single, Y As Single, RX As Single, RY As Single)
Adds an ellipse to the current path with the center in (X, Y) and radii RX and RY. If RX=RY, the ellipse turns into a circle.
Sub AddRect(X As Single, Y As Single, Width As Single, Height As Single)
Adds a rectangle to the current path with the lower-left corner in (X, Y) and size Width x Height.
Sub Append(Contents As String)
Appends raw PostScript operators directly to the content stream of the canvas. This method should only be used by developers with advanced PDF knowledge.
Function BeginMarkedContent() As Integer

Begins a marked content sequence of drawing operators. Returns the unique ID for this marked content. Must be matched with a call to EndMarkedContent.

For more information, see Section 14.3.4 - PDF/A-3 Compliance.

This method was introduced in Version 3.7.

Sub BeginText()
Appends the PDF language operator BT to the content stream of the canvas. This method should only be used by developers with advanced PDF knowledge.
Sub Clear()
Clears the current canvas of all drawing operators.
Sub Clip(Optional EvenOdd = False)
For more information on clipping paths, see Section 4.5.3 - Clipping Paths.

EvenOdd specifies the filling rule to be used. If set to True or omitted, the nonzero winding number rule is used, otherwise the even-odd rule is used. For more information on filling rules Section 4.2 - AspPDF Implementation of Drawing.

Sub ClosePath()
Closes the current subpath by appending a straight line from the current point to the beginning of the subpath.
Sub DrawBarcode(Data As String, Param As Variant)

Draws a scannable linear (1D) bar code on the canvas.

Data specifies the data (digits and letters) to be displayed as a barcode.

Param is a parameter object or parameter string specifying the barcode type as well as other parameters.

For the full description of the DrawBarcode method and its parameters, see Section 13.1 - Reguar Barcodes.

Function DrawBarcode2D(TextData As String, Param As Variant, Optional BinaryData) As PdfParam

Draws a two-dimensional barcode on a page. Currently, four types are supported: PDF417, Data Matrix, QR Code and Aztec. Returns various properties of the barcode symbol just drawn. Introduced in Version 1.8. QR Code is supported as of Version 2.0.0.7. Aztec is supported as of Version 3.4.0.7.

TextData specifies the data to be encoded as a barcode.

Param is a PdfParam object or parameter string specifying the following barcode properties:

  • X, Y - the coordinates of the lower-left corner of the barcode symbol on the page. These are the only required parameters.
  • Type - specifies the barcode type. Valid values are 1 (PDF417), 2 (Data Matrix), 3 (QR Code) and 4 (Aztec). 1 by default.
  • BarWidth - the width of the narrowest vertical bar (PDF417) or cell (Data Matrix, QR Code, Aztec), in user units. 1 by default.
  • AspectRatio - in PDF417 barcodes, the ratio of the row height to the narrowest bar width. 2 by default. Ignored in Data Matrix, QR Code and Aztec barcodes as the cells are always square.
  • ErrorLevel - in PDF417, QR Code and Aztec barcodes, controls the amount of error correction information in the symbol. The higher this number is, the more resistant to damage (and larger in size) the symbol gets.
    • In PDF417, the valid values are 0 to 8. The value of 0 means no error correction. If this parameter is not specified at all, the error level is computed automatically based on the data size according to the standard PDF417 specifications.
    • In QR Code, the valid values are 0 to 3, 0 (default) being the lowest error correction level.
    • In Aztec, the valid values are 1 to 4 (2 by default.)
    • This parameter is ignored in Data Matrix barcodes as the error level is always determined automatically.
  • Encoding - in Data Matrix barcodes, specifies data encoding. Valid values are: 0 (Automatic), 1 (ASCII), 2 (C40), 3 (Text), 4 (X12), 5 (Edifact) and 6 (Binary). 0 (Automatic) by default. Ignored in PDF417, QR Code and Aztec barcodes.
  • Columns - in PDF417 barcodes, the symbol will contain at least this number of data columns, provided there is enough data for it. If not specified, the number of columns is determined automatically. In Data Matrix barcodes, if this value is specified, Rows must also be specified. Valid combinations can be found here. Ignored in QR Code and Aztec.
  • Rows - in PDF417 barcodes, the symbol will contain at least this number of rows, provided there is enough data for it. If not specified, the number of rows is determined automatically. In Data Matrix barcodes, if this value is specified, Columns must also be specified. Valid combinations can be found here. Ignored in QR Code and Aztec.
  • Version - in QR Code, determines the size of the symbol. 0 by default which means the size is determined automatically. Other valid values: 1 to 40 (the bigger the number the larger the symbol.) In Aztec, the valid values are 0 (default, automatic size determination) and 1 to 36. See Section 13.2.4 for the table of valid values. Ignored in PDF417 and DataMatrix.
  • Angle - an angle of counter-clockwise rotation (in degrees) of the barcode around its lower-left corner. 0 by default.
  • Color - barcode color, the current fill color by default.
  • BgColor - background color (the color of the "white" rectangular area underneath the barcode.) Transparent by default. Useful to make the barcode background white if the page background is non-white.
  • BgMargin - the size (in user units) of the margins around the barcode. 2 x BarWidth by default. Ignored unless BgColor is specified.
  • Width, Height - in PDF417 bacodes, specify the overall width and height of the barcode symbol in user units, including the quiet zone (described below.) Both parameters must be specified to have an effect, i.e. if one is omitted, the other is ignored. If both of these parameters are specified, BarWidth and AspectRatio are ignored. Requires Version 3.2.0.1+.
  • QZH, QZV - in PDF417 bacodes, specify the "quiet zone" space margins in user units on the left/right and top/bottom sides of the barcode, respectively. 0 by default. These parameters are only used if the Width/Height parameters are specified. Requires Version 3.2.0.1+.
  • Binary - in PDF417 bacodes, if set to true, forces the byte (or binary) compression mode in which each codeword represents 1.2 bytes of information The default text compression mode encodes (roughly) 2 characters per codeword. False by default. Requires Version 3.2.0.1+.

BinaryData specifies binary information to be encoded as a barcode. If this optional argument is specified, the TextData argument is ignored.

The method returns an instance of the PdfParam object populated with the following properties of the symbol just rendered: Width, Height, Columns, Rows and ErrorLevel (the latter is only returned when Type=1.)

For more information about 2D barcodes and the DrawBarcode2D method, see Section 13.2 - Two-Dimensional Barcodes.

Sub DrawEllipse(X As Single, Y As Single, RX As Single, RY As Single)
Draws an ellipse with the center in (X, Y) and radii RX and RY. If RX=RY, the ellipse turns into a circle.
Sub DrawGraphics(Graphics As PdfGraphics, Param As Variant)

Draws a PdfGraphics object on the canvas.

Graphics is an instance of the PdfGraphics object representing the graphics object to be drawn.

Param is a PdfParam object or parameter string specifying the following drawing parameters:

  • X, Y (required): the coordinates of the lower-left corner of the graphics on the canvas.
  • Angle (optional): the angle (in degrees) to rotate the graphics counter-clockwise around its lower-left corner.
  • ScaleX, ScaleY (optional): the scaling factors along the X and Y axes, respectively.

Usage:

Page.Canvas.DrawGraphics MyGraphics, "x=10; y=300"

For more information on the PdfGraphics object, see Section 5.3 - PdfGraphics Object.

Sub DrawImage(Image As PdfImage, Param As Variant)

Draws a PdfImage object on the canvas.

Image is an instance of the PdfImage object representing the image to be drawn.

Param is a PdfParam object or parameter string specifying image drawing parameters. The parameters are the same as in the DrawGraphics method.

Usage:

Page.Canvas.DrawImage Image, "x=10;y=300,ScaleX=.5,Scaley=.5"

For more information on the PdfImage object, see Section 5.1 - PdfImage Object.

Sub DrawLine(X1 As Single, Y1 As Single, X2 As Single, Y2 As Single)
Draws a line from point (X1, Y1) to point (X2, Y2).
Sub DrawRect(X As Single, Y As Single, Width As Single, Height As Single)
Draws a rectangle with the lower-left corner in (X, Y) and size Width x Height.
Function DrawTable(Table As PdfTable, Param As Variant) As Long

Draws a table, or a portion thereof, on the canvas.

Table is an instance of the PdfTable object creatable via PdfDocument's CreateTable method. Only rows that fully fit on the canvas are displayed. When the next row cannot be fit on the canvas, the process stops.

Param is a PdfParam object or parameter string specifying the following table drawing parameters:

  • X, Y (required): the coordinates of the upper-left corner of the table on the canvas.
  • MaxHeight (optional): the maximum height of the table on the canvas. By default, it is set to the Y value (the distance between the top of the table and bottom of the canvas).
  • RowFrom - RowTo, RowFrom1 - RowTo1, etc. (optional) - row ranges to display.

The method returns the index of the last row it could fully fit on the canvas. If the method returns 0 it means even the first row alone could not fit and nothing was drawn.

Usage:

Page.Canvas.DrawTable Table, "x=10; y=200; RowFrom=1; RowTo=20"

For more information on the PdfTable object, see Chapter 7 - Tables. For the full description of the DrawTable method, see Section 7.3 - Table Rendering.

Function DrawText(Text As String, Param As Variant, Font As PdfFont) As Long

Draws a text string specified by Text using the font specified by Font.

Param is a PdfParam object or parameter string specifying the following text drawing parameters.

  • X, Y (required) - the coordinates of the upper-left corner of the bounding box the text will be inscribed in.
  • Size (optional) - the font size, 10 by default.
  • Width (optional) - the width of the bounding box the text will be inscribed in. The box is infinitely wide by default.
  • Height (optional) - the height of the bounding box the text will be inscribed in. The box is infinitely high by default.
  • Alignment (optional) - text alignment, left (0) by default, other valid values are right (1) and center (2). The right and center alignment values require that Width be specified as well.
  • Rendering (optional) - font rendering, valid values described in Section 6.1.2 - Rendering Parameter.
  • Color (optional) - font color in RGB color space, black by default.
  • tc, tm, ty, tk (optional) - font color components in CMYK color space.
  • Angle (optional) - angle (in degrees) by which the text should be rotated counter-clockwise around the upper-left corner of the bounding box.
  • Spacing (optional) - the distance between individual lines of text, 1 by default.
  • Tab (optional) - the size of a tab indent, 10 "space" characters by default.
  • ReverseHebrewArabic (optional) - reverses the sequence of Hebrew and Arabic characters in a string if set to True.
  • HTML (optional) - if set to True, enables HTML tag recognition. When this parameter is set to true, the Angle, Tab, Alignment and ReverseHebrewArabic parameters are ignored. False by default. For more information on HTML support, see Section 6.4 - HTML Support.
  • ColorSpace, c1, c2, ..., cN (optional) - introduced in Version 2.7 to enable colors in color spaces other than RGB or CMYK. For more information, see Section 16.4 - Using Color Spaces with PdfTable and Other Objects.
  • ColorComponents (optional) - introduced in Version 3.7.0.3 to enable colors in color spaces other than DeviceRGB to be used in the HTML mode. Ignored unless HTML is set to True. For more information, see Subsection 16.4.2 of the user manual.

The method returns the number of printed characters. This number may be less than the length of the original text string if the entire string did not fit in the provided bounding box.

Usage:

Page.Canvas.DrawText "Hello World!", "x=10; y=200", Font

For more information on text and fonts, see Chapter 6 - Text and Fonts. For the full description of the DrawText method, see Section 6.1 - Bounding Box Parameters.

Sub EndMarkedContent()

Ends a marked content sequence of drawing operators begun by a call to BeginMarkedContent.

For more information, see Section 14.3.4 - PDF/A-3 Compliance.

This method was introduced in Version 3.7.

Sub EndText()
Appends the PDF language operator ET to the content stream of the canvas. This method should only be used by developers with advanced PDF knowledge.
Sub Fill(Optional EvenOdd = False)
Fills the current path. EvenOdd specifies the filling rule to be used. If set to True or omitted, the nonzero winding number rule is used, otherwise the even-odd rule is used. For more information on filling rules Section 4.2 - AspPDF Implementation of Drawing.
Sub FillEllipse(X As Single, Y As Single, RX As Single, RY As Single)
Fills an ellipse with the center in (X, Y) and radii RX and RY. If RX=RY, the ellipse turns into a circle.
Sub FillRect(X As Single, Y As Single, Width As Single, Height As Single)
Fills a rectangle with the lower-left corner in (X, Y) and size Width x Height.
Sub FillStroke(Optional EvenOdd = False)
Fills, then strokes the current path. EvenOdd specifies the filling rule to be used. If set to True or omitted, the nonzero winding number rule is used, otherwise the even-odd rule is used. For more information on filling rules Section 4.2 - AspPDF Implementation of Drawing.
Sub FillWithPattern(Graph As PdfGraphics, Optional EvenOdd = False)

Fills the current path with a pattern cell specified by Graph, a PdfGraphics object created using the Pattern=true parameter.

EvenOdd specifies the filling rule to be used (see Fill for the description of this argument).

For more information about patterns, see Section 5.3.2 - Tiling Patterns and Section 16.5 - Patterns and Shadings.

This method was introduced by version 1.6.

Sub FillWithShading(Shading As PdfShading)

Fills the current path with a shading specified by Shading, a PdfShading object creatable via the PdfDocument.CreateShading method.

For more information, see Section 16.5 - Patterns and Shadings.

This method was introduced by version 3.5.

Sub LineTo(X As Single, Y As Single)
Appends a straight line segment to the current path extending from the current point to (X, Y)
Sub MoveTo(X As Single, Y As Single)
Starts a new subpath from the point (X, Y).
Sub RestoreState()
Restores the graphics state saved with SaveState. For more information about saving and restoring the graphics state, Section 4.5.2 - Graphics State Stack.
Sub SaveState()
Saves the current graphics state. For more information about saving and restoring the graphics state, Section 4.5.2 - Graphics State Stack.
Sub SetColor(R As Single, G As Single, B As Single)

Sets the current stroking color space to "DeviceRGB", and sets the current color in RGB color space to be used by all stroking methods such as Stroke, DrawLine, DrawRect, DrawEllipse, etc. The current color is black by default.

R, G, B specify the RGB components of the color in the range [0, 1].

Sub SetColorCMYK(C As Single, M As Single, Y As Single, K As Single)

Sets the current stroking color space to "DeviceCMYK", and sets the current color in CMYK color space to be used by all stroking methods such as Stroke, DrawLine, DrawRect, DrawEllipse, etc. The current color is black by default.

C, M, Y, K specify the CMYK components of the color in the range [0, 1].

Sub SetColorEx(Param As Variant)

Sets the current stroking color. Does not change the current color space. An arbitrary number of color components can be specified. This method should be used in conjunction with the SetColorSpace method.

Param is a PdfParam object or parameter string specifying the color component values:

  • c1, c2, ..., cN (required) - color components in the range [0.0, 1.0]. The number of color components must match the currently selected color space.

As of Version 3.5, Param can also be an instance of the PdfGraphics object representing a pattern to be used as the current stroking color.

Usage:

' Set current stroking color via its color components
Page.Canvas.SetColorSpace Doc.CreateColorSpace("DeviceRGB")
Page.Canvas.SetColorEx "c1=0.5; c2=0.3; c3=1" ' 3 color components

' Set a pattern as current fill color
Set Pattern = Doc.CreatePattern(...)
Page.Canvas.SetColorEx objPattern

For more information, see Section 16.1 - Color Space Object, Section 16.5 - Patterns and Shadings.

This method was introduced by Version 2.5.

Sub SetColorSpace(ColorSpace As PdfColorSpace)

Sets the current stroking color space to ColorSpace.

For more information, see Section 16.1 - Color Space Object.

This method was introduced by Version 2.5.

Sub SetCTM(a As Single, b As Single, c As Single, d As Single, e As Single, f As Single)
Sets the current transformation matrix (CTM). For more information about the transformation matrix, see Section 4.5.1 - Transformation Martix.
Sub SetFillColor(R As Single, G As Single, B As Single)

Sets the current fill color space to "DeviceRGB", and sets the current fill color in RGB color space to be used by all filling methods such as Fill, FillStroke, FillRect, FillEllipse, etc. The current fill color is black by default.

R, G, B specify the RGB components of the color in the range [0, 1].

Sub SetFillColorCMYK(C As Single, M As Single, Y As Single, K As Single)

Sets the current fill color space to "DeviceCMYK", and sets the current fill color in CMYK color space to be used by all filling methods such as Fill, FillStroke, FillRect, FillEllipse, etc. The current fill color is black by default.

C, M, Y, K specify the CMYK components of the color in the range [0, 1].

Sub SetFillColorEx(Param As Variant)

Sets the current fill color. Does not change the current color space. An arbitrary number of color components can be specified. This method should be used in conjunction with the SetFillColorSpace method.

Param is a PdfParam object or parameter string specifying the color component values:

  • c1, c2, ..., cN (required) - color components in the range [0.0, 1.0]. The number of color components must match the currently selected color space.

As of Version 3.5, Param can also be an instance of the PdfGraphics object representing a pattern to be used as the current stroking color.

Usage:

' Set current fill color via its color components
Page.Canvas.SetFillColorSpace Doc.CreateColorSpace("DeviceCMYK")
Page.Canvas.SetFillColorEx "c1=0.5; c2=0.3; c3=1; c4=0.8" ' 4 color components

' Set a pattern as current fill color
Set Pattern = Doc.CreatePattern(...)
Page.Canvas.SetFillColorEx objPattern

For more information, see Section 16.1 - Color Space Object, Section 16.5 - Patterns and Shadings.

This method was introduced by Version 2.5.

Sub SetFillColorSpace(ColorSpace As PdfColorSpace)

Sets the current fill color space to ColorSpace.

For more information, see Section 16.1 - PdfColorSpace Object.

This method was introduced by Version 2.5.

Sub SetGState(GState As PdfGState)

Sets the current graphics state object to GState.

For more information, see Section 17.1 - PdfGState: Overview.

This method was introduced by Version 3.1.

Sub SetParams(Param As Variant)

Enables setting several graphics state parameters at once via a PdfParam object or parameter string. These parameters include:

  • Color - same effect as SetColor method, but the color can be specified by name, such as red, or via a Hex value, such as &HFF0000.
  • FillColor - same effect as SetFillColor method, but the fill color can be specified by name, such as red, or via a Hex value, such as &HFF0000.
  • r, g, b - same effect as SetColor method.
  • fr, fg, fb - same effect as SetFillColor method.
  • c, m, y, k - same effect as SetColorCMYK method.
  • fc, fm, fy, fk - same effect as SetFillColorCMYK method.
  • LineWidth, LineCap, LineJoin, MeterLimit - same affect as LineWidth, LineCap, LineJoin and MeterLimit properties.
  • Dash1, Dash2, ...., DashPhase - specify the line dash pattern. For more information on dash patterns, see Section 4.4.4 - Line Dash Pattern.

Usage:

Canvas.SetParams "Color=blue; FillColor=yellow; LineWidth=3"
Canvas.SetParams "Color=&H0000FF; FillColor=&HFFFF00; Dash1=2"
Canvas.SetParams "r=1; g=0; b=.5; "
Sub SetTM(a As Single, b As Single, c As Single, d As Single, e As Single, f As Single)
Sets the current text transformation matrix (TM). A TM is similar to CTM except that it applies to text operators only. This method should be used by advanced users only.
Sub Stroke()
Strokes the current path.
Other Products
AspUpload
AspEmail
AspEmail.NET
AspJpeg
AspJpeg.NET
AspHEIF
AspPDF.NET
AspEncrypt
AspGrid
AspUser