@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gdkpixbuf/pixbuf-loader.js

@@ -4,6 +4,53 @@ import { PixbufFormat } from "./pixbuf-format.js";
 import { Pixbuf } from "./pixbuf.js";
 import { PixbufAnimation } from "./pixbuf-animation.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * Incremental image loader.
+ *
+ * `GdkPixbufLoader` provides a way for applications to drive the
+ * process of loading an image, by letting them send the image data
+ * directly to the loader instead of having the loader read the data
+ * from a file. Applications can use this functionality instead of
+ * `gdk_pixbuf_new_from_file()` or `gdk_pixbuf_animation_new_from_file()`
+ * when they need to parse image data in small chunks. For example,
+ * it should be used when reading an image from a (potentially) slow
+ * network connection, or when loading an extremely large file.
+ *
+ * To use `GdkPixbufLoader` to load an image, create a new instance,
+ * and call [method@GdkPixbuf.PixbufLoader.write] to send the data
+ * to it. When done, [method@GdkPixbuf.PixbufLoader.close] should be
+ * called to end the stream and finalize everything.
+ *
+ * The loader will emit three important signals throughout the process:
+ *
+ * - [signal@GdkPixbuf.PixbufLoader::size-prepared] will be emitted as
+ * soon as the image has enough information to determine the size of
+ * the image to be used. If you want to scale the image while loading
+ * it, you can call [method@GdkPixbuf.PixbufLoader.set_size] in
+ * response to this signal.
+ * - [signal@GdkPixbuf.PixbufLoader::area-prepared] will be emitted as
+ * soon as the pixbuf of the desired has been allocated. You can obtain
+ * the `GdkPixbuf` instance by calling [method@GdkPixbuf.PixbufLoader.get_pixbuf].
+ * If you want to use it, simply acquire a reference to it. You can
+ * also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same
+ * pixbuf.
+ * - [signal@GdkPixbuf.PixbufLoader::area-updated] will be emitted every
+ * time a region is updated. This way you can update a partially
+ * completed image. Note that you do not know anything about the
+ * completeness of an image from the updated area. For example, in an
+ * interlaced image you will need to make several passes before the
+ * image is done loading.
+ *
+ * ## Loading an animation
+ *
+ * Loading an animation is almost as easy as loading an image. Once the
+ * first [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been
+ * emitted, you can call [method@GdkPixbuf.PixbufLoader.get_animation] to
+ * get the [class@GdkPixbuf.PixbufAnimation] instance, and then call
+ * and [method@GdkPixbuf.PixbufAnimation.get_iter] to get a
+ * [class@GdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the
+ * desired time stamp.
+ */
 const SIGNAL_META = {
     "area-prepared": { params: [], returnType: { type: "undefined" } },
     "area-updated": {
@@ -25,9 +72,30 @@ const SIGNAL_META = {
     },
 };
 export class PixbufLoader extends GObject.GObject {
+    /**
+     * Creates a new pixbuf loader object.
+     */
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new pixbuf loader object that always attempts to parse
+     * image data as if it were an image of MIME type @mime_type, instead of
+     * identifying the type automatically.
+     *
+     * This function is useful if you want an error if the image isn't the
+     * expected MIME type; for loading image formats that can't be reliably
+     * identified by looking at the data; or if the user manually forces a
+     * specific MIME type.
+     *
+     * The list of supported mime types depends on what image loaders
+     * are installed, but typically "image/png", "image/jpeg", "image/gif",
+     * "image/tiff" and "image/x-xpixmap" are among the supported mime types.
+     * To obtain the full list of supported mime types, call
+     * gdk_pixbuf_format_get_mime_types() on each of the #GdkPixbufFormat
+     * structs returned by gdk_pixbuf_get_formats().
+     * @param mimeType - the mime type to be loaded
+     */
     static loaderNewWithMimeType(mimeType) {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_new_with_mime_type", [
             {
@@ -37,6 +105,23 @@ export class PixbufLoader extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, PixbufLoader);
     }
+    /**
+     * Creates a new pixbuf loader object that always attempts to parse
+     * image data as if it were an image of type @image_type, instead of
+     * identifying the type automatically.
+     *
+     * This function is useful if you want an error if the image isn't the
+     * expected type; for loading image formats that can't be reliably
+     * identified by looking at the data; or if the user manually forces
+     * a specific type.
+     *
+     * The list of supported image formats depends on what image loaders
+     * are installed, but typically "png", "jpeg", "gif", "tiff" and
+     * "xpm" are among the supported formats. To obtain the full list of
+     * supported image formats, call gdk_pixbuf_format_get_name() on each
+     * of the #GdkPixbufFormat structs returned by gdk_pixbuf_get_formats().
+     * @param imageType - name of the image format to be loaded with the image
+     */
     static loaderNewWithType(imageType) {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_new_with_type", [
             {
@@ -52,6 +137,23 @@ export class PixbufLoader extends GObject.GObject {
             borrowed: false,
         });
     }
+    /**
+     * Informs a pixbuf loader that no further writes with
+     * gdk_pixbuf_loader_write() will occur, so that it can free its
+     * internal loading structures.
+     *
+     * This function also tries to parse any data that hasn't yet been parsed;
+     * if the remaining data is partial or corrupt, an error will be returned.
+     *
+     * If `FALSE` is returned, `error` will be set to an error from the
+     * `GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains.
+     *
+     * If you're just cancelling a load rather than expecting it to be finished,
+     * passing `NULL` for `error` to ignore it is reasonable.
+     *
+     * Remember that this function does not release a reference on the loader, so
+     * you will need to explicitly release any reference you hold.
+     */
     close() {
         const error = { value: null };
         const result = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_close", [
@@ -76,6 +178,16 @@ export class PixbufLoader extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating.
+     *
+     * In general it only makes sense to call this function after the
+     * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted by
+     * the loader.
+     *
+     * If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared`
+     * signal, this function will return `NULL`.
+     */
     getAnimation() {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_get_animation", [
             {
@@ -87,6 +199,10 @@ export class PixbufLoader extends GObject.GObject {
             return null;
         return getObject(ptr, PixbufAnimation);
     }
+    /**
+     * Obtains the available information about the format of the
+     * currently loading image file.
+     */
     getFormat() {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_get_format", [
             {
@@ -103,6 +219,23 @@ export class PixbufLoader extends GObject.GObject {
             return null;
         return getObject(ptr, PixbufFormat);
     }
+    /**
+     * Queries the #GdkPixbuf that a pixbuf loader is currently creating.
+     *
+     * In general it only makes sense to call this function after the
+     * [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been
+     * emitted by the loader; this means that enough data has been read
+     * to know the size of the image that will be allocated.
+     *
+     * If the loader has not received enough data via gdk_pixbuf_loader_write(),
+     * then this function returns `NULL`.
+     *
+     * The returned pixbuf will be the same in all future calls to the loader,
+     * so if you want to keep using it, you should acquire a reference to it.
+     *
+     * Additionally, if the loader is an animation, it will return the "static
+     * image" of the animation (see gdk_pixbuf_animation_get_static_image()).
+     */
     getPixbuf() {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_get_pixbuf", [
             {
@@ -114,6 +247,18 @@ export class PixbufLoader extends GObject.GObject {
             return null;
         return getObject(ptr, Pixbuf);
     }
+    /**
+     * Causes the image to be scaled while it is loaded.
+     *
+     * The desired image size can be determined relative to the original
+     * size of the image by calling gdk_pixbuf_loader_set_size() from a
+     * signal handler for the ::size-prepared signal.
+     *
+     * Attempts to set the desired image size  are ignored after the
+     * emission of the ::size-prepared signal.
+     * @param width - The desired width of the image being loaded.
+     * @param height - The desired height of the image being loaded.
+     */
     setSize(width, height) {
         call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_set_size", [
             {
@@ -130,6 +275,11 @@ export class PixbufLoader extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Parses the next `count` bytes in the given image buffer.
+     * @param buf - Pointer to image data.
+     * @param count - Length of the `buf` buffer in bytes.
+     */
     write(buf, count) {
         const error = { value: null };
         const result = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_write", [
@@ -165,6 +315,10 @@ export class PixbufLoader extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Parses the next contents of the given image buffer.
+     * @param buffer - The image data as a `GBytes` buffer.
+     */
     writeBytes(buffer) {
         const error = { value: null };
         const result = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_loader_write_bytes", [

package/dist/generated/gdkpixbuf/pixbuf-simple-anim.d.ts

@@ -1,10 +1,30 @@
 import { Pixbuf } from "./pixbuf.js";
 import { PixbufAnimation } from "./pixbuf-animation.js";
+/** An opaque struct representing a simple animation. */
 export declare class PixbufSimpleAnim extends PixbufAnimation {
+    /**
+     * Creates a new, empty animation.
+     * @param width - the width of the animation
+     * @param height - the height of the animation
+     * @param rate - the speed of the animation, in frames per second
+     */
     constructor(width: number, height: number, rate: number);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Adds a new frame to @animation. The `pixbuf` must
+     * have the dimensions specified when the animation
+     * was constructed.
+     * @param pixbuf - the pixbuf to add
+     */
     addFrame(pixbuf: Pixbuf): void;
+    /**
+     * Gets whether `animation` should loop indefinitely when it reaches the end.
+     */
     getLoop(): boolean;
+    /**
+     * Sets whether `animation` should loop indefinitely when it reaches the end.
+     * @param loop - whether to loop the animation
+     */
     setLoop(loop: boolean): void;
 }

package/dist/generated/gdkpixbuf/pixbuf-simple-anim.js

@@ -1,5 +1,6 @@
 import { call } from "@gtkx/native";
 import { PixbufAnimation } from "./pixbuf-animation.js";
+/** An opaque struct representing a simple animation. */
 export class PixbufSimpleAnim extends PixbufAnimation {
     constructor(...args) {
         super(...args);
@@ -21,6 +22,12 @@ export class PixbufSimpleAnim extends PixbufAnimation {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Adds a new frame to @animation. The `pixbuf` must
+     * have the dimensions specified when the animation
+     * was constructed.
+     * @param pixbuf - the pixbuf to add
+     */
     addFrame(pixbuf) {
         call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_simple_anim_add_frame", [
             {
@@ -33,6 +40,9 @@ export class PixbufSimpleAnim extends PixbufAnimation {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets whether `animation` should loop indefinitely when it reaches the end.
+     */
     getLoop() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_simple_anim_get_loop", [
             {
@@ -41,6 +51,10 @@ export class PixbufSimpleAnim extends PixbufAnimation {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets whether `animation` should loop indefinitely when it reaches the end.
+     * @param loop - whether to loop the animation
+     */
     setLoop(loop) {
         call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_simple_anim_set_loop", [
             {