PdfCanvas Object

Overview

PdfCanvas encapsulates AspPDF.NET'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

string HtmlTag (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.

int LineCap (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.

int LineJoin (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.

float LineWidth (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.

float MiterLimit (Read/Write)

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

string Value (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

void AbandonPath()
This method cancels all previous path-construction operators. For more information on path construction, see Section 4.1 - Introduction to PDF Drawing
void AddCurve(float X1, float Y1, float X2, float Y2, float X3, float Y3)
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.
void AddEllipse(float X, float Y, float RX, float RY)
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.
void AddRect(float X, float Y, float Width, float Height)
Adds a rectangle to the current path with the lower-left corner in (X, Y) and size Width x Height.
void Append(string Contents)
Appends raw PostScript operators directly to the content stream of the canvas. This method should only be used by developers with advanced PDF knowledge.
int BeginMarkedContent()

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.

void 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.
void Clear()
Clears the current canvas of all drawing operators.
void Clip()
void Clip(bool EvenOdd)
For more information on clipping paths, see Section 4.5.3 - Clipping Paths.

EvenOdd specifies the filling rule to be used. False by default. If set to True, 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.

void ClosePath()
Closes the current subpath by appending a straight line from the current point to the beginning of the subpath.
void DrawBarcode(string Data, object Param)

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.

PdfParam DrawBarcode2D(string TextData, object Param)
PdfParam DrawBarcode2D(byte [] BinaryData, object Param)

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.

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.30456+.
  • 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.30456+.
  • 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.30456+.

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.

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

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:

objPage.Canvas.DrawGraphics( objGraphics, "x=10; y=300" );

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

void DrawImage(PdfImage Image, object Param)

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:

objPage.Canvas.DrawImage( objImage, "x=10;y=300,ScaleX=.5,Scaley=.5" );

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

void DrawLine(float X1, float Y1, float X2, float Y2)
Draws a line from point (X1, Y1) to point (X2, Y2).
void DrawRect(float X, float Y, float Width, float Height)
Draws a rectangle with the lower-left corner in (X, Y) and size Width x Height.
int DrawTable(PdfTable Table, object Param)

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:

objPage.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.

int DrawText(string Text, object Param, PdfFont Font)

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.34872 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:

objPage.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.

void 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.

void 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.
void Fill()
void Fill(bool EvenOdd)
Fills the current path. EvenOdd specifies the filling rule to be used. False by default. If set to True, 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.
void FillEllipse(float X, float Y, float RX, float RY)
Fills an ellipse with the center in (X, Y) and radii RX and RY. If RX=RY, the ellipse turns into a circle.
void FillRect(float X, float Y, float Width, float Height)
Fills a rectangle with the lower-left corner in (X, Y) and size Width x Height.
void FillStroke()
void FillStroke(bool EvenOdd)
Fills, then strokes the current path. EvenOdd specifies the filling rule to be used. False by default. If set to True, 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.
void FillWithPattern(PdfGraphics Graph)
void FillWithPattern(PdfGraphics Graph, bool EvenOdd)

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). False by default.

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.

void FillWithShading(PdfShading Shading)

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.

void LineTo(float X, float Y)
Appends a straight line segment to the current path extending from the current point to (X, Y)
void MoveTo(float X, float Y)
Starts a new subpath from the point (X, Y).
void 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.
void SaveState()
Saves the current graphics state. For more information about saving and restoring the graphics state, Section 4.5.2 - Graphics State Stack.
void SetColor(float R, float G, float B)

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].

void SetColorCMYK(float C, float M, float Y, float K)

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].

void SetColorEx(object Param)

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
objPage.Canvas.SetColorSpace( objDoc.CreateColorSpace("DeviceRGB") );
objPage.Canvas.SetColorEx( "c1=0.5; c2=0.3; c3=1" ); // 3 color components

' Set a pattern as current stroking color PdfGraphics objPattern = objDoc.CreatePattern(...);
objPage.Canvas.SetColorEx( objPattern ); // use pattern as current color

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

This method was introduced by Version 2.5.

void SetColorSpace(PdfColorSpace ColorSpace)

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.

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

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].

void SetFillColorCMYK(float C, float M, float Y, float K)

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].

void SetFillColorEx(object Param)

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
objPage.Canvas.SetColorSpace( objDoc.CreateColorSpace("DeviceRGB") );
objPage.Canvas.SetFillColorEx( "c1=0.5; c2=0.3; c3=1" ); // 3 color components

' Set a pattern as current fill color
PdfGraphics objPattern = objDoc.CreatePattern(...);
objPage.Canvas.SetFillColorEx( objPattern ); // use pattern as current color

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

This method was introduced by Version 2.5.

void SetFillColorSpace(PdfColorSpace ColorSpace)

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.

void SetGState(PdfGState GState)

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.

void SetParams(object Param)

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;" );
void SetTM(float a, float b, float c, float d, float e, float f)
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.
void Stroke()
Strokes the current path.
Other Products
AspUpload
AspEmail
AspEmail.NET
AspJpeg
AspJpeg.NET
AspHEIF
AspPDF
AspEncrypt
AspGrid
AspUser