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}