Struct PdfPage

pub struct PdfPage<'a> { /* private fields */ }

A single page in a PdfDocument.

In addition to its own intrinsic properties, a PdfPage serves as the entry point to all object collections related to a single page in a document. These collections include:

• PdfPage::annotations(), an immutable collection of all the user annotations attached to the PdfPage.
• PdfPage::annotations_mut(), a mutable collection of all the user annotations attached to the PdfPage.
• PdfPage::boundaries(), an immutable collection of the boundary boxes relating to the PdfPage.
• PdfPage::boundaries_mut(), a mutable collection of the boundary boxes relating to the PdfPage.
• PdfPage::links(), an immutable collection of the links on the PdfPage.
• PdfPage::links_mut(), a mutable collection of the links on the PdfPage.
• PdfPage::objects(), an immutable collection of all the displayable objects on the PdfPage.
• PdfPage::objects_mut(), a mutable collection of all the displayable objects on the PdfPage.

Implementations

impl<'a> PdfPage<'a>

pub fn bindings(&self) -> &'a dyn PdfiumLibraryBindings

Returns the PdfiumLibraryBindings used by this PdfPage.

pub fn label(&self) -> Option<&str>

Returns the label assigned to this PdfPage, if any.

pub fn width(&self) -> PdfPoints

Returns the width of this PdfPage in device-independent points. One point is 1/72 inches, roughly 0.358 mm.

pub fn height(&self) -> PdfPoints

Returns the height of this PdfPage in device-independent points. One point is 1/72 inches, roughly 0.358 mm.

pub fn page_size(&self) -> PdfRect

Returns the width and height of this PdfPage expressed as a PdfRect.

pub fn orientation(&self) -> PdfPageOrientation

Returns PdfPageOrientation::Landscape if the width of this PdfPage is greater than its height; otherwise returns PdfPageOrientation::Portrait.

pub fn is_portrait(&self) -> bool

Returns true if this PdfPage has orientation PdfPageOrientation::Portrait.

pub fn is_landscape(&self) -> bool

Returns true if this PdfPage has orientation PdfPageOrientation::Landscape.

pub fn rotation(&self) -> Result<PdfPageRenderRotation, PdfiumError>

Returns any intrinsic rotation encoded into this document indicating a rotation should be applied to this PdfPage during rendering.

pub fn set_rotation(&mut self, rotation: PdfPageRenderRotation)

Sets the intrinsic rotation that should be applied to this PdfPage during rendering.

pub fn has_transparency(&self) -> bool

Returns true if any object on the page contains transparency.

pub fn paper_size(&self) -> PdfPagePaperSize

Returns the paper size of this PdfPage.

pub fn has_embedded_thumbnail(&self) -> bool

Returns true if this PdfPage contains an embedded thumbnail.

Embedded thumbnails can be generated as a courtesy by PDF generators to save PDF consumers the burden of having to render their own thumbnails on the fly. If a thumbnail for this page was not embedded at the time the document was created, one can easily be rendered using the standard rendering functions:

    let thumbnail_desired_pixel_size = 128;

    let thumbnail = page.render_with_config(
        &PdfRenderConfig::thumbnail(thumbnail_desired_pixel_size)
    )?; // Renders a 128 x 128 thumbnail of the page

pub fn embedded_thumbnail(&self) -> Result<PdfBitmap<'_>, PdfiumError>

Returns the embedded thumbnail for this PdfPage, if any.

Embedded thumbnails can be generated as a courtesy by PDF generators to save PDF consumers the burden of having to render their own thumbnails on the fly. If a thumbnail for this page was not embedded at the time the document was created, one can easily be rendered using the standard rendering functions:

    let thumbnail_desired_pixel_size = 128;

    let thumbnail = page.render_with_config(
        &PdfRenderConfig::thumbnail(thumbnail_desired_pixel_size)
    )?; // Renders a 128 x 128 thumbnail of the page

pub fn text(&self) -> Result<PdfPageText<'_>, PdfiumError>

Returns the collection of text boxes contained within this PdfPage.

pub fn annotations(&self) -> &PdfPageAnnotations<'a>

Returns an immutable collection of the annotations that have been added to this PdfPage.

pub fn annotations_mut(&mut self) -> &mut PdfPageAnnotations<'a>

