Struct PdfPagePathObject 

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

A single PdfPageObject of type PdfPageObjectType::Path. The page object defines a path.

Paths define shapes, trajectories, and regions of all sorts. They are used to draw lines, define the shapes of filled areas, and specify boundaries for clipping other graphics. A path is composed of one or more path segments, each specifying a straight or curved line segment. Each segment may connect to one another, forming a closed sub-path, or may be disconnected from one another, forming one or more open sub-paths. A path therefore is made up of one or more disconnected sub-paths, each comprising a sequence of connected segments. Closed sub-paths can be filled; both closed and open sub-paths can be stroked. The topology of the path is unrestricted; it may be concave or convex, may contain multiple sub-paths representing disjoint areas, and may intersect itself in arbitrary ways.

Page objects can be created either attached to a PdfPage (in which case the page object’s memory is owned by the containing page) or detached from any page (in which case the page object’s memory is owned by the object). Page objects are not rendered until they are attached to a page; page objects that are never attached to a page will be lost when they fall out of scope.

The simplest way to create a path object that is immediately attached to a page is to call one of the PdfPageObjects::create_path_object_*() functions to create lines, cubic Bézier curves, rectangles, circles, and ellipses. Alternatively you can create a detached path object using one of the following functions, but you must add the object to a containing PdfPageObjects collection manually.

• PdfPagePathObject::new(): creates an empty detached path object. Segments can be added to the path by sequentially calling one or more of the PdfPagePathObject::move_to(), PdfPagePathObject::line_to(), or PdfPagePathObject::bezier_to() functions. A closed sub-path can be created by calling the PdfPagePathObject::close_path() function. Convenience functions for adding rectangles, circles, and ellipses are also available with the PdfPagePathObject::rect_to(), PdfPagePathObject::circle_to(), and PdfPagePathObject::ellipse_to() functions, which create the desired shapes by constructing closed sub-paths from other path segments.
• PdfPagePathObject::new_line(): creates a detached path object initialized with a single straight line.
• PdfPagePathObject::new_bezier(): creates a detached path object initialized with a single cubic Bézier curve.
• PdfPagePathObject::new_rect(): creates a detached path object initialized with a rectangular path.
• PdfPagePathObject::new_circle(): creates a detached path object initialized with a circular path, filling the given rectangle.
• PdfPagePathObject::new_circle_at(): creates a detached path object initialized with a circular path, centered at a particular origin point with a given radius.
• PdfPagePathObject::new_ellipse(): creates a detached path object initialized with an elliptical path, filling the given rectangle.
• PdfPagePathObject::new_ellipse_at(): creates a detached path object initialized with an elliptical path, centered at a particular origin point with given horizontal and vertical radii.

The detached path object can later be attached to a page by calling the PdfPageObjectsCommon::add_path_object() function.

Implementations

impl<'a> PdfPagePathObject<'a>

