pango/auto/
context.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::{
6    ffi, Direction, Font, FontDescription, FontFamily, FontMap, FontMetrics, Fontset, Gravity,
7    GravityHint, Language, Matrix,
8};
9use glib::{prelude::*, translate::*};
10
11glib::wrapper! {
12    /// A [`Context`][crate::Context] stores global information used to control the
13    /// itemization process.
14    ///
15    /// The information stored by [`Context`][crate::Context] includes the fontmap used
16    /// to look up fonts, and default values such as the default language,
17    /// default gravity, or default font.
18    ///
19    /// To obtain a [`Context`][crate::Context], use [`FontMapExt::create_context()`][crate::prelude::FontMapExt::create_context()].
20    #[doc(alias = "PangoContext")]
21    pub struct Context(Object<ffi::PangoContext, ffi::PangoContextClass>);
22
23    match fn {
24        type_ => || ffi::pango_context_get_type(),
25    }
26}
27
28impl Context {
29    /// Creates a new [`Context`][crate::Context] initialized to default values.
30    ///
31    /// This function is not particularly useful as it should always
32    /// be followed by a [`set_font_map()`][Self::set_font_map()] call, and the
33    /// function [`FontMapExt::create_context()`][crate::prelude::FontMapExt::create_context()] does these two steps
34    /// together and hence users are recommended to use that.
35    ///
36    /// If you are using Pango as part of a higher-level system,
37    /// that system may have it's own way of create a [`Context`][crate::Context].
38    /// For instance, the GTK toolkit has, among others,
39    /// `gtk_widget_get_pango_context()`. Use those instead.
40    ///
41    /// # Returns
42    ///
43    /// the newly allocated [`Context`][crate::Context], which should
44    ///   be freed with g_object_unref().
45    #[doc(alias = "pango_context_new")]
46    pub fn new() -> Context {
47        unsafe { from_glib_full(ffi::pango_context_new()) }
48    }
49
50    /// Forces a change in the context, which will cause any [`Layout`][crate::Layout]
51    /// using this context to re-layout.
52    ///
53    /// This function is only useful when implementing a new backend
54    /// for Pango, something applications won't do. Backends should
55    /// call this function if they have attached extra data to the context
56    /// and such data is changed.
57    #[doc(alias = "pango_context_changed")]
58    pub fn changed(&self) {
59        unsafe {
60            ffi::pango_context_changed(self.to_glib_none().0);
61        }
62    }
63
64    /// Retrieves the base direction for the context.
65    ///
66    /// See [`set_base_dir()`][Self::set_base_dir()].
67    ///
68    /// # Returns
69    ///
70    /// the base direction for the context.
71    #[doc(alias = "pango_context_get_base_dir")]
72    #[doc(alias = "get_base_dir")]
73    pub fn base_dir(&self) -> Direction {
74        unsafe { from_glib(ffi::pango_context_get_base_dir(self.to_glib_none().0)) }
75    }
76
77    /// Retrieves the base gravity for the context.
78    ///
79    /// See [`set_base_gravity()`][Self::set_base_gravity()].
80    ///
81    /// # Returns
82    ///
83    /// the base gravity for the context.
84    #[doc(alias = "pango_context_get_base_gravity")]
85    #[doc(alias = "get_base_gravity")]
86    pub fn base_gravity(&self) -> Gravity {
87        unsafe { from_glib(ffi::pango_context_get_base_gravity(self.to_glib_none().0)) }
88    }
89
90    /// Retrieve the default font description for the context.
91    ///
92    /// # Returns
93    ///
94    /// a pointer to the context's default font
95    ///   description. This value must not be modified or freed.
96    #[doc(alias = "pango_context_get_font_description")]
97    #[doc(alias = "get_font_description")]
98    pub fn font_description(&self) -> Option<FontDescription> {
99        unsafe {
100            from_glib_none(ffi::pango_context_get_font_description(
101                self.to_glib_none().0,
102            ))
103        }
104    }
105
106    /// Gets the [`FontMap`][crate::FontMap] used to look up fonts for this context.
107    ///
108    /// # Returns
109    ///
110    /// the font map for the.
111    ///   [`Context`][crate::Context] This value is owned by Pango and should not be
112    ///   unreferenced.
113    #[doc(alias = "pango_context_get_font_map")]
114    #[doc(alias = "get_font_map")]
115    pub fn font_map(&self) -> Option<FontMap> {
116        unsafe { from_glib_none(ffi::pango_context_get_font_map(self.to_glib_none().0)) }
117    }
118
119    /// Retrieves the gravity for the context.
120    ///
121    /// This is similar to [`base_gravity()`][Self::base_gravity()],
122    /// except for when the base gravity is [`Gravity::Auto`][crate::Gravity::Auto] for
123    /// which [`Gravity::for_matrix()`][crate::Gravity::for_matrix()] is used to return the
124    /// gravity from the current context matrix.
125    ///
126    /// # Returns
127    ///
128    /// the resolved gravity for the context.
129    #[doc(alias = "pango_context_get_gravity")]
130    #[doc(alias = "get_gravity")]
131    pub fn gravity(&self) -> Gravity {
132        unsafe { from_glib(ffi::pango_context_get_gravity(self.to_glib_none().0)) }
133    }
134
135    /// Retrieves the gravity hint for the context.
136    ///
137    /// See [`set_gravity_hint()`][Self::set_gravity_hint()] for details.
138    ///
139    /// # Returns
140    ///
141    /// the gravity hint for the context.
142    #[doc(alias = "pango_context_get_gravity_hint")]
143    #[doc(alias = "get_gravity_hint")]
144    pub fn gravity_hint(&self) -> GravityHint {
145        unsafe { from_glib(ffi::pango_context_get_gravity_hint(self.to_glib_none().0)) }
146    }
147
148    /// Retrieves the global language tag for the context.
149    ///
150    /// # Returns
151    ///
152    /// the global language tag.
153    #[doc(alias = "pango_context_get_language")]
154    #[doc(alias = "get_language")]
155    pub fn language(&self) -> Option<Language> {
156        unsafe { from_glib_none(ffi::pango_context_get_language(self.to_glib_none().0)) }
157    }
158
159    /// Gets the transformation matrix that will be applied when
160    /// rendering with this context.
161    ///
162    /// See [`set_matrix()`][Self::set_matrix()].
163    ///
164    /// # Returns
165    ///
166    /// the matrix, or [`None`] if no
167    ///   matrix has been set (which is the same as the identity matrix).
168    ///   The returned matrix is owned by Pango and must not be modified
169    ///   or freed.
170    #[doc(alias = "pango_context_get_matrix")]
171    #[doc(alias = "get_matrix")]
172    pub fn matrix(&self) -> Option<Matrix> {
173        unsafe { from_glib_none(ffi::pango_context_get_matrix(self.to_glib_none().0)) }
174    }
175
176    /// Get overall metric information for a particular font description.
177    ///
178    /// Since the metrics may be substantially different for different scripts,
179    /// a language tag can be provided to indicate that the metrics should be
180    /// retrieved that correspond to the script(s) used by that language.
181    ///
182    /// The [`FontDescription`][crate::FontDescription] is interpreted in the same way as by [`itemize()`][crate::itemize()],
183    /// and the family name may be a comma separated list of names. If characters
184    /// from multiple of these families would be used to render the string, then
185    /// the returned fonts would be a composite of the metrics for the fonts loaded
186    /// for the individual families.
187    /// ## `desc`
188    /// a [`FontDescription`][crate::FontDescription] structure. [`None`] means that the
189    ///   font description from the context will be used.
190    /// ## `language`
191    /// language tag used to determine which script to get
192    ///   the metrics for. [`None`] means that the language tag from the context
193    ///   will be used. If no language tag is set on the context, metrics
194    ///   for the default language (as determined by [`Language::default()`][crate::Language::default()]
195    ///   will be returned.
196    ///
197    /// # Returns
198    ///
199    /// a [`FontMetrics`][crate::FontMetrics] object. The caller must call
200    ///   `Pango::FontMetrics::unref()` when finished using the object.
201    #[doc(alias = "pango_context_get_metrics")]
202    #[doc(alias = "get_metrics")]
203    pub fn metrics(
204        &self,
205        desc: Option<&FontDescription>,
206        language: Option<&Language>,
207    ) -> FontMetrics {
208        unsafe {
209            from_glib_full(ffi::pango_context_get_metrics(
210                self.to_glib_none().0,
211                desc.to_glib_none().0,
212                mut_override(language.to_glib_none().0),
213            ))
214        }
215    }
216
217    /// Returns whether font rendering with this context should
218    /// round glyph positions and widths.
219    #[cfg(feature = "v1_44")]
220    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
221    #[doc(alias = "pango_context_get_round_glyph_positions")]
222    #[doc(alias = "get_round_glyph_positions")]
223    pub fn is_round_glyph_positions(&self) -> bool {
224        unsafe {
225            from_glib(ffi::pango_context_get_round_glyph_positions(
226                self.to_glib_none().0,
227            ))
228        }
229    }
230
231    /// Returns the current serial number of @self.
232    ///
233    /// The serial number is initialized to an small number larger than zero
234    /// when a new context is created and is increased whenever the context
235    /// is changed using any of the setter functions, or the [`FontMap`][crate::FontMap] it
236    /// uses to find fonts has changed. The serial may wrap, but will never
237    /// have the value 0. Since it can wrap, never compare it with "less than",
238    /// always use "not equals".
239    ///
240    /// This can be used to automatically detect changes to a [`Context`][crate::Context],
241    /// and is only useful when implementing objects that need update when their
242    /// [`Context`][crate::Context] changes, like [`Layout`][crate::Layout].
243    ///
244    /// # Returns
245    ///
246    /// The current serial number of @self.
247    #[doc(alias = "pango_context_get_serial")]
248    #[doc(alias = "get_serial")]
249    pub fn serial(&self) -> u32 {
250        unsafe { ffi::pango_context_get_serial(self.to_glib_none().0) }
251    }
252
253    /// List all families for a context.
254    ///
255    /// # Returns
256    ///
257    ///
258    /// ## `families`
259    /// location
260    ///   to store a pointer to an array of [`FontFamily`][crate::FontFamily]. This array should
261    ///   be freed with g_free().
262    #[doc(alias = "pango_context_list_families")]
263    pub fn list_families(&self) -> Vec<FontFamily> {
264        unsafe {
265            let mut families = std::ptr::null_mut();
266            let mut n_families = std::mem::MaybeUninit::uninit();
267            ffi::pango_context_list_families(
268                self.to_glib_none().0,
269                &mut families,
270                n_families.as_mut_ptr(),
271            );
272            FromGlibContainer::from_glib_container_num(families, n_families.assume_init() as _)
273        }
274    }
275
276    /// Loads the font in one of the fontmaps in the context
277    /// that is the closest match for @desc.
278    /// ## `desc`
279    /// a [`FontDescription`][crate::FontDescription] describing the font to load
280    ///
281    /// # Returns
282    ///
283    /// the newly allocated [`Font`][crate::Font]
284    ///   that was loaded, or [`None`] if no font matched.
285    #[doc(alias = "pango_context_load_font")]
286    pub fn load_font(&self, desc: &FontDescription) -> Option<Font> {
287        unsafe {
288            from_glib_full(ffi::pango_context_load_font(
289                self.to_glib_none().0,
290                desc.to_glib_none().0,
291            ))
292        }
293    }
294
295    /// Load a set of fonts in the context that can be used to render
296    /// a font matching @desc.
297    /// ## `desc`
298    /// a [`FontDescription`][crate::FontDescription] describing the fonts to load
299    /// ## `language`
300    /// a [`Language`][crate::Language] the fonts will be used for
301    ///
302    /// # Returns
303    ///
304    /// the newly allocated
305    ///   [`Fontset`][crate::Fontset] loaded, or [`None`] if no font matched.
306    #[doc(alias = "pango_context_load_fontset")]
307    pub fn load_fontset(&self, desc: &FontDescription, language: &Language) -> Option<Fontset> {
308        unsafe {
309            from_glib_full(ffi::pango_context_load_fontset(
310                self.to_glib_none().0,
311                desc.to_glib_none().0,
312                mut_override(language.to_glib_none().0),
313            ))
314        }
315    }
316
317    /// Sets the base direction for the context.
318    ///
319    /// The base direction is used in applying the Unicode bidirectional
320    /// algorithm; if the @direction is [`Direction::Ltr`][crate::Direction::Ltr] or
321    /// [`Direction::Rtl`][crate::Direction::Rtl], then the value will be used as the paragraph
322    /// direction in the Unicode bidirectional algorithm. A value of
323    /// [`Direction::WeakLtr`][crate::Direction::WeakLtr] or [`Direction::WeakRtl`][crate::Direction::WeakRtl] is used only
324    /// for paragraphs that do not contain any strong characters themselves.
325    /// ## `direction`
326    /// the new base direction
327    #[doc(alias = "pango_context_set_base_dir")]
328    pub fn set_base_dir(&self, direction: Direction) {
329        unsafe {
330            ffi::pango_context_set_base_dir(self.to_glib_none().0, direction.into_glib());
331        }
332    }
333
334    /// Sets the base gravity for the context.
335    ///
336    /// The base gravity is used in laying vertical text out.
337    /// ## `gravity`
338    /// the new base gravity
339    #[doc(alias = "pango_context_set_base_gravity")]
340    pub fn set_base_gravity(&self, gravity: Gravity) {
341        unsafe {
342            ffi::pango_context_set_base_gravity(self.to_glib_none().0, gravity.into_glib());
343        }
344    }
345
346    /// Set the default font description for the context
347    /// ## `desc`
348    /// the new pango font description
349    #[doc(alias = "pango_context_set_font_description")]
350    pub fn set_font_description(&self, desc: Option<&FontDescription>) {
351        unsafe {
352            ffi::pango_context_set_font_description(self.to_glib_none().0, desc.to_glib_none().0);
353        }
354    }
355
356    /// Sets the font map to be searched when fonts are looked-up
357    /// in this context.
358    ///
359    /// This is only for internal use by Pango backends, a [`Context`][crate::Context]
360    /// obtained via one of the recommended methods should already have a
361    /// suitable font map.
362    /// ## `font_map`
363    /// the [`FontMap`][crate::FontMap] to set.
364    #[doc(alias = "pango_context_set_font_map")]
365    pub fn set_font_map(&self, font_map: Option<&impl IsA<FontMap>>) {
366        unsafe {
367            ffi::pango_context_set_font_map(
368                self.to_glib_none().0,
369                font_map.map(|p| p.as_ref()).to_glib_none().0,
370            );
371        }
372    }
373
374    /// Sets the gravity hint for the context.
375    ///
376    /// The gravity hint is used in laying vertical text out, and
377    /// is only relevant if gravity of the context as returned by
378    /// [`gravity()`][Self::gravity()] is set to [`Gravity::East`][crate::Gravity::East]
379    /// or [`Gravity::West`][crate::Gravity::West].
380    /// ## `hint`
381    /// the new gravity hint
382    #[doc(alias = "pango_context_set_gravity_hint")]
383    pub fn set_gravity_hint(&self, hint: GravityHint) {
384        unsafe {
385            ffi::pango_context_set_gravity_hint(self.to_glib_none().0, hint.into_glib());
386        }
387    }
388
389    /// Sets the global language tag for the context.
390    ///
391    /// The default language for the locale of the running process
392    /// can be found using [`Language::default()`][crate::Language::default()].
393    /// ## `language`
394    /// the new language tag.
395    #[doc(alias = "pango_context_set_language")]
396    pub fn set_language(&self, language: Option<&Language>) {
397        unsafe {
398            ffi::pango_context_set_language(
399                self.to_glib_none().0,
400                mut_override(language.to_glib_none().0),
401            );
402        }
403    }
404
405    /// Sets the transformation matrix that will be applied when rendering
406    /// with this context.
407    ///
408    /// Note that reported metrics are in the user space coordinates before
409    /// the application of the matrix, not device-space coordinates after the
410    /// application of the matrix. So, they don't scale with the matrix, though
411    /// they may change slightly for different matrices, depending on how the
412    /// text is fit to the pixel grid.
413    /// ## `matrix`
414    /// a [`Matrix`][crate::Matrix], or [`None`] to unset any existing
415    /// matrix. (No matrix set is the same as setting the identity matrix.)
416    #[doc(alias = "pango_context_set_matrix")]
417    pub fn set_matrix(&self, matrix: Option<&Matrix>) {
418        unsafe {
419            ffi::pango_context_set_matrix(self.to_glib_none().0, matrix.to_glib_none().0);
420        }
421    }
422
423    /// Sets whether font rendering with this context should
424    /// round glyph positions and widths to integral positions,
425    /// in device units.
426    ///
427    /// This is useful when the renderer can't handle subpixel
428    /// positioning of glyphs.
429    ///
430    /// The default value is to round glyph positions, to remain
431    /// compatible with previous Pango behavior.
432    /// ## `round_positions`
433    /// whether to round glyph positions
434    #[cfg(feature = "v1_44")]
435    #[cfg_attr(docsrs, doc(cfg(feature = "v1_44")))]
436    #[doc(alias = "pango_context_set_round_glyph_positions")]
437    pub fn set_round_glyph_positions(&self, round_positions: bool) {
438        unsafe {
439            ffi::pango_context_set_round_glyph_positions(
440                self.to_glib_none().0,
441                round_positions.into_glib(),
442            );
443        }
444    }
445}
446
447impl Default for Context {
448    fn default() -> Self {
449        Self::new()
450    }
451}