AspPDF.com -- PdfPage Object

PdfPage represents an individual page in the PDF document. An instance of the PdfPage object is creatable or obtainable via the PdfPages collection returned by the Pages property of the PdfDocument object.

Properties

Annots

Background

Annots As PdfAnnots (Read-only)

Returns the PdfAnnots collection of annotations associated with this page. For more information on annotations, see Section 10.3 - Annotations.

Background As PdfCanvas (Read-only)

Returns an instance of the PdfCanvas object representing this page's background (as opposed to the Canvas property which represents the foreground). This property should be used to draw underneath an existing drawing of the page.

BleedBox As PdfRect (Read-only)

Returns the page's bleed box, which is a region to which the content should be clipped when output in a production environment. This property was introduced in Version 2.9.

Canvas As PdfCanvas (Read-only)

Returns an instance of the PdfCanvas object representing this page's foreground. For more information, see Section 4.2 - AspPDF Implementation of Drawing.

CropBox As PdfRect (Read-only)

Returns the page's crop box, which is a rectangle defining the visible region of default user space. When the page is displayed or printed, its contents are to be clipped (cropped) to this rectangle.

Height As Single (Read/Write)

Returns or specifies this page's height in default user units.

Index As Long (Read-only)

Returns the page's 1-based index in the PdfPages collection, which is also the page number.

MediaBox As PdfRect (Read-only)

Returns the page's media box, which is a rectangle defining the boundaries of the physical medium on which the page is intended to be displayed or printed.

NextPage As PdfPage (Read-only)

Returns a page immediately following this page in the document. If this is the last page, a new page is added to the end of the document and the newly created instance of the PdfPage object is returned.

Rotate As Long (Read/Write)

Returns or specifies the number of degrees by which the page should be rotated clockwise when displayed or printed. The value must be a multiple of 90.

Thumb As PdfImage (Read/Write)

Specifies an image object defining this page's thumbnail. By default, PDF viewer applications such as Acrobat Reader automatically generate thumbnails from page contents. Use this property to replace the default page thumbnail with your own image.

TrimBox As PdfRect (Read-only)

Returns the page's trim box, which is a rectangle defining the intended dimensions of the finished page after trimming. This property was introduced in Version 2.9.

Width As Single (Read/Write)

Returns or specifies this page's width in default user units.

Function CreateCheckbox(Name As String, Param As Variant, Parent As PdfAnnot) As PdfAnnot

Creates a checkbox form field and places it on the page. Updates PdfDocument's Form collection if this is a top-level form field. Returns an instance of the PdfAnnot object representing this form field.

Name uniquely identifies this form field.

Param is a PdfParam object or parameter string specifying various appearance parameters of the checkbox field, including:

X, Y, Width, Height (required) - specify the form field's location and size on the page.

State (optional) - specifies the initial state of the checkbox. Possible values are: 1 (on) and 0 (off, default).

ReadOnly (optional) - if set to True, the field cannot be changed by the user. False by default.

NoExport (optional) - if set to True, the field's information is not included with the rest of the form items when the form is submitted.

Required (optional) - if set to True, the field must be filled by the user or the form cannot be submitted. False by default. This parameter is not applicable to checkboxes.

Highlight (optional) - specifies the highlight option when the field is clicked on by the user. Possible values: 0 (none), 1 (invert), 2 (outline), 3 (push, default).

FontSize (optional) - font size to be used. 10 by default. Not applicable to checkboxes.

Print (optional) - if set to True, the field will be printed along with the rest of the page. Otherwise, it won't be printed. False by default.

Parent specifies the parent form field. Can be set to Nothing if this is a top-level form field.

For more information on interactive form fields, see Chapter 11 - Forms.

Function CreateChoice(Name As String, Options As String, Selection As String, Param As Variant, Font As PdfFont, Parent As PdfAnnot) As PdfAnnot

Creates a choice form field, such as a list or combo box, and places it on the page. Updates PdfDocument's Form collection if this is a top-level form field. Returns an instance of the PdfAnnot object representing this form field.

Name uniquely identifies this form field.

Options is list of options for this field where the options are separated from each other with ##, for example "Left##Right##Center". Here, the list or combo box will be populated by three options, "Left", "Right" and "Center".

The list may also contain name/value pairs separated by %%. A name is what is displayed on the page, and the value is what gets submitted when this item is selected, for example "Left%%1##Right%%2##Center%%3". Here, the list is still populated by the same three strings, but their underlying values are set to 1, 2, and 3, respectively. This is similar to the HTML block

<SELECT>
<OPTION VALUE="1">Left</OPTION>
<OPTION VALUE="2">Right</OPTION>
<OPTION VALUE="3">Center</OPTION>
</SELECT>

Selection is a string specifying the initial selection, such as "Left". If this is a multi-select form field, the Selection argument may be a ##-separated list of values.

