Class (GI Struct)

Gsk-4.0 ▶ Gsk ▶ PathBuilderSince 4.14

Constructs Gsk.Path objects.

A path is constructed like this:

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 Gsk.PathBuilder.add_circle or by adding from other paths like Gsk.PathBuilder.add_path.

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 Gsk.PathBuilder.move_to 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 Gsk.PathBuilder.close 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 Gsk.PathBuilder will reduce the degree of added Bézier curves as much as possible, to simplify rendering.

4.14

Index

Constructors

constructor

Properties

$gtype

Methods

add_cairo_path add_circle add_layout add_path add_rect add_reverse_path add_rounded_rect add_segment arc_to close conic_to cubic_to get_current_point html_arc_to line_to move_to quad_to ref rel_arc_to rel_conic_to rel_cubic_to rel_html_arc_to rel_line_to rel_move_to rel_quad_to rel_svg_arc_to svg_arc_to to_path unref new

Constructors

Properties

$gtype: GType<PathBuilder>

Methods

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

    Parameters

    • center: Graphene.Point

      the center of the circle

    • radius: number

      the radius of the circle

    Returns void

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

    Parameters

    Returns void

  • Adds a rounded rectangle as a new contour.

    The path is going around the rectangle in clockwise direction.

    Parameters

    Returns void

  • 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 Gsk.PathBuilder.add_path.

    Parameters

    • path: Gsk.Path

      the path to take the segment to

    • start: PathPoint

      the point on path to start at

    • end: PathPoint

      the point on path to end at

    Returns void

  • 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 Gsk.PathBuilder.conic_to or Gsk.PathBuilder.svg_arc_to.

    Arc To

    Parameters

    • x1: number

      x coordinate of first control point

    • y1: number

      y coordinate of first control point

    • x2: number

      x coordinate of second control point

    • y2: number

      y coordinate of second control point

    Returns void

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

    Note that this is different from calling Gsk.PathBuilder.line_to 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.

    Returns void

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

    Conic To

    Parameters

    • x1: number

      x coordinate of control point

    • y1: number

      y coordinate of control point

    • x2: number

      x coordinate of the end of the curve

    • y2: number

      y coordinate of the end of the curve

    • weight: number

      weight of the control point, must be greater than zero

    Returns void

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

    Cubic To

    Parameters

    • x1: number

      x coordinate of first control point

    • y1: number

      y coordinate of first control point

    • x2: number

      x coordinate of second control point

    • y2: number

      y coordinate of second control point

    • x3: number

      x coordinate of the end of the curve

    • y3: number

      y coordinate of the end of the curve

    Returns void

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

    Returns Graphene.Point

    the current point

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

    Parameters

    • x1: number

      x coordinate of first control point

    • y1: number

      y coordinate of first control point

    • x2: number

      x coordinate of second control point

    • y2: number

      y coordinate of second control point

    • radius: number

      radius of the circle

    Returns void

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

    Line To

    Parameters

    • x: number

      x coordinate

    • y: number

      y coordinate

    Returns void

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

    Parameters

    • x: number

      x coordinate

    • y: number

      y coordinate

    Returns void

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

    Quad To

    Parameters

    • x1: number

      x coordinate of control point

    • y1: number

      y coordinate of control point

    • x2: number

      x coordinate of the end of the curve

    • y2: number

      y coordinate of the end of the curve

    Returns void

  • 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 Gsk.PathBuilder.arc_to.

    Parameters

    • x1: number

      x coordinate of first control point

    • y1: number

      y coordinate of first control point

    • x2: number

      x coordinate of second control point

    • y2: number

      y coordinate of second control point

    Returns void

  • 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 Gsk.PathBuilder.conic_to.

    Parameters

    • x1: number

      x offset of control point

    • y1: number

      y offset of control point

    • x2: number

      x offset of the end of the curve

    • y2: number

      y offset of the end of the curve

    • weight: number

      weight of the curve, must be greater than zero

    Returns void

  • 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 Gsk.PathBuilder.cubic_to.

    Parameters

    • x1: number

      x offset of first control point

    • y1: number

      y offset of first control point

    • x2: number

      x offset of second control point

    • y2: number

      y offset of second control point

    • x3: number

      x offset of the end of the curve

    • y3: number

      y offset of the end of the curve

    Returns void

  • Implements arc-to according to the HTML Canvas spec.

    All coordinates are given relative to the current point.

    This is the relative version of Gsk.PathBuilder.html_arc_to.

    Parameters

    • x1: number

      x coordinate of first control point

    • y1: number

      y coordinate of first control point

    • x2: number

      x coordinate of second control point

    • y2: number

      y coordinate of second control point

    • radius: number

      radius of the circle

    Returns void

  • 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 Gsk.PathBuilder.line_to.

    Parameters

    • x: number

      x offset

    • y: number

      y offset

    Returns void

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

    This is the relative version of Gsk.PathBuilder.move_to.

    Parameters

    • x: number

      x offset

    • y: number

      y offset

    Returns void

  • 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 Gsk.PathBuilder.quad_to.

    Parameters

    • x1: number

      x offset of control point

    • y1: number

      y offset of control point

    • x2: number

      x offset of the end of the curve

    • y2: number

      y offset of the end of the curve

    Returns void

  • Implements arc-to according to the SVG spec.

    All coordinates are given relative to the current point.

    This is the relative version of Gsk.PathBuilder.svg_arc_to.

    Parameters

    • rx: number

      x radius

    • ry: number

      y radius

    • x_axis_rotation: number

      the rotation of the ellipsis

    • large_arc: boolean

      whether to add the large arc

    • positive_sweep: boolean

      whether to sweep in the positive direction

    • x: number

      x coordinate of the endpoint

    • y: number

      y coordinate of the endpoint

    Returns void

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

    Parameters

    • rx: number

      x radius

    • ry: number

      y radius

    • x_axis_rotation: number

      the rotation of the ellipsis

    • large_arc: boolean

      whether to add the large arc

    • positive_sweep: boolean

      whether to sweep in the positive direction

    • x: number

      x coordinate of the endpoint

    • y: number

      y coordinate of the endpoint

    Returns void

  • Creates a new path from the given builder.

    The given Gsk.PathBuilder is reset once this function returns; you cannot call this function multiple times on the same builder instance.

    This function is intended primarily for language bindings. C code should use Gsk.PathBuilder.free_to_path.

    Returns Gsk.Path

    the newly created path with all the contours added to the builder