gsk4/auto/

path_builder.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

use crate::{ffi, Path, PathPoint, RoundedRect};
use glib::translate::*;

glib::wrapper! {
    /// An auxiliary object for constructing [`Path`][crate::Path] objects.
    ///
    /// A path is constructed like this:
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    /// GskPath *
    /// construct_path (void)
    /// {
    ///   GskPathBuilder *builder;
    ///
    ///   builder = gsk_path_builder_new ();
    ///
    ///   // add contours to the path here
    ///
    ///   return gsk_path_builder_free_to_path (builder);
    /// ```
    ///
    /// Adding contours to the path can be done in two ways.
    /// The easiest option is to use the `gsk_path_builder_add_*` group
    /// of functions that add predefined contours to the current path,
    /// either common shapes like [`add_circle()`][Self::add_circle()]
    /// or by adding from other paths like [`add_path()`][Self::add_path()].
    ///
    /// The `gsk_path_builder_add_*` methods always add complete contours,
    /// and do not use or modify the current point.
    ///
    /// The other option is to define each line and curve manually with
    /// the `gsk_path_builder_*_to` group of functions. You start with
    /// a call to [`move_to()`][Self::move_to()] to set the starting point
    /// and then use multiple calls to any of the drawing functions to
    /// move the pen along the plane. Once you are done, you can call
    /// [`close()`][Self::close()] to close the path by connecting it
    /// back with a line to the starting point.
    ///
    /// This is similar to how paths are drawn in Cairo.
    ///
    /// Note that [`PathBuilder`][crate::PathBuilder] will reduce the degree of added Bézier
    /// curves as much as possible, to simplify rendering.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct PathBuilder(Shared<ffi::GskPathBuilder>);

    match fn {
        ref => |ptr| ffi::gsk_path_builder_ref(ptr),
        unref => |ptr| ffi::gsk_path_builder_unref(ptr),
        type_ => || ffi::gsk_path_builder_get_type(),
    }
}

impl PathBuilder {
    /// Create a new [`PathBuilder`][crate::PathBuilder] object.
    ///
    /// The resulting builder would create an empty [`Path`][crate::Path].
    /// Use addition functions to add types to it.
    ///
    /// # Returns
    ///
    /// a new [`PathBuilder`][crate::PathBuilder]
    #[doc(alias = "gsk_path_builder_new")]
    pub fn new() -> PathBuilder {
        assert_initialized_main_thread!();
        unsafe { from_glib_full(ffi::gsk_path_builder_new()) }
    }

    /// Adds a circle as a new contour.
    ///
    /// The path is going around the circle in clockwise direction.
    ///
    /// If @radius is zero, the contour will be a closed point.
    /// ## `center`
    /// the center of the circle
    /// ## `radius`
    /// the radius of the circle
    #[doc(alias = "gsk_path_builder_add_circle")]
    pub fn add_circle(&self, center: &graphene::Point, radius: f32) {
        unsafe {
            ffi::gsk_path_builder_add_circle(
                self.to_glib_none().0,
                center.to_glib_none().0,
                radius,
            );
        }
    }

    /// Adds the outlines for the glyphs in @layout to the builder.
    /// ## `layout`
    /// the pango layout to add
    #[doc(alias = "gsk_path_builder_add_layout")]
    pub fn add_layout(&self, layout: &pango::Layout) {
        unsafe {
            ffi::gsk_path_builder_add_layout(self.to_glib_none().0, layout.to_glib_none().0);
        }
    }

    /// Appends all of @path to the builder.
    /// ## `path`
    /// the path to append
    #[doc(alias = "gsk_path_builder_add_path")]
    pub fn add_path(&self, path: &Path) {
        unsafe {
            ffi::gsk_path_builder_add_path(self.to_glib_none().0, path.to_glib_none().0);
        }
    }

    /// Adds a rectangle as a new contour.
    ///
    /// The path is going around the rectangle in clockwise direction.
    ///
    /// If the the width or height are 0, the path will be a closed
    /// horizontal or vertical line. If both are 0, it'll be a closed dot.
    /// ## `rect`
    /// the rectangle to create a path for
    #[doc(alias = "gsk_path_builder_add_rect")]
    pub fn add_rect(&self, rect: &graphene::Rect) {
        unsafe {
            ffi::gsk_path_builder_add_rect(self.to_glib_none().0, rect.to_glib_none().0);
        }
    }

