@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/snapshot.d.ts

@@ -6,58 +6,535 @@ import * as Graphene from "../graphene/index.js";
 import * as Gsk from "../gsk/index.js";
 import * as Pango from "../pango/index.js";
 import * as cairo from "../cairo/index.js";
+/**
+ * Assists in creating [class@Gsk.RenderNode]s for widgets.
+ *
+ * It functions in a similar way to a cairo context, and maintains a stack
+ * of render nodes and their associated transformations.
+ *
+ * The node at the top of the stack is the one that `gtk_snapshot_append_…()`
+ * functions operate on. Use the `gtk_snapshot_push_…()` functions and
+ * [method@Snapshot.pop] to change the current node.
+ *
+ * The typical way to obtain a `GtkSnapshot` object is as an argument to
+ * the [vfunc@Gtk.Widget.snapshot] vfunc. If you need to create your own
+ * `GtkSnapshot`, use [ctor@Gtk.Snapshot.new].
+ */
 export declare class Snapshot extends Gdk.Snapshot {
+    /**
+     * Creates a new `GtkSnapshot`.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Appends a stroked border rectangle inside the given @outline.
+     *
+     * The four sides of the border can have different widths and colors.
+     * @param outline - the outline of the border
+     * @param borderWidth - the stroke width of the border on
+     * @param borderColor - the color used on the top, right,
+     */
     appendBorder(outline: number, borderWidth: number[], borderColor: Gdk.RGBA[]): void;
+    /**
+     * Creates a new [class@Gsk.CairoNode] and appends it to the current
+     * render node of @snapshot, without changing the current node.
+     * @param bounds - the bounds for the new node
+     */
     appendCairo(bounds: Graphene.Rect): cairo.Context;
+    /**
+     * Creates a new render node drawing the `color` into the
+     * given `bounds` and appends it to the current render node
+     * of @snapshot.
+     *
+     * You should try to avoid calling this function if
+     * `color` is transparent.
+     * @param color - the color to draw
+     * @param bounds - the bounds for the new node
+     */
     appendColor(color: Gdk.RGBA, bounds: Graphene.Rect): void;
+    /**
+     * Appends a conic gradient node with the given stops to @snapshot.
+     * @param bounds - the rectangle to render the gradient into
+     * @param center - the center point of the conic gradient
+     * @param rotation - the clockwise rotation in degrees of the starting angle.
+     * @param stops - the color stops defining the gradient
+     * @param nStops - the number of elements in @stops
+     */
     appendConicGradient(bounds: Graphene.Rect, center: Graphene.Point, rotation: number, stops: number[], nStops: number): void;
+    /**
+     * A convenience method to fill a path with a color.
+     *
+     * See [method@Gtk.Snapshot.push_fill] if you need
+     * to fill a path with more complex content than
+     * a color.
+     * @param path - The path describing the area to fill
+     * @param fillRule - The fill rule to use
+     * @param color - the color to fill the path with
+     */
     appendFill(path: Gsk.Path, fillRule: Gsk.FillRule, color: Gdk.RGBA): void;
+    /**
+     * Appends an inset shadow into the box given by @outline.
+     * @param outline - outline of the region surrounded by shadow
+     * @param color - color of the shadow
+     * @param dx - horizontal offset of shadow
+     * @param dy - vertical offset of shadow
+     * @param spread - how far the shadow spreads towards the inside
+     * @param blurRadius - how much blur to apply to the shadow
+     */
     appendInsetShadow(outline: number, color: Gdk.RGBA, dx: number, dy: number, spread: number, blurRadius: number): void;
+    /**
+     * Creates render nodes for rendering `layout` in the given foregound `color` and appends them to the current node of `snapshot` without changing the
+     * current node. The current theme's foreground color for a widget can be
+     * obtained with [method@Gtk.Widget.get_color].
+     *
+     * Note that if the layout does not produce any visible output, then nodes
+     * may not be added to the @snapshot.
+     * @param layout - the `PangoLayout` to render
+     * @param color - the foreground color to render the layout in
+     */
     appendLayout(layout: Pango.Layout, color: Gdk.RGBA): void;
+    /**
+     * Appends a linear gradient node with the given stops to @snapshot.
+     * @param bounds - the rectangle to render the linear gradient into
+     * @param startPoint - the point at which the linear gradient will begin
+     * @param endPoint - the point at which the linear gradient will finish
+     * @param stops - the color stops defining the gradient
+     * @param nStops - the number of elements in @stops
+     */
     appendLinearGradient(bounds: Graphene.Rect, startPoint: Graphene.Point, endPoint: Graphene.Point, stops: number[], nStops: number): void;
+    /**
+     * Appends `node` to the current render node of @snapshot,
+     * without changing the current node.
+     *
+     * If `snapshot` does not have a current node yet, `node` will become the initial node.
+     * @param node - a `GskRenderNode`
+     */
     appendNode(node: Gsk.RenderNode): void;
+    /**
+     * Appends an outset shadow node around the box given by @outline.
+     * @param outline - outline of the region surrounded by shadow
+     * @param color - color of the shadow
+     * @param dx - horizontal offset of shadow
+     * @param dy - vertical offset of shadow
+     * @param spread - how far the shadow spreads towards the outside
+     * @param blurRadius - how much blur to apply to the shadow
+     */
     appendOutsetShadow(outline: number, color: Gdk.RGBA, dx: number, dy: number, spread: number, blurRadius: number): void;
+    /**
+     * Appends a radial gradient node with the given stops to @snapshot.
+     * @param bounds - the rectangle to render the readial gradient into
+     * @param center - the center point for the radial gradient
+     * @param hradius - the horizontal radius
+     * @param vradius - the vertical radius
+     * @param start - the start position (on the horizontal axis)
+     * @param end - the end position (on the horizontal axis)
+     * @param stops - the color stops defining the gradient
+     * @param nStops - the number of elements in @stops
+     */
     appendRadialGradient(bounds: Graphene.Rect, center: Graphene.Point, hradius: number, vradius: number, start: number, end: number, stops: number[], nStops: number): void;
+    /**
+     * Appends a repeating linear gradient node with the given stops to @snapshot.
+     * @param bounds - the rectangle to render the linear gradient into
+     * @param startPoint - the point at which the linear gradient will begin
+     * @param endPoint - the point at which the linear gradient will finish
+     * @param stops - the color stops defining the gradient
+     * @param nStops - the number of elements in @stops
+     */
     appendRepeatingLinearGradient(bounds: Graphene.Rect, startPoint: Graphene.Point, endPoint: Graphene.Point, stops: number[], nStops: number): void;
+    /**
+     * Appends a repeating radial gradient node with the given stops to @snapshot.
+     * @param bounds - the rectangle to render the readial gradient into
+     * @param center - the center point for the radial gradient
+     * @param hradius - the horizontal radius
+     * @param vradius - the vertical radius
+     * @param start - the start position (on the horizontal axis)
+     * @param end - the end position (on the horizontal axis)
+     * @param stops - the color stops defining the gradient
+     * @param nStops - the number of elements in @stops
+     */
     appendRepeatingRadialGradient(bounds: Graphene.Rect, center: Graphene.Point, hradius: number, vradius: number, start: number, end: number, stops: number[], nStops: number): void;
+    /**
+     * Creates a new render node drawing the `texture` into the given `bounds` and appends it to the
+     * current render node of @snapshot.
+     *
+     * In contrast to [method@Gtk.Snapshot.append_texture],
+     * this function provides control about how the filter
+     * that is used when scaling.
+     * @param texture - the texture to render
+     * @param filter - the filter to use
+     * @param bounds - the bounds for the new node
+     */
     appendScaledTexture(texture: Gdk.Texture, filter: Gsk.ScalingFilter, bounds: Graphene.Rect): void;
+    /**
+     * A convenience method to stroke a path with a color.
+     *
+     * See [method@Gtk.Snapshot.push_stroke] if you need
+     * to stroke a path with more complex content than
+     * a color.
+     * @param path - The path describing the area to fill
+     * @param stroke - The stroke attributes
+     * @param color - the color to fill the path with
+     */
     appendStroke(path: Gsk.Path, stroke: Gsk.Stroke, color: Gdk.RGBA): void;
+    /**
+     * Creates a new render node drawing the `texture` into the given `bounds` and appends it to the
+     * current render node of @snapshot.
+     *
+     * If the texture needs to be scaled to fill @bounds,
+     * linear filtering is used. See [method@Gtk.Snapshot.append_scaled_texture]
+     * if you need other filtering, such as nearest-neighbour.
+     * @param texture - the texture to render
+     * @param bounds - the bounds for the new node
+     */
     appendTexture(texture: Gdk.Texture, bounds: Graphene.Rect): void;
+    /**
+     * Removes the top element from the stack of render nodes and
+     * adds it to the nearest [class@Gsk.GLShaderNode] below it.
+     *
+     * This must be called the same number of times as the number
+     * of textures is needed for the shader in
+     * [method@Gtk.Snapshot.push_gl_shader].
+     */
     glShaderPopTexture(): void;
+    /**
+     * Applies a perspective projection transform.
+     *
+     * See [method@Gsk.Transform.perspective] for a discussion on the details.
+     * @param depth - distance of the z=0 plane
+     */
     perspective(depth: number): void;
+    /**
+     * Removes the top element from the stack of render nodes,
+     * and appends it to the node underneath it.
+     */
     pop(): void;
+    /**
+     * Blends together two images with the given blend mode.
+     *
+     * Until the first call to [method@Gtk.Snapshot.pop], the
+     * bottom image for the blend operation will be recorded.
+     * After that call, the top image to be blended will be
+     * recorded until the second call to [method@Gtk.Snapshot.pop].
+     *
+     * Calling this function requires two subsequent calls
+     * to [method@Gtk.Snapshot.pop].
+     * @param blendMode - blend mode to use
+     */
     pushBlend(blendMode: Gsk.BlendMode): void;
+    /**
+     * Blurs an image.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     * @param radius - the blur radius to use. Must be positive
+     */
     pushBlur(radius: number): void;
+    /**
+     * Clips an image to a rectangle.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     * @param bounds - the rectangle to clip to
+     */
     pushClip(bounds: Graphene.Rect): void;
+    /**
+     * Modifies the colors of an image by applying an affine transformation
+     * in RGB space.
+     *
+     * In particular, the colors will be transformed by applying
+     *
+     * pixel = transpose(color_matrix) * pixel + color_offset
+     *
+     * for every pixel. The transformation operates on unpremultiplied
+     * colors, with color components ordered R, G, B, A.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     * @param colorMatrix - the color matrix to use
+     * @param colorOffset - the color offset to use
+     */
     pushColorMatrix(colorMatrix: Graphene.Matrix, colorOffset: Graphene.Vec4): void;
+    /**
+     * Modifies the colors of an image by applying a transfer
+     * function for each component.
+     *
+     * The transfer functions operate on unpremultiplied colors.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     * @param red - the transfer for the red component
+     * @param green - the transfer for the green component
+     * @param blue - the transfer for the blue component
+     * @param alpha - the transfer for the alpha component
+     */
     pushComponentTransfer(red: Gsk.ComponentTransfer, green: Gsk.ComponentTransfer, blue: Gsk.ComponentTransfer, alpha: Gsk.ComponentTransfer): void;
+    /**
+     * Snapshots a cross-fade operation between two images with the
+     * given @progress.
+     *
+     * Until the first call to [method@Gtk.Snapshot.pop], the start image
+     * will be snapshot. After that call, the end image will be recorded
+     * until the second call to [method@Gtk.Snapshot.pop].
+     *
+     * Calling this function requires two subsequent calls
+     * to [method@Gtk.Snapshot.pop].
+     * @param progress - progress between 0.0 and 1.0
+     */
     pushCrossFade(progress: number): void;
+    /**
+     * Fills the area given by `path` and `fill_rule` with an image and discards everything
+     * outside of it.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     *
+     * If you want to fill the path with a color, [method@Gtk.Snapshot.append_fill]
+     * than rendering new ones, use [method@Gtk.Snapshot.append_fill]
+     * may be more convenient.
+     * @param path - The path describing the area to fill
+     * @param fillRule - The fill rule to use
+     */
     pushFill(path: Gsk.Path, fillRule: Gsk.FillRule): void;
+    /**
+     * Push a [class@Gsk.GLShaderNode].
+     *
+     * The node uses the given [class@Gsk.GLShader] and uniform values
+     * Additionally this takes a list of `n_children` other nodes
+     * which will be passed to the [class@Gsk.GLShaderNode].
+     *
+     * The `take_args` argument is a block of data to use for uniform
+     * arguments, as per types and offsets defined by the @shader.
+     * Normally this is generated by [method@Gsk.GLShader.format_args]
+     * or [struct@Gsk.ShaderArgsBuilder].
+     *
+     * The snapshotter takes ownership of @take_args, so the caller should
+     * not free it after this.
+     *
+     * If the renderer doesn't support GL shaders, or if there is any
+     * problem when compiling the shader, then the node will draw pink.
+     * You should use [method@Gsk.GLShader.compile] to ensure the `shader` will work for the renderer before using it.
+     *
+     * If the shader requires textures (see [method@Gsk.GLShader.get_n_textures]),
+     * then it is expected that you call [method@Gtk.Snapshot.gl_shader_pop_texture]
+     * the number of times that are required. Each of these calls will generate
+     * a node that is added as a child to the `GskGLShaderNode`, which in turn
+     * will render these offscreen and pass as a texture to the shader.
+     *
+     * Once all textures (if any) are pop:ed, you must call the regular
+     * [method@Gtk.Snapshot.pop].
+     *
+     * If you want to use pre-existing textures as input to the shader rather
+     * than rendering new ones, use [method@Gtk.Snapshot.append_texture] to
+     * push a texture node. These will be used directly rather than being
+     * re-rendered.
+     *
+     * For details on how to write shaders, see [class@Gsk.GLShader].
+     * @param shader - The code to run
+     * @param bounds - the rectangle to render into
+     * @param takeArgs - Data block with arguments for the shader.
+     */
     pushGlShader(shader: Gsk.GLShader, bounds: Graphene.Rect, takeArgs: GLib.Bytes): void;
+    /**
+     * Until the first call to [method@Gtk.Snapshot.pop], the
+     * mask image for the mask operation will be recorded.
+     *
+     * After that call, the source image will be recorded until
+     * the second call to [method@Gtk.Snapshot.pop].
+     *
+     * Calling this function requires 2 subsequent calls to gtk_snapshot_pop().
+     * @param maskMode - mask mode to use
+     */
     pushMask(maskMode: Gsk.MaskMode): void;
+    /**
+     * Modifies the opacity of an image.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     * @param opacity - the opacity to use
+     */
     pushOpacity(opacity: number): void;
+    /**
+     * Creates a node that repeats the child node.
+     *
+     * The child is recorded until the next call to [method@Gtk.Snapshot.pop].
+     * @param bounds - the bounds within which to repeat
+     * @param childBounds - the bounds of the child or %NULL
+     */
     pushRepeat(bounds: Graphene.Rect, childBounds?: Graphene.Rect | null): void;
+    /**
+     * Clips an image to a rounded rectangle.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     * @param bounds - the rounded rectangle to clip to
+     */
     pushRoundedClip(bounds: number): void;
+    /**
+     * Applies a shadow to an image.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     * @param shadow - the first shadow specification
+     * @param nShadows - number of shadow specifications
+     */
     pushShadow(shadow: number[], nShadows: number): void;
+    /**
+     * Strokes the given `path` with the attributes given by `stroke` and
+     * an image.
+     *
+     * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
+     *
+     * Note that the strokes are subject to the same transformation as
+     * everything else, so uneven scaling will cause horizontal and vertical
+     * strokes to have different widths.
+     *
+     * If you want to stroke the path with a color, [method@Gtk.Snapshot.append_stroke]
+     * may be more convenient.
+     * @param path - The path to stroke
+     * @param stroke - The stroke attributes
+     */
     pushStroke(path: Gsk.Path, stroke: Gsk.Stroke): void;
+    /**
+     * Creates a render node for the CSS background according to @context,
+     * and appends it to the current node of @snapshot, without changing
+     * the current node.
+     * @param context - the style context that defines the background
+     * @param x - X origin of the rectangle
+     * @param y - Y origin of the rectangle
+     * @param width - rectangle width
+     * @param height - rectangle height
+     */
     renderBackground(context: StyleContext, x: number, y: number, width: number, height: number): void;
+    /**
+     * Creates a render node for the focus outline according to @context,
+     * and appends it to the current node of @snapshot, without changing
+     * the current node.
+     * @param context - the style context that defines the focus ring
+     * @param x - X origin of the rectangle
+     * @param y - Y origin of the rectangle
+     * @param width - rectangle width
+     * @param height - rectangle height
+     */
     renderFocus(context: StyleContext, x: number, y: number, width: number, height: number): void;
+    /**
+     * Creates a render node for the CSS border according to @context,
+     * and appends it to the current node of @snapshot, without changing
+     * the current node.
+     * @param context - the style context that defines the frame
+     * @param x - X origin of the rectangle
+     * @param y - Y origin of the rectangle
+     * @param width - rectangle width
+     * @param height - rectangle height
+     */
     renderFrame(context: StyleContext, x: number, y: number, width: number, height: number): void;
+    /**
+     * Draws a text caret using `snapshot` at the specified index of @layout.
+     * @param context - a `GtkStyleContext`
+     * @param x - X origin
+     * @param y - Y origin
+     * @param layout - the `PangoLayout` of the text
+     * @param index - the index in the `PangoLayout`
+     * @param direction - the `PangoDirection` of the text
+     */
     renderInsertionCursor(context: StyleContext, x: number, y: number, layout: Pango.Layout, index: number, direction: Pango.Direction): void;
+    /**
+     * Creates a render node for rendering `layout` according to the style
+     * information in @context, and appends it to the current node of @snapshot,
+     * without changing the current node.
+     * @param context - the style context that defines the text
+     * @param x - X origin of the rectangle
+     * @param y - Y origin of the rectangle
+     * @param layout - the `PangoLayout` to render
+     */
     renderLayout(context: StyleContext, x: number, y: number, layout: Pango.Layout): void;
+    /**
+     * Restores `snapshot` to the state saved by a preceding call to
+     * [method@Snapshot.save] and removes that state from the stack of
+     * saved states.
+     */
     restore(): void;
+    /**
+     * Rotates @@snapshot's coordinate system by `angle` degrees in 2D space -
+     * or in 3D speak, rotates around the Z axis. The rotation happens around
+     * the origin point of (0, 0) in the @snapshot's current coordinate system.
+     *
+     * To rotate around axes other than the Z axis, use [method@Gsk.Transform.rotate_3d].
+     * @param angle - the rotation angle, in degrees (clockwise)
+     */
     rotate(angle: number): void;
+    /**
+     * Rotates @snapshot's coordinate system by `angle` degrees around @axis.
+     *
+     * For a rotation in 2D space, use [method@Gsk.Transform.rotate].
+     * @param angle - the rotation angle, in degrees (clockwise)
+     * @param axis - The rotation axis
+     */
     rotate_3d(angle: number, axis: Graphene.Vec3): void;
+    /**
+     * Makes a copy of the current state of `snapshot` and saves it
+     * on an internal stack.
+     *
+     * When [method@Gtk.Snapshot.restore] is called, `snapshot` will
+     * be restored to the saved state.
+     *
+     * Multiple calls to [method@Gtk.Snapshot.save] and [method@Gtk.Snapshot.restore]
+     * can be nested; each call to `gtk_snapshot_restore()` restores the state from
+     * the matching paired `gtk_snapshot_save()`.
+     *
+     * It is necessary to clear all saved states with corresponding
+     * calls to `gtk_snapshot_restore()`.
+     */
     save(): void;
+    /**
+     * Scales @snapshot's coordinate system in 2-dimensional space by
+     * the given factors.
+     *
+     * Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions.
+     * @param factorX - scaling factor on the X axis
+     * @param factorY - scaling factor on the Y axis
+     */
     scale(factorX: number, factorY: number): void;
+    /**
+     * Scales @snapshot's coordinate system by the given factors.
+     * @param factorX - scaling factor on the X axis
+     * @param factorY - scaling factor on the Y axis
+     * @param factorZ - scaling factor on the Z axis
+     */
     scale_3d(factorX: number, factorY: number, factorZ: number): void;
+    /**
+     * Returns the render node that was constructed
+     * by @snapshot.
+     *
+     * Note that this function may return %NULL if nothing has been
+     * added to the snapshot or if its content does not produce pixels
+     * to be rendered.
+     *
+     * After calling this function, it is no longer possible to
+     * add more nodes to @snapshot. The only function that should
+     * be called after this is [method@GObject.Object.unref].
+     */
     toNode(): Gsk.RenderNode | null;
+    /**
+     * Returns a paintable encapsulating the render node
+     * that was constructed by @snapshot.
+     *
+     * After calling this function, it is no longer possible to
+     * add more nodes to @snapshot. The only function that should
+     * be called after this is [method@GObject.Object.unref].
+     * @param size - The size of the resulting paintable
+     */
     toPaintable(size?: Graphene.Size | null): Gdk.Paintable | null;
+    /**
+     * Transforms @snapshot's coordinate system with the given @transform.
+     * @param transform - the transform to apply
+     */
     transform(transform?: Gsk.Transform | null): void;
+    /**
+     * Transforms @snapshot's coordinate system with the given @matrix.
+     * @param matrix - the matrix to multiply the transform with
+     */
     transformMatrix(matrix: Graphene.Matrix): void;
+    /**
+     * Translates @snapshot's coordinate system by `point` in 2-dimensional space.
+     * @param point - the point to translate the snapshot by
+     */
     translate(point: Graphene.Point): void;
+    /**
+     * Translates @snapshot's coordinate system by @point.
+     * @param point - the point to translate the snapshot by
+     */
     translate_3d(point: Graphene.Point3D): void;
     connect(signal: "notify", handler: (self: Snapshot, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;