gsk4/auto/

path.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, FillRule, PathPoint, Stroke};
use glib::translate::*;

glib::wrapper! {
    /// Describes lines and curves that are more complex than simple rectangles.
    ///
    /// Paths can used for rendering (filling or stroking) and for animations
    /// (e.g. as trajectories).
    ///
    /// [`Path`][crate::Path] is an immutable, opaque, reference-counted struct.
    /// After creation, you cannot change the types it represents. Instead,
    /// new [`Path`][crate::Path] objects have to be created. The [`PathBuilder`][crate::PathBuilder]
    /// structure is meant to help in this endeavor.
    ///
    /// Conceptually, a path consists of zero or more contours (continuous, connected
    /// curves), each of which may or may not be closed. Contours are typically
    /// constructed from Bézier segments.
    ///
    /// <picture>
    ///   <source srcset="path-dark.png" media="(prefers-color-scheme: dark)">
    ///   <img alt="A Path" src="path-light.png">
    /// </picture>
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct Path(Shared<ffi::GskPath>);

    match fn {
        ref => |ptr| ffi::gsk_path_ref(ptr),
        unref => |ptr| ffi::gsk_path_unref(ptr),
        type_ => || ffi::gsk_path_get_type(),
    }
}

impl Path {
    /// Computes the bounds of the given path.
    ///
    /// The returned bounds may be larger than necessary, because this
    /// function aims to be fast, not accurate. The bounds are guaranteed
    /// to contain the path.
    ///
    /// It is possible that the returned rectangle has 0 width and/or height.
    /// This can happen when the path only describes a point or an
    /// axis-aligned line.
    ///
    /// If the path is empty, false is returned and @bounds are set to
    /// graphene_rect_zero(). This is different from the case where the path
    /// is a single point at the origin, where the @bounds will also be set to
    /// the zero rectangle but true will be returned.
    ///
    /// # Returns
    ///
    /// true if the path has bounds, false if the path is known
    ///   to be empty and have no bounds
    ///
    /// ## `bounds`
    /// return location for the bounds
    #[doc(alias = "gsk_path_get_bounds")]
    #[doc(alias = "get_bounds")]
    pub fn bounds(&self) -> Option<graphene::Rect> {
        unsafe {
            let mut bounds = graphene::Rect::uninitialized();
            let ret = from_glib(ffi::gsk_path_get_bounds(
                self.to_glib_none().0,
                bounds.to_glib_none_mut().0,
            ));
            if ret {
                Some(bounds)
            } else {
                None
            }
        }
    }

