PdfPage Class

A page of a document (ISO 32000-2, 7.7.3.3). The members read and write the page dictionary; the inheritable entries are looked up in the page tree.

public sealed class PdfPage

Properties

NameDescription
AdditionalActionsGets the additional actions of the page (/AA, ISO 32000-2, 12.6.3): the actions run when the page is opened and closed.
AnnotationsGets the annotations of the page (ISO 32000-2, 12.5).
ArtBoxGets or sets the art box (ISO 32000-2, 14.11.2): the extent of the meaningful content of the page. It is not inherited; the default is the crop box.
BleedBoxGets or sets the bleed box (ISO 32000-2, 14.11.2): the region the content is clipped to in a production environment, which includes the bleed area of the trimmed page. It is not inherited; the default is the crop box.
CropBoxGets or sets the crop box: the region of the page that is displayed or printed. It is inherited from the page tree; the default is the media box.
DictionaryGets the page dictionary.
DisplaySizeGets the size of the page as it is displayed, in 1/72 inch: the visible region (the crop box clipped to the media box) rotated by PdfPage.Rotation and scaled by PdfPage.UserUnit.
DisplayToUserSpaceGets the matrix from the display space of the page to its default user space. In the display space, the origin is the lower-left corner of the page as it is displayed (cropped and rotated), x increases to the right, y upward, and the unit is 1/72 inch.
DocumentGets the document of the page.
LabelGets the label of the page (ISO 32000-2, 12.4.2), such as iii or A-2, or null when the document has no page labels or the page is not in it.
MediaBoxGets or sets the media box: the boundaries of the medium the page is printed on. It is inherited from the page tree; the default is US Letter.
ReferenceGets the reference to the page object.
ResourcesGets the resource dictionary of the page, inherited from the page tree, or null when there is none.
RotationGets or sets the clockwise rotation of the page when it is displayed: 0, 90, 180 or 270 degrees. It is inherited from the page tree.
TrimBoxGets or sets the trim box (ISO 32000-2, 14.11.2): the intended dimensions of the finished page after trimming. It is not inherited; the default is the crop box.
UserSpaceToDisplayGets the matrix from the default user space of the page to its display space: the inverse of PdfPage.DisplayToUserSpace.
UserUnitGets the size of the user space unit in 1/72 inch (ISO 32000-2, 14.11.2). The default is 1, which is also the value of a page whose /UserUnit is not a positive number.

AdditionalActions

PdfPage.cs

Gets the additional actions of the page (/AA, ISO 32000-2, 12.6.3): the actions run when the page is opened and closed.

public PdfAdditionalActions AdditionalActions { get; }

Property value

PdfAdditionalActions

Annotations

PdfPage.cs

Gets the annotations of the page (ISO 32000-2, 12.5).

public PdfAnnotationCollection Annotations { get; }

Gets or sets the art box (ISO 32000-2, 14.11.2): the extent of the meaningful content of the page. It is not inherited; the default is the crop box.

public PdfRectangle ArtBox { get; set; }

Property value

PdfRectangle

Exceptions

ArgumentException
A coordinate of the value is not a finite number.

BleedBox

PdfPage.cs

Gets or sets the bleed box (ISO 32000-2, 14.11.2): the region the content is clipped to in a production environment, which includes the bleed area of the trimmed page. It is not inherited; the default is the crop box.

public PdfRectangle BleedBox { get; set; }

Property value

PdfRectangle

Exceptions

ArgumentException
A coordinate of the value is not a finite number.

CropBox

PdfPage.cs

Gets or sets the crop box: the region of the page that is displayed or printed. It is inherited from the page tree; the default is the media box.

public PdfRectangle CropBox { get; set; }

Property value

PdfRectangle

Exceptions

ArgumentException
A coordinate of the value is not a finite number.

Dictionary

PdfPage.cs

Gets the page dictionary.

public PdfDictionary Dictionary { get; }

Property value

PdfDictionary

DisplaySize

PdfPage.cs

Gets the size of the page as it is displayed, in 1/72 inch: the visible region (the crop box clipped to the media box) rotated by PdfPage.Rotation and scaled by PdfPage.UserUnit.

public PdfSize DisplaySize { get; }

Property value

PdfSize

DisplayToUserSpace

PdfPage.cs

