pango/auto/

font_description.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, FontMask, Gravity, Stretch, Style, Variant, Weight};
use glib::translate::*;

glib::wrapper! {
    /// A [`FontDescription`][crate::FontDescription] describes a font in an implementation-independent
    /// manner.
    ///
    /// [`FontDescription`][crate::FontDescription] structures are used both to list what fonts are
    /// available on the system and also for specifying the characteristics of
    /// a font to load.
    #[derive(Debug, PartialOrd, Ord)]
    pub struct FontDescription(Boxed<ffi::PangoFontDescription>);

    match fn {
        copy => |ptr| ffi::pango_font_description_copy(ptr),
        free => |ptr| ffi::pango_font_description_free(ptr),
        type_ => || ffi::pango_font_description_get_type(),
    }
}

impl FontDescription {
    /// Creates a new font description structure with all fields unset.
    ///
    /// # Returns
    ///
    /// the newly allocated [`FontDescription`][crate::FontDescription],
    ///   which should be freed using `Pango::FontDescription::free()`.
    #[doc(alias = "pango_font_description_new")]
    pub fn new() -> FontDescription {
        unsafe { from_glib_full(ffi::pango_font_description_new()) }
    }

    /// Determines if the style attributes of @new_match are a closer match
    /// for @self than those of @old_match are, or if @old_match is [`None`],
    /// determines if @new_match is a match at all.
    ///
    /// Approximate matching is done for weight and style; other style attributes
    /// must match exactly. Style attributes are all attributes other than family
    /// and size-related attributes. Approximate matching for style considers
    /// [`Style::Oblique`][crate::Style::Oblique] and [`Style::Italic`][crate::Style::Italic] as matches, but not as good
    /// a match as when the styles are equal.
    ///
    /// Note that @old_match must match @self.
    /// ## `old_match`
    /// a [`FontDescription`][crate::FontDescription], or [`None`]
    /// ## `new_match`
    /// a [`FontDescription`][crate::FontDescription]
    ///
    /// # Returns
    ///
    /// [`true`] if @new_match is a better match
    #[doc(alias = "pango_font_description_better_match")]
    pub fn better_match(
        &self,
        old_match: Option<&FontDescription>,
        new_match: &FontDescription,
    ) -> bool {
        unsafe {
            from_glib(ffi::pango_font_description_better_match(
                self.to_glib_none().0,
                old_match.to_glib_none().0,
                new_match.to_glib_none().0,
            ))
        }
    }

    #[doc(alias = "pango_font_description_equal")]
    fn equal(&self, desc2: &FontDescription) -> bool {
        unsafe {
            from_glib(ffi::pango_font_description_equal(
                self.to_glib_none().0,
                desc2.to_glib_none().0,
            ))
        }
    }