    /// Appends all of @path to the builder, in reverse order.
    /// ## `path`
    /// the path to append
    #[doc(alias = "gsk_path_builder_add_reverse_path")]
    pub fn add_reverse_path(&self, path: &Path) {
        unsafe {
            ffi::gsk_path_builder_add_reverse_path(self.to_glib_none().0, path.to_glib_none().0);
        }
    }

    /// Adds a rounded rectangle as a new contour.
    ///
    /// The path is going around the rectangle in clockwise direction.
    /// ## `rect`
    /// the rounded rect
    #[doc(alias = "gsk_path_builder_add_rounded_rect")]
    pub fn add_rounded_rect(&self, rect: &RoundedRect) {
        unsafe {
            ffi::gsk_path_builder_add_rounded_rect(self.to_glib_none().0, rect.to_glib_none().0);
        }
    }

    /// Adds a segment of a path to the builder.
    ///
    /// If @start is equal to or after @end, the path will first add the
    /// segment from @start to the end of the path, and then add the segment
    /// from the beginning to @end. If the path is closed, these segments
    /// will be connected.
    ///
    /// Note that this method always adds a path with the given start point
    /// and end point. To add a closed path, use [`add_path()`][Self::add_path()].
    /// ## `path`
    /// the path to take the segment to
    /// ## `start`
    /// the point on @path to start at
    /// ## `end`
    /// the point on @path to end at
    #[doc(alias = "gsk_path_builder_add_segment")]
    pub fn add_segment(&self, path: &Path, start: &PathPoint, end: &PathPoint) {
        unsafe {
            ffi::gsk_path_builder_add_segment(
                self.to_glib_none().0,
                path.to_glib_none().0,
                start.to_glib_none().0,
                end.to_glib_none().0,
            );
        }
    }

    /// Adds an elliptical arc from the current point to @x2, @y2
    /// with @x1, @y1 determining the tangent directions.
    ///
    /// After this, @x2, @y2 will be the new current point.
    ///
    /// Note: Two points and their tangents do not determine
    /// a unique ellipse, so GSK just picks one. If you need more
    /// precise control, use [`conic_to()`][Self::conic_to()]
    /// or [`svg_arc_to()`][Self::svg_arc_to()].
    ///
    /// <picture>
    ///   <source srcset="arc-dark.png" media="(prefers-color-scheme: dark)">
    ///   <img alt="Arc To" src="arc-light.png">
    /// </picture>
    /// ## `x1`
    /// x coordinate of first control point
    /// ## `y1`
    /// y coordinate of first control point
    /// ## `x2`
    /// x coordinate of second control point
    /// ## `y2`
    /// y coordinate of second control point
    #[doc(alias = "gsk_path_builder_arc_to")]
    pub fn arc_to(&self, x1: f32, y1: f32, x2: f32, y2: f32) {
        unsafe {
            ffi::gsk_path_builder_arc_to(self.to_glib_none().0, x1, y1, x2, y2);
        }
    }

    /// Ends the current contour with a line back to the start point.
    ///
    /// Note that this is different from calling [`line_to()`][Self::line_to()]
    /// with the start point in that the contour will be closed. A closed
    /// contour behaves differently from an open one. When stroking, its
    /// start and end point are considered connected, so they will be
    /// joined via the line join, and not ended with line caps.
    #[doc(alias = "gsk_path_builder_close")]
    pub fn close(&self) {
        unsafe {
            ffi::gsk_path_builder_close(self.to_glib_none().0);
        }
    }

