pango/auto/

glyph_string.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, Analysis, Font, Rectangle};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// A [`GlyphString`][crate::GlyphString] is used to store strings of glyphs with geometry
    /// and visual attribute information.
    ///
    /// The storage for the glyph information is owned by the structure
    /// which simplifies memory management.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct GlyphString(Boxed<ffi::PangoGlyphString>);

    match fn {
        copy => |ptr| ffi::pango_glyph_string_copy(mut_override(ptr)),
        free => |ptr| ffi::pango_glyph_string_free(ptr),
        type_ => || ffi::pango_glyph_string_get_type(),
    }
}

impl GlyphString {
    /// Create a new [`GlyphString`][crate::GlyphString].
    ///
    /// # Returns
    ///
    /// the newly allocated [`GlyphString`][crate::GlyphString], which
    ///   should be freed with `Pango::GlyphString::free()`.
    #[doc(alias = "pango_glyph_string_new")]
    pub fn new() -> GlyphString {
        unsafe { from_glib_full(ffi::pango_glyph_string_new()) }
    }

    /// Compute the logical and ink extents of a glyph string.
    ///
    /// See the documentation for [`FontExt::glyph_extents()`][crate::prelude::FontExt::glyph_extents()] for details
    /// about the interpretation of the rectangles.
    ///
    /// Examples of logical (red) and ink (green) rects:
    ///
    /// ![](rects1.png) ![](rects2.png)
    /// ## `font`
    /// a [`Font`][crate::Font]
    ///
    /// # Returns
    ///
    ///
    /// ## `ink_rect`
    /// rectangle used to store the extents of the glyph string as drawn
    ///
    /// ## `logical_rect`
    /// rectangle used to store the logical extents of the glyph string
    #[doc(alias = "pango_glyph_string_extents")]
    pub fn extents(&mut self, font: &impl IsA<Font>) -> (Rectangle, Rectangle) {
        unsafe {
            let mut ink_rect = Rectangle::uninitialized();
            let mut logical_rect = Rectangle::uninitialized();
            ffi::pango_glyph_string_extents(
                self.to_glib_none_mut().0,
                font.as_ref().to_glib_none().0,
                ink_rect.to_glib_none_mut().0,
                logical_rect.to_glib_none_mut().0,
            );
            (ink_rect, logical_rect)
        }
    }

    /// Computes the extents of a sub-portion of a glyph string.
    ///
    /// The extents are relative to the start of the glyph string range
    /// (the origin of their coordinate system is at the start of the range,
    /// not at the start of the entire glyph string).
    /// ## `start`
    /// start index
    /// ## `end`
    /// end index (the range is the set of bytes with
    ///   indices such that start <= index < end)
    /// ## `font`
    /// a [`Font`][crate::Font]
    ///
    /// # Returns
    ///
    ///
    /// ## `ink_rect`
    /// rectangle used to
    ///   store the extents of the glyph string range as drawn
    ///
    /// ## `logical_rect`
    /// rectangle used to
    ///   store the logical extents of the glyph string range
    #[doc(alias = "pango_glyph_string_extents_range")]
    pub fn extents_range(
        &mut self,
        start: i32,
        end: i32,
        font: &impl IsA<Font>,
    ) -> (Rectangle, Rectangle) {
        unsafe {
            let mut ink_rect = Rectangle::uninitialized();
            let mut logical_rect = Rectangle::uninitialized();
            ffi::pango_glyph_string_extents_range(
                self.to_glib_none_mut().0,
                start,
                end,
                font.as_ref().to_glib_none().0,
                ink_rect.to_glib_none_mut().0,
                logical_rect.to_glib_none_mut().0,
            );
            (ink_rect, logical_rect)
        }
    }

    /// Computes the logical width of the glyph string.
    ///
    /// This can also be computed using [`extents()`][Self::extents()].
    /// However, since this only computes the width, it's much faster. This
    /// is in fact only a convenience function that computes the sum of
    /// @geometry.width for each glyph in the @self.
    ///
    /// # Returns
    ///
    /// the logical width of the glyph string.
    #[doc(alias = "pango_glyph_string_get_width")]
    #[doc(alias = "get_width")]
    pub fn width(&self) -> i32 {
        unsafe { ffi::pango_glyph_string_get_width(mut_override(self.to_glib_none().0)) }
    }

