Gsk::Path Class Reference

Describes lines and curves that are more complex than simple rectangles. More...

#include <gskmm/path.h>

Public Types
enum class	ForeachFlags {   ForeachFlags::ONLY_LINES = 0x0 ,   ForeachFlags::QUAD = 1 << 0 ,   ForeachFlags::CUBIC = 1 << 1 ,   ForeachFlags::CONIC = 1 << 2 }
	Flags that can be passed to Gsk::Path::foreach() to influence what kinds of operations the path is decomposed into. More...
enum class	Intersection {   Intersection::NONE ,   Intersection::NORMAL ,   Intersection::START ,   Intersection::END }
	The values of this enumeration classify intersections between paths. More...
enum class	Operation {   Operation::MOVE ,   Operation::CLOSE ,   Operation::LINE ,   Operation::QUAD ,   Operation::CUBIC ,   Operation::CONIC }
	Describes the segments of a Gsk::Path. More...
using	SlotForeach = sigc::slot<bool(Operation, const std::vector<Gdk::Graphene::Point>&, float)>
	Type of the callback to iterate through the operations of a path.
using	SlotIntersection
	Type of the callback to iterate through the intersections of two paths.

Public Member Functions
void	reference () const
	Increment the reference count for this object.
void	unreference () const
	Decrement the reference count for this object.
GskPath *	gobj ()
	Provides access to the underlying C instance.
const GskPath *	gobj () const
	Provides access to the underlying C instance.
GskPath *	gobj_copy () const
	Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
	Path ()=delete
	Path (const Path &)=delete
Path &	operator= (const Path &)=delete
Glib::ustring	to_string () const
	Converts the path into a human-readable string.
void	to_cairo (const ::Cairo::RefPtr< ::Cairo::Context > & cr) const
	Appends the path to a cairo context for drawing with Cairo.
bool	is_empty () const
	Checks if the path is empty, i.e. contains no lines or curves.
bool	is_closed () const
	Returns if the path represents a single closed contour.
std::optional< Gdk::Graphene::Rect >	get_bounds () const
	Computes the bounds of the given path.
std::optional< Gdk::Graphene::Rect >	get_tight_bounds () const
	Computes the tight bounds of the given path.
std::optional< Gdk::Graphene::Rect >	get_stroke_bounds (const Stroke & stroke) const
	Computes the bounds for stroking the given path with the given parameters.
bool	in_fill (const Gdk::Graphene::Point & point, FillRule fill_rule) const
	Returns whether a point is inside the fill area of a path.
std::optional< PathPoint >	get_start_point () const
	Gets the start point of the path.
std::optional< PathPoint >	get_end_point () const
	Gets the end point of the path.
bool	get_next (PathPoint & point) const
	Moves point to the next vertex.
bool	get_previous (PathPoint & point) const
	Moves point to the previous vertex.
std::optional< std::pair< PathPoint, float > >	get_closest_point (const Gdk::Graphene::Point & point, float threshold) const
	Computes the closest point on the path to the given point.
bool	foreach (ForeachFlags flags, const SlotForeach & slot)
	Calls slot for every operation of the path.
bool	equal (const Glib::RefPtr< const Path > & path2) const
	Returns whether two paths have identical structure.
bool	foreach_intersection (const Glib::RefPtr< const Path > & path2, const SlotIntersection & slot)
	Finds intersections between two paths.

Static Public Member Functions
static Glib::RefPtr< Path >	parse (const Glib::ustring & stringstring)
	Constructs a path from a serialized form.

Protected Member Functions
void	operator delete (void *, std::size_t)

Related Symbols
(Note that these are not member symbols.)
Glib::RefPtr< Gsk::Path >	wrap (GskPath * object, bool take_copy=false)
	A Glib::wrap() method for this object.

Detailed Description

Describes lines and curves that are more complex than simple rectangles.

Paths can be used for rendering (filling or stroking) and for animations (e.g. as trajectories).

Gsk::Path is an immutable, opaque, reference-counted struct. After creation, you cannot change the types it represents. Instead, new Gsk::Path 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)"> </picture>

Since gtkmm 4.24

Member Typedef Documentation

SlotForeach

using Gsk::Path::SlotForeach = sigc::slot<bool(Operation, const std::vector<Gdk::Graphene::Point>&, float)>

Type of the callback to iterate through the operations of a path.

For each operation, the callback is given the op itself, the points that the operation is applied to in pts, and a weight for conic curves.

Each contour of the path starts with a Gsk::Path::Operation::MOVE operation. Closed contours end with a Gsk::Path::Operation::CLOSE operation.

Since gtkmm 4.24

Parameters

op	The operation.
pts	The points of the operation.
weight	The weight for conic curves, or unused if not a conic curve.

Returns

true to continue iterating the path, false to immediately abort and not call the function again.

SlotIntersection

using Gsk::Path::SlotIntersection

Initial value:

sigc::slot<bool(const Glib::RefPtr<Path>&,
   const PathPoint&, const Glib::RefPtr<Path>&, const PathPoint&, Intersection kind)>

Type of the callback to iterate through the intersections of two paths.

Since gtkmm 4.24

Parameters

path1	The first path.
point1	The intersection as point on path1.
path2	The second path.
point2	The intersection as point on path2.
kind	The nature of the intersection.

Returns

true to continue iterating, false to stop the iteration and not call the function again

Constructor & Destructor Documentation

Path() [1/2]

Gsk::Path::Path ( )

delete

Path() [2/2]

Gsk::Path::Path ( const Path & )

delete

Member Function Documentation

equal()

bool Gsk::Path::equal

(

const Glib::RefPtr< const Path > &

path2

)

const

Returns whether two paths have identical structure.

