4.4 KiB
Title: Paths Slug: paths
GSK provides a path object that can be used to render more complex shapes than lines or rounded rectangles. It is comparable to cairos path API, with some notable differences.
In general, a path consists of one or more connected contours, each of which may have multiple segments, and may or may not be closed.
The central object of the GSK path api is the immutable [struct@Gsk.Path] struct, which contains path data in compact form suitable for rendering.
Creating Paths
Since GskPath is immutable, the auxiliary [struct@Gsk.PathBuilder] struct
can be used to construct a path piece by piece. The GskPathBuilder API
has three distinct groups of functions:
-
Functions for adding complete contours, such as [method@Gsk.PathBuilder.add_rect], [method@Gsk.PathBuilder.add_rounded_rect], [method@Gsk.PathBuilder.add_circle].
-
Functions for building contours from individual segments, like [method@Gsk.PathBuilder.move_to], [method@Gsk.PathBuilder.line_to], [method@Gsk.PathBuilder.cubic_to], [method@Gsk.PathBuilder.close].
-
Adding parts of a preexisting path. Functions in this group include [method@Gsk.PathBuilder.add_path] and [method@Gsk.PathBuilder.add_segment].
When you are done with building a path, you can convert the accumulated path
data into a GskPath struct with [method@Gsk.PathBuilder.free_to_path].
A sometimes convenient alternative is to create a path from a serialized form, with [func@Gsk.Path.parse]. This function interprets strings in SVG path syntax, such as:
M 100 100 C 100 200 200 200 200 100 Z
Rendering with Paths
There are two main ways to render with paths. The first is to fill the interior of a path with a color or more complex content, such as a gradient. GSK currently supports two different ways of determining what part of the plane are interior to the path, which can be selected with a [enum@Gsk.FillRule] value.
Alternatively, a path can be stroked, which means to emulate drawing with an idealized pen along the path. The result of stroking a path is another path (the stroke path), which is then filled.
The stroke operation can be influenced with the [struct@Gsk.Stroke] struct that collects various stroke parameters, such as the line width, the style of line joins and line caps to use, and a dash pattern.
GSK provides render nodes for these path rendering operations: [class@Gsk.FillNode] and [class@Gsk.StrokeNode], and GTK has convenience API to use them with [class@Gtk.Snapshot].
Other Path APIs
Beyond rendering, paths can be used e.g. as trajectories in animations.
In such uses, it is often important to access properties of paths, such as
their tangents at certain points. GSK provides an abstract representation
for points on a path in the form of the [struct@Gsk.PathPoint] struct.
You can query properties of a path at certain point once you have a
GskPathPoint representing that point.
GskPathPoint structs can be compared for equality with [method@Gsk.PathPoint.equal]
and ordered wrt. to which one comes first, using [method@Gsk.PathPoint.compare].
To obtain a GskPathPoint, use [method@Gsk.Path.get_closest_point], [method@Gsk.Path.get_start_point] or [method@Gsk.Path.get_end_point].
To query properties of the path at a point, use [method@Gsk.PathPoint.get_position], [method@Gsk.PathPoint.get_tangent], [method@Gsk.PathPoint.get_rotation] and [method@Gsk.PathPoint.get_curvature].