pango/auto/

renderer.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

#[cfg(feature = "v1_58")]
#[cfg_attr(docsrs, doc(cfg(feature = "v1_58")))]
use crate::RenderComponent;
use crate::{
    Color, Font, Glyph, GlyphItem, GlyphString, Layout, LayoutLine, Matrix, RenderPart, ffi,
};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// [`Renderer`][crate::Renderer] is a base class for objects that can render text
    /// provided as [`GlyphString`][crate::GlyphString] or [`Layout`][crate::Layout].
    ///
    /// By subclassing [`Renderer`][crate::Renderer] and overriding operations such as
    /// @draw_glyphs and @draw_rectangle, renderers for particular font
    /// backends and destinations can be created.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// # Implements
    ///
    /// [`RendererExt`][trait@crate::prelude::RendererExt]
    #[doc(alias = "PangoRenderer")]
    pub struct Renderer(Object<ffi::PangoRenderer, ffi::PangoRendererClass>);

    match fn {
        type_ => || ffi::pango_renderer_get_type(),
    }
}

impl Renderer {
    pub const NONE: Option<&'static Renderer> = None;
}

/// Trait containing all [`struct@Renderer`] methods.
///
/// # Implementors
///
/// [`Renderer`][struct@crate::Renderer]
pub trait RendererExt: IsA<Renderer> + 'static {
    /// Does initial setup before rendering operations on @self.
    ///
    /// [`deactivate()`][Self::deactivate()] should be called when done drawing.
    /// Calls such as [`draw_layout()`][Self::draw_layout()] automatically
    /// activate the layout before drawing on it.
    ///
    /// Calls to [`activate()`][Self::activate()] and
    /// [`deactivate()`][Self::deactivate()] can be nested and the
    /// renderer will only be initialized and deinitialized once.
    #[doc(alias = "pango_renderer_activate")]
    fn activate(&self) {
        unsafe {
            ffi::pango_renderer_activate(self.as_ref().to_glib_none().0);
        }
    }

    /// Cleans up after rendering operations on @self.
    ///
    /// See docs for [`activate()`][Self::activate()].
    #[doc(alias = "pango_renderer_deactivate")]
    fn deactivate(&self) {
        unsafe {
            ffi::pango_renderer_deactivate(self.as_ref().to_glib_none().0);
        }
    }

    /// Draw a squiggly line that approximately covers the given rectangle
    /// in the style of an underline used to indicate a spelling error.
    ///
    /// The width of the underline is rounded to an integer number
    /// of up/down segments and the resulting rectangle is centered
    /// in the original rectangle.
    ///
    /// This should be called while @self is already active.
    /// Use [`activate()`][Self::activate()] to activate a renderer.
    /// ## `x`
    /// X coordinate of underline, in Pango units in user coordinate system
    /// ## `y`
    /// Y coordinate of underline, in Pango units in user coordinate system
    /// ## `width`
    /// width of underline, in Pango units in user coordinate system
    /// ## `height`
    /// height of underline, in Pango units in user coordinate system
    #[doc(alias = "pango_renderer_draw_error_underline")]
    fn draw_error_underline(&self, x: i32, y: i32, width: i32, height: i32) {
        unsafe {
            ffi::pango_renderer_draw_error_underline(
                self.as_ref().to_glib_none().0,
                x,
                y,
                width,
                height,
            );
        }
    }

    /// Draws a single glyph with coordinates in device space.
    /// ## `font`
    /// a [`Font`][crate::Font]
    /// ## `glyph`
    /// the glyph index of a single glyph
    /// ## `x`
    /// X coordinate of left edge of baseline of glyph
    /// ## `y`
    /// Y coordinate of left edge of baseline of glyph
    #[doc(alias = "pango_renderer_draw_glyph")]
    fn draw_glyph(&self, font: &impl IsA<Font>, glyph: Glyph, x: f64, y: f64) {
        unsafe {
            ffi::pango_renderer_draw_glyph(
                self.as_ref().to_glib_none().0,
                font.as_ref().to_glib_none().0,
                glyph,
                x,
                y,
            );
        }
    }

    /// Draws the glyphs in @glyph_item with the specified [`Renderer`][crate::Renderer],
    /// embedding the text associated with the glyphs in the output if the
    /// output format supports it.
    ///
    /// This is useful for rendering text in PDF.
    ///
    /// Note that this method does not handle attributes in @glyph_item.
    /// If you want colors, shapes and lines handled automatically according
    /// to those attributes, you need to use pango_renderer_draw_layout_line()
    /// or pango_renderer_draw_layout().
    ///
    /// Note that @text is the start of the text for layout, which is then
    /// indexed by `glyph_item->item->offset`.
    ///
    /// If @text is [`None`], this simply calls [`draw_glyphs()`][Self::draw_glyphs()].
    ///
    /// The default implementation of this method simply falls back to
    /// [`draw_glyphs()`][Self::draw_glyphs()].
    /// ## `text`
    /// the UTF-8 text that @glyph_item refers to
    /// ## `glyph_item`
    /// a [`GlyphItem`][crate::GlyphItem]
    /// ## `x`
    /// X position of left edge of baseline, in user space coordinates
    ///   in Pango units
    /// ## `y`
    /// Y position of left edge of baseline, in user space coordinates
    ///   in Pango units
    #[doc(alias = "pango_renderer_draw_glyph_item")]
    fn draw_glyph_item(&self, text: Option<&str>, glyph_item: &mut GlyphItem, x: i32, y: i32) {
        unsafe {
            ffi::pango_renderer_draw_glyph_item(
                self.as_ref().to_glib_none().0,
                text.to_glib_none().0,
                glyph_item.to_glib_none_mut().0,
                x,
                y,
            );
        }
    }

    /// Draws the glyphs in @glyphs with the specified [`Renderer`][crate::Renderer].
    /// ## `font`
    /// a [`Font`][crate::Font]
    /// ## `glyphs`
    /// a [`GlyphString`][crate::GlyphString]
    /// ## `x`
    /// X position of left edge of baseline, in user space coordinates
    ///   in Pango units.
    /// ## `y`
    /// Y position of left edge of baseline, in user space coordinates
    ///   in Pango units.
    #[doc(alias = "pango_renderer_draw_glyphs")]
    fn draw_glyphs(&self, font: &impl IsA<Font>, glyphs: &mut GlyphString, x: i32, y: i32) {
        unsafe {
            ffi::pango_renderer_draw_glyphs(
                self.as_ref().to_glib_none().0,
                font.as_ref().to_glib_none().0,
                glyphs.to_glib_none_mut().0,
                x,
                y,
            );
        }
    }

    /// Draws @layout with the specified [`Renderer`][crate::Renderer].
    ///
    /// This is equivalent to drawing the lines of the layout, at their
    /// respective positions relative to @x, @y.
    /// ## `layout`
    /// a [`Layout`][crate::Layout]
    /// ## `x`
    /// X position of left edge of baseline, in user space coordinates
    ///   in Pango units.
    /// ## `y`
    /// Y position of left edge of baseline, in user space coordinates
    ///   in Pango units.
    #[doc(alias = "pango_renderer_draw_layout")]
    fn draw_layout(&self, layout: &Layout, x: i32, y: i32) {
        unsafe {
            ffi::pango_renderer_draw_layout(
                self.as_ref().to_glib_none().0,
                layout.to_glib_none().0,
                x,
                y,
            );
        }
    }

    /// Draws @line with the specified [`Renderer`][crate::Renderer].
    ///
    /// This draws the glyph items that make up the line, as well as
    /// shapes, backgrounds and lines that are specified by the attributes
    /// of those items.
    /// ## `line`
    /// a [`LayoutLine`][crate::LayoutLine]
    /// ## `x`
    /// X position of left edge of baseline, in user space coordinates
    ///   in Pango units.
    /// ## `y`
    /// Y position of left edge of baseline, in user space coordinates
    ///   in Pango units.
    #[doc(alias = "pango_renderer_draw_layout_line")]
    fn draw_layout_line(&self, line: &LayoutLine, x: i32, y: i32) {
        unsafe {
            ffi::pango_renderer_draw_layout_line(
                self.as_ref().to_glib_none().0,
                line.to_glib_none().0,
                x,
                y,
            );
        }
    }

    /// Draws an axis-aligned rectangle in user space coordinates with the
    /// specified [`Renderer`][crate::Renderer].
    ///
    /// This should be called while @self is already active.
    /// Use [`activate()`][Self::activate()] to activate a renderer.
    /// ## `part`
    /// type of object this rectangle is part of
    /// ## `x`
    /// X position at which to draw rectangle, in user space coordinates
    ///   in Pango units
    /// ## `y`
    /// Y position at which to draw rectangle, in user space coordinates
    ///   in Pango units
    /// ## `width`
    /// width of rectangle in Pango units
    /// ## `height`
    /// height of rectangle in Pango units
    #[doc(alias = "pango_renderer_draw_rectangle")]
    fn draw_rectangle(&self, part: RenderPart, x: i32, y: i32, width: i32, height: i32) {
        unsafe {
            ffi::pango_renderer_draw_rectangle(
                self.as_ref().to_glib_none().0,
                part.into_glib(),
                x,
                y,
                width,
                height,
            );
        }
    }

    /// Draws a trapezoid with the parallel sides aligned with the X axis
    /// using the given [`Renderer`][crate::Renderer]; coordinates are in device space.
    /// ## `part`
    /// type of object this trapezoid is part of
    /// ## `y1_`
    /// Y coordinate of top of trapezoid
    /// ## `x11`
    /// X coordinate of left end of top of trapezoid
    /// ## `x21`
    /// X coordinate of right end of top of trapezoid
    /// ## `y2`
    /// Y coordinate of bottom of trapezoid
    /// ## `x12`
    /// X coordinate of left end of bottom of trapezoid
    /// ## `x22`
    /// X coordinate of right end of bottom of trapezoid
    #[doc(alias = "pango_renderer_draw_trapezoid")]
    fn draw_trapezoid(
        &self,
        part: RenderPart,
        y1_: f64,
        x11: f64,
        x21: f64,
        y2: f64,
        x12: f64,
        x22: f64,
    ) {
        unsafe {
            ffi::pango_renderer_draw_trapezoid(
                self.as_ref().to_glib_none().0,
                part.into_glib(),
                y1_,
                x11,
                x21,
                y2,
                x12,
                x22,
            );
        }
    }

    /// Gets the current alpha for the specified part.
    /// ## `part`
    /// the part to get the alpha for
    ///
    /// # Returns
    ///
    /// the alpha for the specified part,
    ///   or 0 if it hasn't been set and should be
    ///   inherited from the environment.
    #[doc(alias = "pango_renderer_get_alpha")]
    #[doc(alias = "get_alpha")]
    fn alpha(&self, part: RenderPart) -> u16 {
        unsafe { ffi::pango_renderer_get_alpha(self.as_ref().to_glib_none().0, part.into_glib()) }
    }

    /// Gets the current rendering color for the specified part.
    /// ## `part`
    /// the part to get the color for
    ///
    /// # Returns
    ///
    /// the color for the
    ///   specified part, or [`None`] if it hasn't been set and should be
    ///   inherited from the environment.
    #[doc(alias = "pango_renderer_get_color")]
    #[doc(alias = "get_color")]
    fn color(&self, part: RenderPart) -> Option<Color> {
        unsafe {
            from_glib_none(ffi::pango_renderer_get_color(
                self.as_ref().to_glib_none().0,
                part.into_glib(),
            ))
        }
    }

    /// Gets the components that are included in the output of the renderer.
    ///
    /// # Returns
    ///
    /// the components
    #[cfg(feature = "v1_58")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_58")))]
    #[doc(alias = "pango_renderer_get_components")]
    #[doc(alias = "get_components")]
    fn components(&self) -> RenderComponent {
        unsafe {
            from_glib(ffi::pango_renderer_get_components(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the layout currently being rendered using @self.
    ///
    /// Calling this function only makes sense from inside a subclass's
    /// methods, like in its draw_shape vfunc, for example.
    ///
    /// The returned layout should not be modified while still being
    /// rendered.
    ///
    /// # Returns
    ///
    /// the layout, or [`None`] if
    ///   no layout is being rendered using @self at this time.
    #[doc(alias = "pango_renderer_get_layout")]
    #[doc(alias = "get_layout")]
    fn layout(&self) -> Option<Layout> {
        unsafe {
            from_glib_none(ffi::pango_renderer_get_layout(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the layout line currently being rendered using @self.
    ///
    /// Calling this function only makes sense from inside a subclass's
    /// methods, like in its draw_shape vfunc, for example.
    ///
    /// The returned layout line should not be modified while still being
    /// rendered.
    ///
    /// # Returns
    ///
    /// the layout line, or [`None`]
    ///   if no layout line is being rendered using @self at this time.
    #[doc(alias = "pango_renderer_get_layout_line")]
    #[doc(alias = "get_layout_line")]
    fn layout_line(&self) -> Option<LayoutLine> {
        unsafe {
            from_glib_none(ffi::pango_renderer_get_layout_line(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the transformation matrix that will be applied when
    /// rendering.
    ///
    /// See [`set_matrix()`][Self::set_matrix()].
    ///
    /// # Returns
    ///
    /// the matrix, or [`None`] if no matrix has
    ///   been set (which is the same as the identity matrix). The returned
    ///   matrix is owned by Pango and must not be modified or freed.
    #[doc(alias = "pango_renderer_get_matrix")]
    #[doc(alias = "get_matrix")]
    fn matrix(&self) -> Option<Matrix> {
        unsafe {
            from_glib_none(ffi::pango_renderer_get_matrix(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Informs Pango that the way that the rendering is done
    /// for @part has changed.
    ///
    /// This should be called if the rendering changes in a way that would
    /// prevent multiple pieces being joined together into one drawing call.
    /// For instance, if a subclass of [`Renderer`][crate::Renderer] was to add a stipple
    /// option for drawing underlines, it needs to call
    ///
    /// ```text
    /// pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE);
    /// ```
    ///
    /// When the stipple changes or underlines with different stipples
    /// might be joined together. Pango automatically calls this for
    /// changes to colors. (See [`set_color()`][Self::set_color()])
    /// ## `part`
    /// the part for which rendering has changed.
    #[doc(alias = "pango_renderer_part_changed")]
    fn part_changed(&self, part: RenderPart) {
        unsafe {
            ffi::pango_renderer_part_changed(self.as_ref().to_glib_none().0, part.into_glib());
        }
    }

    /// Sets the alpha for part of the rendering.
    ///
    /// Note that the alpha may only be used if a color is
    /// specified for @part as well.
    /// ## `part`
    /// the part to set the alpha for
    /// ## `alpha`
    /// an alpha value between 1 and 65536, or 0 to unset the alpha
    #[doc(alias = "pango_renderer_set_alpha")]
    fn set_alpha(&self, part: RenderPart, alpha: u16) {
        unsafe {
            ffi::pango_renderer_set_alpha(self.as_ref().to_glib_none().0, part.into_glib(), alpha);
        }
    }

    /// Sets the color for part of the rendering.
    ///
    /// Also see [`set_alpha()`][Self::set_alpha()].
    /// ## `part`
    /// the part to change the color of
    /// ## `color`
    /// the new color or [`None`] to unset the current color
    #[doc(alias = "pango_renderer_set_color")]
    fn set_color(&self, part: RenderPart, color: Option<&Color>) {
        unsafe {
            ffi::pango_renderer_set_color(
                self.as_ref().to_glib_none().0,
                part.into_glib(),
                color.to_glib_none().0,
            );
        }
    }

    /// Sets the components to include in the output of the renderer.
    /// ## `components`
    /// the components to include
    #[cfg(feature = "v1_58")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_58")))]
    #[doc(alias = "pango_renderer_set_components")]
    fn set_components(&self, components: RenderComponent) {
        unsafe {
            ffi::pango_renderer_set_components(
                self.as_ref().to_glib_none().0,
                components.into_glib(),
            );
        }
    }

    /// Sets the transformation matrix that will be applied when rendering.
    /// ## `matrix`
    /// a [`Matrix`][crate::Matrix], or [`None`] to unset any existing matrix
    ///  (No matrix set is the same as setting the identity matrix.)
    #[doc(alias = "pango_renderer_set_matrix")]
    fn set_matrix(&self, matrix: Option<&Matrix>) {
        unsafe {
            ffi::pango_renderer_set_matrix(self.as_ref().to_glib_none().0, matrix.to_glib_none().0);
        }
    }
}

impl<O: IsA<Renderer>> RendererExt for O {}