    /// Gets the family name field of a font description.
    ///
    /// See [`set_family()`][Self::set_family()].
    ///
    /// # Returns
    ///
    /// the family name field for the
    ///   font description, or [`None`] if not previously set. This has the same
    ///   life-time as the font description itself and should not be freed.
    #[doc(alias = "pango_font_description_get_family")]
    #[doc(alias = "get_family")]
    pub fn family(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::pango_font_description_get_family(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the gravity field of a font description.
    ///
    /// See [`set_gravity()`][Self::set_gravity()].
    ///
    /// # Returns
    ///
    /// the gravity field for the font description.
    ///   Use [`set_fields()`][Self::set_fields()] to find out
    ///   if the field was explicitly set or not.
    #[doc(alias = "pango_font_description_get_gravity")]
    #[doc(alias = "get_gravity")]
    pub fn gravity(&self) -> Gravity {
        unsafe {
            from_glib(ffi::pango_font_description_get_gravity(
                self.to_glib_none().0,
            ))
        }
    }

    /// Determines which fields in a font description have been set.
    ///
    /// # Returns
    ///
    /// a bitmask with bits set corresponding to the
    ///   fields in @self that have been set.
    #[doc(alias = "pango_font_description_get_set_fields")]
    #[doc(alias = "get_set_fields")]
    pub fn set_fields(&self) -> FontMask {
        unsafe {
            from_glib(ffi::pango_font_description_get_set_fields(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the size field of a font description.
    ///
    /// See [`set_size()`][Self::set_size()].
    ///
    /// # Returns
    ///
    /// the size field for the font description in points
    ///   or device units. You must call
    ///   [`is_size_absolute()`][Self::is_size_absolute()] to find out
    ///   which is the case. Returns 0 if the size field has not previously
    ///   been set or it has been set to 0 explicitly.
    ///   Use [`set_fields()`][Self::set_fields()] to find out
    ///   if the field was explicitly set or not.
    #[doc(alias = "pango_font_description_get_size")]
    #[doc(alias = "get_size")]
    pub fn size(&self) -> i32 {
        unsafe { ffi::pango_font_description_get_size(self.to_glib_none().0) }
    }

    /// Determines whether the size of the font is in points (not absolute)
    /// or device units (absolute).
    ///
    /// See [`set_size()`][Self::set_size()]
    /// and [`set_absolute_size()`][Self::set_absolute_size()].
    ///
    /// # Returns
    ///
    /// whether the size for the font description is in
    ///   points or device units. Use [`set_fields()`][Self::set_fields()]
    ///   to find out if the size field of the font description was explicitly
    ///   set or not.
    #[doc(alias = "pango_font_description_get_size_is_absolute")]
    #[doc(alias = "get_size_is_absolute")]
    pub fn is_size_absolute(&self) -> bool {
        unsafe {
            from_glib(ffi::pango_font_description_get_size_is_absolute(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the stretch field of a font description.
    ///
    /// See [`set_stretch()`][Self::set_stretch()].
    ///
    /// # Returns
    ///
    /// the stretch field for the font description.
    ///   Use [`set_fields()`][Self::set_fields()] to find
    ///   out if the field was explicitly set or not.
    #[doc(alias = "pango_font_description_get_stretch")]
    #[doc(alias = "get_stretch")]
    pub fn stretch(&self) -> Stretch {
        unsafe {
            from_glib(ffi::pango_font_description_get_stretch(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the style field of a [`FontDescription`][crate::FontDescription].
    ///
    /// See [`set_style()`][Self::set_style()].
    ///
    /// # Returns
    ///
    /// the style field for the font description.
    ///   Use [`set_fields()`][Self::set_fields()] to
    ///   find out if the field was explicitly set or not.
    #[doc(alias = "pango_font_description_get_style")]
    #[doc(alias = "get_style")]
    pub fn style(&self) -> Style {
        unsafe { from_glib(ffi::pango_font_description_get_style(self.to_glib_none().0)) }
    }

    /// Gets the variant field of a [`FontDescription`][crate::FontDescription].
    ///
    /// See [`set_variant()`][Self::set_variant()].
    ///
    /// # Returns
    ///
    /// the variant field for the font description.
    ///   Use [`set_fields()`][Self::set_fields()] to find
    ///   out if the field was explicitly set or not.
    #[doc(alias = "pango_font_description_get_variant")]
    #[doc(alias = "get_variant")]
    pub fn variant(&self) -> Variant {
        unsafe {
            from_glib(ffi::pango_font_description_get_variant(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the variations field of a font description.
    ///
    /// See [`set_variations()`][Self::set_variations()].
    ///
    /// # Returns
    ///
    /// the variations field for the font
    ///   description, or [`None`] if not previously set. This has the same
    ///   life-time as the font description itself and should not be freed.
    #[cfg(feature = "v1_42")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_42")))]
    #[doc(alias = "pango_font_description_get_variations")]
    #[doc(alias = "get_variations")]
    pub fn variations(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::pango_font_description_get_variations(
                self.to_glib_none().0,
            ))
        }
    }

    /// Gets the weight field of a font description.
    ///
    /// See [`set_weight()`][Self::set_weight()].
    ///
    /// # Returns
    ///
    /// the weight field for the font description.
    ///   Use [`set_fields()`][Self::set_fields()] to find
    ///   out if the field was explicitly set or not.
    #[doc(alias = "pango_font_description_get_weight")]
    #[doc(alias = "get_weight")]
    pub fn weight(&self) -> Weight {
        unsafe {
            from_glib(ffi::pango_font_description_get_weight(
                self.to_glib_none().0,
            ))
        }
    }

    #[doc(alias = "pango_font_description_hash")]
    fn hash(&self) -> u32 {
        unsafe { ffi::pango_font_description_hash(self.to_glib_none().0) }
    }

    /// Merges the fields that are set in @desc_to_merge into the fields in
    /// @self.
    ///
    /// If @replace_existing is [`false`], only fields in @self that
    /// are not already set are affected. If [`true`], then fields that are
    /// already set will be replaced as well.
    ///
    /// If @desc_to_merge is [`None`], this function performs nothing.
    /// ## `desc_to_merge`
    /// the [`FontDescription`][crate::FontDescription] to merge from,
    ///   or [`None`]
    /// ## `replace_existing`
    /// if [`true`], replace fields in @self with the
    ///   corresponding values from @desc_to_merge, even if they
    ///   are already exist.
    #[doc(alias = "pango_font_description_merge")]
    pub fn merge(&mut self, desc_to_merge: Option<&FontDescription>, replace_existing: bool) {
        unsafe {
            ffi::pango_font_description_merge(
                self.to_glib_none_mut().0,
                desc_to_merge.to_glib_none().0,
                replace_existing.into_glib(),
            );
        }
    }

    /// Sets the size field of a font description, in device units.
    ///
    /// This is mutually exclusive with [`set_size()`][Self::set_size()]
    /// which sets the font size in points.
    /// ## `size`
    /// the new size, in Pango units. There are `PANGO_SCALE` Pango units
    ///   in one device unit. For an output backend where a device unit is a pixel,
    ///   a @size value of 10 * PANGO_SCALE gives a 10 pixel font.
    #[doc(alias = "pango_font_description_set_absolute_size")]
    pub fn set_absolute_size(&mut self, size: f64) {
        unsafe {
            ffi::pango_font_description_set_absolute_size(self.to_glib_none_mut().0, size);
        }
    }

    /// Sets the family name field of a font description.
    ///
    /// The family
    /// name represents a family of related font styles, and will
    /// resolve to a particular [`FontFamily`][crate::FontFamily]. In some uses of
    /// [`FontDescription`][crate::FontDescription], it is also possible to use a comma
    /// separated list of family names for this field.
    /// ## `family`
    /// a string representing the family name.
    #[doc(alias = "pango_font_description_set_family")]
    pub fn set_family(&mut self, family: &str) {
        unsafe {
            ffi::pango_font_description_set_family(
                self.to_glib_none_mut().0,
                family.to_glib_none().0,
            );
        }
    }

    /// Sets the gravity field of a font description.
    ///
    /// The gravity field
    /// specifies how the glyphs should be rotated. If @gravity is
    /// [`Gravity::Auto`][crate::Gravity::Auto], this actually unsets the gravity mask on
    /// the font description.
    ///
    /// This function is seldom useful to the user. Gravity should normally
    /// be set on a [`Context`][crate::Context].
    /// ## `gravity`
    /// the gravity for the font description.
    #[doc(alias = "pango_font_description_set_gravity")]
    pub fn set_gravity(&mut self, gravity: Gravity) {
        unsafe {
            ffi::pango_font_description_set_gravity(self.to_glib_none_mut().0, gravity.into_glib());
        }
    }

    /// Sets the size field of a font description in fractional points.
    ///
    /// This is mutually exclusive with
    /// [`set_absolute_size()`][Self::set_absolute_size()].
    /// ## `size`
    /// the size of the font in points, scaled by `PANGO_SCALE`.
    ///   (That is, a @size value of 10 * PANGO_SCALE is a 10 point font.
    ///   The conversion factor between points and device units depends on
    ///   system configuration and the output device. For screen display, a
    ///   logical DPI of 96 is common, in which case a 10 point font corresponds
    ///   to a 10 * (96 / 72) = 13.3 pixel font.
    ///   Use [`set_absolute_size()`][Self::set_absolute_size()] if you need
    ///   a particular size in device units.
    #[doc(alias = "pango_font_description_set_size")]
    pub fn set_size(&mut self, size: i32) {
        unsafe {
            ffi::pango_font_description_set_size(self.to_glib_none_mut().0, size);
        }
    }

    /// Sets the stretch field of a font description.
    ///
    /// The [`Stretch`][crate::Stretch] field specifies how narrow or
    /// wide the font should be.
    /// ## `stretch`
    /// the stretch for the font description
    #[doc(alias = "pango_font_description_set_stretch")]
    pub fn set_stretch(&mut self, stretch: Stretch) {
        unsafe {
            ffi::pango_font_description_set_stretch(self.to_glib_none_mut().0, stretch.into_glib());
        }
    }

    /// Sets the style field of a [`FontDescription`][crate::FontDescription].
    ///
    /// The [`Style`][crate::Style] enumeration describes whether the font is
    /// slanted and the manner in which it is slanted; it can be either
    /// [`Style::Normal`][crate::Style::Normal], [`Style::Italic`][crate::Style::Italic], or [`Style::Oblique`][crate::Style::Oblique].
    ///
    /// Most fonts will either have a italic style or an oblique style,
    /// but not both, and font matching in Pango will match italic
    /// specifications with oblique fonts and vice-versa if an exact
    /// match is not found.
    /// ## `style`
    /// the style for the font description
    #[doc(alias = "pango_font_description_set_style")]
    pub fn set_style(&mut self, style: Style) {
        unsafe {
            ffi::pango_font_description_set_style(self.to_glib_none_mut().0, style.into_glib());
        }
    }

    /// Sets the variant field of a font description.
    ///
    /// The [`Variant`][struct@crate::Variant] can either be [`Variant::Normal`][crate::Variant::Normal]
    /// or [`Variant::SmallCaps`][crate::Variant::SmallCaps].
    /// ## `variant`
    /// the variant type for the font description.
    #[doc(alias = "pango_font_description_set_variant")]
    pub fn set_variant(&mut self, variant: Variant) {
        unsafe {
            ffi::pango_font_description_set_variant(self.to_glib_none_mut().0, variant.into_glib());
        }
    }

    /// Sets the variations field of a font description.
    ///
    /// OpenType font variations allow to select a font instance by
    /// specifying values for a number of axes, such as width or weight.
    ///
    /// The format of the variations string is
    ///
    ///     AXIS1=VALUE,AXIS2=VALUE...
    ///
    /// with each AXIS a 4 character tag that identifies a font axis,
    /// and each VALUE a floating point number. Unknown axes are ignored,
    /// and values are clamped to their allowed range.
    ///
    /// Pango does not currently have a way to find supported axes of
    /// a font. Both harfbuzz and freetype have API for this. See
    /// for example [hb_ot_var_get_axis_infos](https://harfbuzz.github.io/harfbuzz-hb-ot-var.html#hb-ot-var-get-axis-infos).
    /// ## `variations`
    /// a string representing the variations
    #[cfg(feature = "v1_42")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_42")))]
    #[doc(alias = "pango_font_description_set_variations")]
    pub fn set_variations(&mut self, variations: Option<&str>) {
        unsafe {
            ffi::pango_font_description_set_variations(
                self.to_glib_none_mut().0,
                variations.to_glib_none().0,
            );
        }
    }

    /// Sets the variations field of a font description.
    ///
    /// This is like [`set_variations()`][Self::set_variations()], except
    /// that no copy of @variations is made. The caller must make sure that
    /// the string passed in stays around until @self has been freed
    /// or the name is set again. This function can be used if
    /// @variations is a static string such as a C string literal,
    /// or if @self is only needed temporarily.
    /// ## `variations`
    /// a string representing the variations
    #[cfg(feature = "v1_42")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_42")))]
    #[doc(alias = "pango_font_description_set_variations_static")]
    pub fn set_variations_static(&mut self, variations: &str) {
        unsafe {
            ffi::pango_font_description_set_variations_static(
                self.to_glib_none_mut().0,
                variations.to_glib_none().0,
            );
        }
    }

    /// Sets the weight field of a font description.
    ///
    /// The weight field
    /// specifies how bold or light the font should be. In addition
    /// to the values of the [`Weight`][crate::Weight] enumeration, other
    /// intermediate numeric values are possible.
    /// ## `weight`
    /// the weight for the font description.
    #[doc(alias = "pango_font_description_set_weight")]
    pub fn set_weight(&mut self, weight: Weight) {
        unsafe {
            ffi::pango_font_description_set_weight(self.to_glib_none_mut().0, weight.into_glib());
        }
    }

    /// Creates a filename representation of a font description.
    ///
    /// The filename is identical to the result from calling
    /// [`to_str()`][Self::to_str()], but with underscores
    /// instead of characters that are untypical in filenames, and in
    /// lower case only.
    ///
    /// # Returns
    ///
    /// a new string that must be freed with g_free().
    #[doc(alias = "pango_font_description_to_filename")]
    pub fn to_filename(&self) -> Option<glib::GString> {
        unsafe {
            from_glib_full(ffi::pango_font_description_to_filename(
                self.to_glib_none().0,
            ))
        }
    }

    /// Creates a string representation of a font description.
    ///
    /// See [`from_string()`][Self::from_string()] for a description
    /// of the format of the string representation. The family list in
    /// the string description will only have a terminating comma if
    /// the last word of the list is a valid style option.
    ///
    /// # Returns
    ///
    /// a new string that must be freed with g_free().
    #[doc(alias = "pango_font_description_to_string")]
    #[doc(alias = "to_string")]
    pub fn to_str(&self) -> glib::GString {
        unsafe { from_glib_full(ffi::pango_font_description_to_string(self.to_glib_none().0)) }
    }

    /// Unsets some of the fields in a [`FontDescription`][crate::FontDescription].
    ///
    /// The unset fields will get back to their default values.
    /// ## `to_unset`
    /// bitmask of fields in the @self to unset.
    #[doc(alias = "pango_font_description_unset_fields")]
    pub fn unset_fields(&mut self, to_unset: FontMask) {
        unsafe {
            ffi::pango_font_description_unset_fields(
                self.to_glib_none_mut().0,
                to_unset.into_glib(),
            );
        }
    }

    /// Creates a new font description from a string representation.
    ///
    /// The string must have the form
    ///
    ///     "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS]",
    ///
    /// where FAMILY-LIST is a comma-separated list of families optionally
    /// terminated by a comma, STYLE_OPTIONS is a whitespace-separated list
    /// of words where each word describes one of style, variant, weight,
    /// stretch, or gravity, and SIZE is a decimal number (size in points)
    /// or optionally followed by the unit modifier "px" for absolute size.
    /// VARIATIONS is a comma-separated list of font variation
    /// specifications of the form @‍axis=value (the = sign is optional).
    ///
    /// The following words are understood as styles:
    /// "Normal", "Roman", "Oblique", "Italic".
    ///
    /// The following words are understood as variants:
    /// "Small-Caps", "All-Small-Caps", "Petite-Caps", "All-Petite-Caps",
    /// "Unicase", "Title-Caps".
    ///
    /// The following words are understood as weights:
    /// "Thin", "Ultra-Light", "Extra-Light", "Light", "Semi-Light",
    /// "Demi-Light", "Book", "Regular", "Medium", "Semi-Bold", "Demi-Bold",
    /// "Bold", "Ultra-Bold", "Extra-Bold", "Heavy", "Black", "Ultra-Black",
    /// "Extra-Black".
    ///
    /// The following words are understood as stretch values:
    /// "Ultra-Condensed", "Extra-Condensed", "Condensed", "Semi-Condensed",
    /// "Semi-Expanded", "Expanded", "Extra-Expanded", "Ultra-Expanded".
    ///
    /// The following words are understood as gravity values:
    /// "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left",
    /// "East", "Rotated-Right", "West".
    ///
    /// Any one of the options may be absent. If FAMILY-LIST is absent, then
    /// the family_name field of the resulting font description will be
    /// initialized to [`None`]. If STYLE-OPTIONS is missing, then all style
    /// options will be set to the default values. If SIZE is missing, the
    /// size in the resulting font description will be set to 0.
    ///
    /// A typical example:
    ///
    ///     "Cantarell Italic Light 15 @‍wght=200"
    /// ## `str`
    /// string representation of a font description.
    ///
    /// # Returns
    ///
    /// a new [`FontDescription`][crate::FontDescription].
    #[doc(alias = "pango_font_description_from_string")]
    pub fn from_string(str: &str) -> FontDescription {
        unsafe {
            from_glib_full(ffi::pango_font_description_from_string(
                str.to_glib_none().0,
            ))
        }
    }
}

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

impl PartialEq for FontDescription {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.equal(other)
    }
}

impl Eq for FontDescription {}

impl std::fmt::Display for FontDescription {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.write_str(&self.to_str())
    }
}

impl std::hash::Hash for FontDescription {
    #[inline]
    fn hash<H>(&self, state: &mut H)
    where
        H: std::hash::Hasher,
    {
        std::hash::Hash::hash(&self.hash(), state)
    }
}

unsafe impl Send for FontDescription {}
unsafe impl Sync for FontDescription {}