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 PdfPageProperties
| Name | Description |
|---|---|
| AdditionalActions | Gets the additional actions of the page (/AA, ISO 32000-2, 12.6.3): the actions run when the page is opened and closed. |
| Annotations | Gets the annotations of the page (ISO 32000-2, 12.5). |
| ArtBox | 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. |
| BleedBox | 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. |
| CropBox | 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. |
| Dictionary | Gets the page dictionary. |
| DisplaySize | 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. |
| DisplayToUserSpace | 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. |
| Document | Gets the document of the page. |
| Label | 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. |
| MediaBox | 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. |
| Reference | Gets the reference to the page object. |
| Resources | Gets the resource dictionary of the page, inherited from the page tree, or null when there is none. |
| Rotation | 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. |
| TrimBox | 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. |
| UserSpaceToDisplay | Gets the matrix from the default user space of the page to its display space: the inverse of PdfPage.DisplayToUserSpace. |
| UserUnit | 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. |
AdditionalActions
PdfPage.csGets 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
Annotations
PdfPage.csGets the annotations of the page (ISO 32000-2, 12.5).
public PdfAnnotationCollection Annotations { get; }Property value
ArtBox
PdfPage.csGets 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; }BleedBox
PdfPage.csGets 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; }CropBox
PdfPage.csGets 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; }Dictionary
PdfPage.csDisplaySize
PdfPage.csGets 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
DisplayToUserSpace
PdfPage.csGets 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
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.csLabel
PdfPage.csMediaBox
PdfPage.csGets 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; }Reference
PdfPage.csResources
PdfPage.csGets the resource dictionary of the page, inherited from the page tree, or null when there is none.
public PdfDictionary? Resources { get; }Property value
Rotation
PdfPage.csGets 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; }TrimBox
PdfPage.csGets 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; }UserSpaceToDisplay
PdfPage.csGets 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
UserUnit
PdfPage.csMethods
| Name | Description |
|---|---|
| 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.csAdds 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
textstring- The text.
optionsPdfWatermarkOptions?- The options, or
nullforPdfWatermarkOptions.Default.
Exceptions
ArgumentExceptiontextis 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.csCreates 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.csCreates 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
placementPdfContentPlacementPdfContentPlacement.Overto paint over the content of the page (asPdfPage.CreateContentBuilder),PdfContentPlacement.Underto 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
ArgumentOutOfRangeExceptionplacementis not a value ofPdfContentPlacement.
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.csFinds 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
optionsPdfLayoutOptions?- The options, or
nullforPdfLayoutOptions.Default.
Returns
PdfLayoutPage The layout.
Exceptions
InvalidPdfContentException- A content stream cannot be decoded.
ExtractText overloads
ExtractText()
PdfPage.csExtracts 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.csExtracts the text of the page, in the order of the content, with a line break between the lines.
public string ExtractText(PdfTextExtractionOptions? options)Parameters
optionsPdfTextExtractionOptions?- The options, or
nullforPdfTextExtractionOptions.Default.
Returns
string The text.
Exceptions
PdfResourceLimitException- The content runs more operators and glyphs than the limit (forms that paint forms).
ExtractTextLayout(PdfTextExtractionOptions?)
PdfPage.csExtracts 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
optionsPdfTextExtractionOptions?- The options, or
nullforPdfTextExtractionOptions.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.csFlattens 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
optionsPdfAnnotationFlattenOptions?- The options, or
nullforPdfAnnotationFlattenOptions.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.csGets 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.csGets 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.csRemoves 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
areasIEnumerable<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.
optionsPdfRedactionOptions?- The options, or
nullforPdfRedactionOptions.Default.
Returns
PdfRedactionResult What was removed.
Exceptions
ArgumentNullExceptionareasisnull.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.