@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -3,10 +3,32 @@ import { getObject } from "@gtkx/ffi";
 import { Pixbuf } from "./pixbuf.js";
 import { PixbufAnimationIter } from "./pixbuf-animation-iter.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * An opaque object representing an animation.
+ *
+ * The GdkPixBuf library provides a simple mechanism to load and
+ * represent animations. An animation is conceptually a series of
+ * frames to be displayed over time.
+ *
+ * The animation may not be represented as a series of frames
+ * internally; for example, it may be stored as a sprite and
+ * instructions for moving the sprite around a background.
+ *
+ * To display an animation you don't need to understand its
+ * representation, however; you just ask `GdkPixbuf` what should
+ * be displayed at a given point in time.
+ */
 export class PixbufAnimation extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a new pixbuf animation by loading an image from an resource.
+     *
+     * The file format is detected automatically. If `NULL` is returned, then
+     * `error` will be set.
+     * @param resourcePath - the path of the resource file
+     */
     static animationNewFromResource(resourcePath) {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_new_from_resource", [
             {
@@ -16,6 +38,22 @@ export class PixbufAnimation extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, PixbufAnimation);
     }
+    /**
+     * Creates a new animation by loading it from an input stream.
+     *
+     * The file format is detected automatically.
+     *
+     * If `NULL` is returned, then `error` will be set.
+     *
+     * The `cancellable` can be used to abort the operation from another thread.
+     * If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be
+     * returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and
+     * `G_IO_ERROR` domains.
+     *
+     * The stream is not closed.
+     * @param stream - a `GInputStream` to load the pixbuf from
+     * @param cancellable - optional `GCancellable` object
+     */
     static animationNewFromStream(stream, cancellable) {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_new_from_stream", [
             {
@@ -30,6 +68,11 @@ export class PixbufAnimation extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, PixbufAnimation);
     }
