@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gsk/path-builder.js

@@ -2,8 +2,54 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Path } from "./path.js";
 import * as Graphene from "../graphene/index.js";
+/**
+ * Constructs `GskPath` objects.
+ *
+ * A path is constructed like this:
+ *
+ * ```c
+ * 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 [method@Gsk.PathBuilder.add_circle]
+ * or by adding from other paths like [method@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 [method@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
+ * [method@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 `GskPathBuilder` will reduce the degree of added Bézier
+ * curves as much as possible, to simplify rendering.
+ */
 export class PathBuilder {
     ptr;
+    /**
+     * Create a new `GskPathBuilder` object.
+     *
+     * The resulting builder would create an empty `GskPath`.
+     * Use addition functions to add types to it.
+     */
     constructor() {
         this.ptr = this.createPtr([]);
     }
@@ -14,6 +60,13 @@ export class PathBuilder {
             innerType: "GskPathBuilder",
         });
     }
+    /**
+     * Adds a Cairo path to the builder.
+     *
+     * You can use cairo_copy_path() to access the path
+     * from a Cairo context.
+     * @param path - a path
+     */
     addCairoPath(path) {
         call("libgtk-4.so.1", "gsk_path_builder_add_cairo_path", [
             {
@@ -26,6 +79,15 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     * @param center - the center of the circle
+     * @param radius - the radius of the circle
+     */
     addCircle(center, radius) {
         call("libgtk-4.so.1", "gsk_path_builder_add_circle", [
             {
@@ -47,6 +109,10 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds the outlines for the glyphs in `layout` to the builder.
+     * @param layout - the pango layout to add
+     */
     addLayout(layout) {
         call("libgtk-4.so.1", "gsk_path_builder_add_layout", [
             {
@@ -59,6 +125,10 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Appends all of `path` to the builder.
+     * @param path - the path to append
+     */
     addPath(path) {
         call("libgtk-4.so.1", "gsk_path_builder_add_path", [
             {
@@ -76,6 +146,15 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     * @param rect - the rectangle to create a path for
+     */
     addRect(rect) {
         call("libgtk-4.so.1", "gsk_path_builder_add_rect", [
             {
@@ -93,6 +172,10 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Appends all of `path` to the builder, in reverse order.
+     * @param path - the path to append
+     */
     addReversePath(path) {
         call("libgtk-4.so.1", "gsk_path_builder_add_reverse_path", [
             {
@@ -110,6 +193,12 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a rounded rectangle as a new contour.
+     *
+     * The path is going around the rectangle in clockwise direction.
+     * @param rect - the rounded rect
+     */
     addRoundedRect(rect) {
         call("libgtk-4.so.1", "gsk_path_builder_add_rounded_rect", [
             {
@@ -122,6 +211,20 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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 [method@Gsk.PathBuilder.add_path].
+     * @param path - the path to take the segment to
+     * @param start - the point on `path` to start at
+     * @param end - the point on `path` to end at
+     */
     addSegment(path, start, end) {
         call("libgtk-4.so.1", "gsk_path_builder_add_segment", [
             {
@@ -157,6 +260,20 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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 [method@Gsk.PathBuilder.conic_to]
+     * or [method@Gsk.PathBuilder.svg_arc_to].
+     * @param x1 - x coordinate of first control point
+     * @param y1 - y coordinate of first control point
+     * @param x2 - x coordinate of second control point
+     * @param y2 - y coordinate of second control point
+     */
     arcTo(x1, y1, x2, y2) {
         call("libgtk-4.so.1", "gsk_path_builder_arc_to", [
             {
@@ -181,6 +298,15 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Ends the current contour with a line back to the start point.
+     *
+     * Note that this is different from calling [method@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.
+     */
     close() {
         call("libgtk-4.so.1", "gsk_path_builder_close", [
             {
@@ -189,6 +315,24 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline)
+     * 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.
+     * @param x1 - x coordinate of control point
+     * @param y1 - y coordinate of control point
+     * @param x2 - x coordinate of the end of the curve
+     * @param y2 - y coordinate of the end of the curve
+     * @param weight - weight of the control point, must be greater than zero
+     */
     conicTo(x1, y1, x2, y2, weight) {
         call("libgtk-4.so.1", "gsk_path_builder_conic_to", [
             {
@@ -217,6 +361,19 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_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.
+     * @param x1 - x coordinate of first control point
+     * @param y1 - y coordinate of first control point
+     * @param x2 - x coordinate of second control point
+     * @param y2 - y coordinate of second control point
+     * @param x3 - x coordinate of the end of the curve
+     * @param y3 - y coordinate of the end of the curve
+     */
     cubicTo(x1, y1, x2, y2, x3, y3) {
         call("libgtk-4.so.1", "gsk_path_builder_cubic_to", [
             {
@@ -249,6 +406,16 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     */
     getCurrentPoint() {
         const ptr = call("libgtk-4.so.1", "gsk_path_builder_get_current_point", [
             {
@@ -263,6 +430,22 @@ export class PathBuilder {
         });
         return getObject(ptr, Graphene.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.
+     * @param x1 - x coordinate of first control point
+     * @param y1 - y coordinate of first control point
+     * @param x2 - x coordinate of second control point
+     * @param y2 - y coordinate of second control point
+     * @param radius - radius of the circle
+     */
     htmlArcTo(x1, y1, x2, y2, radius) {
         call("libgtk-4.so.1", "gsk_path_builder_html_arc_to", [
             {
@@ -291,6 +474,12 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Draws a line from the current point to @x, `y` and makes it
+     * the new current point.
+     * @param x - x coordinate
+     * @param y - y coordinate
+     */
     lineTo(x, y) {
         call("libgtk-4.so.1", "gsk_path_builder_line_to", [
             {
@@ -307,6 +496,15 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     * @param x - x coordinate
+     * @param y - y coordinate
+     */
     moveTo(x, y) {
         call("libgtk-4.so.1", "gsk_path_builder_move_to", [
             {
@@ -323,6 +521,16 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_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.
+     * @param x1 - x coordinate of control point
+     * @param y1 - y coordinate of control point
+     * @param x2 - x coordinate of the end of the curve
+     * @param y2 - y coordinate of the end of the curve
+     */
     quadTo(x1, y1, x2, y2) {
         call("libgtk-4.so.1", "gsk_path_builder_quad_to", [
             {
@@ -347,6 +555,12 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Acquires a reference on the given builder.
+     *
+     * This function is intended primarily for language bindings.
+     * `GskPathBuilder` objects should not be kept around.
+     */
     ref() {
         const ptr = call("libgtk-4.so.1", "gsk_path_builder_ref", [
             {
@@ -361,6 +575,17 @@ export class PathBuilder {
         });
         return getObject(ptr, PathBuilder);
     }
+    /**
+     * 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 [method@Gsk.PathBuilder.arc_to].
+     * @param x1 - x coordinate of first control point
+     * @param y1 - y coordinate of first control point
+     * @param x2 - x coordinate of second control point
+     * @param y2 - y coordinate of second control point
+     */
     relArcTo(x1, y1, x2, y2) {
         call("libgtk-4.so.1", "gsk_path_builder_rel_arc_to", [
             {
@@ -385,6 +610,20 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a [conic curve](https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline)
+     * 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 [method@Gsk.PathBuilder.conic_to].
+     * @param x1 - x offset of control point
+     * @param y1 - y offset of control point
+     * @param x2 - x offset of the end of the curve
+     * @param y2 - y offset of the end of the curve
+     * @param weight - weight of the curve, must be greater than zero
+     */
     relConicTo(x1, y1, x2, y2, weight) {
         call("libgtk-4.so.1", "gsk_path_builder_rel_conic_to", [
             {
@@ -413,6 +652,21 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a [cubic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_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 [method@Gsk.PathBuilder.cubic_to].
+     * @param x1 - x offset of first control point
+     * @param y1 - y offset of first control point
+     * @param x2 - x offset of second control point
+     * @param y2 - y offset of second control point
+     * @param x3 - x offset of the end of the curve
+     * @param y3 - y offset of the end of the curve
+     */
     relCubicTo(x1, y1, x2, y2, x3, y3) {
         call("libgtk-4.so.1", "gsk_path_builder_rel_cubic_to", [
             {
@@ -445,6 +699,18 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Implements arc-to according to the HTML Canvas spec.
+     *
+     * All coordinates are given relative to the current point.
+     *
+     * This is the relative version of [method@Gsk.PathBuilder.html_arc_to].
+     * @param x1 - x coordinate of first control point
+     * @param y1 - y coordinate of first control point
+     * @param x2 - x coordinate of second control point
+     * @param y2 - y coordinate of second control point
+     * @param radius - radius of the circle
+     */
     relHtmlArcTo(x1, y1, x2, y2, radius) {
         call("libgtk-4.so.1", "gsk_path_builder_rel_html_arc_to", [
             {
@@ -473,6 +739,14 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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 [method@Gsk.PathBuilder.line_to].
+     * @param x - x offset
+     * @param y - y offset
+     */
     relLineTo(x, y) {
         call("libgtk-4.so.1", "gsk_path_builder_rel_line_to", [
             {
@@ -489,6 +763,13 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Starts a new contour by placing the pen at @x, `y` relative to the current point.
+     *
+     * This is the relative version of [method@Gsk.PathBuilder.move_to].
+     * @param x - x offset
+     * @param y - y offset
+     */
     relMoveTo(x, y) {
         call("libgtk-4.so.1", "gsk_path_builder_rel_move_to", [
             {
@@ -505,6 +786,18 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Adds a [quadratic Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_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 [method@Gsk.PathBuilder.quad_to].
+     * @param x1 - x offset of control point
+     * @param y1 - y offset of control point
+     * @param x2 - x offset of the end of the curve
+     * @param y2 - y offset of the end of the curve
+     */
     relQuadTo(x1, y1, x2, y2) {
         call("libgtk-4.so.1", "gsk_path_builder_rel_quad_to", [
             {
@@ -529,6 +822,20 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Implements arc-to according to the SVG spec.
+     *
+     * All coordinates are given relative to the current point.
+     *
+     * This is the relative version of [method@Gsk.PathBuilder.svg_arc_to].
+     * @param rx - x radius
+     * @param ry - y radius
+     * @param xAxisRotation - the rotation of the ellipsis
+     * @param largeArc - whether to add the large arc
+     * @param positiveSweep - whether to sweep in the positive direction
+     * @param x - x coordinate of the endpoint
+     * @param y - y coordinate of the endpoint
+     */
     relSvgArcTo(rx, ry, xAxisRotation, largeArc, positiveSweep, x, y) {
         call("libgtk-4.so.1", "gsk_path_builder_rel_svg_arc_to", [
             {
@@ -565,6 +872,22 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     * @param rx - x radius
+     * @param ry - y radius
+     * @param xAxisRotation - the rotation of the ellipsis
+     * @param largeArc - whether to add the large arc
+     * @param positiveSweep - whether to sweep in the positive direction
+     * @param x - x coordinate of the endpoint
+     * @param y - y coordinate of the endpoint
+     */
     svgArcTo(rx, ry, xAxisRotation, largeArc, positiveSweep, x, y) {
         call("libgtk-4.so.1", "gsk_path_builder_svg_arc_to", [
             {
@@ -601,6 +924,16 @@ export class PathBuilder {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Creates a new path 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 [method@Gsk.PathBuilder.free_to_path].
+     */
     toPath() {
         const ptr = call("libgtk-4.so.1", "gsk_path_builder_to_path", [
             {
@@ -615,6 +948,9 @@ export class PathBuilder {
         });
         return getObject(ptr, Path);
     }
+    /**
+     * Releases a reference on the given builder.
+     */
     unref() {
         call("libgtk-4.so.1", "gsk_path_builder_unref", [
             {

package/dist/generated/gsk/path-measure.d.ts

@@ -1,16 +1,63 @@
 import { Ref } from "@gtkx/native";
 import { Path } from "./path.js";
 import { PathPoint } from "./path-point.js";
+/**
+ * Performs measurements on paths such as determining the length of the path.
+ *
+ * Many measuring operations require sampling the path length
+ * at intermediate points. Therefore, a `GskPathMeasure` has
+ * a tolerance that determines what precision is required
+ * for such approximations.
+ *
+ * A `GskPathMeasure` struct is a reference counted struct
+ * and should be treated as opaque.
+ */
 export declare class PathMeasure {
     ptr: unknown;
+    /**
+     * Creates a measure object for the given `path` with the
+     * default tolerance.
+     * @param path - the path to measure
+     */
     constructor(path: Path);
     constructor(_args: unknown[]);
+    /**
+     * Creates a measure object for the given `path` and @tolerance.
+     * @param path - the path to measure
+     * @param tolerance - the tolerance for measuring operations
+     */
     static measureNewWithTolerance(path: Path, tolerance: number): PathMeasure;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the length of the path being measured.
+     *
+     * The length is cached, so this function does not do any work.
+     */
     getLength(): number;
+    /**
+     * Returns the path that the measure was created for.
+     */
     getPath(): Path;
+    /**
+     * Gets the point at the given distance into the path.
+     *
+     * An empty path has no points, so false is returned in that case.
+     * @param distance - the distance
+     * @param result - return location for the point
+     */
     getPoint(distance: number, result: Ref<PathPoint>): boolean;
+    /**
+     * Returns the tolerance that the measure was created with.
+     */
     getTolerance(): number;
+    /**
+     * Increases the reference count of a `GskPathMeasure` by one.
+     */
     ref(): PathMeasure;
+    /**
+     * Decreases the reference count of a `GskPathMeasure` by one.
+     *
+     * If the resulting reference count is zero, frees the object.
+     */
     unref(): void;
 }

package/dist/generated/gsk/path-measure.js

@@ -1,12 +1,28 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Path } from "./path.js";
+/**
+ * Performs measurements on paths such as determining the length of the path.
+ *
+ * Many measuring operations require sampling the path length
+ * at intermediate points. Therefore, a `GskPathMeasure` has
+ * a tolerance that determines what precision is required
+ * for such approximations.
+ *
+ * A `GskPathMeasure` struct is a reference counted struct
+ * and should be treated as opaque.
+ */
 export class PathMeasure {
     ptr;
     constructor(...args) {
         const _args = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * Creates a measure object for the given `path` and @tolerance.
+     * @param path - the path to measure
+     * @param tolerance - the tolerance for measuring operations
+     */
     static measureNewWithTolerance(path, tolerance) {
         const ptr = call("libgtk-4.so.1", "gsk_path_measure_new_with_tolerance", [
             {
@@ -39,6 +55,11 @@ export class PathMeasure {
             },
         ], { type: "boxed", borrowed: true, innerType: "GskPathMeasure" });
     }
+    /**
+     * Gets the length of the path being measured.
+     *
+     * The length is cached, so this function does not do any work.
+     */
     getLength() {
         return call("libgtk-4.so.1", "gsk_path_measure_get_length", [
             {
@@ -47,6 +68,9 @@ export class PathMeasure {
             },
         ], { type: "float", size: 32 });
     }
+    /**
+     * Returns the path that the measure was created for.
+     */
     getPath() {
         const ptr = call("libgtk-4.so.1", "gsk_path_measure_get_path", [
             {
@@ -61,6 +85,13 @@ export class PathMeasure {
         });
         return getObject(ptr, Path);
     }
+    /**
+     * Gets the point at the given distance into the path.
+     *
+     * An empty path has no points, so false is returned in that case.
+     * @param distance - the distance
+     * @param result - return location for the point
+     */
     getPoint(distance, result) {
         return call("libgtk-4.so.1", "gsk_path_measure_get_point", [
             {
@@ -84,6 +115,9 @@ export class PathMeasure {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns the tolerance that the measure was created with.
+     */
     getTolerance() {
         return call("libgtk-4.so.1", "gsk_path_measure_get_tolerance", [
             {
@@ -92,6 +126,9 @@ export class PathMeasure {
             },
         ], { type: "float", size: 32 });
     }
+    /**
+     * Increases the reference count of a `GskPathMeasure` by one.
+     */
     ref() {
         const ptr = call("libgtk-4.so.1", "gsk_path_measure_ref", [
             {
@@ -106,6 +143,11 @@ export class PathMeasure {
         });
         return getObject(ptr, PathMeasure);
     }
+    /**
+     * Decreases the reference count of a `GskPathMeasure` by one.
+     *
+     * If the resulting reference count is zero, frees the object.
+     */
     unref() {
         call("libgtk-4.so.1", "gsk_path_measure_unref", [
             {