pango/auto/
font.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
5#[cfg(feature = "v1_50")]
6#[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
7use crate::Context;
8#[cfg(feature = "v1_46")]
9#[cfg_attr(docsrs, doc(cfg(feature = "v1_46")))]
10use crate::FontFace;
11use crate::{ffi, Coverage, FontDescription, FontMap, FontMetrics, Glyph, Language, Rectangle};
12use glib::{prelude::*, translate::*};
13
14glib::wrapper! {
15    /// A [`Font`][crate::Font] is used to represent a font in a
16    /// rendering-system-independent manner.
17    ///
18    /// This is an Abstract Base Class, you cannot instantiate it.
19    ///
20    /// # Implements
21    ///
22    /// [`FontExt`][trait@crate::prelude::FontExt]
23    #[doc(alias = "PangoFont")]
24    pub struct Font(Object<ffi::PangoFont, ffi::PangoFontClass>);
25
26    match fn {
27        type_ => || ffi::pango_font_get_type(),
28    }
29}
30
31impl Font {
32    pub const NONE: Option<&'static Font> = None;
33
34    /// Loads data previously created via [`FontExt::serialize()`][crate::prelude::FontExt::serialize()].
35    ///
36    /// For a discussion of the supported format, see that function.
37    ///
38    /// Note: to verify that the returned font is identical to
39    /// the one that was serialized, you can compare @bytes to the
40    /// result of serializing the font again.
41    /// ## `context`
42    /// a [`Context`][crate::Context]
43    /// ## `bytes`
44    /// the bytes containing the data
45    ///
46    /// # Returns
47    ///
48    /// a new [`Font`][crate::Font]
49    #[cfg(feature = "v1_50")]
50    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
51    #[doc(alias = "pango_font_deserialize")]
52    pub fn deserialize(
53        context: &Context,
54        bytes: &glib::Bytes,
55    ) -> Result<Option<Font>, glib::Error> {
56        unsafe {
57            let mut error = std::ptr::null_mut();
58            let ret = ffi::pango_font_deserialize(
59                context.to_glib_none().0,
60                bytes.to_glib_none().0,
61                &mut error,
62            );
63            if error.is_null() {
64                Ok(from_glib_full(ret))
65            } else {
66                Err(from_glib_full(error))
67            }
68        }
69    }
70}
71
72mod sealed {
73    pub trait Sealed {}
74    impl<T: super::IsA<super::Font>> Sealed for T {}
75}
76
77/// Trait containing all [`struct@Font`] methods.
78///
79/// # Implementors
80///
81/// [`Font`][struct@crate::Font]
82pub trait FontExt: IsA<Font> + sealed::Sealed + 'static {
83    /// Returns a description of the font, with font size set in points.
84    ///
85    /// Use [`describe_with_absolute_size()`][Self::describe_with_absolute_size()] if you want
86    /// the font size in device units.
87    ///
88    /// # Returns
89    ///
90    /// a newly-allocated [`FontDescription`][crate::FontDescription] object.
91    #[doc(alias = "pango_font_describe")]
92    fn describe(&self) -> FontDescription {
93        unsafe { from_glib_full(ffi::pango_font_describe(self.as_ref().to_glib_none().0)) }
94    }
95
96    /// Returns a description of the font, with absolute font size set
97    /// in device units.
98    ///
99    /// Use [`describe()`][Self::describe()] if you want the font size in points.
100    ///
101    /// # Returns
102    ///
103    /// a newly-allocated [`FontDescription`][crate::FontDescription] object.
104    #[doc(alias = "pango_font_describe_with_absolute_size")]
105    fn describe_with_absolute_size(&self) -> FontDescription {
106        unsafe {
107            from_glib_full(ffi::pango_font_describe_with_absolute_size(
108                self.as_ref().to_glib_none().0,
109            ))
110        }
111    }
112
113    /// Computes the coverage map for a given font and language tag.
114    /// ## `language`
115    /// the language tag
116    ///
117    /// # Returns
118    ///
119    /// a newly-allocated [`Coverage`][crate::Coverage]
120    ///   object.
121    #[doc(alias = "pango_font_get_coverage")]
122    #[doc(alias = "get_coverage")]
123    fn coverage(&self, language: &Language) -> Coverage {
124        unsafe {
125            from_glib_full(ffi::pango_font_get_coverage(
126                self.as_ref().to_glib_none().0,
127                mut_override(language.to_glib_none().0),
128            ))
129        }
130    }
131
132    /// Gets the [`FontFace`][crate::FontFace] to which @self belongs.
133    ///
134    /// # Returns
135    ///
136    /// the [`FontFace`][crate::FontFace]
137    #[cfg(feature = "v1_46")]
138    #[cfg_attr(docsrs, doc(cfg(feature = "v1_46")))]
139    #[doc(alias = "pango_font_get_face")]
140    #[doc(alias = "get_face")]
141    fn face(&self) -> FontFace {
142        unsafe { from_glib_none(ffi::pango_font_get_face(self.as_ref().to_glib_none().0)) }
143    }
144
145    //#[cfg(feature = "v1_44")]
146    //#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
147    //#[doc(alias = "pango_font_get_features")]
148    //#[doc(alias = "get_features")]
149    //fn features(&self, features: /*Unimplemented*/&mut Basic: Pointer, len: u32, num_features: &mut u32) {
150    //    unsafe { TODO: call ffi:pango_font_get_features() }
151    //}
152
153    /// Gets the font map for which the font was created.
154    ///
155    /// Note that the font maintains a *weak* reference to
156    /// the font map, so if all references to font map are
157    /// dropped, the font map will be finalized even if there
158    /// are fonts created with the font map that are still alive.
159    /// In that case this function will return [`None`].
160    ///
161    /// It is the responsibility of the user to ensure that the
162    /// font map is kept alive. In most uses this is not an issue
163    /// as a [`Context`][crate::Context] holds a reference to the font map.
164    ///
165    /// # Returns
166    ///
167    /// the [`FontMap`][crate::FontMap]
168    ///   for the font
169    #[doc(alias = "pango_font_get_font_map")]
170    #[doc(alias = "get_font_map")]
171    fn font_map(&self) -> Option<FontMap> {
172        unsafe { from_glib_none(ffi::pango_font_get_font_map(self.as_ref().to_glib_none().0)) }
173    }
174
175    /// Gets the logical and ink extents of a glyph within a font.
176    ///
177    /// The coordinate system for each rectangle has its origin at the
178    /// base line and horizontal origin of the character with increasing
179    /// coordinates extending to the right and down. The macros PANGO_ASCENT(),
180    /// PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert
181    /// from the extents rectangle to more traditional font metrics. The units
182    /// of the rectangles are in 1/PANGO_SCALE of a device unit.
183    ///
184    /// If @self is [`None`], this function gracefully sets some sane values in the
185    /// output variables and returns.
186    /// ## `glyph`
187    /// the glyph index
188    ///
189    /// # Returns
190    ///
191    ///
192    /// ## `ink_rect`
193    /// rectangle used to store the extents of the glyph as drawn
194    ///
195    /// ## `logical_rect`
196    /// rectangle used to store the logical extents of the glyph
197    #[doc(alias = "pango_font_get_glyph_extents")]
198    #[doc(alias = "get_glyph_extents")]
199    fn glyph_extents(&self, glyph: Glyph) -> (Rectangle, Rectangle) {
200        unsafe {
201            let mut ink_rect = Rectangle::uninitialized();
202            let mut logical_rect = Rectangle::uninitialized();
203            ffi::pango_font_get_glyph_extents(
204                self.as_ref().to_glib_none().0,
205                glyph,
206                ink_rect.to_glib_none_mut().0,
207                logical_rect.to_glib_none_mut().0,
208            );
209            (ink_rect, logical_rect)
210        }
211    }
212
213    //#[cfg(feature = "v1_44")]
214    //#[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
215    //#[doc(alias = "pango_font_get_hb_font")]
216    //#[doc(alias = "get_hb_font")]
217    //fn hb_font(&self) -> /*Ignored*/Option<harf_buzz::font_t> {
218    //    unsafe { TODO: call ffi:pango_font_get_hb_font() }
219    //}
220
221    /// Returns the languages that are supported by @self.
222    ///
223    /// If the font backend does not provide this information,
224    /// [`None`] is returned. For the fontconfig backend, this
225    /// corresponds to the FC_LANG member of the FcPattern.
226    ///
227    /// The returned array is only valid as long as the font
228    /// and its fontmap are valid.
229    ///
230    /// # Returns
231    ///
232    /// an array of [`Language`][crate::Language]
233    #[cfg(feature = "v1_50")]
234    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
235    #[doc(alias = "pango_font_get_languages")]
236    #[doc(alias = "get_languages")]
237    fn languages(&self) -> Vec<Language> {
238        unsafe {
239            FromGlibPtrContainer::from_glib_none(ffi::pango_font_get_languages(
240                self.as_ref().to_glib_none().0,
241            ))
242        }
243    }
244
245    /// Gets overall metric information for a font.
246    ///
247    /// Since the metrics may be substantially different for different scripts,
248    /// a language tag can be provided to indicate that the metrics should be
249    /// retrieved that correspond to the script(s) used by that language.
250    ///
251    /// If @self is [`None`], this function gracefully sets some sane values in the
252    /// output variables and returns.
253    /// ## `language`
254    /// language tag used to determine which script
255    ///   to get the metrics for, or [`None`] to indicate to get the metrics for
256    ///   the entire font.
257    ///
258    /// # Returns
259    ///
260    /// a [`FontMetrics`][crate::FontMetrics] object. The caller must call
261    ///   `Pango::FontMetrics::unref()` when finished using the object.
262    #[doc(alias = "pango_font_get_metrics")]
263    #[doc(alias = "get_metrics")]
264    fn metrics(&self, language: Option<&Language>) -> FontMetrics {
265        unsafe {
266            from_glib_full(ffi::pango_font_get_metrics(
267                self.as_ref().to_glib_none().0,
268                mut_override(language.to_glib_none().0),
269            ))
270        }
271    }
272
273    /// Returns whether the font provides a glyph for this character.
274    /// ## `wc`
275    /// a Unicode character
276    ///
277    /// # Returns
278    ///
279    /// `TRUE` if @self can render @wc
280    #[cfg(feature = "v1_44")]
281    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
282    #[doc(alias = "pango_font_has_char")]
283    fn has_char(&self, wc: char) -> bool {
284        unsafe {
285            from_glib(ffi::pango_font_has_char(
286                self.as_ref().to_glib_none().0,
287                wc.into_glib(),
288            ))
289        }
290    }
291
292    /// Serializes the @self in a way that can be uniquely identified.
293    ///
294    /// There are no guarantees about the format of the output across different
295    /// versions of Pango.
296    ///
297    /// The intended use of this function is testing, benchmarking and debugging.
298    /// The format is not meant as a permanent storage format.
299    ///
300    /// To recreate a font from its serialized form, use [`Font::deserialize()`][crate::Font::deserialize()].
301    ///
302    /// # Returns
303    ///
304    /// a `GBytes` containing the serialized form of @self
305    #[cfg(feature = "v1_50")]
306    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
307    #[doc(alias = "pango_font_serialize")]
308    fn serialize(&self) -> glib::Bytes {
309        unsafe { from_glib_full(ffi::pango_font_serialize(self.as_ref().to_glib_none().0)) }
310    }
311}
312
313impl<O: IsA<Font>> FontExt for O {}