pango/auto/
renderer.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, Color, Font, Glyph, GlyphItem, GlyphString, Layout, LayoutLine, Matrix, RenderPart,
7};
8use glib::{prelude::*, translate::*};
9
10glib::wrapper! {
11    /// [`Renderer`][crate::Renderer] is a base class for objects that can render text
12    /// provided as [`GlyphString`][crate::GlyphString] or [`Layout`][crate::Layout].
13    ///
14    /// By subclassing [`Renderer`][crate::Renderer] and overriding operations such as
15    /// @draw_glyphs and @draw_rectangle, renderers for particular font
16    /// backends and destinations can be created.
17    ///
18    /// This is an Abstract Base Class, you cannot instantiate it.
19    ///
20    /// # Implements
21    ///
22    /// [`RendererExt`][trait@crate::prelude::RendererExt]
23    #[doc(alias = "PangoRenderer")]
24    pub struct Renderer(Object<ffi::PangoRenderer, ffi::PangoRendererClass>);
25
26    match fn {
27        type_ => || ffi::pango_renderer_get_type(),
28    }
29}
30
31impl Renderer {
32    pub const NONE: Option<&'static Renderer> = None;
33}
34
35mod sealed {
36    pub trait Sealed {}
37    impl<T: super::IsA<super::Renderer>> Sealed for T {}
38}
39
40/// Trait containing all [`struct@Renderer`] methods.
41///
42/// # Implementors
43///
44/// [`Renderer`][struct@crate::Renderer]
45pub trait RendererExt: IsA<Renderer> + sealed::Sealed + 'static {
46    /// Does initial setup before rendering operations on @self.
47    ///
48    /// [`deactivate()`][Self::deactivate()] should be called when done drawing.
49    /// Calls such as [`draw_layout()`][Self::draw_layout()] automatically
50    /// activate the layout before drawing on it.
51    ///
52    /// Calls to [`activate()`][Self::activate()] and
53    /// [`deactivate()`][Self::deactivate()] can be nested and the
54    /// renderer will only be initialized and deinitialized once.
55    #[doc(alias = "pango_renderer_activate")]
56    fn activate(&self) {
57        unsafe {
58            ffi::pango_renderer_activate(self.as_ref().to_glib_none().0);
59        }
60    }
61
62    /// Cleans up after rendering operations on @self.
63    ///
64    /// See docs for [`activate()`][Self::activate()].
65    #[doc(alias = "pango_renderer_deactivate")]
66    fn deactivate(&self) {
67        unsafe {
68            ffi::pango_renderer_deactivate(self.as_ref().to_glib_none().0);
69        }
70    }
71
72    /// Draw a squiggly line that approximately covers the given rectangle
73    /// in the style of an underline used to indicate a spelling error.
74    ///
75    /// The width of the underline is rounded to an integer number
76    /// of up/down segments and the resulting rectangle is centered
77    /// in the original rectangle.
78    ///
79    /// This should be called while @self is already active.
80    /// Use [`activate()`][Self::activate()] to activate a renderer.
81    /// ## `x`
82    /// X coordinate of underline, in Pango units in user coordinate system
83    /// ## `y`
84    /// Y coordinate of underline, in Pango units in user coordinate system
85    /// ## `width`
86    /// width of underline, in Pango units in user coordinate system
87    /// ## `height`
88    /// height of underline, in Pango units in user coordinate system
89    #[doc(alias = "pango_renderer_draw_error_underline")]
90    fn draw_error_underline(&self, x: i32, y: i32, width: i32, height: i32) {
91        unsafe {
92            ffi::pango_renderer_draw_error_underline(
93                self.as_ref().to_glib_none().0,
94                x,
95                y,
96                width,
97                height,
98            );
99        }
100    }
101
102    /// Draws a single glyph with coordinates in device space.
103    /// ## `font`
104    /// a [`Font`][crate::Font]
105    /// ## `glyph`
106    /// the glyph index of a single glyph
107    /// ## `x`
108    /// X coordinate of left edge of baseline of glyph
109    /// ## `y`
110    /// Y coordinate of left edge of baseline of glyph
111    #[doc(alias = "pango_renderer_draw_glyph")]
112    fn draw_glyph(&self, font: &impl IsA<Font>, glyph: Glyph, x: f64, y: f64) {
113        unsafe {
114            ffi::pango_renderer_draw_glyph(
115                self.as_ref().to_glib_none().0,
116                font.as_ref().to_glib_none().0,
117                glyph,
118                x,
119                y,
120            );
121        }
122    }
123
124    /// Draws the glyphs in @glyph_item with the specified [`Renderer`][crate::Renderer],
125    /// embedding the text associated with the glyphs in the output if the
126    /// output format supports it.
127    ///
128    /// This is useful for rendering text in PDF.
129    ///
130    /// Note that this method does not handle attributes in @glyph_item.
131    /// If you want colors, shapes and lines handled automatically according
132    /// to those attributes, you need to use pango_renderer_draw_layout_line()
133    /// or pango_renderer_draw_layout().
134    ///
135    /// Note that @text is the start of the text for layout, which is then
136    /// indexed by `glyph_item->item->offset`.
137    ///
138    /// If @text is [`None`], this simply calls [`draw_glyphs()`][Self::draw_glyphs()].
139    ///
140    /// The default implementation of this method simply falls back to
141    /// [`draw_glyphs()`][Self::draw_glyphs()].
142    /// ## `text`
143    /// the UTF-8 text that @glyph_item refers to
144    /// ## `glyph_item`
145    /// a [`GlyphItem`][crate::GlyphItem]
146    /// ## `x`
147    /// X position of left edge of baseline, in user space coordinates
148    ///   in Pango units
149    /// ## `y`
150    /// Y position of left edge of baseline, in user space coordinates
151    ///   in Pango units
152    #[doc(alias = "pango_renderer_draw_glyph_item")]
153    fn draw_glyph_item(&self, text: Option<&str>, glyph_item: &mut GlyphItem, x: i32, y: i32) {
154        unsafe {
155            ffi::pango_renderer_draw_glyph_item(
156                self.as_ref().to_glib_none().0,
157                text.to_glib_none().0,
158                glyph_item.to_glib_none_mut().0,
159                x,
160                y,
161            );
162        }
163    }
164
165    /// Draws the glyphs in @glyphs with the specified [`Renderer`][crate::Renderer].
166    /// ## `font`
167    /// a [`Font`][crate::Font]
168    /// ## `glyphs`
169    /// a [`GlyphString`][crate::GlyphString]
170    /// ## `x`
171    /// X position of left edge of baseline, in user space coordinates
172    ///   in Pango units.
173    /// ## `y`
174    /// Y position of left edge of baseline, in user space coordinates
175    ///   in Pango units.
176    #[doc(alias = "pango_renderer_draw_glyphs")]
177    fn draw_glyphs(&self, font: &impl IsA<Font>, glyphs: &mut GlyphString, x: i32, y: i32) {
178        unsafe {
179            ffi::pango_renderer_draw_glyphs(
180                self.as_ref().to_glib_none().0,
181                font.as_ref().to_glib_none().0,
182                glyphs.to_glib_none_mut().0,
183                x,
184                y,
185            );
186        }
187    }
188
189    /// Draws @layout with the specified [`Renderer`][crate::Renderer].
190    ///
191    /// This is equivalent to drawing the lines of the layout, at their
192    /// respective positions relative to @x, @y.
193    /// ## `layout`
194    /// a [`Layout`][crate::Layout]
195    /// ## `x`
196    /// X position of left edge of baseline, in user space coordinates
197    ///   in Pango units.
198    /// ## `y`
199    /// Y position of left edge of baseline, in user space coordinates
200    ///   in Pango units.
201    #[doc(alias = "pango_renderer_draw_layout")]
202    fn draw_layout(&self, layout: &Layout, x: i32, y: i32) {
203        unsafe {
204            ffi::pango_renderer_draw_layout(
205                self.as_ref().to_glib_none().0,
206                layout.to_glib_none().0,
207                x,
208                y,
209            );
210        }
211    }
212
213    /// Draws @line with the specified [`Renderer`][crate::Renderer].
214    ///
215    /// This draws the glyph items that make up the line, as well as
216    /// shapes, backgrounds and lines that are specified by the attributes
217    /// of those items.
218    /// ## `line`
219    /// a [`LayoutLine`][crate::LayoutLine]
220    /// ## `x`
221    /// X position of left edge of baseline, in user space coordinates
222    ///   in Pango units.
223    /// ## `y`
224    /// Y position of left edge of baseline, in user space coordinates
225    ///   in Pango units.
226    #[doc(alias = "pango_renderer_draw_layout_line")]
227    fn draw_layout_line(&self, line: &LayoutLine, x: i32, y: i32) {
228        unsafe {
229            ffi::pango_renderer_draw_layout_line(
230                self.as_ref().to_glib_none().0,
231                line.to_glib_none().0,
232                x,
233                y,
234            );
235        }
236    }
237
238    /// Draws an axis-aligned rectangle in user space coordinates with the
239    /// specified [`Renderer`][crate::Renderer].
240    ///
241    /// This should be called while @self is already active.
242    /// Use [`activate()`][Self::activate()] to activate a renderer.
243    /// ## `part`
244    /// type of object this rectangle is part of
245    /// ## `x`
246    /// X position at which to draw rectangle, in user space coordinates
247    ///   in Pango units
248    /// ## `y`
249    /// Y position at which to draw rectangle, in user space coordinates
250    ///   in Pango units
251    /// ## `width`
252    /// width of rectangle in Pango units
253    /// ## `height`
254    /// height of rectangle in Pango units
255    #[doc(alias = "pango_renderer_draw_rectangle")]
256    fn draw_rectangle(&self, part: RenderPart, x: i32, y: i32, width: i32, height: i32) {
257        unsafe {
258            ffi::pango_renderer_draw_rectangle(
259                self.as_ref().to_glib_none().0,
260                part.into_glib(),
261                x,
262                y,
263                width,
264                height,
265            );
266        }
267    }
268
269    /// Draws a trapezoid with the parallel sides aligned with the X axis
270    /// using the given [`Renderer`][crate::Renderer]; coordinates are in device space.
271    /// ## `part`
272    /// type of object this trapezoid is part of
273    /// ## `y1_`
274    /// Y coordinate of top of trapezoid
275    /// ## `x11`
276    /// X coordinate of left end of top of trapezoid
277    /// ## `x21`
278    /// X coordinate of right end of top of trapezoid
279    /// ## `y2`
280    /// Y coordinate of bottom of trapezoid
281    /// ## `x12`
282    /// X coordinate of left end of bottom of trapezoid
283    /// ## `x22`
284    /// X coordinate of right end of bottom of trapezoid
285    #[doc(alias = "pango_renderer_draw_trapezoid")]
286    fn draw_trapezoid(
287        &self,
288        part: RenderPart,
289        y1_: f64,
290        x11: f64,
291        x21: f64,
292        y2: f64,
293        x12: f64,
294        x22: f64,
295    ) {
296        unsafe {
297            ffi::pango_renderer_draw_trapezoid(
298                self.as_ref().to_glib_none().0,
299                part.into_glib(),
300                y1_,
301                x11,
302                x21,
303                y2,
304                x12,
305                x22,
306            );
307        }
308    }
309
310    /// Gets the current alpha for the specified part.
311    /// ## `part`
312    /// the part to get the alpha for
313    ///
314    /// # Returns
315    ///
316    /// the alpha for the specified part,
317    ///   or 0 if it hasn't been set and should be
318    ///   inherited from the environment.
319    #[doc(alias = "pango_renderer_get_alpha")]
320    #[doc(alias = "get_alpha")]
321    fn alpha(&self, part: RenderPart) -> u16 {
322        unsafe { ffi::pango_renderer_get_alpha(self.as_ref().to_glib_none().0, part.into_glib()) }
323    }
324
325    /// Gets the current rendering color for the specified part.
326    /// ## `part`
327    /// the part to get the color for
328    ///
329    /// # Returns
330    ///
331    /// the color for the
332    ///   specified part, or [`None`] if it hasn't been set and should be
333    ///   inherited from the environment.
334    #[doc(alias = "pango_renderer_get_color")]
335    #[doc(alias = "get_color")]
336    fn color(&self, part: RenderPart) -> Option<Color> {
337        unsafe {
338            from_glib_none(ffi::pango_renderer_get_color(
339                self.as_ref().to_glib_none().0,
340                part.into_glib(),
341            ))
342        }
343    }
344
345    /// Gets the layout currently being rendered using @self.
346    ///
347    /// Calling this function only makes sense from inside a subclass's
348    /// methods, like in its draw_shape vfunc, for example.
349    ///
350    /// The returned layout should not be modified while still being
351    /// rendered.
352    ///
353    /// # Returns
354    ///
355    /// the layout, or [`None`] if
356    ///   no layout is being rendered using @self at this time.
357    #[doc(alias = "pango_renderer_get_layout")]
358    #[doc(alias = "get_layout")]
359    fn layout(&self) -> Option<Layout> {
360        unsafe {
361            from_glib_none(ffi::pango_renderer_get_layout(
362                self.as_ref().to_glib_none().0,
363            ))
364        }
365    }
366
367    /// Gets the layout line currently being rendered using @self.
368    ///
369    /// Calling this function only makes sense from inside a subclass's
370    /// methods, like in its draw_shape vfunc, for example.
371    ///
372    /// The returned layout line should not be modified while still being
373    /// rendered.
374    ///
375    /// # Returns
376    ///
377    /// the layout line, or [`None`]
378    ///   if no layout line is being rendered using @self at this time.
379    #[doc(alias = "pango_renderer_get_layout_line")]
380    #[doc(alias = "get_layout_line")]
381    fn layout_line(&self) -> Option<LayoutLine> {
382        unsafe {
383            from_glib_none(ffi::pango_renderer_get_layout_line(
384                self.as_ref().to_glib_none().0,
385            ))
386        }
387    }
388
389    /// Gets the transformation matrix that will be applied when
390    /// rendering.
391    ///
392    /// See [`set_matrix()`][Self::set_matrix()].
393    ///
394    /// # Returns
395    ///
396    /// the matrix, or [`None`] if no matrix has
397    ///   been set (which is the same as the identity matrix). The returned
398    ///   matrix is owned by Pango and must not be modified or freed.
399    #[doc(alias = "pango_renderer_get_matrix")]
400    #[doc(alias = "get_matrix")]
401    fn matrix(&self) -> Option<Matrix> {
402        unsafe {
403            from_glib_none(ffi::pango_renderer_get_matrix(
404                self.as_ref().to_glib_none().0,
405            ))
406        }
407    }
408
409    /// Informs Pango that the way that the rendering is done
410    /// for @part has changed.
411    ///
412    /// This should be called if the rendering changes in a way that would
413    /// prevent multiple pieces being joined together into one drawing call.
414    /// For instance, if a subclass of [`Renderer`][crate::Renderer] was to add a stipple
415    /// option for drawing underlines, it needs to call
416    ///
417    /// ```text
418    /// pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE);
419    /// ```
420    ///
421    /// When the stipple changes or underlines with different stipples
422    /// might be joined together. Pango automatically calls this for
423    /// changes to colors. (See [`set_color()`][Self::set_color()])
424    /// ## `part`
425    /// the part for which rendering has changed.
426    #[doc(alias = "pango_renderer_part_changed")]
427    fn part_changed(&self, part: RenderPart) {
428        unsafe {
429            ffi::pango_renderer_part_changed(self.as_ref().to_glib_none().0, part.into_glib());
430        }
431    }
432
433    /// Sets the alpha for part of the rendering.
434    ///
435    /// Note that the alpha may only be used if a color is
436    /// specified for @part as well.
437    /// ## `part`
438    /// the part to set the alpha for
439    /// ## `alpha`
440    /// an alpha value between 1 and 65536, or 0 to unset the alpha
441    #[doc(alias = "pango_renderer_set_alpha")]
442    fn set_alpha(&self, part: RenderPart, alpha: u16) {
443        unsafe {
444            ffi::pango_renderer_set_alpha(self.as_ref().to_glib_none().0, part.into_glib(), alpha);
445        }
446    }
447
448    /// Sets the color for part of the rendering.
449    ///
450    /// Also see [`set_alpha()`][Self::set_alpha()].
451    /// ## `part`
452    /// the part to change the color of
453    /// ## `color`
454    /// the new color or [`None`] to unset the current color
455    #[doc(alias = "pango_renderer_set_color")]
456    fn set_color(&self, part: RenderPart, color: Option<&Color>) {
457        unsafe {
458            ffi::pango_renderer_set_color(
459                self.as_ref().to_glib_none().0,
460                part.into_glib(),
461                color.to_glib_none().0,
462            );
463        }
464    }
465
466    /// Sets the transformation matrix that will be applied when rendering.
467    /// ## `matrix`
468    /// a [`Matrix`][crate::Matrix], or [`None`] to unset any existing matrix
469    ///  (No matrix set is the same as setting the identity matrix.)
470    #[doc(alias = "pango_renderer_set_matrix")]
471    fn set_matrix(&self, matrix: Option<&Matrix>) {
472        unsafe {
473            ffi::pango_renderer_set_matrix(self.as_ref().to_glib_none().0, matrix.to_glib_none().0);
474        }
475    }
476}
477
478impl<O: IsA<Renderer>> RendererExt for O {}