Gsk.Path¶

Fields¶

None

Methods¶

class	`parse` (string)
	`foreach` (flags, func, *user_data)
	`get_bounds` ()
	`get_closest_point` (point, threshold)
	`get_end_point` ()
	`get_start_point` ()
	`get_stroke_bounds` (stroke)
	`in_fill` (point, fill_rule)
	`is_closed` ()
	`is_empty` ()
	`print_` (string)
	`ref` ()
	`to_cairo` (cr)
	`to_string` ()
	`unref` ()

Details¶

class Gsk.Path¶

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 [struct`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.

New in version 4.14.

classmethod parse(string)¶

Parameters:: string (str) – a string
Returns:: a new GskPath, or NULL if string could not be parsed
Return type:: Gsk.Path or None

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 [method`Gsk`.Path.to_string].

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.

New in version 4.14.

foreach(flags, func, *user_data)¶

Parameters:

flags (Gsk.PathForeachFlags) – flags to pass to the foreach function
func (Gsk.PathForeachFunc) – the function to call for operations
user_data (object or None) – user data passed to func

Returns:

false if func returned false, true otherwise.

Return type:

bool

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.

New in version 4.14.

get_bounds()¶

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

Return type:

(bool, bounds: Graphene.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.

New in version 4.14.

get_closest_point(point, threshold)¶

Parameters:

point (Graphene.Point) – the point
threshold (float) – 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

Return type:

(bool, result: Gsk.PathPoint, distance: float)

Computes the closest point on the path to the given point.

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

New in version 4.14.

get_end_point()¶

Returns:

true if result was filled

result:: return location for point

Return type:

(bool, result: Gsk.PathPoint)

Gets the end point of the path.

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

New in version 4.14.

get_start_point()¶

Returns:

true if result was filled

result:: return location for point

Return type:

(bool, result: Gsk.PathPoint)

Gets the start point of the path.

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

New in version 4.14.

get_stroke_bounds(stroke)¶

Parameters:

stroke (Gsk.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

Return type:

(bool, bounds: Graphene.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.

New in version 4.14.

in_fill(point, fill_rule)¶

Parameters:

point (Graphene.Point) – the point to test
fill_rule (Gsk.FillRule) – the fill rule to follow

Returns:

true if point is inside

Return type:

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.

New in version 4.14.

is_closed()¶

Returns:: true if the path is closed
Return type:: bool

Returns if the path represents a single closed contour.

New in version 4.14.

is_empty()¶

Returns:: true if the path is empty
Return type:: bool

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

New in version 4.14.

print_(string)¶

Parameters:: string (GLib.String) – the string to print into

Converts the path into a human-readable representation.

The string is compatible with (a superset of) SVG path syntax, see [func`Gsk`.Path.parse] for a summary of the syntax.

New in version 4.14.

ref()¶

Returns:: the passed in GskPath
Return type:: Gsk.Path

Increases the reference count of a path by one.

New in version 4.14.

to_cairo(cr)¶

Parameters:: cr (cairo.Context) – a cairo 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 GskPath.

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

New in version 4.14.

to_string()¶

Returns:: a new string for self
Return type:: str

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 [method`Gsk`.Path.print], see that function for details.

New in version 4.14.

unref()¶

Decreases the reference count of a path by one.

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

New in version 4.14.