Struct pdfium_render::page::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::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 document(&self) -> &'a PdfDocument<'a>

Returns the PdfDocument containing this PdfPage.

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

Returns the PdfiumLibraryBindings used by the PdfDocument containing 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<PdfBitmapRotation, 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: PdfBitmapRotation)

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 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 render(
    &self,
    width: u16,
    height: u16,
    rotation: Option<PdfBitmapRotation>
) -> 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: u16,
    height: u16,
    rotation: Option<PdfBitmapRotation>
) -> Result<(), PdfiumError>

Renders this PdfPage into the given PdfBitmap using the given 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 flatten(&mut self) -> Result<(), PdfiumError>

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

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, any changes not applied are 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, any changes not applied are 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, any changes not applied are 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.