GI.Gsk.Structs.Path

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 [structgsk.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>

Since: 4.14

Exported types

newtype Path

Memory-managed wrapper type.

Constructors

Path (ManagedPtr Path)

Instances

Eq Path

Defined in GI.Gsk.Structs.Path

Methods

(==) :: Path -> Path -> Bool

(/=) :: Path -> Path -> Bool

GBoxed Path

Defined in GI.Gsk.Structs.Path

ManagedPtrNewtype Path

Defined in GI.Gsk.Structs.Path

Methods

toManagedPtr :: Path -> ManagedPtr Path

TypedObject Path

Defined in GI.Gsk.Structs.Path

Methods

glibType :: IO GType

HasParentTypes Path

Defined in GI.Gsk.Structs.Path

IsGValue (Maybe Path)

Convert Path to and from GValue. See toGValue and fromGValue.

Defined in GI.Gsk.Structs.Path

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Path -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Path)

type ParentTypes Path

Defined in GI.Gsk.Structs.Path

type ParentTypes Path = '[] :: [Type]

Methods

Click to display all available methods, including inherited ones

Methods

foreach, inFill, isClosed, isEmpty, print, ref, toCairo, toString, unref.

Getters

getBounds, getStrokeBounds.

Setters

None.

foreach

pathForeach

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> [PathForeachFlags]

flags: flags to pass to the foreach function. See [flagsgsk.PathForeachFlags] for details about flags

-> PathForeachFunc

func: the function to call for operations

-> m Bool

Returns: FALSE if func returned FALSE, TRUE` otherwise.

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.

Since: 4.14

getBounds

pathGetBounds

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> m (Bool, Rect)

Returns: TRUE if the path has bounds, FALSE if the path is known to be empty and have no 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 rectZero. 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.

Since: 4.14

getStrokeBounds

pathGetStrokeBounds

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GtkPath

-> Stroke

stroke: stroke parameters

-> m (Bool, Rect)

Returns: TRUE if the path has bounds, FALSE if the path is known to be empty and have no 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.

Since: 4.14

inFill

pathInFill

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> Point

point: the point to test

-> FillRule

fillRule: the fill rule to follow

-> m Bool

Returns: TRUE if point is inside

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.

Since: 4.14

isClosed

pathIsClosed

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> m Bool

Returns: TRUE if the path is closed

Returns if the path represents a single closed contour.

Since: 4.14

isEmpty

pathIsEmpty

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> m Bool

Returns: TRUE if the path is empty

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

Since: 4.14

parse

pathParse

Arguments

:: (HasCallStack, MonadIO m)

=> Text

string: a string

-> m (Maybe Path)

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

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

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: 4.14

print

pathPrint

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> String

string: The string to print into

-> m ()

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

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

Since: 4.14

ref

pathRef

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> m Path

Returns: the passed in GskPath.

Increases the reference count of a GskPath by one.

Since: 4.14

toCairo

pathToCairo

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> Context

cr: a cairo context

-> m ()

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.

Since: 4.14

toString

pathToString

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> m Text

Returns: A new string for self

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 pathPrint, see that function for details.

Since: 4.14

unref

pathUnref

Arguments

:: (HasCallStack, MonadIO m)

=> Path

self: a GskPath

-> m ()

Decreases the reference count of a GskPath by one.

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

Since: 4.14