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}