Returns a mutable collection of the annotations that have been added to this PdfPage.

pub fn boundaries(&self) -> &PdfPageBoundaries<'a>

Returns an immutable collection of the bounding boxes defining the extents of this PdfPage.

pub fn boundaries_mut(&mut self) -> &mut PdfPageBoundaries<'a>

Returns a mutable collection of the bounding boxes defining the extents of this PdfPage.

pub fn links(&self) -> &PdfPageLinks<'a>

Returns an immutable collection of the links on this PdfPage.

pub fn links_mut(&mut self) -> &mut PdfPageLinks<'a>

Returns a mutable collection of the links on this PdfPage.

pub fn objects(&self) -> &PdfPageObjects<'a>

Returns an immutable collection of all the page objects on this PdfPage.

pub fn objects_mut(&mut self) -> &mut PdfPageObjects<'a>

Returns a mutable collection of all the page objects on this PdfPage.

pub fn fonts(&self) -> Vec<PdfFont<'_>>

Returns a list of all the distinct PdfFont instances used by the page text objects on this PdfPage, if any.

pub fn pixels_to_points( &self, x: Pixels, y: Pixels, config: &PdfRenderConfig, ) -> Result<(PdfPoints, PdfPoints), PdfiumError>

Converts from a bitmap coordinate system, measured in Pixels and with constraints and dimensions determined by the given PdfRenderConfig object, to the equivalent position on this page, measured in PdfPoints.

pub fn points_to_pixels( &self, x: PdfPoints, y: PdfPoints, config: &PdfRenderConfig, ) -> Result<(Pixels, Pixels), PdfiumError>

Converts from the page coordinate system, measured in PdfPoints, to the equivalent position in a bitmap coordinate system measured in Pixels and with constraints and dimensions defined by the given PdfRenderConfig object.

pub fn render( &self, width: Pixels, height: Pixels, rotation: Option<PdfPageRenderRotation>, ) -> Result<PdfBitmap<'_>, PdfiumError>

Renders this PdfPage into a PdfBitmap with the given pixel dimensions and page rotation.

It is the responsibility of the caller to ensure the given pixel width and height correctly maintain the page’s aspect ratio.

See also PdfPage::render_with_config(), which calculates the correct pixel dimensions, rotation settings, and rendering options to apply from a PdfRenderConfig object.

Each call to PdfPage::render() creates a new PdfBitmap object and allocates memory for it. To avoid repeated allocations, create a single PdfBitmap object using PdfBitmap::empty() and reuse it across multiple calls to PdfPage::render_into_bitmap().

pub fn render_with_config( &self, config: &PdfRenderConfig, ) -> Result<PdfBitmap<'_>, PdfiumError>

Renders this PdfPage into a new PdfBitmap using pixel dimensions, page rotation settings, and rendering options configured in the given PdfRenderConfig.

Each call to PdfPage::render_with_config() creates a new PdfBitmap object and allocates memory for it. To avoid repeated allocations, create a single PdfBitmap object using PdfBitmap::empty() and reuse it across multiple calls to PdfPage::render_into_bitmap_with_config().