Gets the matrix from the display space of the page to its default user space. In the display space, the origin is the lower-left corner of the page as it is displayed (cropped and rotated), x increases to the right, y upward, and the unit is 1/72 inch.

public PdfMatrix DisplayToUserSpace { get; }

Property value

PdfMatrix

Remarks

Concatenate it to the transformation matrix (PdfContentBuilder.Transform) to draw on a rotated or cropped page as on an upright page of PdfPage.DisplaySize; transform the points of the display, such as the position of a click, with it to get the coordinates of the annotations.

Document

PdfPage.cs

Gets the document of the page.

public PdfDocument Document { get; }

Property value

PdfDocument

Gets the label of the page (ISO 32000-2, 12.4.2), such as iii or A-2, or null when the document has no page labels or the page is not in it.

public string? Label { get; }

Property value

string?

MediaBox

PdfPage.cs

Gets or sets the media box: the boundaries of the medium the page is printed on. It is inherited from the page tree; the default is US Letter.

public PdfRectangle MediaBox { get; set; }

Property value

PdfRectangle

Exceptions

ArgumentException
A coordinate of the value is not a finite number.

Reference

PdfPage.cs

Gets the reference to the page object.

public PdfReference Reference { get; }

Property value

PdfReference

Resources

PdfPage.cs

Gets the resource dictionary of the page, inherited from the page tree, or null when there is none.

public PdfDictionary? Resources { get; }

Property value

PdfDictionary?

Rotation

PdfPage.cs

Gets or sets the clockwise rotation of the page when it is displayed: 0, 90, 180 or 270 degrees. It is inherited from the page tree.

public int Rotation { get; set; }

Property value

int

Exceptions

ArgumentOutOfRangeException
The value is not a multiple of 90.

TrimBox

PdfPage.cs

Gets or sets the trim box (ISO 32000-2, 14.11.2): the intended dimensions of the finished page after trimming. It is not inherited; the default is the crop box.

public PdfRectangle TrimBox { get; set; }

Property value

PdfRectangle

Exceptions

ArgumentException
A coordinate of the value is not a finite number.

UserSpaceToDisplay

PdfPage.cs

Gets the matrix from the default user space of the page to its display space: the inverse of PdfPage.DisplayToUserSpace.

public PdfMatrix UserSpaceToDisplay { get; }

Property value

PdfMatrix

UserUnit

PdfPage.cs

Gets the size of the user space unit in 1/72 inch (ISO 32000-2, 14.11.2). The default is 1, which is also the value of a page whose /UserUnit is not a positive number.

public double UserUnit { get; }

Property value

double

Methods

NameDescription
AddWatermark(string, PdfWatermarkOptions?)Adds a text watermark, such as "DRAFT" or "CONFIDENTIAL", centered on the page as it is displayed (cropped and rotated), as an artifact (14.8.2.2) so that the readers of tagged documents skip it.
CreateContentBuilder()Creates a builder that appends a content stream to the page. When the page already has content, including the content of the builders created before, it is wrapped between q and Q first, so that the new content starts with the default graphics state.
CreateContentBuilder(PdfContentPlacement)Creates a builder that adds a content stream to the page, painted over or under its content. The content of the builder starts with the default graphics state, and does not change the graphics state of the content around it.
ExtractLayout(PdfLayoutOptions?)Finds the layout of the page: its headings, paragraphs, lists, tables and figures, in reading order. A single page has no header nor footer: use PdfDocument.ExtractLayout to find them.
ExtractText()Extracts the text of the page, in the order of the content, with a line break between the lines.
ExtractText(PdfTextExtractionOptions?)Extracts the text of the page, in the order of the content, with a line break between the lines.
ExtractTextLayout(PdfTextExtractionOptions?)Extracts the text of the page with the position of its lines, words and glyphs, in the default user space of the page.
FlattenAnnotations(PdfAnnotationFlattenOptions?)Flattens annotations of the page (ISO 32000-2, 12.5.5): the normal appearance of each one is drawn in the content of the page, then the annotation, its pop-up and the references to it (replies, structure tree, form field) are removed, so that it becomes content that cannot be changed.
GetContentData()Gets the content of the page: its content streams decoded and joined (ISO 32000-2, 7.8.2).
GetImages()Gets the images the content of the page paints (ISO 32000-2, 8.9): the image XObjects, painted by the content or by the forms it paints, and the inline images, in the order they are painted, with the matrix they are painted with. The images of the annotations, of the patterns and of the soft masks are not included.
Redact(IEnumerable<PdfRectangle>, PdfRedactionOptions?)Removes what the page shows in areas: the content is rewritten without the glyphs whose box touches an area (the invisible text included), the subpaths inside an area (the paths that cross one are clipped), and the pixels of the images under an area, in the content of the page and of the forms it paints; the annotations that touch an area are removed, with the values of their form fields. The areas are then painted with PdfRedactionOptions.FillColor.