Param is a PdfParam object or parameter string specifying various appearance parameters of the checkbox field, including:

Combo (optional) - if set to True, the field is a combo box, otherwise it is a list box. False by default.

Edit (optional) - if set to True, the combo includes an editable box as well as a drop list, otherwise it only includes a drop list. False by default. This flag is meaningful only if Combo is set to True.

Sort (optional) - if set to True, the items are sorted alphabetically. The flag is intended for use by form authoring tools, not viewer applications. False by default.

MultiSelect (optional) - if set to True, more than one of the field's option items may be selected simultaneously. False by default.

DoNoSpellCheck (optional) - if set to True, disables spell-checking for this field. This flag is meaningful only if both Combo and Edit are set to True. False by default.

Border (optional) - the border width, 0 by default which means no border.

BorderColor (optional) - the border color, black by default.

BgColor (optional) - the background color, transparent by default.

TopIndex (optional) - for scrollable list boxes, the top index of the first option visible in the list.

X, Y, Width, Height, ReadOnly, NoExport, Required, Highlight, FontSize, Print - same as in the CreateCheckbox method described above.

Font specifies the font to be used to draw field items. Can be set to Nothing, "Times-Roman" by default.

Parent specifies the parent form field. Can be set to Nothing if this is a top-level form field.

For more information on interactive form fields, see Chapter 11 - Forms.

Function CreateDest(Optional Param) As PdfDest

Creates a destination associated with this page. Returns an instance of the PdfDest object representing this destination.

Param is a PdfParam object or parameter string specifying various destination creation options. For the detailed description of this method, see Section 10.1 - Destinations.

Function CreatePushbutton(Name As String, Caption As String, Param As Variant, Font As PdfFont, Parent As PdfAnnot) As PdfAnnot

Creates a pushbutton form field and places it on the page. Updates PdfDocument's Form collection if this is a top-level form field. Returns an instance of the PdfAnnot object representing this form field.

Name uniquely identifies this form field.

Caption specifies the text string to be displayed on the button.

Param is a PdfParam object or parameter string specifying various appearance parameters of the pushbutton field, including:

X, Y, Width, Height, ReadOnly, NoExport, Required, Highlight, FontSize, Print - same as in the CreateCheckbox method described above.

Font specifies the font to be used to draw the caption. Can be set to Nothing, "Times-Roman" by default.

Parent specifies the parent form field. Can be set to Nothing if this is a top-level form field.

For more information on interactive form fields, see Chapter 11 - Forms.

Function CreateRadiobutton(Name As String, OptionName As String, Param As Variant, Parent As PdfAnnot) As PdfAnnot

Creates a radio button field. If this is a child radio button, the method places it on the page. A top-level radio button does not have an appearance but serves as a "group manager" for its child radio buttons. Updates PdfDocument's Form collection if this is a top-level form field. Returns an instance of the PdfAnnot object representing this form field.

Name uniquely identifies this form field.

OptionName identifies an individual option within a group of radio buttons. For top-level radio buttons, this argument specifies the option name of a child radio button selected by default (when the form is reset).

Param is a PdfParam object or parameter string specifying various appearance parameters of the radio button field, including:

NoToggleToOff (optional) - if set to True, exactly one radio button must be selected at all times. Clicking the currently selected button has no effect. If set to False, clicking the selected button deselects it, leaving no buttons selected. False by default. Applies to top-level radio buttons only.

State (optional) - specifies the current selection state. Possible values are: 1 (selected), 0 (deselected, default). Applies to child radio buttons only.

X, Y, Width, Height, ReadOnly, NoExport, Required, Highlight, FontSize, Print - same as in the CreateCheckbox method described above.

Parent specifies the parent radio button field. To create a new radio button group, this argument must be set to Nothing. A PdfAnnot object thus created will represent a radio button group with no visual appearance, not an actual radio button. To add a radio button to an existing group, this argument must be set to a PdfAnnot object representing a radio button group.

For more information on interactive form fields, see Chapter 11 - Forms.

Function CreateTextbox(Name As String, Caption As String, Param As Variant, Font As PdfFont, Parent As PdfAnnot) As PdfAnnot

Creates a textbox form field and places it on the page. Updates PdfDocument's Form collection if this is a top-level form field. Returns an instance of the PdfAnnot object representing this form field.

Name uniquely identifies this form field.

Caption specifies the text string to be displayed in the text box.

Param is a PdfParam object or parameter string specifying various appearance parameters of the textbox field, including:

Multiline (optional) - if set to True, the field may contain multiple lines of text.

Password (optional) - if set to True, the field is intended for entering a secure password that should not be echoed visibly on the screen. False by default.

FileSelect (optional) - if set to True, the text entered in the field represents the pathname of a file whose contents are to be submitted as the value of the field. False by default.

DoNotSpellCheck (optional) - if set to True, disables spell-checking for this field. False by default.

