Struct PdfPageTextObject

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

A single PdfPageObject of type PdfPageObjectType::Text. The page object defines a single piece of formatted text.

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 page text object that is immediately attached to a page is to call the PdfPageObjectsCommon::create_text_object() function.

Creating a detached page text object offers more scope for customization, but you must add the object to a containing PdfPage manually. To create a detached page text object, use the PdfPageTextObject::new() function. The detached page text object can later be attached to a page by using the PdfPageObjectsCommon::add_text_object() function.

Implementations

impl<'a> PdfPageTextObject<'a>

pub fn new( document: &PdfDocument<'a>, text: impl ToString, font: impl ToPdfFontToken, font_size: PdfPoints, ) -> Result<Self, PdfiumError>

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

A single space will be used if the given text is empty, in order to avoid unexpected behaviour from Pdfium when dealing with empty strings.

pub fn render_mode(&self) -> PdfPageTextRenderMode

Returns the text rendering mode for the text contained within this PdfPageTextObject.

pub fn scaled_font_size(&self) -> PdfPoints

Returns the effective size of the text when rendered, taking into account both the font size specified in this text object as well as any vertical scale factor applied to the text object’s transformation matrix.

To retrieve only the specified font size, ignoring any vertical scaling, use the PdfPageTextObject::unscaled_font_size() function.

pub fn unscaled_font_size(&self) -> PdfPoints

Returns the font size of the text specified in this PdfPageTextObject.

Note that the effective size of the text when rendered may differ from the font size if a scaling factor has been applied to this text object’s transformation matrix. To retrieve the effective font size, taking vertical scaling into account, use the PdfPageTextObject::scaled_font_size() function.

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

Returns the PdfFont used to render the text contained within this PdfPageTextObject.

pub fn text(&self) -> String

Returns the text contained within this PdfPageTextObject.

Text retrieval in Pdfium is handled by the PdfPageText object owned by the PdfPage containing this PdfPageTextObject. If this text object has not been attached to a page then text retrieval will be unavailable and an empty string will be returned.

When retrieving the text from many PdfPageTextObject objects (for instance, as part of a loop or an iterator), it may be faster to open the PdfPageText object once and keep it open while processing the text objects, like so:

let text_page = page.text()?; // Opens the text page once.

for object in <some object iterator> {
    let object_text = text_page.for_object(object)?;
}

The PdfPageText object will be closed when the binding to it (text_page in the example above) falls out of scope.

pub fn set_text(&mut self, text: impl ToString) -> Result<(), PdfiumError>

Sets the text contained within this PdfPageTextObject, replacing any existing text.

A single space will be used if the given text is empty, in order to avoid unexpected behaviour from Pdfium when dealing with an empty string.

pub fn set_render_mode( &mut self, render_mode: PdfPageTextRenderMode, ) -> Result<(), PdfiumError>

Sets the text rendering mode for the text contained within this PdfPageTextObject.

pub fn chars( &self, text: &'a PdfPageText<'a>, ) -> Result<PdfPageTextChars<'a>, PdfiumError>

Returns a collection of the characters contained within this PdfPageTextObject, using character retrieval functionality provided by the given PdfPageText object.

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

Returns true if any of the characters contained within this PdfPageTextObject have a glyph shape that descends below the font baseline.

Character retrieval functionality is provided by the given PdfPageText object.

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

Returns the descent of this PdfPageTextObject. The descent is the maximum distance below the baseline reached by any glyph in any of the characters contained in this text object, expressed as a negative points value.

Character retrieval and bounds measurement is provided by the given PdfPageText object.

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 PdfPageTextObject.

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

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

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

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

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

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

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

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

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

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

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

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

Rotates this PdfPageTextObject clockwise by the given number of degrees.

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

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

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

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

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

Returns the transformation matrix currently applied to this PdfPageTextObject.

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

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

pub fn get_horizontal_translation(&self) -> PdfPoints

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

pub fn get_vertical_translation(&self) -> PdfPoints

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

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

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

pub fn get_horizontal_scale(&self) -> PdfMatrixValue

Returns the current horizontal scale factor applied to this PdfPageTextObject.

pub fn get_vertical_scale(&self) -> PdfMatrixValue

Returns the current vertical scale factor applied to this PdfPageTextObject.

pub fn get_rotation_counter_clockwise_degrees(&self) -> PdfMatrixValue

Returns the counter-clockwise rotation applied to this PdfPageTextObject, 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 PdfPageTextObject, 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 PdfPageTextObject, 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 PdfPageTextObject, 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 PdfPageTextObject, 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 PdfPageTextObject, 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 PdfPageTextObject, 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 PdfPageTextObject, 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 PdfPageTextObject, 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 PdfPageTextObject, 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> From<PdfPageTextObject<'a>> for PdfPageObject<'a>

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

Converts to this type from the input type.