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

Contents

- Exported types
- Methods
  - addCairoPath
  - addCircle
  - addLayout
  - addPath
  - addRect
  - addReversePath
  - addRoundedRect
  - addSegment
  - arcTo
  - close
  - conicTo
  - cubicTo
  - getCurrentPoint
  - htmlArcTo
  - lineTo
  - moveTo
  - new
  - quadTo
  - ref
  - relArcTo
  - relConicTo
  - relCubicTo
  - relHtmlArcTo
  - relLineTo
  - relMoveTo
  - relQuadTo
  - relSvgArcTo
  - svgArcTo
  - toPath
  - unref

Description

Constructs `GskPath` objects.

A path is constructed like this:

### c code

    GskPath *
    construct_path (void)
    {
      GskPathBuilder *builder;

      builder = gsk_path_builder_new ();

      // add contours to the path here

      return gsk_path_builder_free_to_path (builder);

Adding contours to the path can be done in two ways. The easiest option is to use the `gsk_path_builder_add_*` group of functions that add predefined contours to the current path, either common shapes like `pathBuilderAddCircle` or by adding from other paths like `pathBuilderAddPath`.

The `gsk_path_builder_add_*` methods always add complete contours, and do not use or modify the current point.

The other option is to define each line and curve manually with the `gsk_path_builder_*_to` group of functions. You start with a call to `pathBuilderMoveTo` to set the starting point and then use multiple calls to any of the drawing functions to move the pen along the plane. Once you are done, you can call `pathBuilderClose` to close the path by connecting it back with a line to the starting point.

This is similar to how paths are drawn in Cairo.

Note that `GskPathBuilder` will reduce the degree of added Bézier curves as much as possible, to simplify rendering.

Since: 4.14

Synopsis

- newtype PathBuilder = PathBuilder (ManagedPtr PathBuilder)
- pathBuilderAddCairoPath :: (HasCallStack, MonadIO m) => PathBuilder -> Path -> m ()
- pathBuilderAddCircle :: (HasCallStack, MonadIO m) => PathBuilder -> Point -> Float -> m ()
- pathBuilderAddLayout :: (HasCallStack, MonadIO m, IsLayout a) => PathBuilder -> a -> m ()
- pathBuilderAddPath :: (HasCallStack, MonadIO m) => PathBuilder -> Path -> m ()
- pathBuilderAddRect :: (HasCallStack, MonadIO m) => PathBuilder -> Rect -> m ()
- pathBuilderAddReversePath :: (HasCallStack, MonadIO m) => PathBuilder -> Path -> m ()
- pathBuilderAddRoundedRect :: (HasCallStack, MonadIO m) => PathBuilder -> RoundedRect -> m ()
- pathBuilderAddSegment :: (HasCallStack, MonadIO m) => PathBuilder -> Path -> PathPoint -> PathPoint -> m ()
- pathBuilderArcTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> m ()
- pathBuilderClose :: (HasCallStack, MonadIO m) => PathBuilder -> m ()
- pathBuilderConicTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> Float -> m ()
- pathBuilderCubicTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> Float -> Float -> m ()
- pathBuilderGetCurrentPoint :: (HasCallStack, MonadIO m) => PathBuilder -> m Point
- pathBuilderHtmlArcTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> Float -> m ()
- pathBuilderLineTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> m ()
- pathBuilderMoveTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> m ()
- pathBuilderNew :: (HasCallStack, MonadIO m) => m PathBuilder
- pathBuilderQuadTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> m ()
- pathBuilderRef :: (HasCallStack, MonadIO m) => PathBuilder -> m PathBuilder
- pathBuilderRelArcTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> m ()
- pathBuilderRelConicTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> Float -> m ()
- pathBuilderRelCubicTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> Float -> Float -> m ()
- pathBuilderRelHtmlArcTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> Float -> m ()
- pathBuilderRelLineTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> m ()
- pathBuilderRelMoveTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> m ()
- pathBuilderRelQuadTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Float -> m ()
- pathBuilderRelSvgArcTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Bool -> Bool -> Float -> Float -> m ()
- pathBuilderSvgArcTo :: (HasCallStack, MonadIO m) => PathBuilder -> Float -> Float -> Float -> Bool -> Bool -> Float -> Float -> m ()
- pathBuilderToPath :: (HasCallStack, MonadIO m) => PathBuilder -> m Path
- pathBuilderUnref :: (HasCallStack, MonadIO m) => PathBuilder -> m ()

# Exported types

newtype PathBuilder Source #

Memory-managed wrapper type.

Constructors

PathBuilder (ManagedPtr PathBuilder) |

#### Instances

Instances details

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

# Methods

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

Expand

#### Methods

addCairoPath, addCircle, addLayout, addPath, addRect, addReversePath, addRoundedRect, addSegment, arcTo, close, conicTo, cubicTo, htmlArcTo, lineTo, moveTo, quadTo, ref, relArcTo, relConicTo, relCubicTo, relHtmlArcTo, relLineTo, relMoveTo, relQuadTo, relSvgArcTo, svgArcTo, toPath, unref.

#### Getters

getCurrentPoint.

#### Setters

None.

## addCairoPath

pathBuilderAddCairoPath Source #

Arguments

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

Adds a Cairo path to the builder.

You can use `cairo_copy_path()` to access the path from a Cairo context.

Since: 4.14

## addCircle

pathBuilderAddCircle Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Point | `center`: the center of the circle
-> Float | `radius`: the radius of the circle
-> m () |

Adds a circle as a new contour.

The path is going around the circle in clockwise direction.

If `radius` is zero, the contour will be a closed point.

Since: 4.14

## addLayout

pathBuilderAddLayout Source #

Arguments

:: (HasCallStack, MonadIO m, IsLayout a) |
=> PathBuilder | `self`: a path builder
-> a | `layout`: the pango layout to add
-> m () |

Adds the outlines for the glyphs in `layout` to the builder.

Since: 4.14

## addPath

pathBuilderAddPath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Path | `path`: the path to append
-> m () |

Appends all of `path` to the builder.

Since: 4.14

## addRect

pathBuilderAddRect Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Rect | `rect`: the rectangle to create a path for
-> m () |

Adds a rectangle as a new contour.

The path is going around the rectangle in clockwise direction.

If the the width or height are 0, the path will be a closed horizontal or vertical line. If both are 0, it'll be a closed dot.

Since: 4.14

## addReversePath

pathBuilderAddReversePath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Path | `path`: the path to append
-> m () |

Appends all of `path` to the builder, in reverse order.

Since: 4.14

## addRoundedRect

pathBuilderAddRoundedRect Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> RoundedRect | `rect`: the rounded rect
-> m () |

Adds a rounded rectangle as a new contour.

The path is going around the rectangle in clockwise direction.

Since: 4.14

## addSegment

pathBuilderAddSegment Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Path | `path`: the path to take the segment to
-> PathPoint | `start`: the point on `path` to start at
-> PathPoint | `end`: the point on `path` to end at
-> m () |

Adds a segment of a path to the builder.

If `start` is equal to or after `end`, the path will first add the segment from `start` to the end of the path, and then add the segment from the beginning to `end`. If the path is closed, these segments will be connected.

Note that this method always adds a path with the given start point and end point. To add a closed path, use `pathBuilderAddPath`.

Since: 4.14

## arcTo

pathBuilderArcTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x coordinate of first control point
-> Float | `y1`: y coordinate of first control point
-> Float | `x2`: x coordinate of second control point
-> Float | `y2`: y coordinate of second control point
-> m () |

Adds an elliptical arc from the current point to `x2`, `y2` with `x1`, `y1` determining the tangent directions.

After this, `x2`, `y2` will be the new current point.

Note: Two points and their tangents do not determine a unique ellipse, so GSK just picks one. If you need more precise control, use `pathBuilderConicTo` or `pathBuilderSvgArcTo`.

<picture> <source srcset="arc-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Arc To" src="arc-light.png"> </picture>

Since: 4.14

## close

pathBuilderClose Source #

Arguments

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

Ends the current contour with a line back to the start point.

Note that this is different from calling `pathBuilderLineTo` with the start point in that the contour will be closed. A closed contour behaves differently from an open one. When stroking, its start and end point are considered connected, so they will be joined via the line join, and not ended with line caps.

Since: 4.14

## conicTo

pathBuilderConicTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x coordinate of control point
-> Float | `y1`: y coordinate of control point
-> Float | `x2`: x coordinate of the end of the curve
-> Float | `y2`: y coordinate of the end of the curve
-> Float | `weight`: weight of the control point, must be greater than zero
-> m () |

Adds a conic curve from the current point to `x2`, `y2` with the given `weight` and `x1`, `y1` as the control point.

The weight determines how strongly the curve is pulled towards the control point. A conic with weight 1 is identical to a quadratic Bézier curve with the same points.

Conic curves can be used to draw ellipses and circles. They are also known as rational quadratic Bézier curves.

After this, `x2`, `y2` will be the new current point.

<picture> <source srcset="conic-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Conic To" src="conic-light.png"> </picture>

Since: 4.14

## cubicTo

pathBuilderCubicTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x coordinate of first control point
-> Float | `y1`: y coordinate of first control point
-> Float | `x2`: x coordinate of second control point
-> Float | `y2`: y coordinate of second control point
-> Float | `x3`: x coordinate of the end of the curve
-> Float | `y3`: y coordinate of the end of the curve
-> m () |

Adds a cubic Bézier curve from the current point to `x3`, `y3` with `x1`, `y1` and `x2`, `y2` as the control points.

After this, `x3`, `y3` will be the new current point.

<picture> <source srcset="cubic-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Cubic To" src="cubic-light.png"> </picture>

Since: 4.14

## getCurrentPoint

pathBuilderGetCurrentPoint Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> m Point | Returns: the current point

Gets the current point.

The current point is used for relative drawing commands and updated after every operation.

When the builder is created, the default current point is set to `0, 0`. Note that this is different from cairo, which starts out without a current point.

Since: 4.14

## htmlArcTo

pathBuilderHtmlArcTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x coordinate of first control point
-> Float | `y1`: y coordinate of first control point
-> Float | `x2`: x coordinate of second control point
-> Float | `y2`: y coordinate of second control point
-> Float | `radius`: radius of the circle
-> m () |

Implements arc-to according to the HTML Canvas spec.

A convenience function that implements the HTML arc_to functionality.

After this, the current point will be the point where the circle with the given radius touches the line from `x1`, `y1` to `x2`, `y2`.

Since: 4.14

## lineTo

pathBuilderLineTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x`: x coordinate
-> Float | `y`: y coordinate
-> m () |

Draws a line from the current point to `x`, `y` and makes it the new current point.

<picture> <source srcset="line-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Line To" src="line-light.png"> </picture>

Since: 4.14

## moveTo

pathBuilderMoveTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x`: x coordinate
-> Float | `y`: y coordinate
-> m () |

Starts a new contour by placing the pen at `x`, `y`.

If this function is called twice in succession, the first call will result in a contour made up of a single point. The second call will start a new contour.

Since: 4.14

## new

pathBuilderNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m PathBuilder | Returns: a new `GskPathBuilder`

Create a new `GskPathBuilder` object.

The resulting builder would create an empty `GskPath`. Use addition functions to add types to it.

Since: 4.14

## quadTo

pathBuilderQuadTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x coordinate of control point
-> Float | `y1`: y coordinate of control point
-> Float | `x2`: x coordinate of the end of the curve
-> Float | `y2`: y coordinate of the end of the curve
-> m () |

Adds a quadratic Bézier curve from the current point to `x2`, `y2` with `x1`, `y1` as the control point.

After this, `x2`, `y2` will be the new current point.

<picture> <source srcset="quad-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Quad To" src="quad-light.png"> </picture>

Since: 4.14

## ref

pathBuilderRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> m PathBuilder | Returns: the given path builder with its reference count increased

Acquires a reference on the given builder.

This function is intended primarily for language bindings. `GskPathBuilder` objects should not be kept around.

Since: 4.14

## relArcTo

pathBuilderRelArcTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x coordinate of first control point
-> Float | `y1`: y coordinate of first control point
-> Float | `x2`: x coordinate of second control point
-> Float | `y2`: y coordinate of second control point
-> m () |

Adds an elliptical arc from the current point to `x2`, `y2` with `x1`, `y1` determining the tangent directions.

All coordinates are given relative to the current point.

This is the relative version of `pathBuilderArcTo`.

Since: 4.14

## relConicTo

pathBuilderRelConicTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x offset of control point
-> Float | `y1`: y offset of control point
-> Float | `x2`: x offset of the end of the curve
-> Float | `y2`: y offset of the end of the curve
-> Float | `weight`: weight of the curve, must be greater than zero
-> m () |

Adds a conic curve from the current point to `x2`, `y2` with the given `weight` and `x1`, `y1` as the control point.

All coordinates are given relative to the current point.

This is the relative version of `pathBuilderConicTo`.

Since: 4.14

## relCubicTo

pathBuilderRelCubicTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x offset of first control point
-> Float | `y1`: y offset of first control point
-> Float | `x2`: x offset of second control point
-> Float | `y2`: y offset of second control point
-> Float | `x3`: x offset of the end of the curve
-> Float | `y3`: y offset of the end of the curve
-> m () |

Adds a cubic Bézier curve from the current point to `x3`, `y3` with `x1`, `y1` and `x2`, `y2` as the control points.

All coordinates are given relative to the current point.

This is the relative version of `pathBuilderCubicTo`.

Since: 4.14

## relHtmlArcTo

pathBuilderRelHtmlArcTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x coordinate of first control point
-> Float | `y1`: y coordinate of first control point
-> Float | `x2`: x coordinate of second control point
-> Float | `y2`: y coordinate of second control point
-> Float | `radius`: radius of the circle
-> m () |

Implements arc-to according to the HTML Canvas spec.

All coordinates are given relative to the current point.

This is the relative version of `pathBuilderHtmlArcTo`.

Since: 4.14

## relLineTo

pathBuilderRelLineTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x`: x offset
-> Float | `y`: y offset
-> m () |

Draws a line from the current point to a point offset from it by `x`, `y` and makes it the new current point.

This is the relative version of `pathBuilderLineTo`.

Since: 4.14

## relMoveTo

pathBuilderRelMoveTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x`: x offset
-> Float | `y`: y offset
-> m () |

Starts a new contour by placing the pen at `x`, `y` relative to the current point.

This is the relative version of `pathBuilderMoveTo`.

Since: 4.14

## relQuadTo

pathBuilderRelQuadTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `x1`: x offset of control point
-> Float | `y1`: y offset of control point
-> Float | `x2`: x offset of the end of the curve
-> Float | `y2`: y offset of the end of the curve
-> m () |

Adds a quadratic Bézier curve from the current point to `x2`, `y2` with `x1`, `y1` the control point.

All coordinates are given relative to the current point.

This is the relative version of `pathBuilderQuadTo`.

Since: 4.14

## relSvgArcTo

pathBuilderRelSvgArcTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `rx`: x radius
-> Float | `ry`: y radius
-> Float | `xAxisRotation`: the rotation of the ellipsis
-> Bool | `largeArc`: whether to add the large arc
-> Bool | `positiveSweep`: whether to sweep in the positive direction
-> Float | `x`: x coordinate of the endpoint
-> Float | `y`: y coordinate of the endpoint
-> m () |

Implements arc-to according to the SVG spec.

All coordinates are given relative to the current point.

This is the relative version of `pathBuilderSvgArcTo`.

Since: 4.14

## svgArcTo

pathBuilderSvgArcTo Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> Float | `rx`: x radius
-> Float | `ry`: y radius
-> Float | `xAxisRotation`: the rotation of the ellipsis
-> Bool | `largeArc`: whether to add the large arc
-> Bool | `positiveSweep`: whether to sweep in the positive direction
-> Float | `x`: x coordinate of the endpoint
-> Float | `y`: y coordinate of the endpoint
-> m () |

Implements arc-to according to the SVG spec.

A convenience function that implements the SVG arc_to functionality.

After this, `x`, `y` will be the new current point.

Since: 4.14

## toPath

pathBuilderToPath Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> PathBuilder | `self`: a path builder
-> m Path | Returns: the newly created path with all the contours added to the builder

Creates a new path from the given builder.

The given `GskPathBuilder` is reset to the initial state once this function returns. Calling this function again on the same builder instance will therefore produce an empty path, not a copy of the same path.

This function is intended primarily for language bindings. C code should use `PathBuilder`.`free_to_path`().

Since: 4.14

## unref

pathBuilderUnref Source #

Arguments

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

Releases a reference on the given builder.

Since: 4.14