pango/auto/

context.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, Direction, Font, FontDescription, FontFamily, FontMap, FontMetrics, Fontset, Gravity,
    GravityHint, Language, Matrix,
};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// A [`Context`][crate::Context] stores global information used to control the
    /// itemization process.
    ///
    /// The information stored by [`Context`][crate::Context] includes the fontmap used
    /// to look up fonts, and default values such as the default language,
    /// default gravity, or default font.
    ///
    /// To obtain a [`Context`][crate::Context], use [`FontMapExt::create_context()`][crate::prelude::FontMapExt::create_context()].
    #[doc(alias = "PangoContext")]
    pub struct Context(Object<ffi::PangoContext, ffi::PangoContextClass>);

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

impl Context {
    /// Creates a new [`Context`][crate::Context] initialized to default values.
    ///
    /// This function is not particularly useful as it should always
    /// be followed by a [`set_font_map()`][Self::set_font_map()] call, and the
    /// function [`FontMapExt::create_context()`][crate::prelude::FontMapExt::create_context()] does these two steps
    /// together and hence users are recommended to use that.
    ///
    /// 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_context_new")]
    pub fn new() -> Context {
        unsafe { from_glib_full(ffi::pango_context_new()) }
    }

    /// Forces a change in the context, which will cause any [`Layout`][crate::Layout]
    /// using this context to re-layout.
    ///
    /// 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_context_changed")]
    pub fn changed(&self) {
        unsafe {
            ffi::pango_context_changed(self.to_glib_none().0);
        }
    }

    /// Retrieves the base direction for the context.
    ///
    /// See [`set_base_dir()`][Self::set_base_dir()].
    ///
    /// # Returns
    ///
    /// the base direction for the context.
    #[doc(alias = "pango_context_get_base_dir")]
    #[doc(alias = "get_base_dir")]
    pub fn base_dir(&self) -> Direction {
        unsafe { from_glib(ffi::pango_context_get_base_dir(self.to_glib_none().0)) }
    }

    /// Retrieves the base gravity for the context.
    ///
    /// See [`set_base_gravity()`][Self::set_base_gravity()].
    ///
    /// # Returns
    ///
    /// the base gravity for the context.
    #[doc(alias = "pango_context_get_base_gravity")]
    #[doc(alias = "get_base_gravity")]
    pub fn base_gravity(&self) -> Gravity {
        unsafe { from_glib(ffi::pango_context_get_base_gravity(self.to_glib_none().0)) }
    }

