Struct PdfPageGroupObject

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

A group of PdfPageObject objects contained in the same PdfPageObjects collection. The page objects contained in the group can be manipulated and transformed together as if they were a single object.

Groups are bound to specific pages in the document. To create an empty group, use either the PdfPageObjects::create_new_group() function or the PdfPageGroupObject::empty() function. To create a populated group, use one of the PdfPageGroupObject::new(), PdfPageGroupObject::from_vec(), or PdfPageGroupObject::from_slice() functions.

Implementations

impl<'a> PdfPageGroupObject<'a>

pub fn empty(page: &'a PdfPage<'_>) -> Self

Creates a new, empty PdfPageGroupObject that can be used to hold any page objects on the given PdfPage.

pub fn new<F>(page: &'a PdfPage<'_>, predicate: F) -> Result<Self, PdfiumError>

where F: FnMut(&PdfPageObject<'_>) -> bool,

Creates a new PdfPageGroupObject that includes any page objects on the given PdfPage matching the given predicate function.

pub fn from_vec( page: &PdfPage<'a>, objects: Vec<PdfPageObject<'a>>, ) -> Result<Self, PdfiumError>

Creates a new PdfPageGroupObject that includes the given page objects on the given PdfPage.

pub fn from_slice( page: &PdfPage<'a>, objects: &mut [PdfPageObject<'a>], ) -> Result<Self, PdfiumError>

Creates a new PdfPageGroupObject that includes the given page objects on the given PdfPage.

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

Returns the PdfiumLibraryBindings used by this group.

pub fn len(&self) -> usize

Returns the number of page objects in this group.

pub fn is_empty(&self) -> bool

Returns true if this group contains no page objects.

