pango/auto/

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

#[cfg(feature = "v1_50")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
use crate::Context;
#[cfg(feature = "v1_46")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_46")))]
use crate::FontFace;
use crate::{ffi, Coverage, FontDescription, FontMap, FontMetrics, Glyph, Language, Rectangle};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// A [`Font`][crate::Font] is used to represent a font in a
    /// rendering-system-independent manner.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// # Implements
    ///
    /// [`FontExt`][trait@crate::prelude::FontExt]
    #[doc(alias = "PangoFont")]
    pub struct Font(Object<ffi::PangoFont, ffi::PangoFontClass>);

    match fn {
        type_ => || ffi::pango_font_get_type(),
    }
}

impl Font {
    pub const NONE: Option<&'static Font> = None;

    /// Loads data previously created via [`FontExt::serialize()`][crate::prelude::FontExt::serialize()].
    ///
    /// For a discussion of the supported format, see that function.
    ///
    /// Note: to verify that the returned font is identical to
    /// the one that was serialized, you can compare @bytes to the
    /// result of serializing the font again.
    /// ## `context`
    /// a [`Context`][crate::Context]
    /// ## `bytes`
    /// the bytes containing the data
    ///
    /// # Returns
    ///
    /// a new [`Font`][crate::Font]
    #[cfg(feature = "v1_50")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    #[doc(alias = "pango_font_deserialize")]
    pub fn deserialize(
        context: &Context,
        bytes: &glib::Bytes,
    ) -> Result<Option<Font>, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::pango_font_deserialize(
                context.to_glib_none().0,
                bytes.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

/// Trait containing all [`struct@Font`] methods.
///
/// # Implementors
///
/// [`Font`][struct@crate::Font]
pub trait FontExt: IsA<Font> + 'static {
    /// Returns a description of the font, with font size set in points.
    ///
    /// Use [`describe_with_absolute_size()`][Self::describe_with_absolute_size()] if you want
    /// the font size in device units.
    ///
    /// # Returns
    ///
    /// a newly-allocated [`FontDescription`][crate::FontDescription] object.
    #[doc(alias = "pango_font_describe")]
    fn describe(&self) -> FontDescription {
        unsafe { from_glib_full(ffi::pango_font_describe(self.as_ref().to_glib_none().0)) }
    }

    /// Returns a description of the font, with absolute font size set
    /// in device units.
    ///
    /// Use [`describe()`][Self::describe()] if you want the font size in points.
    ///
    /// # Returns
    ///
    /// a newly-allocated [`FontDescription`][crate::FontDescription] object.
    #[doc(alias = "pango_font_describe_with_absolute_size")]
    fn describe_with_absolute_size(&self) -> FontDescription {
        unsafe {
            from_glib_full(ffi::pango_font_describe_with_absolute_size(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Computes the coverage map for a given font and language tag.
    /// ## `language`
    /// the language tag
    ///
    /// # Returns
    ///
    /// a newly-allocated [`Coverage`][crate::Coverage]
    ///   object.
    #[doc(alias = "pango_font_get_coverage")]
    #[doc(alias = "get_coverage")]
    fn coverage(&self, language: &Language) -> Coverage {
        unsafe {
            from_glib_full(ffi::pango_font_get_coverage(
                self.as_ref().to_glib_none().0,
                mut_override(language.to_glib_none().0),
            ))
        }
    }

    /// Gets the [`FontFace`][crate::FontFace] to which @self belongs.
    ///
    /// Note that this function can return `NULL` in cases
    /// where the font outlives its font map.
    ///
    /// # Returns
    ///
    /// the [`FontFace`][crate::FontFace]
    #[cfg(feature = "v1_46")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_46")))]
    #[doc(alias = "pango_font_get_face")]
    #[doc(alias = "get_face")]
    fn face(&self) -> Option<FontFace> {
        unsafe { from_glib_none(ffi::pango_font_get_face(self.as_ref().to_glib_none().0)) }
    }

    //#[cfg(feature = "v1_44")]
    //#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
    //#[doc(alias = "pango_font_get_features")]
    //#[doc(alias = "get_features")]
    //fn features(&self, features: /*Unimplemented*/&mut Basic: Pointer, len: u32, num_features: &mut u32) {
    //    unsafe { TODO: call ffi:pango_font_get_features() }
    //}

    /// Gets the font map for which the font was created.
    ///
    /// Note that the font maintains a *weak* reference to
    /// the font map, so if all references to font map are
    /// dropped, the font map will be finalized even if there
    /// are fonts created with the font map that are still alive.
    /// In that case this function will return [`None`].
    ///
    /// It is the responsibility of the user to ensure that the
    /// font map is kept alive. In most uses this is not an issue
    /// as a [`Context`][crate::Context] holds a reference to the font map.
    ///
    /// # Returns
    ///
    /// the [`FontMap`][crate::FontMap]
    ///   for the font
    #[doc(alias = "pango_font_get_font_map")]
    #[doc(alias = "get_font_map")]
    fn font_map(&self) -> Option<FontMap> {
        unsafe { from_glib_none(ffi::pango_font_get_font_map(self.as_ref().to_glib_none().0)) }
    }

    /// Gets the logical and ink extents of a glyph within a font.
    ///
    /// The coordinate system for each rectangle has its origin at the
    /// base line and horizontal origin of the character with increasing
    /// coordinates extending to the right and down. The macros PANGO_ASCENT(),
    /// PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert
    /// from the extents rectangle to more traditional font metrics. The units
    /// of the rectangles are in 1/PANGO_SCALE of a device unit.
    ///
    /// If @self is [`None`], this function gracefully sets some sane values in the
    /// output variables and returns.
    /// ## `glyph`
    /// the glyph index
    ///
    /// # Returns
    ///
    ///
    /// ## `ink_rect`
    /// rectangle used to store the extents of the glyph as drawn
    ///
    /// ## `logical_rect`
    /// rectangle used to store the logical extents of the glyph
    #[doc(alias = "pango_font_get_glyph_extents")]
    #[doc(alias = "get_glyph_extents")]
    fn glyph_extents(&self, glyph: Glyph) -> (Rectangle, Rectangle) {
        unsafe {
            let mut ink_rect = Rectangle::uninitialized();
            let mut logical_rect = Rectangle::uninitialized();
            ffi::pango_font_get_glyph_extents(
                self.as_ref().to_glib_none().0,
                glyph,
                ink_rect.to_glib_none_mut().0,
                logical_rect.to_glib_none_mut().0,
            );
            (ink_rect, logical_rect)
        }
    }

    //#[cfg(feature = "v1_44")]
    //#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
    //#[doc(alias = "pango_font_get_hb_font")]
    //#[doc(alias = "get_hb_font")]
    //fn hb_font(&self) -> /*Ignored*/Option<harf_buzz::font_t> {
    //    unsafe { TODO: call ffi:pango_font_get_hb_font() }
    //}

    /// Returns the languages that are supported by @self.
    ///
    /// If the font backend does not provide this information,
    /// [`None`] is returned. For the fontconfig backend, this
    /// corresponds to the FC_LANG member of the FcPattern.
    ///
    /// The returned array is only valid as long as the font
    /// and its fontmap are valid.
    ///
    /// # Returns
    ///
    /// an array of [`Language`][crate::Language]
    #[cfg(feature = "v1_50")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    #[doc(alias = "pango_font_get_languages")]
    #[doc(alias = "get_languages")]
    fn languages(&self) -> Vec<Language> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::pango_font_get_languages(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets overall metric information for a font.
    ///
    /// Since the metrics may be substantially different for different scripts,
    /// a language tag can be provided to indicate that the metrics should be
    /// retrieved that correspond to the script(s) used by that language.
    ///
    /// If @self is [`None`], this function gracefully sets some sane values in the
    /// output variables and returns.
    /// ## `language`
    /// language tag used to determine which script
    ///   to get the metrics for, or [`None`] to indicate to get the metrics for
    ///   the entire font.
    ///
    /// # Returns
    ///
    /// a [`FontMetrics`][crate::FontMetrics] object. The caller must call
    ///   `Pango::FontMetrics::unref()` when finished using the object.
    #[doc(alias = "pango_font_get_metrics")]
    #[doc(alias = "get_metrics")]
    fn metrics(&self, language: Option<&Language>) -> FontMetrics {
        unsafe {
            from_glib_full(ffi::pango_font_get_metrics(
                self.as_ref().to_glib_none().0,
                mut_override(language.to_glib_none().0),
            ))
        }
    }

    /// Returns whether the font provides a glyph for this character.
    /// ## `wc`
    /// a Unicode character
    ///
    /// # Returns
    ///
    /// `TRUE` if @self can render @wc
    #[cfg(feature = "v1_44")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
    #[doc(alias = "pango_font_has_char")]
    fn has_char(&self, wc: char) -> bool {
        unsafe {
            from_glib(ffi::pango_font_has_char(
                self.as_ref().to_glib_none().0,
                wc.into_glib(),
            ))
        }
    }

    /// Serializes the @self in a way that can be uniquely identified.
    ///
    /// There are no guarantees about the format of the output across different
    /// versions of Pango.
    ///
    /// The intended use of this function is testing, benchmarking and debugging.
    /// The format is not meant as a permanent storage format.
    ///
    /// To recreate a font from its serialized form, use [`Font::deserialize()`][crate::Font::deserialize()].
    ///
    /// # Returns
    ///
    /// a `GBytes` containing the serialized form of @self
    #[cfg(feature = "v1_50")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
    #[doc(alias = "pango_font_serialize")]
    fn serialize(&self) -> glib::Bytes {
        unsafe { from_glib_full(ffi::pango_font_serialize(self.as_ref().to_glib_none().0)) }
    }
}

impl<O: IsA<Font>> FontExt for O {}