gi-gsk-4.0.9: Gsk bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gsk.Structs.Path

Contents

- Exported types
- Methods
  - equal
  - foreach
  - foreachIntersection
  - getBounds
  - getStrokeBounds
  - getTightBounds
  - inFill
  - isClosed
  - isEmpty
  - parse
  - print
  - ref
  - toCairo
  - toString
  - unref

Description

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 `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

Synopsis

- newtype Path = Path (ManagedPtr Path)
- pathEqual :: (HasCallStack, MonadIO m) => Path -> Path -> m Bool
- pathForeach :: (HasCallStack, MonadIO m) => Path -> [PathForeachFlags] -> PathForeachFunc -> m Bool
- pathForeachIntersection :: (HasCallStack, MonadIO m) => Path -> Maybe Path -> PathIntersectionFunc -> m Bool
- pathGetBounds :: (HasCallStack, MonadIO m) => Path -> m (Bool, Rect)
- pathGetStrokeBounds :: (HasCallStack, MonadIO m) => Path -> Stroke -> m (Bool, Rect)
- pathGetTightBounds :: (HasCallStack, MonadIO m) => Path -> m (Bool, Rect)
- pathInFill :: (HasCallStack, MonadIO m) => Path -> Point -> FillRule -> m Bool
- pathIsClosed :: (HasCallStack, MonadIO m) => Path -> m Bool
- pathIsEmpty :: (HasCallStack, MonadIO m) => Path -> m Bool
- pathParse :: (HasCallStack, MonadIO m) => Text -> m (Maybe Path)
- pathPrint :: (HasCallStack, MonadIO m) => Path -> String -> m ()
- pathRef :: (HasCallStack, MonadIO m) => Path -> m Path
- pathToCairo :: (HasCallStack, MonadIO m) => Path -> Context -> m ()
- pathToString :: (HasCallStack, MonadIO m) => Path -> m Text
- pathUnref :: (HasCallStack, MonadIO m) => Path -> m ()

# Exported types

newtype Path Source #

Memory-managed wrapper type.

Constructors

Path (ManagedPtr Path) |

#### Instances

Instances details

Eq Path Source # |
Instance details Defined in GI.Gsk.Structs.Path Methods (==) :: Path -> Path -> Bool Source # (/=) :: Path -> Path -> Bool Source #
GBoxed Path Source # |
Instance details Defined in GI.Gsk.Structs.Path
ManagedPtrNewtype Path Source # |
Instance details Defined in GI.Gsk.Structs.Path Methods toManagedPtr :: Path -> ManagedPtr Path Source #
TypedObject Path Source # |
Instance details Defined in GI.Gsk.Structs.Path Methods glibType :: IO GType Source #
HasParentTypes Path Source # |
Instance details Defined in GI.Gsk.Structs.Path
IsGValue (Maybe Path) Source # | Convert `Path` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gsk.Structs.Path Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Path -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Path) Source #
type ParentTypes Path Source # |
Instance details Defined in GI.Gsk.Structs.Path type ParentTypes Path = '[] :: [Type]

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

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

#### Getters

getBounds, getStrokeBounds, getTightBounds.

#### Setters

None.

## equal

pathEqual Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `path1`: a path
-> Path | `path2`: another path
-> m Bool | Returns: true if `path1` and `path2` have identical structure

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

## foreach

pathForeach Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> [PathForeachFlags] | `flags`: flags to pass to the foreach function
-> 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

## foreachIntersection

pathForeachIntersection Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `path1`: the first path
-> Maybe Path | `path2`: the second path
-> PathIntersectionFunc | `func`: the function to call for intersections
-> m Bool | Returns: `FALSE` if `func` returned FALSE`,` TRUE` otherwise.

Finds intersections between two paths.

This function finds intersections between `path1` and `path2`, and calls `func` 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 `gSKPATHINTERSECTIONSTART`, and once for the end of the segment, with `gSKPATHINTERSECTIONEND`. Note that other intersections may occur between the start and end of such a segment.

If `func` returns `FALSE`, the iteration is stopped.

Since: 4.20

## getBounds

pathGetBounds Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> 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. For accurate bounds, use `pathGetTightBounds`.

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> 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 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: 4.14

## getTightBounds

pathGetTightBounds Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> 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 tight bounds of the given path.

This function works harder than `pathGetBounds` to produce the smallest possible bounds.

Since: 4.22

## inFill

pathInFill Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> Point | `point`: the point to test
-> FillRule | `fillRule`: the fill rule to follow
-> m Bool | Returns: true if `point` is inside

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

## isClosed

pathIsClosed Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> m Bool | Returns: true if the path is closed

Returns if the path represents a single closed contour.

Since: 4.14

## isEmpty

pathIsEmpty Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> 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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `string`: a string
-> m (Maybe Path) | Returns: a new `GskPath`, or `NULL` if `string` could not be parsed

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 `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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> String | `string`: the string to print into
-> m () |

Converts the path into a human-readable representation.

The string is compatible with (a superset of) SVG path syntax, see `pathParse` for a summary of the syntax.

Since: 4.14

## ref

pathRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> m Path | Returns: the passed in `GskPath`

Increases the reference count of a path by one.

Since: 4.14

## toCairo

pathToCairo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> Context | `cr`: a cairo context
-> m () |

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_new_path()` if you want this.

Since: 4.14

## toString

pathToString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> m Text | Returns: a new string for `self`

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

Since: 4.14

## unref

pathUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Path | `self`: a path
-> m () |

Decreases the reference count of a path by one.

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

Since: 4.14