gtkmm: Gsk::Path Class Reference

gtkmm 4.23.2

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Symbols | List of all members
Gsk::Path Class Referencefinal

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 & string)
| 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)>
Gsk::PathPoint
Represents a point on a path.
Definition pathpoint.h:56
Glib::RefPtr
std::shared_ptr< T_CppObject > RefPtr
Gsk::Path::Intersection
Intersection
The values of this enumeration classify intersections between paths.
Definition path.h:175

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