pango/auto/

font_map.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, Context, Font, FontDescription, FontFamily, Fontset, Language};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// A [`FontMap`][crate::FontMap] represents the set of fonts available for a
    /// particular rendering system.
    ///
    /// This is a virtual object with implementations being specific to
    /// particular rendering systems.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `item-type`
    ///  The type of items contained in this list.
    ///
    /// Readable
    ///
    ///
    /// #### `n-items`
    ///  The number of items contained in this list.
    ///
    /// Readable
    ///
    /// # Implements
    ///
    /// [`FontMapExt`][trait@crate::prelude::FontMapExt], [`trait@gio::prelude::ListModelExt`]
    #[doc(alias = "PangoFontMap")]
    pub struct FontMap(Object<ffi::PangoFontMap, ffi::PangoFontMapClass>) @implements gio::ListModel;

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

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

/// Trait containing all [`struct@FontMap`] methods.
///
/// # Implementors
///
/// [`FontMap`][struct@crate::FontMap]
pub trait FontMapExt: IsA<FontMap> + 'static {
    /// Loads a font file with one or more fonts into the [`FontMap`][crate::FontMap].
    ///
    /// The added fonts will take precedence over preexisting
    /// fonts with the same name.
    /// ## `filename`
    /// Path to the font file
    ///
    /// # Returns
    ///
    /// True if the font file is successfully loaded
    ///     into the fontmap, false if an error occurred.
    #[cfg(feature = "v1_56")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_56")))]
    #[doc(alias = "pango_font_map_add_font_file")]
    fn add_font_file(&self, filename: impl AsRef<std::path::Path>) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::pango_font_map_add_font_file(
                self.as_ref().to_glib_none().0,
                filename.as_ref().to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Forces a change in the context, which will cause any [`Context`][crate::Context]
    /// using this fontmap to change.
    ///
    /// This function is only useful when implementing a new backend
    /// for Pango, something applications won't do. Backends should
    /// call this function if they have attached extra data to the
    /// context and such data is changed.
    #[doc(alias = "pango_font_map_changed")]
    fn changed(&self) {
        unsafe {
            ffi::pango_font_map_changed(self.as_ref().to_glib_none().0);
        }
    }

    /// Creates a [`Context`][crate::Context] connected to @self.
    ///
    /// This is equivalent to [`Context::new()`][crate::Context::new()] followed by
    /// [`Context::set_font_map()`][crate::Context::set_font_map()].
    ///
    /// If you are using Pango as part of a higher-level system,
    /// that system may have it's own way of create a [`Context`][crate::Context].
    /// For instance, the GTK toolkit has, among others,
    /// gtk_widget_get_pango_context(). Use those instead.
    ///
    /// # Returns
    ///
    /// the newly allocated [`Context`][crate::Context],
    ///   which should be freed with g_object_unref().
    #[doc(alias = "pango_font_map_create_context")]
    fn create_context(&self) -> Context {
        unsafe {
            from_glib_full(ffi::pango_font_map_create_context(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets a font family by name.
    /// ## `name`
    /// a family name
    ///
    /// # Returns
    ///
    /// the [`FontFamily`][crate::FontFamily]
    #[cfg(feature = "v1_46")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_46")))]
    #[doc(alias = "pango_font_map_get_family")]
    #[doc(alias = "get_family")]
    fn family(&self, name: &str) -> FontFamily {
        unsafe {
            from_glib_none(ffi::pango_font_map_get_family(
                self.as_ref().to_glib_none().0,
                name.to_glib_none().0,
            ))
        }
    }

    /// Returns the current serial number of @self.
    ///
    /// The serial number is initialized to an small number larger than zero
    /// when a new fontmap is created and is increased whenever the fontmap
    /// is changed. It may wrap, but will never have the value 0. Since it can
    /// wrap, never compare it with "less than", always use "not equals".
    ///
    /// The fontmap can only be changed using backend-specific API, like changing
    /// fontmap resolution.
    ///
    /// This can be used to automatically detect changes to a [`FontMap`][crate::FontMap],
    /// like in [`Context`][crate::Context].
    ///
    /// # Returns
    ///
    /// The current serial number of @self.
    #[doc(alias = "pango_font_map_get_serial")]
    #[doc(alias = "get_serial")]
    fn serial(&self) -> u32 {
        unsafe { ffi::pango_font_map_get_serial(self.as_ref().to_glib_none().0) }
    }

    /// List all families for a fontmap.
    ///
    /// Note that the returned families are not in any particular order.
    ///
    /// [`FontMap`][crate::FontMap] also implemented the [`gio::ListModel`][crate::gio::ListModel] interface
    /// for enumerating families.
    ///
    /// # Returns
    ///
    ///
    /// ## `families`
    /// location to
    ///   store a pointer to an array of [`FontFamily`][crate::FontFamily] *.
    ///   This array should be freed with g_free().
    #[doc(alias = "pango_font_map_list_families")]
    fn list_families(&self) -> Vec<FontFamily> {
        unsafe {
            let mut families = std::ptr::null_mut();
            let mut n_families = std::mem::MaybeUninit::uninit();
            ffi::pango_font_map_list_families(
                self.as_ref().to_glib_none().0,
                &mut families,
                n_families.as_mut_ptr(),
            );
            FromGlibContainer::from_glib_container_num(families, n_families.assume_init() as _)
        }
    }

    /// Load the font in the fontmap that is the closest match for @desc.
    /// ## `context`
    /// the [`Context`][crate::Context] the font will be used with
    /// ## `desc`
    /// a [`FontDescription`][crate::FontDescription] describing the font to load
    ///
    /// # Returns
    ///
    /// the newly allocated [`Font`][crate::Font]
    ///   loaded, or [`None`] if no font matched.
    #[doc(alias = "pango_font_map_load_font")]
    fn load_font(&self, context: &Context, desc: &FontDescription) -> Option<Font> {
        unsafe {
            from_glib_full(ffi::pango_font_map_load_font(
                self.as_ref().to_glib_none().0,
                context.to_glib_none().0,
                desc.to_glib_none().0,
            ))
        }
    }

    /// Load a set of fonts in the fontmap that can be used to render
    /// a font matching @desc.
    /// ## `context`
    /// the [`Context`][crate::Context] the font will be used with
    /// ## `desc`
    /// a [`FontDescription`][crate::FontDescription] describing the font to load
    /// ## `language`
    /// a [`Language`][crate::Language] the fonts will be used for
    ///
    /// # Returns
    ///
    /// the newly allocated
    ///   [`Fontset`][crate::Fontset] loaded, or [`None`] if no font matched.
    #[doc(alias = "pango_font_map_load_fontset")]
    fn load_fontset(
        &self,
        context: &Context,
        desc: &FontDescription,
        language: &Language,
    ) -> Option<Fontset> {
        unsafe {
            from_glib_full(ffi::pango_font_map_load_fontset(
                self.as_ref().to_glib_none().0,
                context.to_glib_none().0,
                desc.to_glib_none().0,
                mut_override(language.to_glib_none().0),
            ))
        }
    }

    /// Returns a new font that is like @font, except that its size
    /// is multiplied by @scale, its backend-dependent configuration
    /// (e.g. cairo font options) is replaced by the one in @context,
    /// and its variations are replaced by @variations.
    /// ## `font`
    /// a font in @self
    /// ## `scale`
    /// the scale factor to apply
    /// ## `context`
    /// a [`Context`][crate::Context]
    /// ## `variations`
    /// font variations to use
    ///
    /// # Returns
    ///
    /// the modified font
    #[cfg(feature = "v1_52")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_52")))]
    #[doc(alias = "pango_font_map_reload_font")]
    fn reload_font(
        &self,
        font: &impl IsA<Font>,
        scale: f64,
        context: Option<&Context>,
        variations: Option<&str>,
    ) -> Font {
        unsafe {
            from_glib_full(ffi::pango_font_map_reload_font(
                self.as_ref().to_glib_none().0,
                font.as_ref().to_glib_none().0,
                scale,
                context.to_glib_none().0,
                variations.to_glib_none().0,
            ))
        }
    }
}

impl<O: IsA<FontMap>> FontMapExt for O {}