    /// Computes the closest point on the path to the given point.
    ///
    /// If there is no point closer than the given threshold,
    /// false is returned.
    /// ## `point`
    /// the point
    /// ## `threshold`
    /// maximum allowed distance
    ///
    /// # Returns
    ///
    /// true if @point was set to the closest point
    ///   on @self, false if no point is closer than @threshold
    ///
    /// ## `result`
    /// return location for the closest point
    ///
    /// ## `distance`
    /// return location for the distance
    #[doc(alias = "gsk_path_get_closest_point")]
    #[doc(alias = "get_closest_point")]
    pub fn closest_point(
        &self,
        point: &graphene::Point,
        threshold: f32,
    ) -> Option<(PathPoint, f32)> {
        unsafe {
            let mut result = PathPoint::uninitialized();
            let mut distance = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::gsk_path_get_closest_point(
                self.to_glib_none().0,
                point.to_glib_none().0,
                threshold,
                result.to_glib_none_mut().0,
                distance.as_mut_ptr(),
            ));
            if ret {
                Some((result, distance.assume_init()))
            } else {
                None
            }
        }
    }

    /// Gets the end point of the path.
    ///
    /// An empty path has no points, so false
    /// is returned in this case.
    ///
    /// # Returns
    ///
    /// true if @result was filled
    ///
    /// ## `result`
    /// return location for point
    #[doc(alias = "gsk_path_get_end_point")]
    #[doc(alias = "get_end_point")]
    pub fn end_point(&self) -> Option<PathPoint> {
        unsafe {
            let mut result = PathPoint::uninitialized();
            let ret = from_glib(ffi::gsk_path_get_end_point(
                self.to_glib_none().0,
                result.to_glib_none_mut().0,
            ));
            if ret {
                Some(result)
            } else {
                None
            }
        }
    }

    /// Gets the start point of the path.
    ///
    /// An empty path has no points, so false
    /// is returned in this case.
    ///
    /// # Returns
    ///
    /// true if @result was filled
    ///
    /// ## `result`
    /// return location for point
    #[doc(alias = "gsk_path_get_start_point")]
    #[doc(alias = "get_start_point")]
    pub fn start_point(&self) -> Option<PathPoint> {
        unsafe {
            let mut result = PathPoint::uninitialized();
            let ret = from_glib(ffi::gsk_path_get_start_point(
                self.to_glib_none().0,
                result.to_glib_none_mut().0,
            ));
            if ret {
                Some(result)
            } else {
                None
            }
        }
    }

    /// Computes the bounds for stroking the given path with the
    /// given parameters.
    ///
    /// The returned bounds may be larger than necessary, because this
    /// function aims to be fast, not accurate. The bounds are guaranteed
    /// to contain the area affected by the stroke, including protrusions
    /// like miters.
    /// ## `stroke`
    /// stroke parameters
    ///
    /// # Returns
    ///
    /// true if the path has bounds, false if the path is known
    ///   to be empty and have no bounds.
    ///
    /// ## `bounds`
    /// the bounds to fill in
    #[doc(alias = "gsk_path_get_stroke_bounds")]
    #[doc(alias = "get_stroke_bounds")]
    pub fn stroke_bounds(&self, stroke: &Stroke) -> Option<graphene::Rect> {
        unsafe {
            let mut bounds = graphene::Rect::uninitialized();
            let ret = from_glib(ffi::gsk_path_get_stroke_bounds(
                self.to_glib_none().0,
                stroke.to_glib_none().0,
                bounds.to_glib_none_mut().0,
            ));
            if ret {
                Some(bounds)
            } else {
                None
            }
        }
    }

    /// Returns whether a point is inside the fill area of a path.
    ///
    /// Note that this function assumes that filling a contour
    /// implicitly closes it.
    /// ## `point`
    /// the point to test
    /// ## `fill_rule`
    /// the fill rule to follow
    ///
    /// # Returns
    ///
    /// true if @point is inside
    #[doc(alias = "gsk_path_in_fill")]
    pub fn in_fill(&self, point: &graphene::Point, fill_rule: FillRule) -> bool {
        unsafe {
            from_glib(ffi::gsk_path_in_fill(
                self.to_glib_none().0,
                point.to_glib_none().0,
                fill_rule.into_glib(),
            ))
        }
    }

    /// Returns if the path represents a single closed contour.
    ///
    /// # Returns
    ///
    /// true if the path is closed
    #[doc(alias = "gsk_path_is_closed")]
    pub fn is_closed(&self) -> bool {
        unsafe { from_glib(ffi::gsk_path_is_closed(self.to_glib_none().0)) }
    }

    /// Checks if the path is empty, i.e. contains no lines or curves.
    ///
    /// # Returns
    ///
    /// true if the path is empty
    #[doc(alias = "gsk_path_is_empty")]
    pub fn is_empty(&self) -> bool {
        unsafe { from_glib(ffi::gsk_path_is_empty(self.to_glib_none().0)) }
    }

    /// Appends the path to a cairo context for drawing with Cairo.
    ///
    /// This may cause some suboptimal conversions to be performed as
    /// Cairo does not support all features of [`Path`][crate::Path].
    ///
    /// This function does not clear the existing Cairo path. Call
    /// cairo_new_path() if you want this.
    /// ## `cr`
    /// a cairo context
    #[doc(alias = "gsk_path_to_cairo")]
    pub fn to_cairo(&self, cr: &cairo::Context) {
        unsafe {
            ffi::gsk_path_to_cairo(self.to_glib_none().0, mut_override(cr.to_glib_none().0));
        }
    }

    /// Converts the path into a human-readable string.
    ///
    /// You can use this function in a debugger to get a quick overview
    /// of the path.
    ///
    /// This is a wrapper around `Gsk::Path::print()`, see that function
    /// for details.
    ///
    /// # Returns
    ///
    /// a new string for @self
    #[doc(alias = "gsk_path_to_string")]
    #[doc(alias = "to_string")]
    pub fn to_str(&self) -> glib::GString {
        unsafe { from_glib_full(ffi::gsk_path_to_string(self.to_glib_none().0)) }
    }

    /// Constructs a path from a serialized form.
    ///
    /// The string is expected to be in (a superset of)
    /// [SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData),
    /// as e.g. produced by [`to_str()`][Self::to_str()].
    ///
    /// A high-level summary of the syntax:
    ///
    /// - `M x y` Move to `(x, y)`
    /// - `L x y` Add a line from the current point to `(x, y)`
    /// - `Q x1 y1 x2 y2` Add a quadratic Bézier from the current point to `(x2, y2)`, with control point `(x1, y1)`
    /// - `C x1 y1 x2 y2 x3 y3` Add a cubic Bézier from the current point to `(x3, y3)`, with control points `(x1, y1)` and `(x2, y2)`
    /// - `Z` Close the contour by drawing a line back to the start point
    /// - `H x` Add a horizontal line from the current point to the given x value
    /// - `V y` Add a vertical line from the current point to the given y value
    /// - `T x2 y2` Add a quadratic Bézier, using the reflection of the previous segments' control point as control point
    /// - `S x2 y2 x3 y3` Add a cubic Bézier, using the reflection of the previous segments' second control point as first control point
    /// - `A rx ry r l s x y` Add an elliptical arc from the current point to `(x, y)` with radii rx and ry. See the SVG documentation for how the other parameters influence the arc.
    /// - `O x1 y1 x2 y2 w` Add a rational quadratic Bézier from the current point to `(x2, y2)` with control point `(x1, y1)` and weight `w`.
    ///
    /// All the commands have lowercase variants that interpret coordinates
    /// relative to the current point.
    ///
    /// The `O` command is an extension that is not supported in SVG.
    /// ## `string`
    /// a string
    ///
    /// # Returns
    ///
    /// a new [`Path`][crate::Path], or `NULL` if @string could not be parsed
    #[doc(alias = "gsk_path_parse")]
    pub fn parse(string: &str) -> Result<Path, glib::BoolError> {
        assert_initialized_main_thread!();
        unsafe {
            Option::<_>::from_glib_full(ffi::gsk_path_parse(string.to_glib_none().0))
                .ok_or_else(|| glib::bool_error!("Can't parse Path"))
        }
    }
}

impl std::fmt::Display for Path {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.write_str(&self.to_str())
    }
}