    /// Retrieve the default font description for the context.
    ///
    /// # Returns
    ///
    /// a pointer to the context's default font
    ///   description. This value must not be modified or freed.
    #[doc(alias = "pango_context_get_font_description")]
    #[doc(alias = "get_font_description")]
    pub fn font_description(&self) -> Option<FontDescription> {
        unsafe {
            from_glib_none(ffi::pango_context_get_font_description(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the [`FontMap`][crate::FontMap] used to look up fonts for this context.
    ///
    /// # Returns
    ///
    /// the font map for the.
    ///   [`Context`][crate::Context] This value is owned by Pango and should not be
    ///   unreferenced.
    #[doc(alias = "pango_context_get_font_map")]
    #[doc(alias = "get_font_map")]
    pub fn font_map(&self) -> Option<FontMap> {
        unsafe { from_glib_none(ffi::pango_context_get_font_map(self.to_glib_none().0)) }
    }

    /// Retrieves the gravity for the context.
    ///
    /// This is similar to [`base_gravity()`][Self::base_gravity()],
    /// except for when the base gravity is [`Gravity::Auto`][crate::Gravity::Auto] for
    /// which [`Gravity::for_matrix()`][crate::Gravity::for_matrix()] is used to return the
    /// gravity from the current context matrix.
    ///
    /// # Returns
    ///
    /// the resolved gravity for the context.
    #[doc(alias = "pango_context_get_gravity")]
    #[doc(alias = "get_gravity")]
    pub fn gravity(&self) -> Gravity {
        unsafe { from_glib(ffi::pango_context_get_gravity(self.to_glib_none().0)) }
    }

    /// Retrieves the gravity hint for the context.
    ///
    /// See [`set_gravity_hint()`][Self::set_gravity_hint()] for details.
    ///
    /// # Returns
    ///
    /// the gravity hint for the context.
    #[doc(alias = "pango_context_get_gravity_hint")]
    #[doc(alias = "get_gravity_hint")]
    pub fn gravity_hint(&self) -> GravityHint {
        unsafe { from_glib(ffi::pango_context_get_gravity_hint(self.to_glib_none().0)) }
    }

    /// Retrieves the global language tag for the context.
    ///
    /// # Returns
    ///
    /// the global language tag.
    #[doc(alias = "pango_context_get_language")]
    #[doc(alias = "get_language")]
    pub fn language(&self) -> Option<Language> {
        unsafe { from_glib_none(ffi::pango_context_get_language(self.to_glib_none().0)) }
    }

    /// Gets the transformation matrix that will be applied when
    /// rendering with this context.
    ///
    /// See [`set_matrix()`][Self::set_matrix()].
    ///
    /// # Returns
    ///
    /// the matrix, or [`None`] if no
    ///   matrix has been set (which is the same as the identity matrix).
    ///   The returned matrix is owned by Pango and must not be modified
    ///   or freed.
    #[doc(alias = "pango_context_get_matrix")]
    #[doc(alias = "get_matrix")]
    pub fn matrix(&self) -> Option<Matrix> {
        unsafe { from_glib_none(ffi::pango_context_get_matrix(self.to_glib_none().0)) }
    }

    /// Get overall metric information for a particular font description.
    ///
    /// 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.
    ///
    /// The [`FontDescription`][crate::FontDescription] is interpreted in the same way as by [`itemize()`][crate::itemize()],
    /// and the family name may be a comma separated list of names. If characters
    /// from multiple of these families would be used to render the string, then
    /// the returned fonts would be a composite of the metrics for the fonts loaded
    /// for the individual families.
    /// ## `desc`
    /// a [`FontDescription`][crate::FontDescription] structure. [`None`] means that the
    ///   font description from the context will be used.
    /// ## `language`
    /// language tag used to determine which script to get
    ///   the metrics for. [`None`] means that the language tag from the context
    ///   will be used. If no language tag is set on the context, metrics
    ///   for the default language (as determined by [`Language::default()`][crate::Language::default()]
    ///   will be returned.
    ///
    /// # Returns
    ///
    /// a [`FontMetrics`][crate::FontMetrics] object. The caller must call
    ///   `Pango::FontMetrics::unref()` when finished using the object.
    #[doc(alias = "pango_context_get_metrics")]
    #[doc(alias = "get_metrics")]
    pub fn metrics(
        &self,
        desc: Option<&FontDescription>,
        language: Option<&Language>,
    ) -> FontMetrics {
        unsafe {
            from_glib_full(ffi::pango_context_get_metrics(
                self.to_glib_none().0,
                desc.to_glib_none().0,
                mut_override(language.to_glib_none().0),
            ))
        }
    }

    /// Returns whether font rendering with this context should
    /// round glyph positions and widths.
    #[cfg(feature = "v1_44")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
    #[doc(alias = "pango_context_get_round_glyph_positions")]
    #[doc(alias = "get_round_glyph_positions")]
    pub fn is_round_glyph_positions(&self) -> bool {
        unsafe {
            from_glib(ffi::pango_context_get_round_glyph_positions(
                self.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 context is created and is increased whenever the context
    /// is changed using any of the setter functions, or the [`FontMap`][crate::FontMap] it
    /// uses to find fonts has changed. The serial may wrap, but will never
    /// have the value 0. Since it can wrap, never compare it with "less than",
    /// always use "not equals".
    ///
    /// This can be used to automatically detect changes to a [`Context`][crate::Context],
    /// and is only useful when implementing objects that need update when their
    /// [`Context`][crate::Context] changes, like [`Layout`][crate::Layout].
    ///
    /// # Returns
    ///
    /// The current serial number of @self.
    #[doc(alias = "pango_context_get_serial")]
    #[doc(alias = "get_serial")]
    pub fn serial(&self) -> u32 {
        unsafe { ffi::pango_context_get_serial(self.to_glib_none().0) }
    }

    /// List all families for a context.
    ///
    /// # 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_context_list_families")]
    pub fn list_families(&self) -> Vec<FontFamily> {
        unsafe {
            let mut families = std::ptr::null_mut();
            let mut n_families = std::mem::MaybeUninit::uninit();
            ffi::pango_context_list_families(
                self.to_glib_none().0,
                &mut families,
                n_families.as_mut_ptr(),
            );
            FromGlibContainer::from_glib_container_num(families, n_families.assume_init() as _)
        }
    }

    /// Loads the font in one of the fontmaps in the context
    /// that is the closest match for @desc.
    /// ## `desc`
    /// a [`FontDescription`][crate::FontDescription] describing the font to load
    ///
    /// # Returns
    ///
    /// the newly allocated [`Font`][crate::Font]
    ///   that was loaded, or [`None`] if no font matched.
    #[doc(alias = "pango_context_load_font")]
    pub fn load_font(&self, desc: &FontDescription) -> Option<Font> {
        unsafe {
            from_glib_full(ffi::pango_context_load_font(
                self.to_glib_none().0,
                desc.to_glib_none().0,
            ))
        }
    }

    /// Load a set of fonts in the context that can be used to render
    /// a font matching @desc.
    /// ## `desc`
    /// a [`FontDescription`][crate::FontDescription] describing the fonts 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_context_load_fontset")]
    pub fn load_fontset(&self, desc: &FontDescription, language: &Language) -> Option<Fontset> {
        unsafe {
            from_glib_full(ffi::pango_context_load_fontset(
                self.to_glib_none().0,
                desc.to_glib_none().0,
                mut_override(language.to_glib_none().0),
            ))
        }
    }

    /// Sets the base direction for the context.
    ///
    /// The base direction is used in applying the Unicode bidirectional
    /// algorithm; if the @direction is [`Direction::Ltr`][crate::Direction::Ltr] or
    /// [`Direction::Rtl`][crate::Direction::Rtl], then the value will be used as the paragraph
    /// direction in the Unicode bidirectional algorithm. A value of
    /// [`Direction::WeakLtr`][crate::Direction::WeakLtr] or [`Direction::WeakRtl`][crate::Direction::WeakRtl] is used only
    /// for paragraphs that do not contain any strong characters themselves.
    /// ## `direction`
    /// the new base direction
    #[doc(alias = "pango_context_set_base_dir")]
    pub fn set_base_dir(&self, direction: Direction) {
        unsafe {
            ffi::pango_context_set_base_dir(self.to_glib_none().0, direction.into_glib());
        }
    }

    /// Sets the base gravity for the context.
    ///
    /// The base gravity is used in laying vertical text out.
    /// ## `gravity`
    /// the new base gravity
    #[doc(alias = "pango_context_set_base_gravity")]
    pub fn set_base_gravity(&self, gravity: Gravity) {
        unsafe {
            ffi::pango_context_set_base_gravity(self.to_glib_none().0, gravity.into_glib());
        }
    }

    /// Set the default font description for the context
    /// ## `desc`
    /// the new pango font description
    #[doc(alias = "pango_context_set_font_description")]
    pub fn set_font_description(&self, desc: Option<&FontDescription>) {
        unsafe {
            ffi::pango_context_set_font_description(self.to_glib_none().0, desc.to_glib_none().0);
        }
    }

    /// Sets the font map to be searched when fonts are looked-up
    /// in this context.
    ///
    /// This is only for internal use by Pango backends, a [`Context`][crate::Context]
    /// obtained via one of the recommended methods should already have a
    /// suitable font map.
    /// ## `font_map`
    /// the [`FontMap`][crate::FontMap] to set.
    #[doc(alias = "pango_context_set_font_map")]
    pub fn set_font_map(&self, font_map: Option<&impl IsA<FontMap>>) {
        unsafe {
            ffi::pango_context_set_font_map(
                self.to_glib_none().0,
                font_map.map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets the gravity hint for the context.
    ///
    /// The gravity hint is used in laying vertical text out, and
    /// is only relevant if gravity of the context as returned by
    /// [`gravity()`][Self::gravity()] is set to [`Gravity::East`][crate::Gravity::East]
    /// or [`Gravity::West`][crate::Gravity::West].
    /// ## `hint`
    /// the new gravity hint
    #[doc(alias = "pango_context_set_gravity_hint")]
    pub fn set_gravity_hint(&self, hint: GravityHint) {
        unsafe {
            ffi::pango_context_set_gravity_hint(self.to_glib_none().0, hint.into_glib());
        }
    }

    /// Sets the global language tag for the context.
    ///
    /// The default language for the locale of the running process
    /// can be found using [`Language::default()`][crate::Language::default()].
    /// ## `language`
    /// the new language tag.
    #[doc(alias = "pango_context_set_language")]
    pub fn set_language(&self, language: Option<&Language>) {
        unsafe {
            ffi::pango_context_set_language(
                self.to_glib_none().0,
                mut_override(language.to_glib_none().0),
            );
        }
    }

    /// Sets the transformation matrix that will be applied when rendering
    /// with this context.
    ///
    /// Note that reported metrics are in the user space coordinates before
    /// the application of the matrix, not device-space coordinates after the
    /// application of the matrix. So, they don't scale with the matrix, though
    /// they may change slightly for different matrices, depending on how the
    /// text is fit to the pixel grid.
    /// ## `matrix`
    /// a [`Matrix`][crate::Matrix], or [`None`] to unset any existing
    /// matrix. (No matrix set is the same as setting the identity matrix.)
    #[doc(alias = "pango_context_set_matrix")]
    pub fn set_matrix(&self, matrix: Option<&Matrix>) {
        unsafe {
            ffi::pango_context_set_matrix(self.to_glib_none().0, matrix.to_glib_none().0);
        }
    }

    /// Sets whether font rendering with this context should
    /// round glyph positions and widths to integral positions,
    /// in device units.
    ///
    /// This is useful when the renderer can't handle subpixel
    /// positioning of glyphs.
    ///
    /// The default value is to round glyph positions, to remain
    /// compatible with previous Pango behavior.
    /// ## `round_positions`
    /// whether to round glyph positions
    #[cfg(feature = "v1_44")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
    #[doc(alias = "pango_context_set_round_glyph_positions")]
    pub fn set_round_glyph_positions(&self, round_positions: bool) {
        unsafe {
            ffi::pango_context_set_round_glyph_positions(
                self.to_glib_none().0,
                round_positions.into_glib(),
            );
        }
    }
}

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