AddWatermark(string, PdfWatermarkOptions?)

PdfPage.Watermark.cs

Adds a text watermark, such as "DRAFT" or "CONFIDENTIAL", centered on the page as it is displayed (cropped and rotated), as an artifact (14.8.2.2) so that the readers of tagged documents skip it.

public void AddWatermark(string text, PdfWatermarkOptions? options = null)

Parameters

text string
The text.
options PdfWatermarkOptions?
The options, or null for PdfWatermarkOptions.Default.

Exceptions

ArgumentException
text is empty, or a character has no glyph in the font.
ArgumentOutOfRangeException
The opacity is not between 0 and 1, or the font size is not a positive number.

Remarks

The text is drawn once in a form XObject. PdfDocument.AddWatermark adds the same form to every page. The watermark is content of the page: its text is extracted with the text of the page.

CreateContentBuilder overloads

CreateContentBuilder()

PdfPage.cs

Creates a builder that appends a content stream to the page. When the page already has content, including the content of the builders created before, it is wrapped between q and Q first, so that the new content starts with the default graphics state.

public PdfContentBuilder CreateContentBuilder()
Returns

PdfContentBuilder The builder.

Remarks

The isolation relies on the content of each builder being balanced: call PdfContentBuilder.Complete to check it. The resources the builder adds go to a resource dictionary of the page itself: the resources the page shares with other pages (an indirect dictionary, or a category of the page tree) are copied first, so that the other pages do not change.

CreateContentBuilder(PdfContentPlacement)

PdfPage.cs

Creates a builder that adds a content stream to the page, painted over or under its content. The content of the builder starts with the default graphics state, and does not change the graphics state of the content around it.

public PdfContentBuilder CreateContentBuilder(PdfContentPlacement placement)
Parameters
placement PdfContentPlacement
PdfContentPlacement.Over to paint over the content of the page (as PdfPage.CreateContentBuilder), PdfContentPlacement.Under to paint under it, such as a background or a watermark that the content covers. The content of each new builder under the page is painted under the content of the builders created before.
Returns

PdfContentBuilder The builder.

Exceptions
ArgumentOutOfRangeException
placement is not a value of PdfContentPlacement.
Remarks

The isolation relies on the content of each builder being balanced: call PdfContentBuilder.Complete to check it. The resources the builder adds go to a resource dictionary of the page itself, as with PdfPage.CreateContentBuilder.

ExtractLayout(PdfLayoutOptions?)

PdfPage.Layout.cs

Finds the layout of the page: its headings, paragraphs, lists, tables and figures, in reading order. A single page has no header nor footer: use PdfDocument.ExtractLayout to find them.

public PdfLayoutPage ExtractLayout(PdfLayoutOptions? options = null)

Parameters

options PdfLayoutOptions?
The options, or null for PdfLayoutOptions.Default.

Returns

PdfLayoutPage The layout.

Exceptions

InvalidPdfContentException
A content stream cannot be decoded.

ExtractText overloads

ExtractText()

PdfPage.cs

Extracts the text of the page, in the order of the content, with a line break between the lines.

public string ExtractText()
Returns

string The text.

Exceptions
PdfResourceLimitException
The content runs more operators and glyphs than the limit (forms that paint forms).

ExtractText(PdfTextExtractionOptions?)

PdfPage.cs

Extracts the text of the page, in the order of the content, with a line break between the lines.

public string ExtractText(PdfTextExtractionOptions? options)
Parameters
options PdfTextExtractionOptions?
The options, or null for PdfTextExtractionOptions.Default.
Returns

string The text.

Exceptions
PdfResourceLimitException
The content runs more operators and glyphs than the limit (forms that paint forms).

ExtractTextLayout(PdfTextExtractionOptions?)