    /// Converts from character position to x position.
    ///
    /// The X position is measured from the left edge of the run.
    /// Character positions are obtained using font metrics for ligatures
    /// where available, and computed by dividing up each cluster
    /// into equal portions, otherwise.
    ///
    /// <picture>
    ///   <source srcset="glyphstring-positions-dark.png" media="(prefers-color-scheme: dark)">
    ///   <img alt="Glyph positions" src="glyphstring-positions-light.png">
    /// </picture>
    /// ## `text`
    /// the text for the run
    /// ## `length`
    /// the number of bytes (not characters) in @text.
    /// ## `analysis`
    /// the analysis information return from [`itemize()`][crate::itemize()]
    /// ## `index_`
    /// the byte index within @text
    /// ## `trailing`
    /// whether we should compute the result for the beginning ([`false`])
    ///   or end ([`true`]) of the character.
    ///
    /// # Returns
    ///
    ///
    /// ## `x_pos`
    /// location to store result
    #[doc(alias = "pango_glyph_string_index_to_x")]
    pub fn index_to_x(&self, text: &str, analysis: &Analysis, index_: i32, trailing: bool) -> i32 {
        let length = text.len() as _;
        unsafe {
            let mut x_pos = std::mem::MaybeUninit::uninit();
            ffi::pango_glyph_string_index_to_x(
                mut_override(self.to_glib_none().0),
                text.to_glib_none().0,
                length,
                mut_override(analysis.to_glib_none().0),
                index_,
                trailing.into_glib(),
                x_pos.as_mut_ptr(),
            );
            x_pos.assume_init()
        }
    }

    //#[cfg(feature = "v1_50")]
    //#[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    //#[doc(alias = "pango_glyph_string_index_to_x_full")]
    //pub fn index_to_x_full(&mut self, text: &str, analysis: &mut Analysis, attrs: /*Ignored*/Option<&mut LogAttr>, index_: i32, trailing: bool) -> i32 {
    //    unsafe { TODO: call ffi:pango_glyph_string_index_to_x_full() }
    //}

    /// Resize a glyph string to the given length.
    /// ## `new_len`
    /// the new length of the string
    #[doc(alias = "pango_glyph_string_set_size")]
    pub fn set_size(&mut self, new_len: i32) {
        unsafe {
            ffi::pango_glyph_string_set_size(self.to_glib_none_mut().0, new_len);
        }
    }

    /// Convert from x offset to character position.
    ///
    /// Character positions are computed by dividing up each cluster into
    /// equal portions. In scripts where positioning within a cluster is
    /// not allowed (such as Thai), the returned value may not be a valid
    /// cursor position; the caller must combine the result with the logical
    /// attributes for the text to compute the valid cursor position.
    /// ## `text`
    /// the text for the run
    /// ## `length`
    /// the number of bytes (not characters) in text.
    /// ## `analysis`
    /// the analysis information return from [`itemize()`][crate::itemize()]
    /// ## `x_pos`
    /// the x offset (in Pango units)
    ///
    /// # Returns
    ///
    ///
    /// ## `index_`
    /// location to store calculated byte index within @text
    ///
    /// ## `trailing`
    /// location to store a boolean indicating whether the
    ///   user clicked on the leading or trailing edge of the character
    #[doc(alias = "pango_glyph_string_x_to_index")]
    pub fn x_to_index(&self, text: &str, analysis: &Analysis, x_pos: i32) -> (i32, i32) {
        let length = text.len() as _;
        unsafe {
            let mut index_ = std::mem::MaybeUninit::uninit();
            let mut trailing = std::mem::MaybeUninit::uninit();
            ffi::pango_glyph_string_x_to_index(
                mut_override(self.to_glib_none().0),
                text.to_glib_none().0,
                length,
                mut_override(analysis.to_glib_none().0),
                x_pos,
                index_.as_mut_ptr(),
                trailing.as_mut_ptr(),
            );
            (index_.assume_init(), trailing.assume_init())
        }
    }
}

impl Default for GlyphString {
    fn default() -> Self {
        Self::new()
    }
}

unsafe impl Send for GlyphString {}
unsafe impl Sync for GlyphString {}