pango/auto/
glyph_string.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, Analysis, Font, Rectangle};
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// A [`GlyphString`][crate::GlyphString] is used to store strings of glyphs with geometry
10    /// and visual attribute information.
11    ///
12    /// The storage for the glyph information is owned by the structure
13    /// which simplifies memory management.
14    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
15    pub struct GlyphString(Boxed<ffi::PangoGlyphString>);
16
17    match fn {
18        copy => |ptr| ffi::pango_glyph_string_copy(mut_override(ptr)),
19        free => |ptr| ffi::pango_glyph_string_free(ptr),
20        type_ => || ffi::pango_glyph_string_get_type(),
21    }
22}
23
24impl GlyphString {
25    /// Create a new [`GlyphString`][crate::GlyphString].
26    ///
27    /// # Returns
28    ///
29    /// the newly allocated [`GlyphString`][crate::GlyphString], which
30    ///   should be freed with `Pango::GlyphString::free()`.
31    #[doc(alias = "pango_glyph_string_new")]
32    pub fn new() -> GlyphString {
33        unsafe { from_glib_full(ffi::pango_glyph_string_new()) }
34    }
35
36    /// Compute the logical and ink extents of a glyph string.
37    ///
38    /// See the documentation for [`FontExt::glyph_extents()`][crate::prelude::FontExt::glyph_extents()] for details
39    /// about the interpretation of the rectangles.
40    ///
41    /// Examples of logical (red) and ink (green) rects:
42    ///
43    /// ![](rects1.png) ![](rects2.png)
44    /// ## `font`
45    /// a [`Font`][crate::Font]
46    ///
47    /// # Returns
48    ///
49    ///
50    /// ## `ink_rect`
51    /// rectangle used to store the extents of the glyph string as drawn
52    ///
53    /// ## `logical_rect`
54    /// rectangle used to store the logical extents of the glyph string
55    #[doc(alias = "pango_glyph_string_extents")]
56    pub fn extents(&mut self, font: &impl IsA<Font>) -> (Rectangle, Rectangle) {
57        unsafe {
58            let mut ink_rect = Rectangle::uninitialized();
59            let mut logical_rect = Rectangle::uninitialized();
60            ffi::pango_glyph_string_extents(
61                self.to_glib_none_mut().0,
62                font.as_ref().to_glib_none().0,
63                ink_rect.to_glib_none_mut().0,
64                logical_rect.to_glib_none_mut().0,
65            );
66            (ink_rect, logical_rect)
67        }
68    }
69
70    /// Computes the extents of a sub-portion of a glyph string.
71    ///
72    /// The extents are relative to the start of the glyph string range
73    /// (the origin of their coordinate system is at the start of the range,
74    /// not at the start of the entire glyph string).
75    /// ## `start`
76    /// start index
77    /// ## `end`
78    /// end index (the range is the set of bytes with
79    ///   indices such that start <= index < end)
80    /// ## `font`
81    /// a [`Font`][crate::Font]
82    ///
83    /// # Returns
84    ///
85    ///
86    /// ## `ink_rect`
87    /// rectangle used to
88    ///   store the extents of the glyph string range as drawn
89    ///
90    /// ## `logical_rect`
91    /// rectangle used to
92    ///   store the logical extents of the glyph string range
93    #[doc(alias = "pango_glyph_string_extents_range")]
94    pub fn extents_range(
95        &mut self,
96        start: i32,
97        end: i32,
98        font: &impl IsA<Font>,
99    ) -> (Rectangle, Rectangle) {
100        unsafe {
101            let mut ink_rect = Rectangle::uninitialized();
102            let mut logical_rect = Rectangle::uninitialized();
103            ffi::pango_glyph_string_extents_range(
104                self.to_glib_none_mut().0,
105                start,
106                end,
107                font.as_ref().to_glib_none().0,
108                ink_rect.to_glib_none_mut().0,
109                logical_rect.to_glib_none_mut().0,
110            );
111            (ink_rect, logical_rect)
112        }
113    }
114
115    /// Computes the logical width of the glyph string.
116    ///
117    /// This can also be computed using [`extents()`][Self::extents()].
118    /// However, since this only computes the width, it's much faster. This
119    /// is in fact only a convenience function that computes the sum of
120    /// @geometry.width for each glyph in the @self.
121    ///
122    /// # Returns
123    ///
124    /// the logical width of the glyph string.
125    #[doc(alias = "pango_glyph_string_get_width")]
126    #[doc(alias = "get_width")]
127    pub fn width(&self) -> i32 {
128        unsafe { ffi::pango_glyph_string_get_width(mut_override(self.to_glib_none().0)) }
129    }
130
131    /// Converts from character position to x position.
132    ///
133    /// The X position is measured from the left edge of the run.
134    /// Character positions are obtained using font metrics for ligatures
135    /// where available, and computed by dividing up each cluster
136    /// into equal portions, otherwise.
137    ///
138    /// <picture>
139    ///   <source srcset="glyphstring-positions-dark.png" media="(prefers-color-scheme: dark)">
140    ///   <img alt="Glyph positions" src="glyphstring-positions-light.png">
141    /// </picture>
142    /// ## `text`
143    /// the text for the run
144    /// ## `length`
145    /// the number of bytes (not characters) in @text.
146    /// ## `analysis`
147    /// the analysis information return from [`itemize()`][crate::itemize()]
148    /// ## `index_`
149    /// the byte index within @text
150    /// ## `trailing`
151    /// whether we should compute the result for the beginning ([`false`])
152    ///   or end ([`true`]) of the character.
153    ///
154    /// # Returns
155    ///
156    ///
157    /// ## `x_pos`
158    /// location to store result
159    #[doc(alias = "pango_glyph_string_index_to_x")]
160    pub fn index_to_x(&self, text: &str, analysis: &Analysis, index_: i32, trailing: bool) -> i32 {
161        let length = text.len() as _;
162        unsafe {
163            let mut x_pos = std::mem::MaybeUninit::uninit();
164            ffi::pango_glyph_string_index_to_x(
165                mut_override(self.to_glib_none().0),
166                text.to_glib_none().0,
167                length,
168                mut_override(analysis.to_glib_none().0),
169                index_,
170                trailing.into_glib(),
171                x_pos.as_mut_ptr(),
172            );
173            x_pos.assume_init()
174        }
175    }
176
177    //#[cfg(feature = "v1_50")]
178    //#[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
179    //#[doc(alias = "pango_glyph_string_index_to_x_full")]
180    //pub fn index_to_x_full(&mut self, text: &str, analysis: &mut Analysis, attrs: /*Ignored*/Option<&mut LogAttr>, index_: i32, trailing: bool) -> i32 {
181    //    unsafe { TODO: call ffi:pango_glyph_string_index_to_x_full() }
182    //}
183
184    /// Resize a glyph string to the given length.
185    /// ## `new_len`
186    /// the new length of the string
187    #[doc(alias = "pango_glyph_string_set_size")]
188    pub fn set_size(&mut self, new_len: i32) {
189        unsafe {
190            ffi::pango_glyph_string_set_size(self.to_glib_none_mut().0, new_len);
191        }
192    }
193
194    /// Convert from x offset to character position.
195    ///
196    /// Character positions are computed by dividing up each cluster into
197    /// equal portions. In scripts where positioning within a cluster is
198    /// not allowed (such as Thai), the returned value may not be a valid
199    /// cursor position; the caller must combine the result with the logical
200    /// attributes for the text to compute the valid cursor position.
201    /// ## `text`
202    /// the text for the run
203    /// ## `length`
204    /// the number of bytes (not characters) in text.
205    /// ## `analysis`
206    /// the analysis information return from [`itemize()`][crate::itemize()]
207    /// ## `x_pos`
208    /// the x offset (in Pango units)
209    ///
210    /// # Returns
211    ///
212    ///
213    /// ## `index_`
214    /// location to store calculated byte index within @text
215    ///
216    /// ## `trailing`
217    /// location to store a boolean indicating whether the
218    ///   user clicked on the leading or trailing edge of the character
219    #[doc(alias = "pango_glyph_string_x_to_index")]
220    pub fn x_to_index(&self, text: &str, analysis: &Analysis, x_pos: i32) -> (i32, i32) {
221        let length = text.len() as _;
222        unsafe {
223            let mut index_ = std::mem::MaybeUninit::uninit();
224            let mut trailing = std::mem::MaybeUninit::uninit();
225            ffi::pango_glyph_string_x_to_index(
226                mut_override(self.to_glib_none().0),
227                text.to_glib_none().0,
228                length,
229                mut_override(analysis.to_glib_none().0),
230                x_pos,
231                index_.as_mut_ptr(),
232                trailing.as_mut_ptr(),
233            );
234            (index_.assume_init(), trailing.assume_init())
235        }
236    }
237}
238
239impl Default for GlyphString {
240    fn default() -> Self {
241        Self::new()
242    }
243}
244
245unsafe impl Send for GlyphString {}
246unsafe impl Sync for GlyphString {}