    /// Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline)
    /// from the current point to @x2, @y2 with the given @weight and @x1, @y1 as the
    /// control point.
    ///
    /// The weight determines how strongly the curve is pulled towards the control point.
    /// A conic with weight 1 is identical to a quadratic Bézier curve with the same points.
    ///
    /// Conic curves can be used to draw ellipses and circles. They are also known as
    /// rational quadratic Bézier curves.
    ///
    /// After this, @x2, @y2 will be the new current point.
    ///
    /// <picture>
    ///   <source srcset="conic-dark.png" media="(prefers-color-scheme: dark)">
    ///   <img alt="Conic To" src="conic-light.png">
    /// </picture>
    /// ## `x1`
    /// x coordinate of control point
    /// ## `y1`
    /// y coordinate of control point
    /// ## `x2`
    /// x coordinate of the end of the curve
    /// ## `y2`
    /// y coordinate of the end of the curve
    /// ## `weight`
    /// weight of the control point, must be greater than zero
    #[doc(alias = "gsk_path_builder_conic_to")]
    pub fn conic_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, weight: f32) {
        unsafe {
            ffi::gsk_path_builder_conic_to(self.to_glib_none().0, x1, y1, x2, y2, weight);
        }
    }

    /// Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B`C3``A9zier_curve`)
    /// from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control
    /// points.
    ///
    /// After this, @x3, @y3 will be the new current point.
    ///
    /// <picture>
    ///   <source srcset="cubic-dark.png" media="(prefers-color-scheme: dark)">
    ///   <img alt="Cubic To" src="cubic-light.png">
    /// </picture>
    /// ## `x1`
    /// x coordinate of first control point
    /// ## `y1`
    /// y coordinate of first control point
    /// ## `x2`
    /// x coordinate of second control point
    /// ## `y2`
    /// y coordinate of second control point
    /// ## `x3`
    /// x coordinate of the end of the curve
    /// ## `y3`
    /// y coordinate of the end of the curve
    #[doc(alias = "gsk_path_builder_cubic_to")]
    pub fn cubic_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, x3: f32, y3: f32) {
        unsafe {
            ffi::gsk_path_builder_cubic_to(self.to_glib_none().0, x1, y1, x2, y2, x3, y3);
        }
    }

    /// Gets the current point.
    ///
    /// The current point is used for relative drawing commands and
    /// updated after every operation.
    ///
    /// When the builder is created, the default current point is set
    /// to `0, 0`. Note that this is different from cairo, which starts
    /// out without a current point.
    ///
    /// # Returns
    ///
    /// the current point
    #[doc(alias = "gsk_path_builder_get_current_point")]
    #[doc(alias = "get_current_point")]
    pub fn current_point(&self) -> graphene::Point {
        unsafe {
            from_glib_none(ffi::gsk_path_builder_get_current_point(
                self.to_glib_none().0,
            ))
        }
    }

    /// Implements arc-to according to the HTML Canvas spec.
    ///
    /// A convenience function that implements the
    /// [HTML arc_to](https://html.spec.whatwg.org/multipage/canvas.html#dom-context-2d-arcto-dev)
    /// functionality.
    ///
    /// After this, the current point will be the point where
    /// the circle with the given radius touches the line from
    /// @x1, @y1 to @x2, @y2.
    /// ## `x1`
    /// x coordinate of first control point
    /// ## `y1`
    /// y coordinate of first control point
    /// ## `x2`
    /// x coordinate of second control point
    /// ## `y2`
    /// y coordinate of second control point
    /// ## `radius`
    /// radius of the circle
    #[doc(alias = "gsk_path_builder_html_arc_to")]
    pub fn html_arc_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, radius: f32) {
        unsafe {
            ffi::gsk_path_builder_html_arc_to(self.to_glib_none().0, x1, y1, x2, y2, radius);
        }
    }

    /// Draws a line from the current point to @x, @y and makes it
    /// the new current point.
    ///
    /// <picture>
    ///   <source srcset="line-dark.png" media="(prefers-color-scheme: dark)">
    ///   <img alt="Line To" src="line-light.png">
    /// </picture>
    /// ## `x`
    /// x coordinate
    /// ## `y`
    /// y coordinate
    #[doc(alias = "gsk_path_builder_line_to")]
    pub fn line_to(&self, x: f32, y: f32) {
        unsafe {
            ffi::gsk_path_builder_line_to(self.to_glib_none().0, x, y);
        }
    }

    /// Starts a new contour by placing the pen at @x, @y.
    ///
    /// If this function is called twice in succession, the first
    /// call will result in a contour made up of a single point.
    /// The second call will start a new contour.
    /// ## `x`
    /// x coordinate
    /// ## `y`
    /// y coordinate
    #[doc(alias = "gsk_path_builder_move_to")]
    pub fn move_to(&self, x: f32, y: f32) {
        unsafe {
            ffi::gsk_path_builder_move_to(self.to_glib_none().0, x, y);
        }
    }

    /// Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B`C3``A9zier_curve`)
    /// from the current point to @x2, @y2 with @x1, @y1 as the control point.
    ///
    /// After this, @x2, @y2 will be the new current point.
    ///
    /// <picture>
    ///   <source srcset="quad-dark.png" media="(prefers-color-scheme: dark)">
    ///   <img alt="Quad To" src="quad-light.png">
    /// </picture>
    /// ## `x1`
    /// x coordinate of control point
    /// ## `y1`
    /// y coordinate of control point
    /// ## `x2`
    /// x coordinate of the end of the curve
    /// ## `y2`
    /// y coordinate of the end of the curve
    #[doc(alias = "gsk_path_builder_quad_to")]
    pub fn quad_to(&self, x1: f32, y1: f32, x2: f32, y2: f32) {
        unsafe {
            ffi::gsk_path_builder_quad_to(self.to_glib_none().0, x1, y1, x2, y2);
        }
    }

    /// Adds an elliptical arc from the current point to @x2, @y2
    /// with @x1, @y1 determining the tangent directions.
    ///
    /// All coordinates are given relative to the current point.
    ///
    /// This is the relative version of [`arc_to()`][Self::arc_to()].
    /// ## `x1`
    /// x coordinate of first control point
    /// ## `y1`
    /// y coordinate of first control point
    /// ## `x2`
    /// x coordinate of second control point
    /// ## `y2`
    /// y coordinate of second control point
    #[doc(alias = "gsk_path_builder_rel_arc_to")]
    pub fn rel_arc_to(&self, x1: f32, y1: f32, x2: f32, y2: f32) {
        unsafe {
            ffi::gsk_path_builder_rel_arc_to(self.to_glib_none().0, x1, y1, x2, y2);
        }
    }

    /// Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline)
    /// from the current point to @x2, @y2 with the given @weight and @x1, @y1 as the
    /// control point.
    ///
    /// All coordinates are given relative to the current point.
    ///
    /// This is the relative version of [`conic_to()`][Self::conic_to()].
    /// ## `x1`
    /// x offset of control point
    /// ## `y1`
    /// y offset of control point
    /// ## `x2`
    /// x offset of the end of the curve
    /// ## `y2`
    /// y offset of the end of the curve
    /// ## `weight`
    /// weight of the curve, must be greater than zero
    #[doc(alias = "gsk_path_builder_rel_conic_to")]
    pub fn rel_conic_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, weight: f32) {
        unsafe {
            ffi::gsk_path_builder_rel_conic_to(self.to_glib_none().0, x1, y1, x2, y2, weight);
        }
    }

    /// Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B`C3``A9zier_curve`)
    /// from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control
    /// points.
    ///
    /// All coordinates are given relative to the current point.
    ///
    /// This is the relative version of [`cubic_to()`][Self::cubic_to()].
    /// ## `x1`
    /// x offset of first control point
    /// ## `y1`
    /// y offset of first control point
    /// ## `x2`
    /// x offset of second control point
    /// ## `y2`
    /// y offset of second control point
    /// ## `x3`
    /// x offset of the end of the curve
    /// ## `y3`
    /// y offset of the end of the curve
    #[doc(alias = "gsk_path_builder_rel_cubic_to")]
    pub fn rel_cubic_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, x3: f32, y3: f32) {
        unsafe {
            ffi::gsk_path_builder_rel_cubic_to(self.to_glib_none().0, x1, y1, x2, y2, x3, y3);
        }
    }

    /// Implements arc-to according to the HTML Canvas spec.
    ///
    /// All coordinates are given relative to the current point.
    ///
    /// This is the relative version of [`html_arc_to()`][Self::html_arc_to()].
    /// ## `x1`
    /// x coordinate of first control point
    /// ## `y1`
    /// y coordinate of first control point
    /// ## `x2`
    /// x coordinate of second control point
    /// ## `y2`
    /// y coordinate of second control point
    /// ## `radius`
    /// radius of the circle
    #[doc(alias = "gsk_path_builder_rel_html_arc_to")]
    pub fn rel_html_arc_to(&self, x1: f32, y1: f32, x2: f32, y2: f32, radius: f32) {
        unsafe {
            ffi::gsk_path_builder_rel_html_arc_to(self.to_glib_none().0, x1, y1, x2, y2, radius);
        }
    }

    /// Draws a line from the current point to a point offset from it
    /// by @x, @y and makes it the new current point.
    ///
    /// This is the relative version of [`line_to()`][Self::line_to()].
    /// ## `x`
    /// x offset
    /// ## `y`
    /// y offset
    #[doc(alias = "gsk_path_builder_rel_line_to")]
    pub fn rel_line_to(&self, x: f32, y: f32) {
        unsafe {
            ffi::gsk_path_builder_rel_line_to(self.to_glib_none().0, x, y);
        }
    }

    /// Starts a new contour by placing the pen at @x, @y
    /// relative to the current point.
    ///
    /// This is the relative version of [`move_to()`][Self::move_to()].
    /// ## `x`
    /// x offset
    /// ## `y`
    /// y offset
    #[doc(alias = "gsk_path_builder_rel_move_to")]
    pub fn rel_move_to(&self, x: f32, y: f32) {
        unsafe {
            ffi::gsk_path_builder_rel_move_to(self.to_glib_none().0, x, y);
        }
    }

    /// Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B`C3``A9zier_curve`)
    /// from the current point to @x2, @y2 with @x1, @y1 the control point.
    ///
    /// All coordinates are given relative to the current point.
    ///
    /// This is the relative version of [`quad_to()`][Self::quad_to()].
    /// ## `x1`
    /// x offset of control point
    /// ## `y1`
    /// y offset of control point
    /// ## `x2`
    /// x offset of the end of the curve
    /// ## `y2`
    /// y offset of the end of the curve
    #[doc(alias = "gsk_path_builder_rel_quad_to")]
    pub fn rel_quad_to(&self, x1: f32, y1: f32, x2: f32, y2: f32) {
        unsafe {
            ffi::gsk_path_builder_rel_quad_to(self.to_glib_none().0, x1, y1, x2, y2);
        }
    }

    /// Implements arc-to according to the SVG spec.
    ///
    /// All coordinates are given relative to the current point.
    ///
    /// This is the relative version of [`svg_arc_to()`][Self::svg_arc_to()].
    /// ## `rx`
    /// x radius
    /// ## `ry`
    /// y radius
    /// ## `x_axis_rotation`
    /// the rotation of the ellipsis
    /// ## `large_arc`
    /// whether to add the large arc
    /// ## `positive_sweep`
    /// whether to sweep in the positive direction
    /// ## `x`
    /// x coordinate of the endpoint
    /// ## `y`
    /// y coordinate of the endpoint
    #[doc(alias = "gsk_path_builder_rel_svg_arc_to")]
    pub fn rel_svg_arc_to(
        &self,
        rx: f32,
        ry: f32,
        x_axis_rotation: f32,
        large_arc: bool,
        positive_sweep: bool,
        x: f32,
        y: f32,
    ) {
        unsafe {
            ffi::gsk_path_builder_rel_svg_arc_to(
                self.to_glib_none().0,
                rx,
                ry,
                x_axis_rotation,
                large_arc.into_glib(),
                positive_sweep.into_glib(),
                x,
                y,
            );
        }
    }

    /// Implements arc-to according to the SVG spec.
    ///
    /// A convenience function that implements the
    /// [SVG arc_to](https://www.w3.org/TR/SVG11/paths.html#PathDataEllipticalArcCommands)
    /// functionality.
    ///
    /// After this, @x, @y will be the new current point.
    /// ## `rx`
    /// x radius
    /// ## `ry`
    /// y radius
    /// ## `x_axis_rotation`
    /// the rotation of the ellipsis
    /// ## `large_arc`
    /// whether to add the large arc
    /// ## `positive_sweep`
    /// whether to sweep in the positive direction
    /// ## `x`
    /// x coordinate of the endpoint
    /// ## `y`
    /// y coordinate of the endpoint
    #[doc(alias = "gsk_path_builder_svg_arc_to")]
    pub fn svg_arc_to(
        &self,
        rx: f32,
        ry: f32,
        x_axis_rotation: f32,
        large_arc: bool,
        positive_sweep: bool,
        x: f32,
        y: f32,
    ) {
        unsafe {
            ffi::gsk_path_builder_svg_arc_to(
                self.to_glib_none().0,
                rx,
                ry,
                x_axis_rotation,
                large_arc.into_glib(),
                positive_sweep.into_glib(),
                x,
                y,
            );
        }
    }

    /// Creates a new path from the given builder.
    ///
    /// The given [`PathBuilder`][crate::PathBuilder] is reset once this function returns;
    /// you cannot call this function multiple times on the same builder
    /// instance.
    ///
    /// This function is intended primarily for language bindings.
    /// C code should use `Gsk::PathBuilder::free_to_path()`.
    ///
    /// # Returns
    ///
    /// the newly created path
    ///   with all the contours added to the builder
    #[doc(alias = "gsk_path_builder_to_path")]
    pub fn to_path(&self) -> Path {
        unsafe { from_glib_full(ffi::gsk_path_builder_to_path(self.to_glib_none().0)) }
    }
}

#[cfg(feature = "v4_14")]
#[cfg_attr(docsrs, doc(cfg(feature = "v4_14")))]
impl Default for PathBuilder {
    fn default() -> Self {
        Self::new()
    }
}