pub fn contains(&self, object: &PdfPageObject<'_>) -> bool

Returns true if this group already contains the given page object.

pub fn push( &mut self, object: &mut PdfPageObject<'a>, ) -> Result<(), PdfiumError>

Adds a single PdfPageObject to this group.

pub fn append( &mut self, objects: &mut [PdfPageObject<'a>], ) -> Result<(), PdfiumError>

Adds all the given PdfPageObject objects to this group.

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

Removes every PdfPageObject in this group from the group’s containing PdfPage and from this group, consuming the group.

Each object’s memory ownership will be removed from the PdfPageObjects collection for this group’s containing PdfPage. The objects will also be removed from this group, and the memory owned by each object will be freed.

If the containing PdfPage has a content regeneration strategy of PdfPageContentRegenerationStrategy::AutomaticOnEveryChange then content regeneration will be triggered on the page.

pub fn get( &self, index: PdfPageObjectIndex, ) -> Result<PdfPageObject<'_>, PdfiumError>

Returns a single PdfPageObject from this group.

pub fn retain<F>(&mut self, f: F)

where F: Fn(&PdfPageObject<'_>) -> bool,

Retains only the PdfPageObject objects in this group specified by the given predicate function.

Non-retained objects are only removed from this group. They remain on the source PdfPage that currently contains them.

pub fn retain_if_copyable(&mut self)

👎Deprecated since 0.8.32: This function is no longer relevant, as the PdfPageGroupObject::copy_to_page() function can copy all object types.

Retains only the PdfPageObject objects in this group that can be copied.

Objects that cannot be copied are only removed from this group. They remain on the source PdfPage that currently contains them.

pub fn is_copyable(&self) -> bool

👎Deprecated since 0.8.32: This function is no longer relevant, as the PdfPageGroupObject::copy_to_page() function can copy all object types.

Returns true if all the PdfPageObject objects in this group can be copied.

pub fn try_copy_onto_existing_page<'b>( &self, destination: &mut PdfPage<'b>, ) -> Result<PdfPageGroupObject<'b>, PdfiumError>

👎Deprecated since 0.8.32: This function is no longer relevant, as the PdfPageGroupObject::copy_to_page() function can copy all object types.

Attempts to copy all the PdfPageObject objects in this group, placing the copied objects onto the given existing destination PdfPage.

This function can only copy page objects supported by the PdfPageObjectCommon::try_copy() function. For a different approach that supports more page object types but is more limited in where the copied objects can be placed, see the PdfPageGroupObject::copy_onto_new_page_at_start(), PdfPageGroupObject::copy_onto_new_page_at_end(), and PdfPageGroupObject::copy_onto_new_page_at_index() functions.

If all objects were copied successfully, then a new PdfPageGroupObject containing the clones is returned, allowing the new objects to be manipulated as a group.

pub fn move_to_page(self, page: &mut PdfPage<'_>) -> Result<(), PdfiumError>

Moves the ownership of all the PdfPageObject objects in this group to the given PdfPage, consuming the group. Page content will be regenerated as necessary.

An error will be returned if the destination page is in a different PdfDocument than the source objects. Pdfium only supports safely moving objects within the same document, not across documents.

pub fn move_to_annotation( self, annotation: &mut PdfPageAnnotation<'_>, ) -> Result<(), PdfiumError>

Moves the ownership of all the PdfPageObject objects in this group to the given PdfPageAnnotation, consuming the group. Page content will be regenerated as necessary.

An error will be returned if the destination annotation is in a different PdfDocument than the source objects. Pdfium only supports safely moving objects within the same document, not across documents.

pub fn copy_to_page( &mut self, page: &mut PdfPage<'a>, ) -> Result<PdfPageObject<'a>, PdfiumError>

Copies all the PdfPageObject objects in this group into a new PdfPageXObjectFormObject, then adds the new form object to the page objects collection of the given PdfPage, returning the new form object.

pub fn copy_into_x_object_form_object( &mut self, destination: &mut PdfDocument<'a>, ) -> Result<PdfPageObject<'a>, PdfiumError>

Creates a new PdfPageXObjectFormObject object from the page objects in this group, ready to use in the given destination PdfDocument.

pub fn copy_onto_new_page_at_start( &self, destination: &PdfDocument<'_>, ) -> Result<(), PdfiumError>

👎Deprecated since 0.8.32: This function has been retired in favour of the PdfPageGroupObject::copy_to_page() function.

Copies all the PdfPageObject objects in this group by copying the page containing the objects in this group into a new page at the start of the given destination PdfDocument then removing all objects from the new page not in this group.

This function differs internally from PdfPageGroupObject::try_copy_onto_existing_page() in that it uses Pdfium to copy page objects instead of the PdfPageObjectCommon::try_copy() method provided by pdfium-render. As a result, this function can copy some objects that PdfPageGroupObject::try_copy_onto_existing_page() cannot; for example, it can copy path objects containing Bézier curves. However, it can only copy objects onto a new page, not an existing page, and it cannot return a new PdfPageGroupObject containing the newly created objects.

The new page will have the same size and bounding box configuration as the page containing the objects in this group.

pub fn copy_onto_new_page_at_end( &self, destination: &PdfDocument<'_>, ) -> Result<(), PdfiumError>

👎Deprecated since 0.8.32: This function has been retired in favour of the PdfPageGroupObject::copy_to_page() function.

Copies all the PdfPageObject objects in this group by copying the page containing the objects in this group into a new page at the end of the given destination PdfDocument then removing all objects from the new page not in this group.

This function differs internally from PdfPageGroupObject::try_copy_onto_existing_page() in that it uses Pdfium to copy page objects instead of the PdfPageObjectCommon::try_copy() method provided by pdfium-render. As a result, this function can copy some objects that PdfPageGroupObject::try_copy_onto_existing_page() cannot; for example, it can copy path objects containing Bézier curves. However, it can only copy objects onto a new page, not an existing page, and it cannot return a new PdfPageGroupObject containing the newly created objects.

The new page will have the same size and bounding box configuration as the page containing the objects in this group.

pub fn copy_onto_new_page_at_index( &self, index: PdfPageIndex, destination: &PdfDocument<'_>, ) -> Result<(), PdfiumError>

👎Deprecated since 0.8.32: This function has been retired in favour of the PdfPageGroupObject::copy_to_page() function.

Copies all the PdfPageObject objects in this group by copying the page containing the objects in this group into a new page in the given destination PdfDocument at the given page index, then removing all objects from the new page not in this group.

This function differs internally from PdfPageGroupObject::try_copy_onto_existing_page() in that it uses Pdfium to copy page objects instead of the PdfPageObjectCommon::try_copy() method provided by pdfium-render. As a result, this function can copy some objects that PdfPageGroupObject::try_copy_onto_existing_page() cannot; for example, it can copy path objects containing Bézier curves. However, it can only copy objects onto a new page, not an existing page, and it cannot return a new PdfPageGroupObject containing the newly created objects.

The new page will have the same size and bounding box configuration as the page containing the objects in this group.

pub fn iter(&'a self) -> PdfPageGroupObjectIterator<'a>

Returns an iterator over all the PdfPageObject objects in this group.

pub fn text(&self) -> String

Returns the text contained within all PdfPageTextObject objects in this group.

pub fn text_separated(&self, separator: &str) -> String

Returns the text contained within all PdfPageTextObject objects in this group, separating each text fragment with the given separator.

pub fn has_transparency(&self) -> bool

Returns true if any PdfPageObject in this group contains transparency.

pub fn bounds(&self) -> Result<PdfRect, PdfiumError>

Returns the bounding box of this group of objects. Since the bounds of every object in the group must be considered, this function has runtime complexity of O(n).

pub fn set_blend_mode( &mut self, blend_mode: PdfPageObjectBlendMode, ) -> Result<(), PdfiumError>

Sets the blend mode that will be applied when painting every PdfPageObject in this group.

pub fn set_fill_color( &mut self, fill_color: PdfColor, ) -> Result<(), PdfiumError>

Sets the color of any filled paths in every PdfPageObject in this group.

pub fn set_stroke_color( &mut self, stroke_color: PdfColor, ) -> Result<(), PdfiumError>

Sets the color of any stroked lines in every PdfPageObject in this group.

Even if an object’s path is set with a visible color and a non-zero stroke width, the object’s stroke mode must be set in order for strokes to actually be visible.

pub fn set_stroke_width( &mut self, stroke_width: PdfPoints, ) -> Result<(), PdfiumError>

Sets the width of any stroked lines in every PdfPageObject in this group.

A line width of 0 denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide. However, some devices cannot reproduce 1-pixel lines, and on high-resolution devices, they are nearly invisible. Since the results of rendering such zero-width lines are device-dependent, their use is not recommended.

Even if an object’s path is set with a visible color and a non-zero stroke width, the object’s stroke mode must be set in order for strokes to actually be visible.

pub fn set_line_join( &mut self, line_join: PdfPageObjectLineJoin, ) -> Result<(), PdfiumError>

Sets the line join style that will be used when painting stroked path segments in every PdfPageObject in this group.

pub fn set_line_cap( &mut self, line_cap: PdfPageObjectLineCap, ) -> Result<(), PdfiumError>

Sets the line cap style that will be used when painting stroked path segments in every PdfPageObject in this group.

pub fn set_fill_and_stroke_mode( &mut self, fill_mode: PdfPathFillMode, do_stroke: bool, ) -> Result<(), PdfiumError>

Sets the method used to determine which sub-paths of any path in a PdfPageObject should be filled, and whether or not any path in a PdfPageObject should be stroked, for every PdfPageObject in this group.

Even if an object’s path is set to be stroked, the stroke must be configured with a visible color and a non-zero width in order to actually be visible.

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 every PdfPageObject in this group.

To move, scale, rotate, or skew every PdfPageObject in this group, 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 every PdfPageObject in this group.
• Self::scale(): changes the size of every PdfPageObject in this group.
• every PdfPageObject in this group horizontally around its origin.
• every PdfPageObject in this group vertically around its origin.
• Self::rotate_clockwise_degrees(), Self::rotate_counter_clockwise_degrees(), Self::rotate_clockwise_radians(), Self::rotate_counter_clockwise_radians(): rotates every PdfPageObject in this group around its origin.
• Self::skew_degrees(), Self::skew_radians(): skews every PdfPageObject in this group 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 every PdfPageObject in this group.

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

Resets the transform matrix for every PdfPageObject in this group to the the given PdfMatrix, overriding any previously applied transformations.

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

Resets the transformation matrix for every PdfPageObject in this group to the identity matrix, undoing any previously applied transformations.

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

Moves the origin of every PdfPageObject in this group 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 every PdfPageObject in this group, scaling it by the given horizontal and vertical scale factors.

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

Flips every PdfPageObject in this group horizontally around its origin by applying a horizontal scale factor of -1.

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

Flips every PdfPageObject in this group vertically around its origin by applying a vertical scale factor of -1.

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

Reflects every PdfPageObject in this group by flipping it both horizontally and vertically around its origin.

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

Rotates every PdfPageObject in this group counter-clockwise by the given number of degrees.

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

Rotates every PdfPageObject in this group clockwise by the given number of degrees.

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

Rotates every PdfPageObject in this group counter-clockwise by the given number of radians.

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

Rotates every PdfPageObject in this group 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 every PdfPageObject in this group 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 every PdfPageObject in this group by the given angles in radians.