PdfDocument Object

Overview

PdfDocument is a major object representing a new or existing PDF document. An instance of PdfDocument is creatable via PdfManager's CreateDocument method as well as OpenDocument/OpenDocumentBinary methods.

Member List

Properties

Author As String (Read/Write)
Returns or specifies the document's author (usually the name of the person who created the document).
CompressedXRef As Boolean (Read/Write)
Returns or specifies whether the current document uses a compressed cross-reference table. Modifying this property is generally not recommended. This property was introduced by version 1.8.
CreationDate As Date (Read/Write)
Returns or specifies the date/time the document was created.
Creator As String (Read/Write)
Returns or specifies the document's creator. If the document was converted from to PDF from another format, this property returns the name of the application that created the original document.
Encrypted As Boolean (Read-only)
Returns True is the document is encrypted.
Filename As String (Read-only)
Returns the filename (without a path) under which this document was saved via the Save method. This property is particularly useful when the Save method is called with the Overwrite option set to False and the actual filename may differ from the desired filename passed to the Save method. If the document was saved using SaveToMemory or SaveHttp, this property returns an empty string.
Fonts As PdfFonts (Read-only)
Returns the PdfFonts collection which enables you to obtain a PdfFont object to be passed to text-drawing methods such as Canvas.DrawText. For more information, see Chapter 6 - Text and Fonts.
Form As PdfForm (Read-only)
Returns the PdfForm collection of PdfAnnot objects representing interactive form fields placed on this document. For more information, see Chapter 11 - Forms.
ID As String (Read-only)
Returns this document's Hex-encoded ID which is usually a random 16-byte binary sequence, such as "244F19CCDF3988289B47B29585AD9A12".
ImportInfo As PdfParam (Read-only)

Returns an instance of the PdfParam object populated with the Y-coordinate and page index of the lowest vertical boundary of HTML content rendered by the last successful call to ImportFromUrl. The item names are "Y" and "Page", respectively. This property was introduced in Version 1.9.

For more information, see Section 15.7 - Obtaining Y-Boundary.

KeyLength As Long (Read-only)
If this document is encrypted, returns the key length: 40 or 128 for RC4, and -128 or -256 for AES (128-bit AES is supported in AspPDF 2.2+, and 256-bit AES in AspPDF 3.5.0.6+.) Returns 0 if the document is not encrypted.
Keywords As String (Read/Write)
Returns or specifies keywords associated with this document.
Mac As Boolean (Read-only)
Returns True if this is an existing document and there are indications the file contains a MacBinary header. Returns False in all other cases.
MetaData As String (Read-only)
Returns or specifies this document's XML-based metadata string. For more information, see Section 14.2 - Metadata.
ModDate As Date (Read/Write)
Returns or specifies the date/time the document was most recently modified.
OpenAction As Object (Read/Write)

Specifies a PdfDest or PdfAction object to be used when the document is opened. Use this property if you need the document to fit the window in a particular way upon opening, or perform a certain action (such as execute a script). For more information about destinations and actions, see Section 10.1 - Destinations and Section 10.4 - Actions, respectively.

Usage:

Doc.OpenAction = Doc.Pages(1).CreateDest("Fit=true")

Doc.OpenAction = Doc.CreateAction("type=JavaScript", "this.print(true)" )
OriginalFilename As String (Read-only)
Returns this document's original filename (without a path) if the document was opened using Pdf.OpenDocument. If this is a new document, or if the document was opened using Pdf.OpenDocumentBinary, this property returns an empty string.
OriginalPath As String (Read-only)
Returns this document's full original path if the document was opened using Pdf.OpenDocument. If this is a new document, or if the document was opened using Pdf.OpenDocumentBinary, this property returns an empty string.
OriginalVersion As String (Read-only)
Returns this document's original PDF version embedded in the document header (such as "1.3"). If this is a new document, this property returns an empty string.
Outline As PdfOutline (Read-only)
Returns the PdfOutline collection of PdfOutlineItem objects this document's outline structure. For more information, see Section 10.2 - Outlines.
OwnerPassword As Boolean (Read-only)
Returns True if this document is an existing one (i.e. opened via OpenDocument or OpenDocumentBinary), encrypted and has the owner password specified. Returns False in all other cases. For more information about owner passwords, see Section 8.1 - Overview of PDF Security.
OwnerPasswordUsed As Boolean (Read-only)

Returns True if this document is an existing one (i.e. opened via OpenDocument or OpenDocumentBinary), encrypted, and the owner password (as opposed to the user password) was used to open it. Returns False in all other cases.

This property is useful for permission flag enforcement. For more information about owner passwords, see Section 8.1 - Overview of PDF Security.

PageLayout As pdfPageLayout (Read-only)

Returns or specifies the page layout to be used when the document is opened. This property can be set to one of the four pdfPageLayout constants defined by the AspPDF component, or an integer value. Valid values are:

  • pdfSinglePage (1): display one page at a time.
  • pdfOneColumn (2): display the pages in one column.
  • pdfTwoColumnLeft (3): display the pages in two columns, with odd-numbered pages on the left.
  • pdfTwoColumnRight (4): display the pages in two columns, with odd-numbered pages on the right.

