Struct Path

pub struct Path { /* private fields */ }

Available on crate feature v4_14 only.

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 is an immutable, opaque, reference-counted struct. After creation, you cannot change the types it represents. Instead, new Path objects have to be created. The 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.

GLib type: Shared boxed type with reference counted clone semantics.

Implementations

impl Path

pub fn as_ptr(&self) -> *mut GskPath

Return the inner pointer to the underlying C value.

pub unsafe fn from_glib_ptr_borrow(ptr: &*mut GskPath) -> &Self

Borrows the underlying C value.

impl Path

pub fn bounds(&self) -> Option<Rect>

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

pub fn closest_point( &self, point: &Point, threshold: f32, ) -> Option<(PathPoint, f32)>

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

pub fn end_point(&self) -> Option<PathPoint>

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

pub fn start_point(&self) -> Option<PathPoint>

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

pub fn stroke_bounds(&self, stroke: &Stroke) -> Option<Rect>

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

pub fn in_fill(&self, point: &Point, fill_rule: FillRule) -> bool

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

pub fn is_closed(&self) -> bool

Returns if the path represents a single closed contour.

Returns

true if the path is closed

pub fn is_empty(&self) -> bool

Checks if the path is empty, i.e. contains no lines or curves.

Returns

true if the path is empty

pub fn to_cairo(&self, cr: &Context)

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.

This function does not clear the existing Cairo path. Call cairo_new_path() if you want this.

cr

a cairo context

pub fn to_str(&self) -> GString

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

pub fn parse(string: &str) -> Result<Path, BoolError>

Constructs a path from a serialized form.

The string is expected to be in (a superset of) SVG path syntax, as e.g. produced by 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, or NULL if @string could not be parsed

impl Path

pub fn foreach<P: FnMut(&PathOperation, &Point, usize, f32) -> ControlFlow>( &self, flags: PathForeachFlags, func: P, ) -> ControlFlow

Calls @func for every operation of the path.

Note that this may only approximate @self, because paths can contain optimizations for various specialized contours, and depending on the @flags, the path may be decomposed into simpler curves than the ones that it contained originally.

This function serves two purposes:

• When the @flags allow everything, it provides access to the raw, unmodified data of the path.
• When the @flags disallow certain operations, it provides an approximation of the path using just the allowed operations.

flags

flags to pass to the foreach function

func

the function to call for operations

Returns

false if @func returned false, true otherwise.

Trait Implementations

impl Clone for Path

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the reference. Dropping the reference will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Path

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Path

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Path> for Value

fn from(s: Path) -> Self

Converts to this type from the input type.

impl FromStr for Path

type Err = BoolError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl HasParamSpec for Path

type ParamSpec = ParamSpecBoxed

type SetValue = Path

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecBoxedBuilder<'_, Path>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for Path

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Path

fn cmp(&self, other: &Path) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Path

fn eq(&self, other: &Path) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Path

fn partial_cmp(&self, other: &Path) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for Path

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for Path

impl StructuralPartialEq for Path