DoNotScroll (optional) - if set to True, disables scrolling for this field. False by default.

Alignment (optional) - specifies text alignment. Possible values are: left (0, default), right (1) and center (2).

MaxLen (optional) - specifies the maximum number of characters allowed in the text field.

Border (optional) - the border width, 0 by default which means no border.

BorderColor (optional) - the border color, black by default.

BgColor (optional) - the background color, transparent by default.

Color (optional) - the text color, black by default. This parameter was introduced in Version 3.4.0.1.

X, Y, Width, Height, ReadOnly, NoExport, Required, Highlight, FontSize, Print - same as in the CreateCheckbox method described above.

Font specifies the font to be used to draw the text in the field. Can be set to Nothing, "Times-Roman" by default.

Parent specifies the parent form field. Can be set to Nothing if this is a top-level form field.

For more information on interactive form fields, see Chapter 11 - Forms.

Function ExtractText(Optional Param) As String

Extracts text contents from the page for indexing and searching purposes. Returns the extracted text in Unicode format.

Param is a PdfParam object or parameter string specifying various text extraction options, including:

All (optional) - if set to True, returns all raw contents including text and graphics operators. Useful for debugging or troubleshooting purposes only. False by default.
CodePage (optional) - a code page to be used if the ToUnicode map is not present, when converting text to Unicode. 0 by default which means no conversion will be attempted.

This method is subject to Bit 5 (Copy/extract content) of the document's permission flags. If the document is secure and Bit 5 is cleared, you must open the document with the owner password, not the user password, otherwise this method will throw an error exception.

For more information on this method's parameters and text extraction functionality in general, see Section 9.4 - Content Extraction .

Sub ResetCoordinates()

Resets the current coordinate system of an existing document's page to the defaults. Has no effect if the document is a new one.

This method is useful when drawing text or graphics on top of an existing document which has the default coordinate system modified, causing the new text or graphics to appear inverted, shifted, or scaled. Introduced by Version 1.5.

For more information, see Section 9.3.5 - Coordinate Reset.

Sub SetGroup(Group As PdfGState)

Associates a transparency group with this page object. Group is an instance of the PdfGState object representing a transparency group. This method was introduced in Version 3.1.

For more information, see Section 19.5 - Miscellaneous Features.

Function ToImage(Optional Param) As PdfPreview

Converts the page to an image in PNG format. Returns an instance of the PdfPreview object representing the rasterized image of this page. PdfPreview's methods Save, SaveToMemory and SaveHttp can then be used to save the resultant image to disk, memory or an HTTP stream.

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

ResolutionX, ResolutionY - control the pixel width and height of the resultant image, respectively. By default, the resolutions are 72 (dpi) which makes the pixel dimensions of the resultant image match the width and height (in user units) of the current page. Setting ResolutionX and ResolutionY to values larger (smaller) than 72 increase (decrease) the dimensions of the resultant image proportionally.

Debug - if set to True, enables the creation of the error log accessible via the PdfPreview.Log property. This parameter is useful for debugging and trouble-shooting purposes. False by default.

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 page contains large high-resolution CMYK images and graphics. False by default.

IgnoreRotate - if set to True, ignores the /Rotate attribute of the current page. This may cause a landscape-oriented page to be converted to a portrait-oriented image with the content rotated 90 degrees. False by default.

IgnoreCropBox - if set to True, ignores the /CropBox attribute of the page and uses its /MediaBox attribute instead. This may cause the image to include areas of the page that are normally invisible when viewed in a PDF viewer. False by default.

ExtractText - if set to a non-zero value, enables structured text extraction (text extraction with coordinates) and populates the PdfPreview.TextItems collection. This parameter is a combination (sum) of the following flags:

Bit 1 (1): Enables text extraction. If this flag is not set, text extraction is not performed and the TextItems collection is empty.

Bit 2 (2): Sorts text fragments in the order from top to bottom, and from left to right. If this flag is not set, the text fragments in the TextItems collection appear in an arbitrary order.

Bit 3 (4): Glues adjacent text fragments together. If this flag is not set, a single text fragment may contain a single word, a part of the word or even a single character. Setting this flag usually combines all or most text fragments of a paragraph line into a single long string. For this flag to work, bit 2 must also be set.

Bit 4 (8): Does not glue adjacent text fragments if there is a space character separating them. For this flag to work, flags 2 and 3 must also be set.

0 by default. This parameter was introduced in Version 2.8.

IgnoreObjectNotFound - if set to True, the exception "Object cannot be found" caused by some badly-formed PDF documents is suppressed and the PDF-to-image conversion continues. This parameter was added in Version 3.7. This feature is currently in beta.

For more information, see Chapter 17 - PDF to Image Conversion.

This method was introduced in Version 2.0.

PdfPage Object

Overview

Member List

Properties

Methods