Note that it is possible to construct paths that render identical even though they don't have the same structure.

Since gtkmm 4.24

Parameters

path2

Another path.

Returns

True if path1 and path2 have identical structure.

foreach()

bool Gsk::Path::foreach	(	ForeachFlags	flags,
		const SlotForeach &	slot )

Calls slot 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.

Since gtkmm 4.24

Parameters

flags	Flags to pass to the foreach function.
slot	The function to call for operations.

Returns

False if slot returned false, true otherwise.

foreach_intersection()

bool Gsk::Path::foreach_intersection	(	const Glib::RefPtr< const Path > &	path2,
		const SlotIntersection &	slot )

Finds intersections between two paths.

This function finds intersections between path1 and path2, and calls slot for each of them, in increasing order for path1.

If path2 is not provided or equal to path1, the function finds non-trivial self-intersections of path1.

When segments of the paths coincide, the callback is called once for the start of the segment, with GSK_PATH_INTERSECTION_START, and once for the end of the segment, with GSK_PATH_INTERSECTION_END. Note that other intersections may occur between the start and end of such a segment.

If slot returns false, the iteration is stopped.

Since gtkmm 4.24

Parameters

path2	The second path.
slot	The function to call for intersections.

Returns

false if slot returned false, true otherwise.

get_bounds()

std::optional< Gdk::Graphene::Rect > Gsk::Path::get_bounds

(

)

const

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. For accurate bounds, use get_tight_bounds().

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, no value is returned. This is different from the case where the path is a single point at the origin, where a zero rectangle is returned.

Since gtkmm 4.24

Returns

The bounds of this path, if any.

get_closest_point()

std::optional< std::pair< PathPoint, float > > Gsk::Path::get_closest_point	(	const Gdk::Graphene::Point &	point,
		float	threshold ) const

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

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

Since gtkmm 4.24

Parameters

point	The point.
threshold	Maximum allowed distance.

Returns

{closest_point, distance}, if there is a point within threshold.

get_end_point()

std::optional< PathPoint > Gsk::Path::get_end_point

(

)

const

Gets the end point of the path.

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

Since gtkmm 4.24

Returns

The end point, if any.

get_next()

bool Gsk::Path::get_next

(

PathPoint &

point

)

const

Moves point to the next vertex.

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

Since gtkmm 4.24

Parameters

point

The current point.

Returns

True if point was set.

get_previous()

bool Gsk::Path::get_previous

(

PathPoint &

point

)

const

Moves point to the previous vertex.

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

Since gtkmm 4.24

Parameters

point

The current point.

Returns

True if point was set.

get_start_point()

std::optional< PathPoint > Gsk::Path::get_start_point

(

)

const

Gets the start point of the path.

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

Since gtkmm 4.24

Returns

The start point, if any.

get_stroke_bounds()

std::optional< Gdk::Graphene::Rect > Gsk::Path::get_stroke_bounds

(

const Stroke &

stroke

)

const

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.

Since gtkmm 4.24

Parameters

stroke

Stroke parameters.

Returns

The bounds of this path, if any. See get_bounds().

get_tight_bounds()

std::optional< Gdk::Graphene::Rect > Gsk::Path::get_tight_bounds

(

)

const

Computes the tight bounds of the given path.

This function works harder than get_bounds() to produce the smallest possible bounds.

Since gtkmm 4.24

Returns

The bounds of this path, if any. See get_bounds().

gobj() [1/2]

GskPath * Gsk::Path::gobj

(

)

Provides access to the underlying C instance.

gobj() [2/2]

const GskPath * Gsk::Path::gobj

(

)

const

Provides access to the underlying C instance.

gobj_copy()

GskPath * Gsk::Path::gobj_copy

(

)

const

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

in_fill()

bool Gsk::Path::in_fill	(	const Gdk::Graphene::Point &	point,
		FillRule	fill_rule ) const

Returns whether a point is inside the fill area of a path.

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

Since gtkmm 4.24

Parameters

point	The point to test.
fill_rule	The fill rule to follow.

Returns

True if point is inside.

is_closed()

bool Gsk::Path::is_closed

(

)

const

Returns if the path represents a single closed contour.

Since gtkmm 4.24

Returns

True if the path is closed.

is_empty()

bool Gsk::Path::is_empty

(

)

const

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

Since gtkmm 4.24

Returns

True if the path is empty.

operator delete()

void Gsk::Path::operator delete ( void * , std::size_t  )

protected

operator=()

Path & Gsk::Path::operator= ( const Path & )

delete

parse()

Glib::RefPtr< Path > Gsk::Path::parse ( const Glib::ustring & string )

static

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_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.

Since gtkmm 4.24

Parameters

string

A string.

Returns

A new Gsk::Path, or nullptr if string could not be parsed.

reference()

void Gsk::Path::reference

(

)

const

Increment the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

to_cairo()

void Gsk::Path::to_cairo

(

const ::Cairo::RefPtr< ::Cairo::Context > &

cr

)

const

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 Gsk::Path.

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

Since gtkmm 4.24

Parameters

cr	A cairo context.

to_string()

Glib::ustring Gsk::Path::to_string

(

)

const

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 print(), see that function for details.

Since gtkmm 4.24

Returns

A new string for self.

unreference()

void Gsk::Path::unreference

(

)

const

Decrement the reference count for this object.

You should never need to do this manually - use the object via a RefPtr instead.

Friends And Related Symbol Documentation

wrap()

Glib::RefPtr< Gsk::Path > wrap ( GskPath * object, bool take_copy = false )

related

A Glib::wrap() method for this object.

Parameters

object	The C instance.
take_copy	False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns

A C++ instance that wraps this C instance.