Package org.gnome.gsk

Class Path

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gsk.Path

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class Path
extends ProxyInstance

A GskPath 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).

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

Constructor Summary

Constructors

Constructor	Description
Path(MemorySegment address)	Create a Path proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
boolean	foreach(Set<PathForeachFlags> flags, PathForeachFunc func)	Calls func for every operation of the path.
boolean	foreach(PathForeachFlags flags, PathForeachFunc func)	Calls func for every operation of the path.
boolean	getBounds(Rect bounds)	Computes the bounds of the given path.
boolean	getClosestPoint(Point point, float threshold, PathPoint result, @Nullable Out<Float> distance)	Computes the closest point on the path to the given point and sets the result to it.
boolean	getEndPoint(PathPoint result)	Gets the end point of the path.
boolean	getStartPoint(PathPoint result)	Gets the start point of the path.
boolean	getStrokeBounds(Stroke stroke, Rect bounds)	Computes the bounds for stroking the given path with the parameters in stroke.
static Type	getType()	Get the GType of the Path class
boolean	inFill(Point point, FillRule fillRule)	Returns whether the given point is inside the area that would be affected if the path was filled according to fillRule.
boolean	isClosed()	Returns if the path represents a single closed contour.
boolean	isEmpty()	Checks if the path is empty, i.e.
static Path	parse(String string)	This is a convenience function that constructs a GskPath from a serialized form.
void	print(GString string)	Converts this Path into a human-readable string representation suitable for printing.
Path	ref()	Increases the reference count of a GskPath by one.
void	toCairo(org.freedesktop.cairo.Context cr)	Appends the given path to the given cairo context for drawing with Cairo.
String	toString()	Converts the path into a string that is suitable for printing.
void	unref()	Decreases the reference count of a GskPath by one.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

Path

public Path(MemorySegment address)

Create a Path proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Method Details

getType

public static Type getType()

Get the GType of the Path class

Returns:

the GType

parse

public static Path parse(String string)

This is a convenience function that constructs a GskPath from a serialized form.

The string is expected to be in (a superset of) SVG path syntax, as e.g. produced by toString().

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.

Parameters:

string - a string

Returns:

a new GskPath, or NULL if string could not be parsed

foreach

public boolean foreach(Set<PathForeachFlags> flags,
 PathForeachFunc func)

Calls func for every operation of the path.

Note that this may only approximate this Path, 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.

Parameters:

flags - flags to pass to the foreach function. See Gsk.PathForeachFlags for details about flags

func - the function to call for operations

Returns:

FALSE if func returned FALSE, TRUE` otherwise.

foreach

public boolean foreach(PathForeachFlags flags,
 PathForeachFunc func)

Calls func for every operation of the path.

Note that this may only approximate this Path, 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.

Parameters:

flags - flags to pass to the foreach function. See Gsk.PathForeachFlags for details about flags

func - the function to call for operations

Returns:

FALSE if func returned FALSE, TRUE` otherwise.

getBounds

public boolean getBounds(Rect bounds)

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.

Parameters:

bounds - the bounds of the given path

Returns:

TRUE if the path has bounds, FALSE if the path is known to be empty and have no bounds.

getClosestPoint

public boolean getClosestPoint(Point point,
 float threshold,
 PathPoint result,
 @Nullable
 @Nullable Out<Float> distance)

Computes the closest point on the path to the given point and sets the result to it.

If there is no point closer than the given threshold, FALSE is returned.

Parameters:

point - the point

threshold - maximum allowed distance

result - return location for the closest point

distance - return location for the distance

Returns:

TRUE if point was set to the closest point on this Path, FALSE if no point is closer than threshold

getEndPoint

public boolean getEndPoint(PathPoint result)

Gets the end point of the path.

An empty path has no points, so FALSE is returned in this case.

Parameters:

result - return location for point

Returns:

TRUE if result was filled

getStartPoint

public boolean getStartPoint(PathPoint result)

Gets the start point of the path.

An empty path has no points, so FALSE is returned in this case.

Parameters:

result - return location for point

Returns:

TRUE if result was filled

getStrokeBounds

public boolean getStrokeBounds(Stroke stroke,
 Rect bounds)

Computes the bounds for stroking the given path with the parameters in stroke.

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.

Parameters:

stroke - stroke parameters

bounds - the bounds to fill in

Returns:

TRUE if the path has bounds, FALSE if the path is known to be empty and have no bounds.

inFill

public boolean inFill(Point point,
 FillRule fillRule)

Returns whether the given point is inside the area that would be affected if the path was filled according to fillRule.

Note that this function assumes that filling a contour implicitly closes it.

Parameters:

point - the point to test

fillRule - the fill rule to follow

Returns:

TRUE if point is inside

isClosed

public boolean isClosed()

Returns if the path represents a single closed contour.

Returns:

TRUE if the path is closed

isEmpty

public boolean isEmpty()

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

Returns:

TRUE if the path is empty

print

public void print(GString string)

Converts this Path into a human-readable string representation suitable for printing.

The string is compatible with (a superset of) SVG path syntax, see parse(java.lang.String) for a summary of the syntax.

Parameters:

string - The string to print into

ref

public Path ref()

Increases the reference count of a GskPath by one.

Returns:

the passed in GskPath.

toCairo

public void toCairo(org.freedesktop.cairo.Context cr)

Appends the given path to the given cairo context for drawing with Cairo.

This may cause some suboptimal conversions to be performed as Cairo does not support all features of GskPath.

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

Parameters:

cr - a cairo context

toString

public String toString()

Converts the path into a string that is suitable for printing.

You can use this function in a debugger to get a quick overview of the path.

This is a wrapper around print(org.gnome.glib.GString), see that function for details.

Overrides:

toString in class Object

Returns:

A new string for this Path

unref

public void unref()

Decreases the reference count of a GskPath by one.

If the resulting reference count is zero, frees the path.