+    /**
+     * Finishes an asynchronous pixbuf animation creation operation started with
+     * [func@GdkPixbuf.PixbufAnimation.new_from_stream_async].
+     * @param asyncResult - a #GAsyncResult
+     */
     static animationNewFromStreamFinish(asyncResult) {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_new_from_stream_finish", [
             {
@@ -48,6 +91,20 @@ export class PixbufAnimation extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Creates a new animation by asynchronously loading an image from an input stream.
+     *
+     * For more details see gdk_pixbuf_new_from_stream(), which is the synchronous
+     * version of this function.
+     *
+     * When the operation is finished, `callback` will be called in the main thread.
+     * You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the
+     * result of the operation.
+     * @param stream - a #GInputStream from which to load the animation
+     * @param cancellable - optional #GCancellable object
+     * @param callback - a `GAsyncReadyCallback` to call when the pixbuf is loaded
+     * @param userData - the data to pass to the callback function
+     */
     static newFromStreamAsync(stream, cancellable, callback) {
         call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_new_from_stream_async", [
             {
@@ -71,6 +128,9 @@ export class PixbufAnimation extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Queries the height of the bounding box of a pixbuf animation.
+     */
     getHeight() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_get_height", [
             {
@@ -79,6 +139,43 @@ export class PixbufAnimation extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Get an iterator for displaying an animation.
+     *
+     * The iterator provides the frames that should be displayed at a
+     * given time.
+     *
+     * `start_time` would normally come from g_get_current_time(), and marks
+     * the beginning of animation playback. After creating an iterator, you
+     * should immediately display the pixbuf returned by
+     * gdk_pixbuf_animation_iter_get_pixbuf(). Then, you should install
+     * a timeout (with g_timeout_add()) or by some other mechanism ensure
+     * that you'll update the image after
+     * gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time
+     * the image is updated, you should reinstall the timeout with the new,
+     * possibly-changed delay time.
+     *
+     * As a shortcut, if `start_time` is `NULL`, the result of
+     * g_get_current_time() will be used automatically.
+     *
+     * To update the image (i.e. possibly change the result of
+     * gdk_pixbuf_animation_iter_get_pixbuf() to a new frame of the animation),
+     * call gdk_pixbuf_animation_iter_advance().
+     *
+     * If you're using #GdkPixbufLoader, in addition to updating the image
+     * after the delay time, you should also update it whenever you
+     * receive the area_updated signal and
+     * gdk_pixbuf_animation_iter_on_currently_loading_frame() returns
+     * `TRUE`. In this case, the frame currently being fed into the loader
+     * has received new data, so needs to be refreshed. The delay time for
+     * a frame may also be modified after an area_updated signal, for
+     * example if the delay time for a frame is encoded in the data after
+     * the frame itself. So your timeout should be reinstalled after any
+     * area_updated signal.
+     *
+     * A delay time of -1 is possible, indicating "infinite".
+     * @param startTime - time when the animation starts playing
+     */
     getIter(startTime) {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_get_iter", [
             {
@@ -93,6 +190,19 @@ export class PixbufAnimation extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, PixbufAnimationIter);
     }
+    /**
+     * Retrieves a static image for the animation.
+     *
+     * If an animation is really just a plain image (has only one frame),
+     * this function returns that image.
+     *
+     * If the animation is an animation, this function returns a reasonable
+     * image to use as a static unanimated image, which might be the first
+     * frame, or something more sophisticated depending on the file format.
+     *
+     * If an animation hasn't loaded any frames yet, this function will
+     * return `NULL`.
+     */
     getStaticImage() {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_get_static_image", [
             {
@@ -102,6 +212,9 @@ export class PixbufAnimation extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Pixbuf);
     }
+    /**
+     * Queries the width of the bounding box of a pixbuf animation.
+     */
     getWidth() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_get_width", [
             {
@@ -110,6 +223,14 @@ export class PixbufAnimation extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Checks whether the animation is a static image.
+     *
+     * If you load a file with gdk_pixbuf_animation_new_from_file() and it
+     * turns out to be a plain, unanimated image, then this function will
+     * return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve
+     * the image.
+     */
     isStaticImage() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_animation_is_static_image", [
             {

package/dist/generated/gdkpixbuf/pixbuf-format.d.ts

@@ -2,31 +2,111 @@ export interface PixbufFormatInit {
     flags?: number;
     disabled?: boolean;
 }
+/**
+ * A `GdkPixbufFormat` contains information about the image format accepted
+ * by a module.
+ *
+ * Only modules should access the fields directly, applications should
+ * use the `gdk_pixbuf_format_*` family of functions.
+ */
 export declare class PixbufFormat {
     ptr: unknown;
     constructor(init?: PixbufFormatInit);
     protected createPtr(init: PixbufFormatInit): unknown;
+    /**
+     * Creates a copy of `format`.
+     */
     copy(): PixbufFormat | null;
+    /**
+     * Frees the resources allocated when copying a `GdkPixbufFormat`
+     * using gdk_pixbuf_format_copy()
+     */
     free(): void;
+    /**
+     * Returns a description of the format.
+     */
     getDescription(): string | null;
+    /**
+     * Returns the filename extensions typically used for files in the
+     * given format.
+     */
     getExtensions(): string[] | null;
+    /**
+     * Returns information about the license of the image loader for the format.
+     *
+     * The returned string should be a shorthand for a well known license, e.g.
+     * "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license.
+     */
     getLicense(): string | null;
+    /**
+     * Returns the mime types supported by the format.
+     */
     getMimeTypes(): string[] | null;
+    /**
+     * Returns the name of the format.
+     */
     getName(): string | null;
+    /**
+     * Returns whether this image format is disabled.
+     *
+     * See gdk_pixbuf_format_set_disabled().
+     */
     isDisabled(): boolean;
+    /**
+     * Returns `TRUE` if the save option specified by `option_key` is supported when
+     * saving a pixbuf using the module implementing @format.
+     *
+     * See gdk_pixbuf_save() for more information about option keys.
+     * @param optionKey - the name of an option
+     */
     isSaveOptionSupported(optionKey: string): boolean;
+    /**
+     * Returns whether this image format is scalable.
+     *
+     * If a file is in a scalable format, it is preferable to load it at
+     * the desired size, rather than loading it at the default size and
+     * scaling the resulting pixbuf to the desired size.
+     */
     isScalable(): boolean;
+    /**
+     * Returns whether pixbufs can be saved in the given format.
+     */
     isWritable(): boolean;
+    /**
+     * Disables or enables an image format.
+     *
+     * If a format is disabled, GdkPixbuf won't use the image loader for
+     * this format to load images.
+     *
+     * Applications can use this to avoid using image loaders with an
+     * inappropriate license, see gdk_pixbuf_format_get_license().
+     * @param disabled - `TRUE` to disable the format @format
+     */
     setDisabled(disabled: boolean): void;
+    /** the name of the image format */
     get name(): string;
+    /** the signature of the module */
     get signature(): number;
+    /** the message domain for the `description` */
     get domain(): string;
+    /** a description of the image format */
     get description(): string;
+    /** the MIME types for the image format */
     get mimeTypes(): string[];
+    /**
+     * typical filename extensions for the
+     * image format
+     */
     get extensions(): string[];
+    /** a combination of `GdkPixbufFormatFlags` */
     get flags(): number;
     set flags(value: number);
+    /** a boolean determining whether the loader is disabled` */
     get disabled(): boolean;
     set disabled(value: boolean);
+    /**
+     * a string containing license information, typically set to
+     * shorthands like "GPL", "LGPL", etc.
+     */
     get license(): string;
 }

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

@@ -1,5 +1,12 @@
 import { alloc, call, read, write } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * A `GdkPixbufFormat` contains information about the image format accepted
+ * by a module.
+ *
+ * Only modules should access the fields directly, applications should
+ * use the `gdk_pixbuf_format_*` family of functions.
+ */
 export class PixbufFormat {
     ptr;
     constructor(init = {}) {
@@ -13,6 +20,9 @@ export class PixbufFormat {
             write(ptr, { type: "boolean" }, 52, init.disabled);
         return ptr;
     }
+    /**
+     * Creates a copy of `format`.
+     */
     copy() {
         const ptr = call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_copy", [
             {
@@ -29,6 +39,10 @@ export class PixbufFormat {
             return null;
         return getObject(ptr, PixbufFormat);
     }
+    /**
+     * Frees the resources allocated when copying a `GdkPixbufFormat`
+     * using gdk_pixbuf_format_copy()
+     */
     free() {
         call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_free", [
             {
@@ -37,6 +51,9 @@ export class PixbufFormat {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns a description of the format.
+     */
     getDescription() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_get_description", [
             {
@@ -45,6 +62,10 @@ export class PixbufFormat {
             },
         ], { type: "string" });
     }
+    /**
+     * Returns the filename extensions typically used for files in the
+     * given format.
+     */
     getExtensions() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_get_extensions", [
             {
@@ -53,6 +74,12 @@ export class PixbufFormat {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Returns information about the license of the image loader for the format.
+     *
+     * The returned string should be a shorthand for a well known license, e.g.
+     * "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license.
+     */
     getLicense() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_get_license", [
             {
@@ -61,6 +88,9 @@ export class PixbufFormat {
             },
         ], { type: "string" });
     }
+    /**
+     * Returns the mime types supported by the format.
+     */
     getMimeTypes() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_get_mime_types", [
             {
@@ -69,6 +99,9 @@ export class PixbufFormat {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Returns the name of the format.
+     */
     getName() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_get_name", [
             {
@@ -77,6 +110,11 @@ export class PixbufFormat {
             },
         ], { type: "string" });
     }
+    /**
+     * Returns whether this image format is disabled.
+     *
+     * See gdk_pixbuf_format_set_disabled().
+     */
     isDisabled() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_is_disabled", [
             {
@@ -85,6 +123,13 @@ export class PixbufFormat {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns `TRUE` if the save option specified by `option_key` is supported when
+     * saving a pixbuf using the module implementing @format.
+     *
+     * See gdk_pixbuf_save() for more information about option keys.
+     * @param optionKey - the name of an option
+     */
     isSaveOptionSupported(optionKey) {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_is_save_option_supported", [
             {
@@ -97,6 +142,13 @@ export class PixbufFormat {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether this image format is scalable.
+     *
+     * If a file is in a scalable format, it is preferable to load it at
+     * the desired size, rather than loading it at the default size and
+     * scaling the resulting pixbuf to the desired size.
+     */
     isScalable() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_is_scalable", [
             {
@@ -105,6 +157,9 @@ export class PixbufFormat {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether pixbufs can be saved in the given format.
+     */
     isWritable() {
         return call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_is_writable", [
             {
@@ -113,6 +168,16 @@ export class PixbufFormat {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Disables or enables an image format.
+     *
+     * If a format is disabled, GdkPixbuf won't use the image loader for
+     * this format to load images.
+     *
+     * Applications can use this to avoid using image loaders with an
+     * inappropriate license, see gdk_pixbuf_format_get_license().
+     * @param disabled - `TRUE` to disable the format @format
+     */
     setDisabled(disabled) {
         call("libgdk_pixbuf-2.0.so.0", "gdk_pixbuf_format_set_disabled", [
             {
@@ -125,36 +190,51 @@ export class PixbufFormat {
             },
         ], { type: "undefined" });
     }
+    /** the name of the image format */
     get name() {
         return read(this.ptr, { type: "string" }, 0);
     }
+    /** the signature of the module */
     get signature() {
         return read(this.ptr, { type: "int", size: 64, unsigned: true }, 8);
     }
+    /** the message domain for the `description` */
     get domain() {
         return read(this.ptr, { type: "string" }, 16);
     }
+    /** a description of the image format */
     get description() {
         return read(this.ptr, { type: "string" }, 24);
     }
+    /** the MIME types for the image format */
     get mimeTypes() {
         return read(this.ptr, { type: "array", itemType: { type: "string" } }, 32);
     }
+    /**
+     * typical filename extensions for the
+     * image format
+     */
     get extensions() {
         return read(this.ptr, { type: "array", itemType: { type: "string" } }, 40);
     }
+    /** a combination of `GdkPixbufFormatFlags` */
     get flags() {
         return read(this.ptr, { type: "int", size: 32, unsigned: true }, 48);
     }
     set flags(value) {
         write(this.ptr, { type: "int", size: 32, unsigned: true }, 48, value);
     }
+    /** a boolean determining whether the loader is disabled` */
     get disabled() {
         return read(this.ptr, { type: "boolean" }, 52);
     }
     set disabled(value) {
         write(this.ptr, { type: "boolean" }, 52, value);
     }
+    /**
+     * a string containing license information, typically set to
+     * shorthands like "GPL", "LGPL", etc.
+     */
     get license() {
         return read(this.ptr, { type: "string" }, 56);
     }

package/dist/generated/gdkpixbuf/pixbuf-loader.d.ts

@@ -4,16 +4,123 @@ import { PixbufAnimation } from "./pixbuf-animation.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 export declare class PixbufLoader extends GObject.GObject {
+    /**
+     * Creates a new pixbuf loader object.
+     */
     constructor(...args: unknown[]);
+    /**
+     * 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: string): 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: string): PixbufLoader;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): PixbufAnimation | null;
+    /**
+     * Obtains the available information about the format of the
+     * currently loading image file.
+     */
     getFormat(): PixbufFormat | null;
+    /**
+     * 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(): Pixbuf | null;
+    /**
+     * 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: number, height: number): void;
+    /**
+     * 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: number[], count: number): boolean;
+    /**
+     * Parses the next contents of the given image buffer.
+     * @param buffer - The image data as a `GBytes` buffer.
+     */
     writeBytes(buffer: GLib.Bytes): boolean;
     connect(signal: "area-prepared", handler: (self: PixbufLoader) => void, after?: boolean): number;
     connect(signal: "area-updated", handler: (self: PixbufLoader, x: number, y: number, width: number, height: number) => void, after?: boolean): number;