PdfPage.cs

Extracts the text of the page with the position of its lines, words and glyphs, in the default user space of the page.

public PdfTextLayout ExtractTextLayout(PdfTextExtractionOptions? options = null)

Parameters

options PdfTextExtractionOptions?
The options, or null for PdfTextExtractionOptions.Default.

Returns

PdfTextLayout The lines of the page; its PdfTextLayout.Text is the result of PdfPage.ExtractText.

Exceptions

PdfResourceLimitException
The content runs more operators and glyphs than the limit (forms that paint forms).

FlattenAnnotations(PdfAnnotationFlattenOptions?)

PdfPage.Annotations.cs

Flattens annotations of the page (ISO 32000-2, 12.5.5): the normal appearance of each one is drawn in the content of the page, then the annotation, its pop-up and the references to it (replies, structure tree, form field) are removed, so that it becomes content that cannot be changed.

public int FlattenAnnotations(PdfAnnotationFlattenOptions? options = null)

Parameters

options PdfAnnotationFlattenOptions?
The options, or null for PdfAnnotationFlattenOptions.Default.

Returns

int The number of annotations flattened, the pop-ups left out.

Remarks

An annotation without an appearance gets the one PdfAnnotation.UpdateAppearance draws; when the library does not draw its type, it is removed without being drawn. The appearance is drawn with the opacity (/CA) and in the optional content (/OC) of the annotation, without the effect of the PdfAnnotationFlags.NoZoom and PdfAnnotationFlags.NoRotate flags. To flatten the form fields with their values, use PdfInteractiveForm.Flatten.

GetContentData()

PdfPage.cs

Gets the content of the page: its content streams decoded and joined (ISO 32000-2, 7.8.2).

public byte[] GetContentData()

Returns

byte[] The content.

GetImages()

PdfPage.cs

Gets the images the content of the page paints (ISO 32000-2, 8.9): the image XObjects, painted by the content or by the forms it paints, and the inline images, in the order they are painted, with the matrix they are painted with. The images of the annotations, of the patterns and of the soft masks are not included.

public IReadOnlyList<PdfImageOccurrence> GetImages()

Returns

IReadOnlyList<PdfImageOccurrence> The images.

Exceptions

InvalidPdfContentException
A content stream cannot be decoded.

Redact(IEnumerable<PdfRectangle>, PdfRedactionOptions?)

PdfPage.Redaction.cs

Removes what the page shows in areas: the content is rewritten without the glyphs whose box touches an area (the invisible text included), the subpaths inside an area (the paths that cross one are clipped), and the pixels of the images under an area, in the content of the page and of the forms it paints; the annotations that touch an area are removed, with the values of their form fields. The areas are then painted with PdfRedactionOptions.FillColor.

public PdfRedactionResult Redact(IEnumerable<PdfRectangle> areas, PdfRedactionOptions? options = null)

Parameters

areas IEnumerable<PdfRectangle>
The areas, in the default user space of the page (points, from the lower-left corner of the media box). The empty areas are ignored.
options PdfRedactionOptions?
The options, or null for PdfRedactionOptions.Default.

Returns

PdfRedactionResult What was removed.

Exceptions

ArgumentNullException
areas is null.
InvalidPdfContentException
A content stream, or an image the areas touch, cannot be decoded.
UnsupportedPdfFeatureException
An image the areas touch uses a feature the library does not support.
PdfResourceLimitException
The content runs more operators and glyphs than the limit, or its forms are nested too deep.
InvalidOperationException
No object number is left for the new content: the file uses the highest numbers (see PdfIndirectObjectCollection.Add).

Remarks

The removed content is no longer referenced by the page, so a full save (PdfDocument.Save) does not write it. The document cannot be saved incrementally anymore: the original bytes an incremental update keeps contain what was removed.

The glyphs kept stay in place: the displacement of a removed glyph is replaced by a number of a TJ array. A form XObject or an image the areas touch is replaced on this page by a redacted copy, so that the other pages that paint it are unchanged. A redacted image is stored again in sRGB (as JPEG when it was JPEG), with the erased pixels transparent. The replacement texts, alternate descriptions and expansions of the marked-content sequences that lose content are removed. The content of patterns, soft masks, Type 3 glyphs and the appearances of the annotations that are kept is not changed.

The page is not changed when the method throws.