pango/auto/
font_map.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, Context, Font, FontDescription, FontFamily, Fontset, Language};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// A [`FontMap`][crate::FontMap] represents the set of fonts available for a
10    /// particular rendering system.
11    ///
12    /// This is a virtual object with implementations being specific to
13    /// particular rendering systems.
14    ///
15    /// This is an Abstract Base Class, you cannot instantiate it.
16    ///
17    /// ## Properties
18    ///
19    ///
20    /// #### `item-type`
21    ///  The type of items contained in this list.
22    ///
23    /// Readable
24    ///
25    ///
26    /// #### `n-items`
27    ///  The number of items contained in this list.
28    ///
29    /// Readable
30    ///
31    /// # Implements
32    ///
33    /// [`FontMapExt`][trait@crate::prelude::FontMapExt], [`trait@gio::prelude::ListModelExt`]
34    #[doc(alias = "PangoFontMap")]
35    pub struct FontMap(Object<ffi::PangoFontMap, ffi::PangoFontMapClass>) @implements gio::ListModel;
36
37    match fn {
38        type_ => || ffi::pango_font_map_get_type(),
39    }
40}
41
42impl FontMap {
43    pub const NONE: Option<&'static FontMap> = None;
44}
45
46/// Trait containing all [`struct@FontMap`] methods.
47///
48/// # Implementors
49///
50/// [`FontMap`][struct@crate::FontMap]
51pub trait FontMapExt: IsA<FontMap> + 'static {
52    /// Loads a font file with one or more fonts into the [`FontMap`][crate::FontMap].
53    ///
54    /// The added fonts will take precedence over preexisting
55    /// fonts with the same name.
56    /// ## `filename`
57    /// Path to the font file
58    ///
59    /// # Returns
60    ///
61    /// True if the font file is successfully loaded
62    ///     into the fontmap, false if an error occurred.
63    #[cfg(feature = "v1_56")]
64    #[cfg_attr(docsrs, doc(cfg(feature = "v1_56")))]
65    #[doc(alias = "pango_font_map_add_font_file")]
66    fn add_font_file(&self, filename: impl AsRef<std::path::Path>) -> Result<(), glib::Error> {
67        unsafe {
68            let mut error = std::ptr::null_mut();
69            let is_ok = ffi::pango_font_map_add_font_file(
70                self.as_ref().to_glib_none().0,
71                filename.as_ref().to_glib_none().0,
72                &mut error,
73            );
74            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
75            if error.is_null() {
76                Ok(())
77            } else {
78                Err(from_glib_full(error))
79            }
80        }
81    }
82
83    /// Forces a change in the context, which will cause any [`Context`][crate::Context]
84    /// using this fontmap to change.
85    ///
86    /// This function is only useful when implementing a new backend
87    /// for Pango, something applications won't do. Backends should
88    /// call this function if they have attached extra data to the
89    /// context and such data is changed.
90    #[doc(alias = "pango_font_map_changed")]
91    fn changed(&self) {
92        unsafe {
93            ffi::pango_font_map_changed(self.as_ref().to_glib_none().0);
94        }
95    }
96
97    /// Creates a [`Context`][crate::Context] connected to @self.
98    ///
99    /// This is equivalent to [`Context::new()`][crate::Context::new()] followed by
100    /// [`Context::set_font_map()`][crate::Context::set_font_map()].
101    ///
102    /// If you are using Pango as part of a higher-level system,
103    /// that system may have it's own way of create a [`Context`][crate::Context].
104    /// For instance, the GTK toolkit has, among others,
105    /// gtk_widget_get_pango_context(). Use those instead.
106    ///
107    /// # Returns
108    ///
109    /// the newly allocated [`Context`][crate::Context],
110    ///   which should be freed with g_object_unref().
111    #[doc(alias = "pango_font_map_create_context")]
112    fn create_context(&self) -> Context {
113        unsafe {
114            from_glib_full(ffi::pango_font_map_create_context(
115                self.as_ref().to_glib_none().0,
116            ))
117        }
118    }
119
120    /// Gets a font family by name.
121    /// ## `name`
122    /// a family name
123    ///
124    /// # Returns
125    ///
126    /// the [`FontFamily`][crate::FontFamily]
127    #[cfg(feature = "v1_46")]
128    #[cfg_attr(docsrs, doc(cfg(feature = "v1_46")))]
129    #[doc(alias = "pango_font_map_get_family")]
130    #[doc(alias = "get_family")]
131    fn family(&self, name: &str) -> FontFamily {
132        unsafe {
133            from_glib_none(ffi::pango_font_map_get_family(
134                self.as_ref().to_glib_none().0,
135                name.to_glib_none().0,
136            ))
137        }
138    }
139
140    /// Returns the current serial number of @self.
141    ///
142    /// The serial number is initialized to an small number larger than zero
143    /// when a new fontmap is created and is increased whenever the fontmap
144    /// is changed. It may wrap, but will never have the value 0. Since it can
145    /// wrap, never compare it with "less than", always use "not equals".
146    ///
147    /// The fontmap can only be changed using backend-specific API, like changing
148    /// fontmap resolution.
149    ///
150    /// This can be used to automatically detect changes to a [`FontMap`][crate::FontMap],
151    /// like in [`Context`][crate::Context].
152    ///
153    /// # Returns
154    ///
155    /// The current serial number of @self.
156    #[doc(alias = "pango_font_map_get_serial")]
157    #[doc(alias = "get_serial")]
158    fn serial(&self) -> u32 {
159        unsafe { ffi::pango_font_map_get_serial(self.as_ref().to_glib_none().0) }
160    }
161
162    /// List all families for a fontmap.
163    ///
164    /// Note that the returned families are not in any particular order.
165    ///
166    /// [`FontMap`][crate::FontMap] also implemented the [`gio::ListModel`][crate::gio::ListModel] interface
167    /// for enumerating families.
168    ///
169    /// # Returns
170    ///
171    ///
172    /// ## `families`
173    /// location to
174    ///   store a pointer to an array of [`FontFamily`][crate::FontFamily] *.
175    ///   This array should be freed with g_free().
176    #[doc(alias = "pango_font_map_list_families")]
177    fn list_families(&self) -> Vec<FontFamily> {
178        unsafe {
179            let mut families = std::ptr::null_mut();
180            let mut n_families = std::mem::MaybeUninit::uninit();
181            ffi::pango_font_map_list_families(
182                self.as_ref().to_glib_none().0,
183                &mut families,
184                n_families.as_mut_ptr(),
185            );
186            FromGlibContainer::from_glib_container_num(families, n_families.assume_init() as _)
187        }
188    }
189
190    /// Load the font in the fontmap that is the closest match for @desc.
191    /// ## `context`
192    /// the [`Context`][crate::Context] the font will be used with
193    /// ## `desc`
194    /// a [`FontDescription`][crate::FontDescription] describing the font to load
195    ///
196    /// # Returns
197    ///
198    /// the newly allocated [`Font`][crate::Font]
199    ///   loaded, or [`None`] if no font matched.
200    #[doc(alias = "pango_font_map_load_font")]
201    fn load_font(&self, context: &Context, desc: &FontDescription) -> Option<Font> {
202        unsafe {
203            from_glib_full(ffi::pango_font_map_load_font(
204                self.as_ref().to_glib_none().0,
205                context.to_glib_none().0,
206                desc.to_glib_none().0,
207            ))
208        }
209    }
210
211    /// Load a set of fonts in the fontmap that can be used to render
212    /// a font matching @desc.
213    /// ## `context`
214    /// the [`Context`][crate::Context] the font will be used with
215    /// ## `desc`
216    /// a [`FontDescription`][crate::FontDescription] describing the font to load
217    /// ## `language`
218    /// a [`Language`][crate::Language] the fonts will be used for
219    ///
220    /// # Returns
221    ///
222    /// the newly allocated
223    ///   [`Fontset`][crate::Fontset] loaded, or [`None`] if no font matched.
224    #[doc(alias = "pango_font_map_load_fontset")]
225    fn load_fontset(
226        &self,
227        context: &Context,
228        desc: &FontDescription,
229        language: &Language,
230    ) -> Option<Fontset> {
231        unsafe {
232            from_glib_full(ffi::pango_font_map_load_fontset(
233                self.as_ref().to_glib_none().0,
234                context.to_glib_none().0,
235                desc.to_glib_none().0,
236                mut_override(language.to_glib_none().0),
237            ))
238        }
239    }
240
241    /// Returns a new font that is like @font, except that its size
242    /// is multiplied by @scale, its backend-dependent configuration
243    /// (e.g. cairo font options) is replaced by the one in @context,
244    /// and its variations are replaced by @variations.
245    /// ## `font`
246    /// a font in @self
247    /// ## `scale`
248    /// the scale factor to apply
249    /// ## `context`
250    /// a [`Context`][crate::Context]
251    /// ## `variations`
252    /// font variations to use
253    ///
254    /// # Returns
255    ///
256    /// the modified font
257    #[cfg(feature = "v1_52")]
258    #[cfg_attr(docsrs, doc(cfg(feature = "v1_52")))]
259    #[doc(alias = "pango_font_map_reload_font")]
260    fn reload_font(
261        &self,
262        font: &impl IsA<Font>,
263        scale: f64,
264        context: Option<&Context>,
265        variations: Option<&str>,
266    ) -> Font {
267        unsafe {
268            from_glib_full(ffi::pango_font_map_reload_font(
269                self.as_ref().to_glib_none().0,
270                font.as_ref().to_glib_none().0,
271                scale,
272                context.to_glib_none().0,
273                variations.to_glib_none().0,
274            ))
275        }
276    }
277}
278
279impl<O: IsA<FontMap>> FontMapExt for O {}