pub fn render_into_bitmap( &self, bitmap: &mut PdfBitmap<'_>, width: Pixels, height: Pixels, rotation: Option<PdfPageRenderRotation>, ) -> Result<(), PdfiumError>

Renders this PdfPage into the given PdfBitmap using the given pixel dimensions and page rotation.

It is the responsibility of the caller to ensure the given pixel width and height correctly maintain the page’s aspect ratio. The size of the buffer backing the given bitmap must be sufficiently large to hold the rendered image or an error will be returned.

See also PdfPage::render_into_bitmap_with_config(), which calculates the correct pixel dimensions, rotation settings, and rendering options to apply from a PdfRenderConfig object.

pub fn render_into_bitmap_with_config( &self, bitmap: &mut PdfBitmap<'_>, config: &PdfRenderConfig, ) -> Result<(), PdfiumError>

Renders this PdfPage into the given PdfBitmap using pixel dimensions, page rotation settings, and rendering options configured in the given PdfRenderConfig.

The size of the buffer backing the given bitmap must be sufficiently large to hold the rendered image or an error will be returned.

pub fn transform_with_clip( &mut self, a: PdfMatrixValue, b: PdfMatrixValue, c: PdfMatrixValue, d: PdfMatrixValue, e: PdfMatrixValue, f: PdfMatrixValue, clip: PdfRect, ) -> Result<(), PdfiumError>

Applies the given transformation, expressed as six values representing the six configurable elements of a nine-element 3x3 PDF transformation matrix, to the objects on this PdfPage, restricting the effects of the transformation to the given clipping rectangle.

To move, scale, rotate, or skew the objects on this PdfPage, consider using one or more of the following functions. Internally they all use PdfPage::transform(), but are probably easier to use (and certainly clearer in their intent) in most situations.

• PdfPage::translate(): changes the position of each object on this PdfPage.
• PdfPage::scale(): changes the size of each object on this PdfPage.
• PdfPage::flip_horizontally(): flips each object on this PdfPage horizontally around the page origin point.
• PdfPage::flip_vertically(): flips each object on this PdfPage vertically around the page origin point.
• PdfPage::rotate_clockwise_degrees(), PdfPage::rotate_counter_clockwise_degrees(), PdfPage::rotate_clockwise_radians(), PdfPage::rotate_counter_clockwise_radians(): rotates each object on this PdfPage around its origin.
• PdfPage::skew_degrees(), PdfPage::skew_radians(): skews each object on this PdfPage relative to its axes.

The order in which transformations are applied is significant. For example, the result of rotating then translating an object may be vastly different from translating then rotating the same object.

An overview of PDF transformation matrices can be found in the PDF Reference Manual version 1.7 on page 204; a detailed description can be found in section 4.2.3 on page 207.

pub fn apply_matrix_with_clip( &mut self, matrix: PdfMatrix, clip: PdfRect, ) -> Result<(), PdfiumError>

Applies the given transformation, expressed as a PdfMatrix, to this PdfPage, restricting the effects of the transformation matrix to the given clipping rectangle.

pub fn transform( &mut self, a: PdfMatrixValue, b: PdfMatrixValue, c: PdfMatrixValue, d: PdfMatrixValue, e: PdfMatrixValue, f: PdfMatrixValue, ) -> Result<(), PdfiumError>

Applies the given transformation, expressed as six values representing the six configurable elements of a nine-element 3x3 PDF transformation matrix, to each object on this PdfPage.

To move, scale, rotate, or skew each object on this PdfPage, consider using one or more of the following functions. Internally they all use Self::transform(), but are probably easier to use (and certainly clearer in their intent) in most situations.

• Self::translate(): changes the position of each object on this PdfPage.
• Self::scale(): changes the size of each object on this PdfPage.
• each object on this PdfPage horizontally around its origin.
• each object on this PdfPage vertically around its origin.
• Self::rotate_clockwise_degrees(), Self::rotate_counter_clockwise_degrees(), Self::rotate_clockwise_radians(), Self::rotate_counter_clockwise_radians(): rotates each object on this PdfPage around its origin.
• Self::skew_degrees(), Self::skew_radians(): skews each object on this PdfPage relative to its axes.

The order in which transformations are applied is significant. For example, the result of rotating then translating an object may be vastly different from translating then rotating the same object.

An overview of PDF transformation matrices can be found in the PDF Reference Manual version 1.7 on page 204; a detailed description can be found in section 4.2.3 on page 207.

pub fn apply_matrix(&mut self, matrix: PdfMatrix) -> Result<(), PdfiumError>

Applies the given transformation, expressed as a PdfMatrix, to each object on this PdfPage.

pub fn translate( &mut self, delta_x: PdfPoints, delta_y: PdfPoints, ) -> Result<(), PdfiumError>

Moves the origin of each object on this PdfPage by the given horizontal and vertical delta distances.

pub fn scale( &mut self, horizontal_scale_factor: PdfMatrixValue, vertical_scale_factor: PdfMatrixValue, ) -> Result<(), PdfiumError>

Changes the size of each object on this PdfPage, scaling it by the given horizontal and vertical scale factors.

pub fn flip_horizontally(&mut self) -> Result<(), PdfiumError>

Flips each object on this PdfPage horizontally around its origin by applying a horizontal scale factor of -1.

pub fn flip_vertically(&mut self) -> Result<(), PdfiumError>

Flips each object on this PdfPage vertically around its origin by applying a vertical scale factor of -1.

pub fn reflect(&mut self) -> Result<(), PdfiumError>

Reflects each object on this PdfPage by flipping it both horizontally and vertically around its origin.

pub fn rotate_counter_clockwise_degrees( &mut self, degrees: PdfMatrixValue, ) -> Result<(), PdfiumError>

Rotates each object on this PdfPage counter-clockwise by the given number of degrees.

pub fn rotate_clockwise_degrees( &mut self, degrees: PdfMatrixValue, ) -> Result<(), PdfiumError>

Rotates each object on this PdfPage clockwise by the given number of degrees.

pub fn rotate_counter_clockwise_radians( &mut self, radians: PdfMatrixValue, ) -> Result<(), PdfiumError>

Rotates each object on this PdfPage counter-clockwise by the given number of radians.

pub fn rotate_clockwise_radians( &mut self, radians: PdfMatrixValue, ) -> Result<(), PdfiumError>

Rotates each object on this PdfPage clockwise by the given number of radians.

pub fn skew_degrees( &mut self, x_axis_skew: PdfMatrixValue, y_axis_skew: PdfMatrixValue, ) -> Result<(), PdfiumError>

Skews the axes of each object on this PdfPage by the given angles in degrees.

pub fn skew_radians( &mut self, x_axis_skew: PdfMatrixValue, y_axis_skew: PdfMatrixValue, ) -> Result<(), PdfiumError>

Skews the axes of each object on this PdfPage by the given angles in radians.

pub fn flatten(&mut self) -> Result<(), PdfiumError>

Flattens all annotations and form fields on this PdfPage into the page contents.

pub fn delete(self) -> Result<(), PdfiumError>

Deletes this PdfPage from its containing PdfPages collection, consuming this PdfPage.

pub fn content_regeneration_strategy( &self, ) -> PdfPageContentRegenerationStrategy

Returns the strategy used by pdfium-render to regenerate the content of a PdfPage.

Updates to a PdfPage are not committed to the underlying PdfDocument until the page’s content is regenerated. If a page is reloaded or closed without regenerating the page’s content, all uncommitted changes will be lost.

By default, pdfium-render will trigger content regeneration on any change to a PdfPage; this removes the possibility of data loss, and ensures changes can be read back from other data structures as soon as they are made. However, if many changes are made to a page at once, then regenerating the content after every change is inefficient; it is faster to stage all changes first, then regenerate the page’s content just once. In this case, changing the content regeneration strategy for a PdfPage can improve performance, but you must be careful not to forget to commit your changes before closing or reloading the page.

pub fn set_content_regeneration_strategy( &mut self, strategy: PdfPageContentRegenerationStrategy, )

Sets the strategy used by pdfium-render to regenerate the content of a PdfPage.

Updates to a PdfPage are not committed to the underlying PdfDocument until the page’s content is regenerated. If a page is reloaded or closed without regenerating the page’s content, all uncommitted changes will be lost.

By default, pdfium-render will trigger content regeneration on any change to a PdfPage; this removes the possibility of data loss, and ensures changes can be read back from other data structures as soon as they are made. However, if many changes are made to a page at once, then regenerating the content after every change is inefficient; it is faster to stage all changes first, then regenerate the page’s content just once. In this case, changing the content regeneration strategy for a PdfPage can improve performance, but you must be careful not to forget to commit your changes before closing or reloading the page.

pub fn regenerate_content(&mut self) -> Result<(), PdfiumError>

Commits any staged but unsaved changes to this PdfPage to the underlying PdfDocument.

Updates to a PdfPage are not committed to the underlying PdfDocument until the page’s content is regenerated. If a page is reloaded or closed without regenerating the page’s content, all uncommitted changes will be lost.

By default, pdfium-render will trigger content regeneration on any change to a PdfPage; this removes the possibility of data loss, and ensures changes can be read back from other data structures as soon as they are made. However, if many changes are made to a page at once, then regenerating the content after every change is inefficient; it is faster to stage all changes first, then regenerate the page’s content just once. In this case, changing the content regeneration strategy for a PdfPage can improve performance, but you must be careful not to forget to commit your changes before closing or reloading the page.

Trait Implementations

impl<'a> Drop for PdfPage<'a>

fn drop(&mut self)

Closes this PdfPage, releasing held memory.