pub fn new( document: &PdfDocument<'a>, x: PdfPoints, y: PdfPoints, stroke_color: Option<PdfColor>, stroke_width: Option<PdfPoints>, fill_color: Option<PdfColor>, ) -> Result<Self, PdfiumError>

Creates a new PdfPagePathObject from the given arguments. The returned page object will not be rendered until it is added to a PdfPage using the PdfPageObjectsCommon::add_path_object() function.

The new path will be created with the given initial position and with the given fill and stroke settings applied. Both the stroke color and the stroke width must be provided for the path to be stroked.

Other than setting the initial position, this path will be empty. Add additional segments to this path by calling one or more of the PdfPagePathObject::move_to(), PdfPagePathObject::line_to(), or PdfPagePathObject::bezier_to() functions. A closed sub-path can be created by calling the PdfPagePathObject::close_path() function. Convenience functions for adding rectangles, circles, and ellipses are also available with the PdfPagePathObject::rect_to(), PdfPagePathObject::circle_to(), and PdfPagePathObject::ellipse_to() functions, which create the desired shapes by constructing closed sub-paths from other path segments.

pub fn new_line( document: &PdfDocument<'a>, x1: PdfPoints, y1: PdfPoints, x2: PdfPoints, y2: PdfPoints, stroke_color: PdfColor, stroke_width: PdfPoints, ) -> Result<Self, PdfiumError>

Creates a new PdfPagePathObject from the given arguments. The returned page object will not be rendered until it is added to a PdfPage using the PdfPageObjectsCommon::add_path_object() function.

The new path will be created with a line with the given start and end coordinates, and with the given stroke settings applied.

pub fn new_bezier( document: &PdfDocument<'a>, x1: PdfPoints, y1: PdfPoints, x2: PdfPoints, y2: PdfPoints, control1_x: PdfPoints, control1_y: PdfPoints, control2_x: PdfPoints, control2_y: PdfPoints, stroke_color: PdfColor, stroke_width: PdfPoints, ) -> Result<Self, PdfiumError>

Creates a new PdfPagePathObject from the given arguments. The returned page object will not be rendered until it is added to a PdfPage using the PdfPageObjectsCommon::add_path_object() function.

The new path will be created with a cubic Bézier curve with the given start, end, and control point coordinates, and with the given stroke settings applied.

pub fn new_rect( document: &PdfDocument<'a>, rect: PdfRect, stroke_color: Option<PdfColor>, stroke_width: Option<PdfPoints>, fill_color: Option<PdfColor>, ) -> Result<Self, PdfiumError>

Creates a new PdfPagePathObject from the given arguments. The returned page object will not be rendered until it is added to a PdfPage using the PdfPageObjectsCommon::add_path_object() function.

The new path will be created with a path for the given rectangle, with the given fill and stroke settings applied. Both the stroke color and the stroke width must be provided for the rectangle to be stroked.

pub fn new_circle( document: &PdfDocument<'a>, rect: PdfRect, stroke_color: Option<PdfColor>, stroke_width: Option<PdfPoints>, fill_color: Option<PdfColor>, ) -> Result<Self, PdfiumError>

Creates a new PdfPagePathObject from the given arguments. The returned page object will not be rendered until it is added to a PdfPage using the PdfPageObjectsCommon::add_path_object() function.

The new path will be created with a circle that fills the given rectangle, with the given fill and stroke settings applied. Both the stroke color and the stroke width must be provided for the circle to be stroked.

pub fn new_circle_at( document: &PdfDocument<'a>, center_x: PdfPoints, center_y: PdfPoints, radius: PdfPoints, stroke_color: Option<PdfColor>, stroke_width: Option<PdfPoints>, fill_color: Option<PdfColor>, ) -> Result<Self, PdfiumError>

Creates a new PdfPagePathObject from the given arguments. The returned page object will not be rendered until it is added to a PdfPage using the PdfPageObjectsCommon::add_path_object() function.

The new path will be created with a circle centered at the given coordinates, with the given radius, and with the given fill and stroke settings applied. Both the stroke color and the stroke width must be provided for the circle to be stroked.

pub fn new_ellipse( document: &PdfDocument<'a>, rect: PdfRect, stroke_color: Option<PdfColor>, stroke_width: Option<PdfPoints>, fill_color: Option<PdfColor>, ) -> Result<Self, PdfiumError>

Creates a new PdfPagePathObject from the given arguments. The returned page object will not be rendered until it is added to a PdfPage using the PdfPageObjectsCommon::add_path_object() function.

The new path will be created with an ellipse that fills the given rectangle, with the given fill and stroke settings applied. Both the stroke color and the stroke width must be provided for the ellipse to be stroked.

pub fn new_ellipse_at( document: &PdfDocument<'a>, center_x: PdfPoints, center_y: PdfPoints, x_radius: PdfPoints, y_radius: PdfPoints, stroke_color: Option<PdfColor>, stroke_width: Option<PdfPoints>, fill_color: Option<PdfColor>, ) -> Result<Self, PdfiumError>

Creates a new PdfPagePathObject from the given arguments. The returned page object will not be rendered until it is added to a PdfPage using the PdfPageObjectsCommon::add_path_object() function.

The new path will be created with an ellipse centered at the given coordinates, with the given horizontal and vertical radii, and with the given fill and stroke settings applied. Both the stroke color and the stroke width must be provided for the ellipse to be stroked.

pub fn move_to(&mut self, x: PdfPoints, y: PdfPoints) -> Result<(), PdfiumError>

Begins a new sub-path in this PdfPagePathObject by moving the current point to the given coordinates, omitting any connecting line segment.

pub fn line_to(&mut self, x: PdfPoints, y: PdfPoints) -> Result<(), PdfiumError>

Appends a straight line segment to this PdfPagePathObject from the current point to the given coordinates. The new current point is set to the given coordinates.

pub fn bezier_to( &mut self, x: PdfPoints, y: PdfPoints, control1_x: PdfPoints, control1_y: PdfPoints, control2_x: PdfPoints, control2_y: PdfPoints, ) -> Result<(), PdfiumError>

Appends a cubic Bézier curve to this PdfPagePathObject from the current point to the given coordinates, using the two given Bézier control points. The new current point is set to the given coordinates.

pub fn rect_to(&mut self, x: PdfPoints, y: PdfPoints) -> Result<(), PdfiumError>

Appends a rectangle to this PdfPagePathObject by drawing four line segments from the current point, ending at the given coordinates. The current sub-path will be closed. The new current point is set to the given coordinates.

pub fn ellipse_to( &mut self, x: PdfPoints, y: PdfPoints, ) -> Result<(), PdfiumError>

Appends an ellipse to this PdfPagePathObject by drawing four Bézier curves approximating an ellipse filling a rectangle from the current point to the given coordinates. The current sub-path will be closed. The new current point is set to the given coordinates.

pub fn circle_to( &mut self, x: PdfPoints, y: PdfPoints, ) -> Result<(), PdfiumError>

Appends a circle to this PdfPagePathObject by drawing four Bézier curves approximating a circle filling a rectangle from the current point to the given coordinates. The current sub-path will be closed. The new current point is set to the given coordinates.

Note that perfect circles cannot be represented exactly using Bézier curves. However, a very close approximation, more than sufficient to please the human eye, can be achieved using four Bézier curves, one for each quadrant of the circle.

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

Closes the current sub-path in this PdfPagePathObject by appending a straight line segment from the current point to the starting point of the sub-path.

pub fn fill_mode(&self) -> Result<PdfPathFillMode, PdfiumError>

Returns the method used to determine which sub-paths of any path in this PdfPagePathObject should be filled.

pub fn is_stroked(&self) -> Result<bool, PdfiumError>

Returns true if this PdfPagePathObject will be stroked, regardless of the path’s stroke settings.

Even if this 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 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 this PdfPagePathObject should be filled, and whether or not any path in this PdfPagePathObject should be stroked.

Even if this 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 segments(&self) -> PdfPagePathObjectSegments<'_>

Returns the collection of path segments currently defined by this PdfPagePathObject.

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 this PdfPagePathObject.

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

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

Resets the transform matrix for this PdfPagePathObject 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 this PdfPagePathObject 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 this PdfPagePathObject 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 this PdfPagePathObject, scaling it by the given horizontal and vertical scale factors.

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

Flips this PdfPagePathObject horizontally around its origin by applying a horizontal scale factor of -1.

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

Flips this PdfPagePathObject vertically around its origin by applying a vertical scale factor of -1.

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

Reflects this PdfPagePathObject by flipping it both horizontally and vertically around its origin.

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

Rotates this PdfPagePathObject counter-clockwise by the given number of degrees.

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

Rotates this PdfPagePathObject clockwise by the given number of degrees.

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

Rotates this PdfPagePathObject counter-clockwise by the given number of radians.

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

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

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

Returns the transformation matrix currently applied to this PdfPagePathObject.

pub fn get_translation(&self) -> (PdfPoints, PdfPoints)

Returns the current horizontal and vertical translation of the origin of this PdfPagePathObject.

pub fn get_horizontal_translation(&self) -> PdfPoints

Returns the current horizontal translation of the origin of this PdfPagePathObject.

pub fn get_vertical_translation(&self) -> PdfPoints

Returns the current vertical translation of the origin of this PdfPagePathObject.

pub fn get_scale(&self) -> (PdfMatrixValue, PdfMatrixValue)

Returns the current horizontal and vertical scale factors applied to this PdfPagePathObject.

pub fn get_horizontal_scale(&self) -> PdfMatrixValue

Returns the current horizontal scale factor applied to this PdfPagePathObject.

pub fn get_vertical_scale(&self) -> PdfMatrixValue

Returns the current vertical scale factor applied to this PdfPagePathObject.

pub fn get_rotation_counter_clockwise_degrees(&self) -> PdfMatrixValue

Returns the counter-clockwise rotation applied to this PdfPagePathObject, in degrees.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_rotation_clockwise_degrees(&self) -> PdfMatrixValue

Returns the clockwise rotation applied to this PdfPagePathObject, in degrees.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_rotation_counter_clockwise_radians(&self) -> PdfMatrixValue

Returns the counter-clockwise rotation applied to this PdfPagePathObject, in radians.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_rotation_clockwise_radians(&self) -> PdfMatrixValue

Returns the clockwise rotation applied to this PdfPagePathObject, in radians.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_skew_degrees(&self) -> (PdfMatrixValue, PdfMatrixValue)

Returns the current x axis and y axis skew angles applied to this PdfPagePathObject, in degrees.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_x_axis_skew_degrees(&self) -> PdfMatrixValue

Returns the current x axis skew angle applied to this PdfPagePathObject, in degrees.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_y_axis_skew_degrees(&self) -> PdfMatrixValue

Returns the current y axis skew applied to this PdfPagePathObject, in degrees.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_skew_radians(&self) -> (PdfMatrixValue, PdfMatrixValue)

Returns the current x axis and y axis skew angles applied to this PdfPagePathObject, in radians.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_x_axis_skew_radians(&self) -> PdfMatrixValue

Returns the current x axis skew applied to this PdfPagePathObject, in radians.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

pub fn get_y_axis_skew_radians(&self) -> PdfMatrixValue

Returns the current y axis skew applied to this PdfPagePathObject, in radians.

If the object is both rotated and skewed, the return value of this function will reflect the combined operation.

Trait Implementations

impl<'a> Drop for PdfPagePathObject<'a>

fn drop(&mut self)

Closes this PdfPagePathObject, releasing held memory.

impl<'a> From<PdfPagePathObject<'a>> for PdfPageObject<'a>

fn from(object: PdfPagePathObject<'a>) -> Self

Converts to this type from the input type.