Usage (C#):

objDoc.PageLayout = pdfPageLayout.pdfOneColumn;
PageMode As pdfPageMode (Read/Write)

Returns or specifies how the document should be displayed when opened. This property can be set to one of the four pdfPageMode constants defined by the AspPDF component, or an integer value. Valid values are:

  • pdfUseNone (1): neither document outline nor thumbnail images are visible.
  • pdfUseOutlines (2): document outlines are visible.
  • pdfUseThumbs (3): thumbnail images are visible.
  • pdfFullScreen (4): full-screen mode, with no menu bar, window controls or any other window visible.

Usage (C#):

objDoc.PageMode = pdfPageMode.pdfUseOutlines;
Pages As PdfPages (Read-only)
Returns the PdfPages collection of PdfPage objects representing pages in the document. PdfPages is used to access, add and remove individual pages.
Path As String (Read-only)
Returns the full path under which this document was saved via the Save method. If the document was saved using SaveToMemory or SaveHttp, this property returns an empty string.
Permissions As Long (Read/Write)

If this document is encrypted, returns permission flags associated with this document. If the document is not encrypted, returns 0.

For the detailed description of the PDF permission flags, see Section 8.1.2 - Permission Flags.

Producer As String (Read/Write)
Returns or specifies the document's producer (usually the name of the application that generated this PDF file). When a new document is created, AspPDF sets this property to "Persits Software AspPDF - www.persits.com" by default.
SignatureInfo As String (Read-only)

Returns three comma-separated properties of a digital signature: Hex-encoded SHA hash value, signature location within the PDF file, and signature placeholder's size.

For example:

B7F2211A4D83D624B2C9DF7277C222BA3931E4C8,135676,5000

This property is populated during pre-signing, when the Sign method is called with the first argument set to Nothing (null), and the pre-signed document is saved to disk. Pre-signing is the first step of a three-step process to perform client-side signing of server-side PDFs. For more information, see Section 8.4 - Client-Side Signing of Server-Side PDFs.

This property was introduced in Version 3.4.

Subject As String (Read/Write)
Returns or specifies the document's subject.
Title As String (Read/Write)
Returns or specifies the document's title.
UserPassword As Boolean (Read-only)
Returns True if this document is an existing one (i.e. opened via OpenDocument or OpenDocumentBinary), encrypted and has the user password specified. Returns False in all other cases. For more information about user passwords, see Section 8.1 - Overview of PDF Security.
Version As String (Read/Write)
Specifies the PDF version to be embedded in the document header when the document is saved. "1.3" by default.

Methods

Sub AddImageReplacement(ImageID As String, Obj As Variant)

Adds a mapping between an image item in an existing PDF document to be replaced, and an image or graphics object to replace it with. This method is to be used in conjunction with the image stitching feature (AppendDocument method) to replace images in a document with other images or graphics.

ImageID identifies the inner object ID of the image to be replaced.

Obj is an instance of the PdfImage or PdfGraphics object to replace the old image with.

For more information, see Section 17.8 - Image Replacement.

This method was introduced in Version 3.6.

Sub AddOutputIntent(Condition As String, ConditionID As String, ProfilePath As String, Colors As Integer)

Adds an output intent which is a mapping between a device-dependent color space such as DeviceRGB and a device-independent color space. This method should be used to create PDF/A-compliant documents.

Condition identifies the intended output device or production condition in human-readable form.

ConditionID identifies the intended output device or production condition in human- or machine-readable form. Can be set to "Custom".

ProfilePath specifies the path to the ICC profile file (.icc) which maps the device-dependent color space used by the document to a device-independent one.

Colors specifies the number of color components in the device-dependent color space used by the document (1 for DeviceGray, 3 for DeviceRGB and 4 for DeviceCMYK.)

For more information, see Section 14.3 - AspPDF's Support for PDF/A. This method was introduced in Version 3.3.

Function AddStructureElement(Item As Variant, Type As String, Parent As Integer, Page As PdfPage, Params As String) As Integer

Adds a structure element to the internal logical structure tree of the PDF document. Having a logical structure tree in a document is a requirement for PDF/A-3 compliance. Returns the unique ID of the newly added structure element.

Item specifies the item which this structure element is associated with. Can be an instance of PdfGraphics, PdfImage or PdfAnnot, or a marked content ID returned by the BeginMarkedContent method. Can also be set to Nothing.

Type specifies the element type such as "Document", "P", "H1", "Annot" or any other standard name.

Parent specifies the parent ID which is a unique number returned by a previous call to this method. For the root element, must be set to 0.

Page is an instance of the PdfPage object which this structure item is associated with. Can be set to Nothing.

Params is reserved for future use and should be set to an empty string.

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

This method was introduced in Version 3.7.

Sub AddTemplate(Graph As PdfGraphics, Optional Param As Variant)

Associates a template graphics with this document. If one or more templates are associated with the document, the applicable templates are automatically drawn on newly added pages to serve as the background for these pages. This method is useful when new content needs to be drawn on top of a template (as opposed to a blank page) and the number of pages to be added is not known in advance, such as when calling the ImportFromUrl method. All existing templates can be cleared via the ClearTemplates method.

Graph is an instance of the PdfGraphics object representing the template graphics. It can be newly created or based on the page of another document.

Param is a PdfParam object or parameter string specifying which pages, by index, this template is applicable to as well as the position and scaling of the template on the page. The following parameters are supported (all optional):

  • From - To, From1 - To1, ..., FromN - ToN - specify 1-based ranges of pages that this template is to be applied to. By default, From is 1 and To is infinity.
  • Exclude - if set to 1, all odd pages are excluded; if set to 2, all even pages are excluded; if set to any other number or omitted, no pages are excluded. 0 by default.
  • X, Y - the coordinates of the lower-left corner of the template on the page. (0, 0) by default.
  • ScaleX, ScaleY, Angle - scaling and rotation parameters. (1, 1) and 0 by default.

For more information, see Section 15.8 - Templates. This method was introduced in Version 3.2.

Sub AppendDocument(Document As PdfDocument)

Appends (stitches) an existing PDF document to the current one. Document must be an instance of the PdfDocument object created via OpenDocument or OpenDocumentBinary, but not CreateDocument. One or more documents can be stitched to this document by calling the AppendDocument method multiple times.

If Document is secure, it must have been opened with the owner password, not the user password, otherwise this method throws an error exception.

For more information on document stitching, see Section 14.1 - Document Stitching.

Sub ClearTemplates()
Clears all templates added via the AddTemplate method. This method was introduced in Version 3.2.
Sub Close()

Closes the underlying PDF file if this document object is based on an existing PDF, i.e. opened via the OpenDocument method. Has no effect if this is a new document.

A PDF file opened via OpenDocument always gets closed automatically when the corresponding PdfDocument object is destroyed. However, under .NET garbage collection, the actual object destruction may be deferred thus leaving the PDF file opened and locked indefinitely. The Close method enables you to close the file explicitly when your application needs it.

Function CreateAction(Param As Variant, Value As String) As PdfAction

Creates and returns an instance of the PdfAction object representing an action.

Param is a PdfParam object or parameter string specifying the action type and other type-specific parameters.

Value has different meanings depending on the action type and may be ignored altogether by some action types.

For the detailed description of the CreateAction method and its parameters, see Section 10.4 - Actions.

Function CreateColorSpace(Name As String, Optional Param As Variant) As PdfColorSpace

Creates and returns an instance of the PdfColorSpace object representing a color space.

Name is the name of the color space, such as "DeviceRGB".

Param is a PdfParam object or parameter string specifying various parameters. The list of parameters is too extensive to be shown here.

For the detailed description of the CreateColorSpace method and its parameters, see Section 16.1 - PdfColorSpace Object.

This method was introduced by version 2.5.

Function CreateDest(Page As PdfPage, Param As Variant) As PdfDest

Creates and returns an instance of the PdfDest object representing a destination. This method is redundant. It is recommended that the method Page.CreateDest be used instead.

Page is a PdfPage object the destination is associated with.

Param is a PdfParam object or parameter string specifying various parameters of the destination.

For the detailed description of the CreateDest method and its parameters, see Section 10.1 - Destinations.

Function CreateFunction(Param As Variant) As PdfFunction

Creates and returns an instance of the PdfFunction object representing a transformation function. Functions are used in conjunction with some color spaces.

Param is a PdfParam object or parameter string specifying various parameters. The list of parameters is too extensive to be shown here.

For the detailed description of the CreateFunction method and its parameters, see Section 16.2 - PdfFunction Object.

This method was introduced by version 2.5.

Function CreateGraphics(Param As Variant) As PdfGraphics

Creates and returns an instance of the PdfGraphics object representing a graphics (referred to as a Form XObject by PDF specifications).

Param is a PdfParam object or parameter string specifying various creation parameters of the graphics, including:

  • Left, Bottom, Right, Top (required) - the coordinate space of the graphics. Usually, Left and Bottom are set to 0 and Right and Top to the graphics width and height, respectively.
  • a, b, c, d, e, f (optional) - specify a transformation matrix that maps graphics space into user space ([1 0 0 1 0 0] by default).
  • Pattern (optional) - if set to True, designates this graphics object as a pattern cell. False by default. This parameter was introduced by version 1.6. For more information about patterns, see Section 5.3.2 - Tiling Patterns.

For more information on graphics, see Section 5.3 - PdfGraphics Objects.

Function CreateGraphicsFromPage(Document As IPdfDocument, Index As Long) As PdfGraphics

Creates and returns an instance of the PdfGraphics object representing the page of another document specified by Document. Index specifies the 1-based index of the page within that document to be converted to a graphics object. Document must be an existing document. This method cannot be called on itself.

This method allows the page of another document to be drawn on any page of this document at an arbitrary location with rotation and scaling applied, if necessary.

This method was introduced in Version 2.3.

For more information on creating graphics from pages, see Section 9.6 - Drawing Other Documents' Pages.

Function CreateGState(Param As Variant) As PdfGState

Creates an instance of the graphics state object encapsulating multiple graphics state parameters including those related to transparency operations. Also creates a transparency group object. Both the graphics state and transparency group objects are represented by an instance of the PdfGState object. This method was introduced in Version 3.1.

Param is a PdfParam object or parameter string. Valid parameters, all optional, are as follows:

  • Group - if set to True, the returned instance of the PdfGState object represents a transparency group. If set to False or omitted, it represents a graphics state. False by default.
  • BlendMode - a number between 1 and 16 specifying the blend mode (1 - Normal, 2 - Multiply, 3 - Screen, 4 - Overlay, 5 - Darken, 6 - Lighten, 7 - ColorDodge, 8 - ColorBurn, 9 - HardLight, 10 - SoftLight, 11 - Difference, 12 - Exclusion, 13 - Hue, 14 - Saturation, 15 - Color, 16 - Luminosity). Ignored if Group is set to True.
  • Alpha, FillAlpha - numbers in the range 0.0 to 1.0 specifying the stroke and fill alpha values, respectively. 1.0 by default. Ignored if Group is set to True.
  • Overprint, FillOverprint - stroke and fill overprint Boolean flags, respectively. Ignored if Group is set to True.
  • AlphaIsShape - alpha source flag. If set to True, the soft mask and alpha are interpreted as shape value, otherwise they are interpreted as opacity values. Ignored if Group is set to True.
  • TextKnockout - text knockout flag which determines the behavior of overlapping glyphs. Ignored if Group is set to True.
  • Isolated - specifies the isolated flag for a transparency group. False by default. Ignored if Group is set to False or omitted.
  • Knockout - specifies the knockout flag for a transparency group. False by default. Ignored if Group is set to False or omitted.

For more information on graphics state and transparency group objects, see Chapter 19 - Transparency.

Function CreatePattern(Param As Variant, Shading As PdfShading) As PdfGraphics

Creates an instance of the PdfGraphics object representing a pattern. Creates either a tiling or shading pattern. For tiling patterns, Shading should be set to Nothing, and for shading patterns to a valid PdfShading object creatable via the CreateShading method. The method returns an instance of the PdfGraphics object representing a pattern, which can be passed to the PdfCanvas.SetColorEx and PdfCanvas.SetFillColorEx methods as if it were a regular color.

This method was introduced in Version 3.5.

Param is a PdfParam object or parameter string. Valid parameters are as follows:

  • Type (required) - specifies the pattern type. Must be set to 1 (tiling pattern) and 2 (shading pattern).
  • Left, Bottom, Right, Top (required) - specify the coordinates, in the pattern's coordinate system, of the left, bottom, right and top edges, respectively.
  • PaintType (optional, tiling patterns only) - 1 for a colored tiling pattern, 2 for an uncolored tiling pattern. 1 (colored pattern) is the default value. An uncolored pattern does not specify any color information. Instead, the entire pattern cell is painted with a separately specified color each time the pattern is used. Essentially, it describes a stencil through which the current color is to be poured.
  • TilingType (optional, tiling patterns only) - a code that controls adjustments to the spacing of the tiles relative to the device pixel grid. The valid values are: 1 (default) - constant spacing; 2 - no distortion; 3 - constant spacing and faster tiling.
  • XStep, YStep (optional, tiling patterns only) - the desired horizontal and vertical spacing between pattern cells, respectively, measured in the pattern coordinate system. Right - Left and Top - Bottom by default, respectively.
  • a, b, c, d, e, f (optional) - specify the pattern matrix. The identity matrix [1, 0, 0, 1, 0, 0] by default.

Shading is an instance of the PdfShading object representing a shading this pattern is based on. Must be specified for shading patterns only. Ignored and should be set to Nothing for tiling patterns.

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

Function CreateShading(Param As Variant, Function As PdfFunction, ColorSpace As PdfColorSpace) As PdfShading

Creates an instance of the PdfShading object representing a shading. Creates function-based, axial and radial shadings. Function is required for function-based shadings, and optional for axial and radial shadings. ColorSpace is always required. The method returns an instance of the PdfShading object which can be used directly via PdfCanvas.FillWithShading, or passed to the CreatePattern method to create shading patterns.

This method was introduced in Version 3.5.

Param is a PdfParam object or parameter string. Valid parameters are as follows:

  • Type (required) - specifies the shading type. Must be set to 1 (function-based shading), 2 (axial shading) or 3 (radial shading).
  • bc1, bc2, ..., bcN (optional) - the color components for the background color. N is the number of colorants in the specified color space. If specified, this color is used to fill the area before any painting operations involving the shading are applied.
  • XMin, YMin, XMax, YMax (optional, function-based shadings only) - specify the rectangular domain of coordinates over which the color function is defined. [0.0, 1.0, 0.0, 1.0] by default.
  • t0, t1 (optional, axial and radial shadings only) - specify the limiting values of a parametric variable t which is the input argument to the color function. [0.0, 1.0] by default.
  • Left, Bottom, Right, Top (optional) - specify the shading's bounding box. The coordinates are interpreted in the shading's target coordinate space. If present, this box is applied as a temporary clipping boundary when the shading is painted.
  • a, b, c, d, e, f (optional, function-based shadings only) - specify the transformation matrix mapping the coordinate space specified by the domain [XMin, YMin, XMax, YMax] into the shading's target coordinate space. The identity matrix [1, 0, 0, 1, 0, 0] by default.
  • AntiAlias (optional) - a Boolean flag indicating whether to filter the shading function to prevent antialiasing artifacts. False by default.
  • Offset1, Color1, Offset2, Color2, ..., OffsetM, ColorM (optional, axial and radial shadings only) - a set of pairs Offset/Color defining a gradient. Offsets must be in the range [0.0, 1.0]. If at least two pairs are specified, Function is not used and ignored.
  • ExtendStart, ExtendEnd (optional, axial and radial shadings only) - two Boolean flags specifying whether to extend the shading beyond the starting and ending points of the axis, respectively. (False, False) by default.

Function is an instance of the PdfFunction object representing the color function. The number of inputs must be 2 for function-based shadings, and 1 for axial and radial shadings. The number of outputs must match the number of colorants of the color space specified by ColorSpace. Required for function-based shadings, does not need to be specified for axial and radial shadings if the Offset/Color pairs are specified.

ColorSpace is an instance of the PdfColorSpace object representing the color space for the shading.

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

Function CreateTable(Param As Variant) As PdfTable

Creates and returns an instance of the PdfTable object representing a table.

Param is a PdfParam object or parameter string specifying various creation parameters of the table, including:

  • Width, Height (required) - the table's initial width and height.
  • Cols, Rows (optional) - the initial number of columns and rows in the table. The table is 1x1 by default.
  • CellSpacing (optional) - the table's cell spacing which is the width of a margin separating cells from each other and the outer border. Similar to HTML's CELLSPACING attribute of the <TABLE> tag. 0 by default.
  • CellPadding (optional) - the table's cell padding which is the width of a margin separating cell contents from the cell's borders. Similar to HTML's CELLPADDING attribute of the <TABLE> tag. 0 by default.
  • Border (optional) - the width of the outer border. 0 by default (which means no border).
  • CellBorder (optional) - the width of all cell borders. 1 by default.
  • BorderColor, CellBorderColor (optional) - the color of the outer border and cell border, respectively. Black by default.
  • BgColor, CellBgColor (optional) - the color of the table background and cell background, respectively. Transparent by default.

For more information on tables in general and the CreateTable method in particular, see Chapter 7 - Tables.

Sub Encrypt(Optional OwnerPwd, Optional UserPwd, Optional KeyLength, Optional Permissions)

Encrypts a document with a key of the specified length using the specified passwords, and embeds the specified permission flags into the encrypted document. This method cannot be called on an existing document.

OwnerPwd - the owner password. Optional, an empty string by default.

UserPwd - the user password. Optional, an empty string by default.

KeyLength - the key length, must be 40 or 128 for RC4, or -128 or -256 for AES. 128-bit AES is supported in AspPDF 2.2+, and 256-bit AES in AspPDF 3.5.0.6+. Optional, 40 by default. Note that 40-bit encryption is insecure and should never be used.

Permissions - a combination of pdfPermissions flags. Optional, pdfFull by default.

For more information on PDF security and the Encrypt method, see Chapter 8 - Security.

Function ExtractPages(Param As Variant) As PdfDocument

Extracts one or several pages from an existing document. Returns an instance of the PdfDocument representing the new document.

Param is a PdfParam object or parameter string specifying 1-based indices of pages to be extracted via the parameters Page1, Page2, Page3, etc.

An instance of the PdfDocument object returned by this method cannot be used for anything other than saving.

Usage:

Set NewDoc = Doc.ExtractPages("Page1=2; Page2=6")

For more information, see Section 9.5 - Page Extraction.

Function ImportFromUrl(URL As String, Optional Param, Optional Username, Optional Password) As String

Opens an HTTP URL and converts the content of the page into PDF. Populates the current PdfDocument object with the result of the conversion. The current PdfDocument can either be an empty document created with CreateDocument, or an existing document opened via OpenDocument/OpenDocumentBinary.

Return value: if the Debug parameter (see below) is set to True, this method returns a log of non-fatal errors. Otherwise returns an empty string.

URL can be an http or https address, such as "http://www.server.com/path/file.asp", or a physical local path such as "c:\path\file.html". It can also directly specify an HTML text string, such as "<html>some HTML code</html>".

For more information about this method, see Chapter 15 - HTML to PDF Conversion.

Param is a PdfParam object or parameter string specifying various conversion parameters (all of them optional), including:

  • PageWidth - page width, 612 (8.5") by default.
  • PageHeight - page height, 792 (11") by default.
  • Landscape - if set to True, the document's pages have landscape orientation. False (portrait orientation) by default.
  • LeftMargin, RightMargin, TopMargin, BottomMargin - page margins, 54 (0.75") by default.
  • LeftMarginNNN, RightMarginNNN, TopMarginNNN, BottomMarginNNN - page margins specified individually for page number NNN. Override the default margin settings. Pages with numbers higher than NNN inherit the new settings. The effective page width must be kept unchanged, i.e. the value PageWidth - LeftMarginNNN - RightMarginNNN (or in case of Landscape=true, PageHeight - TopMarginXXX - BottomMarginXXX) must be the same for all pages. These parameters were introduced by version 1.6.0.10.
  • CodePage - specifies the encoding of the page, similar to the View/Encoding option in a browser. This parameter, if specified, overrides the charset value specified via a <META http-equiv="Content-Type"> tag in the document's body. 1252 (US ASCII) by default.
  • StopAfter - specifies the number of pages in a resultant document after which the document creation will be aborted, with an error message added to the log (see the Debug parameter below.) 200 by default.
  • DrawBackground - if set to True, each page of the generated PDF document will display a background specified by the source HTML document's BGCOLOR or BACKGROUND attributes (or their CSS equivalents BACKGROUND-COLOR and BACKGROUND-IMAGE.) False by default, which means the background remains transparent/white regardless of the source HTML document's background settings.
  • StartPage - specifies the 1-based index of a page to begin rendering on. Applies to non-empty documents only. If the specified value is greater than the number of pages in the current document, the rendering will begin on the last page of the document. 1 by default.
  • Hyperlinks - if set to True, all hyperlinks on the page being converted will be enabled (clickable). False by default. This parameter was introduced by version 1.7.
  • Media - specifies which cascading style sheets to read depending on their MEDIA attribute. Can be a combination (sum) of the following values: 1 ("all"), 2 ("screen"), 4 ("print"), 8 ("asppdf") and 128 (all others.) 255 by default, which means the MEDIA attribute is ignored altogether. This parameter was introduced by version 1.7.
  • Scale - specifies a scaling factor at which the document is rendered. 1 by default which means 100%. A number less than 1 shrinks the document, greater than 1 expands it. This parameter was introduced by version 1.7.
  • SplitImages - by default, if the bottom part of an image cannot fit on the page, the whole image is pushed down to the next page to preserve its integrity. If this parameter is set to True, an image may be split between adjacent pages if necessary. False by default. This parameter was introduced by version 1.7.
  • Debug - if set to True, the method returns a log of non-fatal errors encountered during the HTML to PDF conversion process, such as invalid image URLs, unknown fonts, etc. False by default. This parameter should be used for debugging purposes only.
  • Timeout - if set to a positive number, specifies the timeout value (in seconds) for the Resolve, Connect, Send and Receive HTTP operations (same value for all four operations.) By default, these timeout values are 0 (infinite), 60 seconds, 30 seconds and 30 seconds, respectively. This parameter was introduced by version 1.7.
  • InvertCMYK - if set to True, inverts all CMYK images on the HTML document back to normal. False by default. This parameter was introduced in version 2.0.0.7.
  • CheckboxSize - Specifies the display size of the checkbox and radio buttons when converting interactive HTML forms to PDF. 12 by default. This parameter was introduced in version 2.2.0.6.
  • WinHttp - If set to True, directs ImportFromUrl to use the Microsoft WinHttp object instead of XmlHttp to retrieve URL data. WinHttp supports TLS 1.2 on Windows 2012+ and 8+, while XmlHttp does not. False by default. This parameter was introduced in version 3.4.0.5.

Username, Password specify authentication parameters in case the URL is protected with basic authentication. These arguments can also be used to pass the authentication cookie name (prefixed with the word "Cookie:") and cookie value when using .NET Forms authentication. This is described in detail in Section 15.2 - Authentication.

Usage:

' Create a new PDF document from a URL, use Landscape mode, enable hyperlinks
Set Doc = Pdf.CreateDocument
Doc.ImportFromUrl "http://www.server.com", "landscape=true, hyperlinks=true"
Doc.Save "c:\path\doc.pdf"
' Create a new PDF document from a local HTML file, enable logging
Set Doc = Pdf.CreateDocument
LogString = Pdf.ImportFromUrl( "c:\path\doc.htm", "debug=true" )
Doc.Save "c:\path\doc.pdf"
' Render HTML from a URL onto an existing PDF document starting with page 2
Set Doc = Pdf.OpenDocument( "c:\path\template.pdf" )
Doc.ImportFromUrl "http://www.server.com/path/file.asp", "startpage=2"
Doc.Save "c:\path\doc.pdf"
' Use direct HTML feed. The argument string must contain "<html>"
Set Doc = Pdf.CreateDocument
Doc.ImportFromUrl "<html><table><tr><td>...</td></tr></table>"
Doc.Save "c:\path\doc.pdf"
Function OpenImage(Path As String, Param As Variant) As PdfImage

Opens an image from a disk file and returns an instance of the PdfImage object representing this image. Supported image formats are BMP, GIF, JPEG and TIFF. This method returns Nothing if the file being opened is a multi-image TIFF and the Index parameter exceeds the number of images in the file.

Path is a full file path to the image. Must be a physical path, not a URL.

Param is a PdfParam object or parameter string specifying optional image opening properties, including:

  • Invert (optional) - if set to True, inverts an image and displays it as a negative. This parameter is useful for displaying CMYK JPEGs. False by default.
  • Interpolate (optional) - if set to True, instructs a viewer application to perform image interpolation when rendering the image for better quality (but at the expense of performance). False by default.
  • Index (optional) - specifies the 1-based index of an image within a multi-image TIFF file. This parameter is only used when a TIFF file is being opened, and ignored by all other types of images. 1 by default.

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

Function OpenImageBinary(Blob As Variant, Param As Variant) As PdfImage

Opens an image from a memory array specified by Blob. Returns an instance of the PdfImage object representing this image. This method should be used if the image being opened resides in the database as a blob.

Param is a PdfParam object or parameter string specifying optional image opening properties. See OpenImage for details.

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

Function OpenUrl(URL As String, Optional Param, Optional Username, Optional Password) As PdfImage

Opens the specified URL or HTML string (in case URL begins with "<HTML" or "<html") and converts it into a sequence of images using the Microsoft Internet Explorer rendering engine. Returns the top image in the sequence. The other images are to be obtained via the PdfImage.NextImage property.

Param is a PdfParam object or parameter string specifying various conversion parameters (all of them optional), including:

  • AspectRatio - a pagination parameter specifying the height of all (except possibly the last) page images produced by the method indirectly, via the desired page width/height ratio value. The image height is ultimately calculated based on this value and the width of the document, whatever the latter turns out to be. If neither this parameter nor PageHeight is specified, no pagination takes place.
  • PageHeight - a pagination parameter specifying the absolute height (in pixels) of all (except possibly the last) page images produced by the method. If AspectRatio parameter is specified, this parameter is ignored. If neither this parameter nor AspectRatio is specified, no pagination takes place.
  • Hem - the maximum number of pixels each page image can be trimmed by from the bottom so that the page separators would pass through a relatively blank row of pixels to achieve cleaner pagination. If this parameter is 0, no hemming takes place. If this parameter is a negative number, the entire page is scanned for a suitable pixel row.
  • HemColor - a color (usually white) that the hemming process uses as the "base" color that all pixels in each row are compared against to find a row with the fewest pixels deviating from this base color. If this parameter is not specified, the dominant color in each row is calculated and used as the base color.
  • Hyperlinks - if set to True, populates the PdfImage.Hyperlinks collection with the coordinate and URL information of the hyperlinks depicted on this image. False by default.
  • Images - if set to True or omitted, instructs IE to load images. True by default.
  • Video - if set to True or omitted, instructs IE to load video. True by default.
  • DownloadActiveX - if set to True, instructs IE to download ActiveX controls. False by default.
  • RunActiveX - if set to True, instructs IE to run ActiveX controls. False by default.
  • Java - if set to True, instructs IE to enable Java applets. False by default.
  • Scripts - if set to True, instructs IE to enable scripts. False by default.
  • SingleThread - if set to True, the IE WebBrowser object is created on the same thread as the main process. By default, a separate thread is created for that purpose. When the component is used under ASP.NET, trying to create the WebBrowser object on the same thread may cause the web page to hang. False by default.
  • WindowWidth, WindowHeight - the dimensions of the internal window hosting the WebBrowser control. 100x100 by default. Changing this size is usually not necessary except when the HTML page being converted contains frames.
  • PageBreakColor - if specified, causes the method to create a page break along a line of pixels of the specified color. By default, a row of pixels must contain 80% of pixels of the specified color to be considered a page break line. This parameter was introduced in Version 3.0.
  • PageBreakThreshold - specifies, percentage wise, how many pixels in a row must be of a particular color for this row to be considered a page break. 0.8 (80%) by default. This parameter was introduced in Version 3.0.

Username, Password specify authentication parameters in case the URL is protected with basic authentication. These arguments can also be used to pass the authentication cookie name (prefixed with the word "Cookie:") and cookie value when using .NET Forms authentication.

This method was introduced in Version 2.9.

For more information, see Chapter 18 - IE-based HTML-to-PDF conversion.

Function Save(Path As String, Optional Overwrite = True) As String

Saves the document to disk, returns the file name under which the document was saved (without a path).

Path specifies the full file path.

Overwrite is an optional argument specifying whether a file under the same name should be overwritten (if set to True or omitted) or a unique filename should be generated to avoid overwriting an existing file (if set to False). True by default.

For example, if a document is being saved under the name proposal.pdf with the Overwrite argument set to False, and a file with the same name already exists in the destination folder, the Save method will try the filenames proposal(1).pdf, proposal(2).pdf, etc. until a unique name is found.

Returns the filename (without the path) under which this document ends up being saved.

For more information, see Section 3.1 - Hello World Application.

Sub SaveHttp(DispHeader As String, Optional ContentType)

Sends the document to an HTTP stream. This method enables your Web-based application to send PDF documents directly to client browsers without having to save them to disk first. SaveHttp can only be called in an ASP or ASP.NET environment as it internally uses ASP's Response.BinaryWrite method.

DispHeader specifies the Content-Disposition header to be included in the HTTP stream. This header carries the file name information to be presented to the user when the file is saved to disk on the client machine. This argument has to be in the following two formats:

"filename=filename.pdf"

or

"attachment; filename=filename.pdf"

The latter prompts the user to save the file to disk instead of opening it in-place in the browser.

ContentType specifies the value for the Content-Type header. By default, this value is "application/pdf". Using this argument is generally not recommended.

For more information on the SaveHttp method, see Section 3.2.2 - Saving to HTTP Stream.

Function SaveToMemory() As Variant

Saves the document to a memory array. This method is useful for saving PDFs in the database as blobs.

For more information on the SaveToMemory method, see Section 3.2.1 - Saving to Memory.

Sub SendToPrinter(Printer As String, Param As Variant)

Sends the underlying document to the printer.

Printer is a local or network name of the printer, such as "Brother HL-2270DW series" or "\\192.168.3.2\HP LaserJet 6P".
Param is a PdfParam object or parameter string containing various printing parameters, including:

  • Stretch - if set to True, the image is stretched to cover the entire print area. False by default.
  • ScaleX, ScaleY - a number greater than 0. Specifies the scaling factor when Stretch is set to True. A value greater than 1 increases the image, less than 1 decreases it. Ignored when Stretch is False.
  • Duplex - if set to 1 or 2, enables duplex (double-sided) printing in the long-edge-binding and short-edge-binding modes, respectively. 0 (one-sided printing) by default.
  • From1/To1, From2/To2, ..., FromN/ToN - specify N ranges of pages to be printed. Each value must be between 1 and total page count. FromN must not exceed ToN.
  • Tray - specifies the printer tray or bin. This parameter was introduced in Version 2.9. Valid values are printer-specific and should be determined by trial and error. For many printers, they are 256 and higher.
  • Color - if set to True, enables the color printing mode. Use this parameter to print a color PDF on a color printer. This parameter was introduced in Version 3.1. False by default.
  • Copies - specifies the number of copies to be printed. 1 by default. This parameter was introduced in Version 3.2.0.2.
  • Collate - If set to True, enables collation when multiple copies of the document are printed. False by default. This parameter was introduced in Version 3.4.0.3.
  • PaperWidth, PaperHeight - Specify the paper width and height in tenths of a millimeter. Useful when printing on a label printer. These parameters were introduced in Version 3.4.0.3.

The following parameters pertain to the PDF-to-Image conversion which SendToPrinter performs internally:

  • ResolutionX, ResolutionY - control print quality. By default, the resolutions are 72 (dpi) but for better print quality, values such as 300 or even 600 should be used.
  • FastCMYK - if set to True, performs CMYK-to-RGB conversion using a simple linear formula which improves conversion speed at the expense of quality. Only makes a difference if the document contains large high-resolution CMYK images and graphics. False by default.
  • IgnoreRotate - if set to True, ignores the /Rotate attribute of the pages. This may cause a landscape-oriented page to be printed with the content rotated 90 degrees. False by default.
  • IgnoreCropBox - if set to True, ignores the /CropBox attribute of the pages and uses its /MediaBox attribute instead. This may cause the printout to include areas of the page that are normally invisible when viewed in a PDF viewer. False by default.

This method was introduced in Version 2.7.

For more information, see Section 17.6.2 - Document Printing.

Sub SetViewerPrefs(Param As Variant)

Sets various viewer preferences for the document.

Param is a PdfParam object or parameter string containing various viewer preference parameters, including:

  • HideToolbar (optional) - if set to True, hides the viewer application's tool bar.
  • HideMenubar (optional) - if set to True, hides the viewer application's menu bar.
  • HideWindowUI (optional) - if set to True, hides user interface elements in the document's window (such as scroll bars and navigation controls).
  • FitWindow (optional) - if set to True, resizes the document's window to fit the size of the first displayed page.
  • CenterWindow (optional) - if set to True, positions the document's window in the center of the screen.
  • DisplayDocTitle (optional) - if set to True, makes the window's title bar display the document title taken from the Title property of the document. Otherwise, the title bar will display the name of the PDF file containing the document.
  • NonFullScreenPageMode (optional) - the document's page mode specifying how to display the document on exiting full-screen mode. Valid values are: 1 (use none), 2 (use outlines), and 3 (use thumbs).
  • PrintScaling (optional) - controls the page scaling option in a print dialog. True by default which means the application should use the current print scaling. If set to False, the print dialog should reflect no page scaling. This parameter was introduced in version 1.6.0.10.
Function Sign(Msg As Object, Name As String, Optional Reason, Optional Location, Optional Param) As PdfAnnot

Digitally signs the document, embeds the signature into the document in PKCS#7 certificate-based format. Returns an instance of the PdfAnnot object representing this signature field. Documents signed with this method can only be saved to disk, not to memory or an HTTP stream.

Msg is an initialized CryptoMessage object of the Persits Software AspEncrypt component. As of Version 3.4, this argument is optional and can be set to Nothing (null). See comments below.

Name specifies the signer name.

Reason specifies an optional reason for signing.

Location specifies an optional signing location.

Param is a PdfParam object or parameter string specifying various signature creation parameters, including:

  • Visible (optional) - if set to True, makes the signature visible in the form of an icon on a page. The page index and icon coordinates are specified by other parameters. False by default. If set to False, all other parameters, except Windows, are ignored.
  • X, Y, Width, Height (required if Visible is True, ignored otherwise) - control the position of the signature icon on a page.
  • PageIndex (optional, ignored if Visible is false) - the 1-based index of the page to place the signature icon on. 1 by default.
  • Windows (optional) - if set to True, the signature filter value is set to Adobe.PPKMS which denotes the standard Windows security handler. If set to False, the signature filter value is set to VeriSign.PPKVS (VeriSign security plug-in). False by default.
  • BinarySize (optional) - specifies the signature size in bytes. By default, AspPDF determines the signature size automatically by performing an extra signing operation on a random string. As a result, if the signer certificate is PIN-protected, the user has to enter the PIN twice which is an inconvenience. If the BinarySize parameter is specified, AspPDF no longer needs to perform an extra signing operation thus enabling the user to avoid entering the PIN twice. The value for this parameter has to be determined by trial and error. If the value is too small, an exception is thrown. This parameter was added in version 2.0.0.7. As of Version 3.4, this parameter is required if Msg argument is set to Nothing (null).
  • Other parameters recognized by the Annots.Add method can also be used.

As of Version 3.4, if the Sign method is called with the Msg argument set to Nothing (null), the PDF document is "pre-signed" -- a signature placeholder is allocated within the document, but it is filled with 0s. The signature, based on the hash value obtained from the PdfDocument.SignatureInfo property, is then generated on a user workstation, transferred back to the server and injected into the PDF being signed, thus completing the signing process. For more information, see Section 8.4 - Client-Side Signing of Server-Side PDFs.

For more information on the Sign method, see Section 8.3 - Digital Signing.

Function VerifySignature(Msg As Object) As PdfSignature

Verifies a PKCS#7 signature in the document. Can only be called on an existing document, and only on a file-based, not memory-based, document.

Returns Nothing if the document contains no PKCS#7 signatures. Otherwise, returns an instance of the PdfSignature object encapsulating various signature properties, including validation status, etc.

Msg is an empty CryptoMessage object of the Persits Software AspEncrypt component.

For more information on signature validation, see Section 8.3.4 - Signature Validation.

Other Products
AspUpload
AspEmail
AspEmail.NET
AspJpeg
AspJpeg.NET
AspHEIF
AspPDF.NET
AspEncrypt
AspGrid
AspUser