@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gsk/path.js

@@ -1,5 +1,20 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * 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 [struct@Gsk.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.
+ */
 export class Path {
     ptr;
     constructor() {
@@ -8,6 +23,33 @@ export class Path {
     createPtr(_init) {
         return null;
     }
+    /**
+     * 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 [method@Gsk.Path.to_string].
+     *
+     * 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.
+     * @param string - a string
+     */
     static parse(string) {
         const ptr = call("libgtk-4.so.1", "gsk_path_parse", [
             {
@@ -22,6 +64,24 @@ export class Path {
         });
         return getObject(ptr, Path);
     }
+    /**
+     * 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.
+     * @param flags - flags to pass to the foreach function
+     * @param func - the function to call for operations
+     * @param userData - user data passed to @func
+     */
     foreach(flags, func, userData) {
         return call("libgtk-4.so.1", "gsk_path_foreach", [
             {
@@ -43,6 +103,26 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * 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 @GSK_PATH_INTERSECTION_START, and
+     * once for the end of the segment, with @GSK_PATH_INTERSECTION_END.
+     * Note that other intersections may occur between the start and end
+     * of such a segment.
+     *
+     * If `func` returns `FALSE`, the iteration is stopped.
+     * @param path2 - the second path
+     * @param func - the function to call for intersections
+     * @param userData - user data passed to @func
+     */
     foreachIntersection(func, path2, userData) {
         return call("libgtk-4.so.1", "gsk_path_foreach_intersection", [
             {
@@ -70,6 +150,23 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * 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.
+     *
+     * 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
+     * graphene_rect_zero(). 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.
+     * @param bounds - return location for the bounds
+     */
     getBounds(bounds) {
         return call("libgtk-4.so.1", "gsk_path_get_bounds", [
             {
@@ -89,6 +186,16 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Computes the closest point on the path to the given point.
+     *
+     * If there is no point closer than the given threshold,
+     * false is returned.
+     * @param point - the point
+     * @param threshold - maximum allowed distance
+     * @param result - return location for the closest point
+     * @param distance - return location for the distance
+     */
     getClosestPoint(point, threshold, result, distance) {
         return call("libgtk-4.so.1", "gsk_path_get_closest_point", [
             {
@@ -126,6 +233,13 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the end point of the path.
+     *
+     * An empty path has no points, so false
+     * is returned in this case.
+     * @param result - return location for point
+     */
     getEndPoint(result) {
         return call("libgtk-4.so.1", "gsk_path_get_end_point", [
             {
@@ -145,6 +259,13 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the start point of the path.
+     *
+     * An empty path has no points, so false
+     * is returned in this case.
+     * @param result - return location for point
+     */
     getStartPoint(result) {
         return call("libgtk-4.so.1", "gsk_path_get_start_point", [
             {
@@ -164,6 +285,17 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * 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.
+     * @param stroke - stroke parameters
+     * @param bounds - the bounds to fill in
+     */
     getStrokeBounds(stroke, bounds) {
         return call("libgtk-4.so.1", "gsk_path_get_stroke_bounds", [
             {
@@ -192,6 +324,14 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether a point is inside the fill area of a path.
+     *
+     * Note that this function assumes that filling a contour
+     * implicitly closes it.
+     * @param point - the point to test
+     * @param fillRule - the fill rule to follow
+     */
     inFill(point, fillRule) {
         return call("libgtk-4.so.1", "gsk_path_in_fill", [
             {
@@ -213,6 +353,9 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns if the path represents a single closed contour.
+     */
     isClosed() {
         return call("libgtk-4.so.1", "gsk_path_is_closed", [
             {
@@ -221,6 +364,9 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if the path is empty, i.e. contains no lines or curves.
+     */
     isEmpty() {
         return call("libgtk-4.so.1", "gsk_path_is_empty", [
             {
@@ -229,6 +375,14 @@ export class Path {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Converts the path into a human-readable representation.
+     *
+     * The string is compatible with (a superset of)
+     * SVG path syntax,
+     * see [func@Gsk.Path.parse] for a summary of the syntax.
+     * @param string - the string to print into
+     */
     print(string) {
         call("libgtk-4.so.1", "gsk_path_print", [
             {
@@ -246,6 +400,9 @@ export class Path {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Increases the reference count of a path by one.
+     */
     ref() {
         const ptr = call("libgtk-4.so.1", "gsk_path_ref", [
             {
@@ -260,6 +417,16 @@ export class Path {
         });
         return getObject(ptr, Path);
     }
+    /**
+     * 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.
+     * @param cr - a cairo context
+     */
     toCairo(cr) {
         call("libgtk-4.so.1", "gsk_path_to_cairo", [
             {
@@ -277,6 +444,15 @@ export class Path {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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 [method@Gsk.Path.print], see that function
+     * for details.
+     */
     toString() {
         return call("libgtk-4.so.1", "gsk_path_to_string", [
             {
@@ -285,6 +461,11 @@ export class Path {
             },
         ], { type: "string" });
     }
+    /**
+     * Decreases the reference count of a path by one.
+     *
+     * If the resulting reference count is zero, frees the path.
+     */
     unref() {
         call("libgtk-4.so.1", "gsk_path_unref", [
             {

package/dist/generated/gsk/radial-gradient-node.d.ts

@@ -1,15 +1,52 @@
 import { Ref } from "@gtkx/native";
 import * as Graphene from "../graphene/index.js";
 import { RenderNode } from "./render-node.js";
+/** A render node for a radial gradient. */
 export declare class RadialGradientNode extends RenderNode {
+    /**
+     * Creates a `GskRenderNode` that draws a radial gradient.
+     *
+     * The radial gradient
+     * starts around @center. The size of the gradient is dictated by `hradius` in horizontal orientation and by `vradius` in vertical orientation.
+     * @param bounds - the bounds of the node
+     * @param center - the center of the gradient
+     * @param hradius - the horizontal radius
+     * @param vradius - the vertical radius
+     * @param start - a percentage >= 0 that defines the start of the gradient around @center
+     * @param end - a percentage >= 0 that defines the end of the gradient around @center
+     * @param colorStops - a pointer to an array of
+     * @param nColorStops - the number of elements in @color_stops
+     */
     constructor(bounds: Graphene.Rect, center: Graphene.Point, hradius: number, vradius: number, start: number, end: number, colorStops: number[], nColorStops: number);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Retrieves the center pointer for the gradient.
+     */
     getCenter(): Graphene.Point;
+    /**
+     * Retrieves the color stops in the gradient.
+     * @param nStops - the number of color stops in the returned array
+     */
     getColorStops(nStops?: Ref<number> | null): number[];
+    /**
+     * Retrieves the end value for the gradient.
+     */
     getEnd(): number;
+    /**
+     * Retrieves the horizontal radius for the gradient.
+     */
     getHradius(): number;
+    /**
+     * Retrieves the number of color stops in the gradient.
+     */
     getNColorStops(): number;
+    /**
+     * Retrieves the start value for the gradient.
+     */
     getStart(): number;
+    /**
+     * Retrieves the vertical radius for the gradient.
+     */
     getVradius(): number;
 }

package/dist/generated/gsk/radial-gradient-node.js

@@ -2,6 +2,7 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as Graphene from "../graphene/index.js";
 import { RenderNode } from "./render-node.js";
+/** A render node for a radial gradient. */
 export class RadialGradientNode extends RenderNode {
     constructor(...args) {
         super(...args);
@@ -56,6 +57,9 @@ export class RadialGradientNode extends RenderNode {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Retrieves the center pointer for the gradient.
+     */
     getCenter() {
         const ptr = call("libgtk-4.so.1", "gsk_radial_gradient_node_get_center", [
             {
@@ -70,6 +74,10 @@ export class RadialGradientNode extends RenderNode {
         });
         return getObject(ptr, Graphene.Point);
     }
+    /**
+     * Retrieves the color stops in the gradient.
+     * @param nStops - the number of color stops in the returned array
+     */
     getColorStops(nStops) {
         return call("libgtk-4.so.1", "gsk_radial_gradient_node_get_color_stops", [
             {
@@ -86,6 +94,9 @@ export class RadialGradientNode extends RenderNode {
             },
         ], { type: "array", itemType: { type: "int", size: 64, unsigned: true } });
     }
+    /**
+     * Retrieves the end value for the gradient.
+     */
     getEnd() {
         return call("libgtk-4.so.1", "gsk_radial_gradient_node_get_end", [
             {
@@ -94,6 +105,9 @@ export class RadialGradientNode extends RenderNode {
             },
         ], { type: "float", size: 32 });
     }
+    /**
+     * Retrieves the horizontal radius for the gradient.
+     */
     getHradius() {
         return call("libgtk-4.so.1", "gsk_radial_gradient_node_get_hradius", [
             {
@@ -102,6 +116,9 @@ export class RadialGradientNode extends RenderNode {
             },
         ], { type: "float", size: 32 });
     }
+    /**
+     * Retrieves the number of color stops in the gradient.
+     */
     getNColorStops() {
         return call("libgtk-4.so.1", "gsk_radial_gradient_node_get_n_color_stops", [
             {
@@ -110,6 +127,9 @@ export class RadialGradientNode extends RenderNode {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Retrieves the start value for the gradient.
+     */
     getStart() {
         return call("libgtk-4.so.1", "gsk_radial_gradient_node_get_start", [
             {
@@ -118,6 +138,9 @@ export class RadialGradientNode extends RenderNode {
             },
         ], { type: "float", size: 32 });
     }
+    /**
+     * Retrieves the vertical radius for the gradient.
+     */
     getVradius() {
         return call("libgtk-4.so.1", "gsk_radial_gradient_node_get_vradius", [
             {

package/dist/generated/gsk/render-node.d.ts

@@ -3,17 +3,100 @@ import { RenderNodeType } from "./enums.js";
 import * as GLib from "../glib/index.js";
 import * as Graphene from "../graphene/index.js";
 import * as cairo from "../cairo/index.js";
+/**
+ * The basic block in a scene graph to be rendered using [class@Gsk.Renderer].
+ *
+ * Each node has a parent, except the top-level node; each node may have
+ * children nodes.
+ *
+ * Each node has an associated drawing surface, which has the size of
+ * the rectangle set when creating it.
+ *
+ * Render nodes are meant to be transient; once they have been associated
+ * to a [class@Gsk.Renderer] it's safe to release any reference you have on
+ * them. All [class@Gsk.RenderNode]s are immutable, you can only specify their
+ * properties during construction.
+ */
 export declare class RenderNode {
     ptr: unknown;
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Loads data previously created via [method@Gsk.RenderNode.serialize].
+     *
+     * For a discussion of the supported format, see that function.
+     * @param bytes - the bytes containing the data
+     * @param errorFunc - callback on parsing errors
+     * @param userData - user_data for @error_func
+     */
     static deserialize(bytes: GLib.Bytes, errorFunc?: (...args: unknown[]) => unknown | null, userData?: number | null): RenderNode;
+    /**
+     * Draws the contents of a render node on a cairo context.
+     *
+     * Typically, you'll use this function to implement fallback rendering
+     * of render nodes on an intermediate Cairo context, instead of using
+     * the drawing context associated to a [class@Gdk.Surface]'s rendering buffer.
+     *
+     * For advanced nodes that cannot be supported using Cairo, in particular
+     * for nodes doing 3D operations, this function may fail.
+     * @param cr - cairo context to draw to
+     */
     draw(cr: cairo.Context): void;
+    /**
+     * Retrieves the boundaries of the @node.
+     *
+     * The node will not draw outside of its boundaries.
+     * @param bounds - return location for the boundaries
+     */
     getBounds(bounds: Ref<Graphene.Rect>): void;
+    /**
+     * Returns the type of the render node.
+     */
     getNodeType(): RenderNodeType;
+    /**
+     * Gets an opaque rectangle inside the node that GTK can determine to
+     * be fully opaque.
+     *
+     * There is no guarantee that this is indeed the largest opaque rectangle or
+     * that regions outside the rectangle are not opaque. This function is a best
+     * effort with that goal.
+     *
+     * The rectangle will be fully contained in the bounds of the node.
+     * @param outOpaque - return location for the opaque rect
+     */
     getOpaqueRect(outOpaque: Ref<Graphene.Rect>): boolean;
+    /**
+     * Acquires a reference on the given `GskRenderNode`.
+     */
     ref(): RenderNode;
+    /**
+     * Serializes the `node` for later deserialization via
+     * gsk_render_node_deserialize(). No guarantees are made about the format
+     * used other than that the same version of GTK will be able to deserialize
+     * the result of a call to gsk_render_node_serialize() and
+     * gsk_render_node_deserialize() will correctly reject files it cannot open
+     * that were created with previous versions of GTK.
+     *
+     * The intended use of this functions is testing, benchmarking and debugging.
+     * The format is not meant as a permanent storage format.
+     */
     serialize(): GLib.Bytes;
+    /**
+     * Releases a reference on the given `GskRenderNode`.
+     *
+     * If the reference was the last, the resources associated to the `node` are
+     * freed.
+     */
     unref(): void;
+    /**
+     * This function is equivalent to calling [method@Gsk.RenderNode.serialize]
+     * followed by [func@GLib.file_set_contents].
+     *
+     * See those two functions for details on the arguments.
+     *
+     * It is mostly intended for use inside a debugger to quickly dump a render
+     * node to a file for later inspection.
+     * @param filename - the file to save it to
+     */
     writeToFile(filename: string): boolean;
 }

package/dist/generated/gsk/render-node.js

@@ -1,6 +1,20 @@
 import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
+/**
+ * The basic block in a scene graph to be rendered using [class@Gsk.Renderer].
+ *
+ * Each node has a parent, except the top-level node; each node may have
+ * children nodes.
+ *
+ * Each node has an associated drawing surface, which has the size of
+ * the rectangle set when creating it.
+ *
+ * Render nodes are meant to be transient; once they have been associated
+ * to a [class@Gsk.Renderer] it's safe to release any reference you have on
+ * them. All [class@Gsk.RenderNode]s are immutable, you can only specify their
+ * properties during construction.
+ */
 export class RenderNode {
     ptr;
     constructor(...args) {
@@ -9,6 +23,14 @@ export class RenderNode {
     createPtr(_args) {
         return null;
     }
+    /**
+     * Loads data previously created via [method@Gsk.RenderNode.serialize].
+     *
+     * For a discussion of the supported format, see that function.
+     * @param bytes - the bytes containing the data
+     * @param errorFunc - callback on parsing errors
+     * @param userData - user_data for @error_func
+     */
     static deserialize(bytes, errorFunc, userData) {
         const ptr = call("libgtk-4.so.1", "gsk_render_node_deserialize", [
             {
@@ -33,6 +55,17 @@ export class RenderNode {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, RenderNode);
     }
+    /**
+     * Draws the contents of a render node on a cairo context.
+     *
+     * Typically, you'll use this function to implement fallback rendering
+     * of render nodes on an intermediate Cairo context, instead of using
+     * the drawing context associated to a [class@Gdk.Surface]'s rendering buffer.
+     *
+     * For advanced nodes that cannot be supported using Cairo, in particular
+     * for nodes doing 3D operations, this function may fail.
+     * @param cr - cairo context to draw to
+     */
     draw(cr) {
         call("libgtk-4.so.1", "gsk_render_node_draw", [
             {
@@ -50,6 +83,12 @@ export class RenderNode {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Retrieves the boundaries of the @node.
+     *
+     * The node will not draw outside of its boundaries.
+     * @param bounds - return location for the boundaries
+     */
     getBounds(bounds) {
         call("libgtk-4.so.1", "gsk_render_node_get_bounds", [
             {
@@ -69,6 +108,9 @@ export class RenderNode {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the type of the render node.
+     */
     getNodeType() {
         return call("libgtk-4.so.1", "gsk_render_node_get_node_type", [
             {
@@ -77,6 +119,17 @@ export class RenderNode {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets an opaque rectangle inside the node that GTK can determine to
+     * be fully opaque.
+     *
+     * There is no guarantee that this is indeed the largest opaque rectangle or
+     * that regions outside the rectangle are not opaque. This function is a best
+     * effort with that goal.
+     *
+     * The rectangle will be fully contained in the bounds of the node.
+     * @param outOpaque - return location for the opaque rect
+     */
     getOpaqueRect(outOpaque) {
         return call("libgtk-4.so.1", "gsk_render_node_get_opaque_rect", [
             {
@@ -96,6 +149,9 @@ export class RenderNode {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Acquires a reference on the given `GskRenderNode`.
+     */
     ref() {
         const ptr = call("libgtk-4.so.1", "gsk_render_node_ref", [
             {
@@ -105,6 +161,17 @@ export class RenderNode {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, RenderNode);
     }
+    /**
+     * Serializes the `node` for later deserialization via
+     * gsk_render_node_deserialize(). No guarantees are made about the format
+     * used other than that the same version of GTK will be able to deserialize
+     * the result of a call to gsk_render_node_serialize() and
+     * gsk_render_node_deserialize() will correctly reject files it cannot open
+     * that were created with previous versions of GTK.
+     *
+     * The intended use of this functions is testing, benchmarking and debugging.
+     * The format is not meant as a permanent storage format.
+     */
     serialize() {
         const ptr = call("libgtk-4.so.1", "gsk_render_node_serialize", [
             {
@@ -119,6 +186,12 @@ export class RenderNode {
         });
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Releases a reference on the given `GskRenderNode`.
+     *
+     * If the reference was the last, the resources associated to the `node` are
+     * freed.
+     */
     unref() {
         call("libgtk-4.so.1", "gsk_render_node_unref", [
             {
@@ -127,6 +200,16 @@ export class RenderNode {
             },
         ], { type: "undefined" });
     }
+    /**
+     * This function is equivalent to calling [method@Gsk.RenderNode.serialize]
+     * followed by [func@GLib.file_set_contents].
+     *
+     * See those two functions for details on the arguments.
+     *
+     * It is mostly intended for use inside a debugger to quickly dump a render
+     * node to a file for later inspection.
+     * @param filename - the file to save it to
+     */
     writeToFile(filename) {
         const error = { value: null };
         const result = call("libgtk-4.so.1", "gsk_render_node_write_to_file", [