pango/auto/
layout_iter.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, Layout, LayoutLine, LayoutRun, Rectangle};
6use glib::translate::*;
7
8glib::wrapper! {
9    /// A [`LayoutIter`][crate::LayoutIter] can be used to iterate over the visual
10    /// extents of a [`Layout`][crate::Layout].
11    ///
12    /// To obtain a [`LayoutIter`][crate::LayoutIter], use [`Layout::iter()`][crate::Layout::iter()].
13    ///
14    /// The [`LayoutIter`][crate::LayoutIter] structure is opaque, and has no user-visible fields.
15    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
16    pub struct LayoutIter(Boxed<ffi::PangoLayoutIter>);
17
18    match fn {
19        copy => |ptr| ffi::pango_layout_iter_copy(mut_override(ptr)),
20        free => |ptr| ffi::pango_layout_iter_free(ptr),
21        type_ => || ffi::pango_layout_iter_get_type(),
22    }
23}
24
25impl LayoutIter {
26    /// Determines whether @self is on the last line of the layout.
27    ///
28    /// # Returns
29    ///
30    /// [`true`] if @self is on the last line
31    #[doc(alias = "pango_layout_iter_at_last_line")]
32    pub fn at_last_line(&mut self) -> bool {
33        unsafe {
34            from_glib(ffi::pango_layout_iter_at_last_line(
35                self.to_glib_none_mut().0,
36            ))
37        }
38    }
39
40    /// Gets the Y position of the current line's baseline, in layout
41    /// coordinates.
42    ///
43    /// Layout coordinates have the origin at the top left of the entire layout.
44    ///
45    /// # Returns
46    ///
47    /// baseline of current line
48    #[doc(alias = "pango_layout_iter_get_baseline")]
49    #[doc(alias = "get_baseline")]
50    pub fn baseline(&mut self) -> i32 {
51        unsafe { ffi::pango_layout_iter_get_baseline(self.to_glib_none_mut().0) }
52    }
53
54    /// Gets the extents of the current character, in layout coordinates.
55    ///
56    /// Layout coordinates have the origin at the top left of the entire layout.
57    ///
58    /// Only logical extents can sensibly be obtained for characters;
59    /// ink extents make sense only down to the level of clusters.
60    ///
61    /// # Returns
62    ///
63    ///
64    /// ## `logical_rect`
65    /// rectangle to fill with
66    ///   logical extents
67    #[doc(alias = "pango_layout_iter_get_char_extents")]
68    #[doc(alias = "get_char_extents")]
69    pub fn char_extents(&mut self) -> Rectangle {
70        unsafe {
71            let mut logical_rect = Rectangle::uninitialized();
72            ffi::pango_layout_iter_get_char_extents(
73                self.to_glib_none_mut().0,
74                logical_rect.to_glib_none_mut().0,
75            );
76            logical_rect
77        }
78    }
79
80    /// Gets the extents of the current cluster, in layout coordinates.
81    ///
82    /// Layout coordinates have the origin at the top left of the entire layout.
83    ///
84    /// # Returns
85    ///
86    ///
87    /// ## `ink_rect`
88    /// rectangle to fill with ink extents
89    ///
90    /// ## `logical_rect`
91    /// rectangle to fill with logical extents
92    #[doc(alias = "pango_layout_iter_get_cluster_extents")]
93    #[doc(alias = "get_cluster_extents")]
94    pub fn cluster_extents(&mut self) -> (Rectangle, Rectangle) {
95        unsafe {
96            let mut ink_rect = Rectangle::uninitialized();
97            let mut logical_rect = Rectangle::uninitialized();
98            ffi::pango_layout_iter_get_cluster_extents(
99                self.to_glib_none_mut().0,
100                ink_rect.to_glib_none_mut().0,
101                logical_rect.to_glib_none_mut().0,
102            );
103            (ink_rect, logical_rect)
104        }
105    }
106
107    /// Gets the current byte index.
108    ///
109    /// Note that iterating forward by char moves in visual order,
110    /// not logical order, so indexes may not be sequential. Also,
111    /// the index may be equal to the length of the text in the
112    /// layout, if on the [`None`] run (see [`run()`][Self::run()]).
113    ///
114    /// # Returns
115    ///
116    /// current byte index
117    #[doc(alias = "pango_layout_iter_get_index")]
118    #[doc(alias = "get_index")]
119    pub fn index(&mut self) -> i32 {
120        unsafe { ffi::pango_layout_iter_get_index(self.to_glib_none_mut().0) }
121    }
122
123    /// Gets the layout associated with a [`LayoutIter`][crate::LayoutIter].
124    ///
125    /// # Returns
126    ///
127    /// the layout associated with @self
128    #[doc(alias = "pango_layout_iter_get_layout")]
129    #[doc(alias = "get_layout")]
130    pub fn layout(&mut self) -> Option<Layout> {
131        unsafe { from_glib_none(ffi::pango_layout_iter_get_layout(self.to_glib_none_mut().0)) }
132    }
133
134    /// Obtains the extents of the [`Layout`][crate::Layout] being iterated over.
135    ///
136    /// # Returns
137    ///
138    ///
139    /// ## `ink_rect`
140    /// rectangle to fill with ink extents
141    ///
142    /// ## `logical_rect`
143    /// rectangle to fill with logical extents
144    #[doc(alias = "pango_layout_iter_get_layout_extents")]
145    #[doc(alias = "get_layout_extents")]
146    pub fn layout_extents(&mut self) -> (Rectangle, Rectangle) {
147        unsafe {
148            let mut ink_rect = Rectangle::uninitialized();
149            let mut logical_rect = Rectangle::uninitialized();
150            ffi::pango_layout_iter_get_layout_extents(
151                self.to_glib_none_mut().0,
152                ink_rect.to_glib_none_mut().0,
153                logical_rect.to_glib_none_mut().0,
154            );
155            (ink_rect, logical_rect)
156        }
157    }
158
159    /// Gets the current line.
160    ///
161    /// Use the faster [`line_readonly()`][Self::line_readonly()] if
162    /// you do not plan to modify the contents of the line (glyphs,
163    /// glyph widths, etc.).
164    ///
165    /// # Returns
166    ///
167    /// the current line
168    #[doc(alias = "pango_layout_iter_get_line")]
169    #[doc(alias = "get_line")]
170    pub fn line(&mut self) -> Option<LayoutLine> {
171        unsafe { from_glib_none(ffi::pango_layout_iter_get_line(self.to_glib_none_mut().0)) }
172    }
173
174    /// Obtains the extents of the current line.
175    ///
176    /// Extents are in layout coordinates (origin is the top-left corner
177    /// of the entire [`Layout`][crate::Layout]). Thus the extents returned by this
178    /// function will be the same width/height but not at the same x/y
179    /// as the extents returned from [`LayoutLine::extents()`][crate::LayoutLine::extents()].
180    ///
181    /// # Returns
182    ///
183    ///
184    /// ## `ink_rect`
185    /// rectangle to fill with ink extents
186    ///
187    /// ## `logical_rect`
188    /// rectangle to fill with logical extents
189    #[doc(alias = "pango_layout_iter_get_line_extents")]
190    #[doc(alias = "get_line_extents")]
191    pub fn line_extents(&mut self) -> (Rectangle, Rectangle) {
192        unsafe {
193            let mut ink_rect = Rectangle::uninitialized();
194            let mut logical_rect = Rectangle::uninitialized();
195            ffi::pango_layout_iter_get_line_extents(
196                self.to_glib_none_mut().0,
197                ink_rect.to_glib_none_mut().0,
198                logical_rect.to_glib_none_mut().0,
199            );
200            (ink_rect, logical_rect)
201        }
202    }
203
204    /// Gets the current line for read-only access.
205    ///
206    /// This is a faster alternative to [`line()`][Self::line()],
207    /// but the user is not expected to modify the contents of the line
208    /// (glyphs, glyph widths, etc.).
209    ///
210    /// # Returns
211    ///
212    /// the current line, that should not be
213    ///   modified
214    #[doc(alias = "pango_layout_iter_get_line_readonly")]
215    #[doc(alias = "get_line_readonly")]
216    pub fn line_readonly(&mut self) -> Option<LayoutLine> {
217        unsafe {
218            from_glib_none(ffi::pango_layout_iter_get_line_readonly(
219                self.to_glib_none_mut().0,
220            ))
221        }
222    }
223
224    /// Divides the vertical space in the [`Layout`][crate::Layout] being iterated over
225    /// between the lines in the layout, and returns the space belonging to
226    /// the current line.
227    ///
228    /// A line's range includes the line's logical extents. plus half of the
229    /// spacing above and below the line, if [`Layout::set_spacing()`][crate::Layout::set_spacing()]
230    /// has been called to set layout spacing. The Y positions are in layout
231    /// coordinates (origin at top left of the entire layout).
232    ///
233    /// Note: Since 1.44, Pango uses line heights for placing lines, and there
234    /// may be gaps between the ranges returned by this function.
235    ///
236    /// # Returns
237    ///
238    ///
239    /// ## `y0_`
240    /// start of line
241    ///
242    /// ## `y1_`
243    /// end of line
244    #[doc(alias = "pango_layout_iter_get_line_yrange")]
245    #[doc(alias = "get_line_yrange")]
246    pub fn line_yrange(&mut self) -> (i32, i32) {
247        unsafe {
248            let mut y0_ = std::mem::MaybeUninit::uninit();
249            let mut y1_ = std::mem::MaybeUninit::uninit();
250            ffi::pango_layout_iter_get_line_yrange(
251                self.to_glib_none_mut().0,
252                y0_.as_mut_ptr(),
253                y1_.as_mut_ptr(),
254            );
255            (y0_.assume_init(), y1_.assume_init())
256        }
257    }
258
259    /// Gets the current run.
260    ///
261    /// When iterating by run, at the end of each line, there's a position
262    /// with a [`None`] run, so this function can return [`None`]. The [`None`] run
263    /// at the end of each line ensures that all lines have at least one run,
264    /// even lines consisting of only a newline.
265    ///
266    /// Use the faster [`run_readonly()`][Self::run_readonly()] if you do not
267    /// plan to modify the contents of the run (glyphs, glyph widths, etc.).
268    ///
269    /// # Returns
270    ///
271    /// the current run
272    #[doc(alias = "pango_layout_iter_get_run")]
273    #[doc(alias = "get_run")]
274    pub fn run(&mut self) -> Option<LayoutRun> {
275        unsafe { from_glib_none(ffi::pango_layout_iter_get_run(self.to_glib_none_mut().0)) }
276    }
277
278    /// Gets the Y position of the current run's baseline, in layout
279    /// coordinates.
280    ///
281    /// Layout coordinates have the origin at the top left of the entire layout.
282    ///
283    /// The run baseline can be different from the line baseline, for
284    /// example due to superscript or subscript positioning.
285    #[cfg(feature = "v1_50")]
286    #[cfg_attr(docsrs, doc(cfg(feature = "v1_50")))]
287    #[doc(alias = "pango_layout_iter_get_run_baseline")]
288    #[doc(alias = "get_run_baseline")]
289    pub fn run_baseline(&mut self) -> i32 {
290        unsafe { ffi::pango_layout_iter_get_run_baseline(self.to_glib_none_mut().0) }
291    }
292
293    /// Gets the extents of the current run in layout coordinates.
294    ///
295    /// Layout coordinates have the origin at the top left of the entire layout.
296    ///
297    /// # Returns
298    ///
299    ///
300    /// ## `ink_rect`
301    /// rectangle to fill with ink extents
302    ///
303    /// ## `logical_rect`
304    /// rectangle to fill with logical extents
305    #[doc(alias = "pango_layout_iter_get_run_extents")]
306    #[doc(alias = "get_run_extents")]
307    pub fn run_extents(&mut self) -> (Rectangle, Rectangle) {
308        unsafe {
309            let mut ink_rect = Rectangle::uninitialized();
310            let mut logical_rect = Rectangle::uninitialized();
311            ffi::pango_layout_iter_get_run_extents(
312                self.to_glib_none_mut().0,
313                ink_rect.to_glib_none_mut().0,
314                logical_rect.to_glib_none_mut().0,
315            );
316            (ink_rect, logical_rect)
317        }
318    }
319
320    /// Gets the current run for read-only access.
321    ///
322    /// When iterating by run, at the end of each line, there's a position
323    /// with a [`None`] run, so this function can return [`None`]. The [`None`] run
324    /// at the end of each line ensures that all lines have at least one run,
325    /// even lines consisting of only a newline.
326    ///
327    /// This is a faster alternative to [`run()`][Self::run()],
328    /// but the user is not expected to modify the contents of the run (glyphs,
329    /// glyph widths, etc.).
330    ///
331    /// # Returns
332    ///
333    /// the current run, that
334    ///   should not be modified
335    #[doc(alias = "pango_layout_iter_get_run_readonly")]
336    #[doc(alias = "get_run_readonly")]
337    pub fn run_readonly(&mut self) -> Option<LayoutRun> {
338        unsafe {
339            from_glib_none(ffi::pango_layout_iter_get_run_readonly(
340                self.to_glib_none_mut().0,
341            ))
342        }
343    }
344
345    /// Moves @self forward to the next character in visual order.
346    ///
347    /// If @self was already at the end of the layout, returns [`false`].
348    ///
349    /// # Returns
350    ///
351    /// whether motion was possible
352    #[doc(alias = "pango_layout_iter_next_char")]
353    pub fn next_char(&mut self) -> bool {
354        unsafe { from_glib(ffi::pango_layout_iter_next_char(self.to_glib_none_mut().0)) }
355    }
356
357    /// Moves @self forward to the next cluster in visual order.
358    ///
359    /// If @self was already at the end of the layout, returns [`false`].
360    ///
361    /// # Returns
362    ///
363    /// whether motion was possible
364    #[doc(alias = "pango_layout_iter_next_cluster")]
365    pub fn next_cluster(&mut self) -> bool {
366        unsafe {
367            from_glib(ffi::pango_layout_iter_next_cluster(
368                self.to_glib_none_mut().0,
369            ))
370        }
371    }
372
373    /// Moves @self forward to the start of the next line.
374    ///
375    /// If @self is already on the last line, returns [`false`].
376    ///
377    /// # Returns
378    ///
379    /// whether motion was possible
380    #[doc(alias = "pango_layout_iter_next_line")]
381    pub fn next_line(&mut self) -> bool {
382        unsafe { from_glib(ffi::pango_layout_iter_next_line(self.to_glib_none_mut().0)) }
383    }
384
385    /// Moves @self forward to the next run in visual order.
386    ///
387    /// If @self was already at the end of the layout, returns [`false`].
388    ///
389    /// # Returns
390    ///
391    /// whether motion was possible
392    #[doc(alias = "pango_layout_iter_next_run")]
393    pub fn next_run(&mut self) -> bool {
394        unsafe { from_glib(ffi::pango_layout_iter_next_run(self.to_glib_none_mut().0)) }
395    }
396}