Package org.gnome.gsk

Class PathBuilder

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gsk.PathBuilder

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class PathBuilder
extends ProxyInstance

GskPathBuilder is an auxiliary object for constructing GskPath 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 addCircle(org.gnome.graphene.Point, float) or by adding from other paths like addPath(org.gnome.gsk.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 moveTo(float, float) 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 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 GskPathBuilder will reduce the degree of added Bézier curves as much as possible, to simplify rendering.

Constructor Summary

Constructors

Constructor	Description
PathBuilder()	Create a new GskPathBuilder object.
PathBuilder(MemorySegment address)	Create a PathBuilder proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
void	addCairoPath(org.freedesktop.cairo.Path path)	Adds a Cairo path to the builder.
void	addCircle(Point center, float radius)	Adds a circle with the center and radius.
void	addLayout(Layout layout)	Adds the outlines for the glyphs in layout to the builder.
void	addPath(Path path)	Appends all of path to the builder.
void	addRect(Rect rect)	Adds rect as a new contour to the path built by the builder.
void	addReversePath(Path path)	Appends all of path to the builder, in reverse order.
void	addRoundedRect(RoundedRect rect)	Adds rect as a new contour to the path built in this PathBuilder.
void	addSegment(Path path, PathPoint start, PathPoint end)	Adds to this PathBuilder the segment of path from start to end.
void	arcTo(float x1, float y1, float x2, float y2)	Adds an elliptical arc from the current point to x2, y2 with x1, y1 determining the tangent directions.
void	close()	Ends the current contour with a line back to the start point.
void	conicTo(float x1, float y1, float x2, float y2, float weight)	Adds a conic curve from the current point to x2, y2 with the given weight and x1, y1 as the control point.
void	cubicTo(float x1, float y1, float x2, float y2, float x3, float y3)	Adds a cubic Bézier curve from the current point to x3, y3 with x1, y1 and x2, y2 as the control points.
Path	freeToPath()	Creates a new GskPath from the current state of the given builder, and unrefs the builder instance.
Point	getCurrentPoint()	Gets the current point.
static Type	getType()	Get the GType of the PathBuilder class
void	htmlArcTo(float x1, float y1, float x2, float y2, float radius)	Implements arc-to according to the HTML Canvas spec.
void	lineTo(float x, float y)	Draws a line from the current point to x, y and makes it the new current point.
void	moveTo(float x, float y)	Starts a new contour by placing the pen at x, y.
void	quadTo(float x1, float y1, float x2, float y2)	Adds a quadratic Bézier curve from the current point to x2, y2 with x1, y1 as the control point.
PathBuilder	ref()	Acquires a reference on the given builder.
void	relArcTo(float x1, float y1, float x2, float y2)	Adds an elliptical arc from the current point to x2, y2 with x1, y1 determining the tangent directions.
void	relConicTo(float x1, float y1, float x2, float y2, float weight)	Adds a conic curve from the current point to x2, y2 with the given weight and x1, y1 as the control point.
void	relCubicTo(float x1, float y1, float x2, float y2, float x3, float y3)	Adds a cubic Bézier curve from the current point to x3, y3 with x1, y1 and x2, y2 as the control points.
void	relHtmlArcTo(float x1, float y1, float x2, float y2, float radius)	Implements arc-to according to the HTML Canvas spec.
void	relLineTo(float x, float y)	Draws a line from the current point to a point offset from it by x, y and makes it the new current point.
void	relMoveTo(float x, float y)	Starts a new contour by placing the pen at x, y relative to the current point.
void	relQuadTo(float x1, float y1, float x2, float y2)	Adds a quadratic Bézier curve from the current point to x2, y2 with x1, y1 the control point.
void	relSvgArcTo(float rx, float ry, float xAxisRotation, boolean largeArc, boolean positiveSweep, float x, float y)	Implements arc-to according to the SVG spec.
void	svgArcTo(float rx, float ry, float xAxisRotation, boolean largeArc, boolean positiveSweep, float x, float y)	Implements arc-to according to the SVG spec.
Path	toPath()	Creates a new GskPath from the given builder.
void	unref()	Releases a reference on the given builder.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PathBuilder

public PathBuilder(MemorySegment address)

Create a PathBuilder proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

PathBuilder

public PathBuilder()

Create a new GskPathBuilder object.

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

Method Details

getType

public static Type getType()

Get the GType of the PathBuilder class

Returns:

the GType

addCairoPath

public void addCairoPath(org.freedesktop.cairo.Path path)

Adds a Cairo path to the builder.

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

Parameters:

path - a path

addCircle

public void addCircle(Point center,
 float radius)

Adds a circle with the center and radius.

The path is going around the circle in clockwise direction.

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

Parameters:

center - the center of the circle

radius - the radius of the circle

addLayout

public void addLayout(Layout layout)

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

Parameters:

layout - the pango layout to add

addPath

public void addPath(Path path)

Appends all of path to the builder.

Parameters:

path - the path to append

addRect

public void addRect(Rect rect)

Adds rect as a new contour to the path built by the builder.

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:

rect - The rectangle to create a path for

addReversePath

public void addReversePath(Path path)

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

Parameters:

path - the path to append

addRoundedRect

public void addRoundedRect(RoundedRect rect)

Adds rect as a new contour to the path built in this PathBuilder.

The path is going around the rectangle in clockwise direction.

Parameters:

rect - the rounded rect

addSegment

public void addSegment(Path path,
 PathPoint start,
 PathPoint end)

Adds to this PathBuilder the segment of path from start to end.

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 addPath(org.gnome.gsk.Path).

Parameters:

path - the GskPath to take the segment to

start - the point on path to start at

end - the point on path to end at

arcTo

public void arcTo(float x1,
 float y1,
 float x2,
 float y2)

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 conicTo(float, float, float, float, float) or svgArcTo(float, float, float, boolean, boolean, float, float).

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

Parameters:

x1 - x coordinate of first control point

y1 - y coordinate of first control point

x2 - x coordinate of second control point

y2 - y coordinate of second control point

close

public void close()

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

Note that this is different from calling lineTo(float, float) 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.

conicTo

public void conicTo(float x1,
 float y1,
 float x2,
 float y2,
 float weight)

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>

Parameters:

x1 - x coordinate of control point

y1 - y coordinate of control point

x2 - x coordinate of the end of the curve

y2 - y coordinate of the end of the curve

weight - weight of the control point, must be greater than zero

cubicTo

public void cubicTo(float x1,
 float y1,
 float x2,
 float y2,
 float x3,
 float y3)

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>

Parameters:

x1 - x coordinate of first control point

y1 - y coordinate of first control point

x2 - x coordinate of second control point

y2 - y coordinate of second control point

x3 - x coordinate of the end of the curve

y3 - y coordinate of the end of the curve

freeToPath

public Path freeToPath()

Creates a new GskPath from the current state of the given builder, and unrefs the builder instance.

Returns:

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

getCurrentPoint

public Point getCurrentPoint()

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:

The current point

htmlArcTo

public void htmlArcTo(float x1,
 float y1,
 float x2,
 float y2,
 float radius)

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 - X coordinate of first control point

y1 - Y coordinate of first control point

x2 - X coordinate of second control point

y2 - Y coordinate of second control point

radius - Radius of the circle

lineTo

public void lineTo(float x,
 float y)

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>

Parameters:

x - x coordinate

y - y coordinate

moveTo

public void moveTo(float x,
 float y)

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 - x coordinate

y - y coordinate

quadTo

public void quadTo(float x1,
 float y1,
 float x2,
 float y2)

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>

Parameters:

x1 - x coordinate of control point

y1 - y coordinate of control point

x2 - x coordinate of the end of the curve

y2 - y coordinate of the end of the curve

ref

public PathBuilder ref()

Acquires a reference on the given builder.

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

Returns:

the given GskPathBuilder with its reference count increased

relArcTo

public void relArcTo(float x1,
 float y1,
 float x2,
 float y2)

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 arcTo(float, float, float, float).

Parameters:

x1 - x coordinate of first control point

y1 - y coordinate of first control point

x2 - x coordinate of second control point

y2 - y coordinate of second control point

relConicTo

public void relConicTo(float x1,
 float y1,
 float x2,
 float y2,
 float weight)

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 conicTo(float, float, float, float, float).

Parameters:

x1 - x offset of control point

y1 - y offset of control point

x2 - x offset of the end of the curve

y2 - y offset of the end of the curve

weight - weight of the curve, must be greater than zero

relCubicTo

public void relCubicTo(float x1,
 float y1,
 float x2,
 float y2,
 float x3,
 float y3)

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 cubicTo(float, float, float, float, float, float).

Parameters:

x1 - x offset of first control point

y1 - y offset of first control point

x2 - x offset of second control point

y2 - y offset of second control point

x3 - x offset of the end of the curve

y3 - y offset of the end of the curve

relHtmlArcTo

public void relHtmlArcTo(float x1,
 float y1,
 float x2,
 float y2,
 float radius)

Implements arc-to according to the HTML Canvas spec.

All coordinates are given relative to the current point.

This is the relative version of htmlArcTo(float, float, float, float, float).

Parameters:

x1 - X coordinate of first control point

y1 - Y coordinate of first control point

x2 - X coordinate of second control point

y2 - Y coordinate of second control point

radius - Radius of the circle

relLineTo

public void relLineTo(float x,
 float y)

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 lineTo(float, float).

Parameters:

x - x offset

y - y offset

relMoveTo

public void relMoveTo(float x,
 float y)

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

This is the relative version of moveTo(float, float).

Parameters:

x - x offset

y - y offset

relQuadTo

public void relQuadTo(float x1,
 float y1,
 float x2,
 float y2)

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 quadTo(float, float, float, float).

Parameters:

x1 - x offset of control point

y1 - y offset of control point

x2 - x offset of the end of the curve

y2 - y offset of the end of the curve

relSvgArcTo

public void relSvgArcTo(float rx,
 float ry,
 float xAxisRotation,
 boolean largeArc,
 boolean positiveSweep,
 float x,
 float y)

Implements arc-to according to the SVG spec.

All coordinates are given relative to the current point.

This is the relative version of svgArcTo(float, float, float, boolean, boolean, float, float).

Parameters:

rx - X radius

ry - Y radius

xAxisRotation - the rotation of the ellipsis

largeArc - whether to add the large arc

positiveSweep - whether to sweep in the positive direction

x - the X coordinate of the endpoint

y - the Y coordinate of the endpoint

svgArcTo

public void svgArcTo(float rx,
 float ry,
 float xAxisRotation,
 boolean largeArc,
 boolean positiveSweep,
 float x,
 float y)

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 - X radius

ry - Y radius

xAxisRotation - the rotation of the ellipsis

largeArc - whether to add the large arc

positiveSweep - whether to sweep in the positive direction

x - the X coordinate of the endpoint

y - the Y coordinate of the endpoint

toPath

public Path toPath()

Creates a new GskPath from the given builder.

The given GskPathBuilder 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 freeToPath().

Returns:

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

unref

public void unref()

Releases a reference on the given builder.