@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/file-enumerator.js

@@ -3,6 +3,34 @@ import { NativeError, getObject } from "@gtkx/ffi";
 import { File } from "./file.js";
 import { FileInfo } from "./file-info.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GFileEnumerator` allows you to operate on a set of [iface@Gio.File] objects,
+ * returning a [class@Gio.FileInfo] structure for each file enumerated (e.g.
+ * [method@Gio.File.enumerate_children] will return a `GFileEnumerator` for each
+ * of the children within a directory).
+ *
+ * To get the next file's information from a `GFileEnumerator`, use
+ * [method@Gio.FileEnumerator.next_file] or its asynchronous version,
+ * [method@Gio.FileEnumerator.next_files_async]. Note that the asynchronous
+ * version will return a list of [class@Gio.FileInfo] objects, whereas the
+ * synchronous will only return the next file in the enumerator.
+ *
+ * The ordering of returned files is unspecified for non-Unix
+ * platforms; for more information, see [method@GLib.Dir.read_name].  On Unix,
+ * when operating on local files, returned files will be sorted by
+ * inode number.  Effectively you can assume that the ordering of
+ * returned files will be stable between successive calls (and
+ * applications) assuming the directory is unchanged.
+ *
+ * If your application needs a specific ordering, such as by name or
+ * modification time, you will have to implement that in your
+ * application code.
+ *
+ * To close a `GFileEnumerator`, use [method@Gio.FileEnumerator.close], or
+ * its asynchronous version, [method@Gio.FileEnumerator.close_async]. Once
+ * a `GFileEnumerator` is closed, no further actions may be performed
+ * on it, and it should be freed with [method@GObject.Object.unref].
+ */
 export class FileEnumerator extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -18,6 +46,15 @@ export class FileEnumerator extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Releases all resources used by this enumerator, making the
+     * enumerator return %G_IO_ERROR_CLOSED on all calls.
+     *
+     * This will be automatically called when the last reference
+     * is dropped, but you might want to call this function to make
+     * sure resources are released as early as possible.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     close(cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_file_enumerator_close", [
@@ -47,6 +84,18 @@ export class FileEnumerator extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Asynchronously closes the file enumerator.
+     *
+     * If `cancellable` is not %NULL, then the operation can be cancelled by
+     * triggering the cancellable object from another thread. If the operation
+     * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in
+     * g_file_enumerator_close_finish().
+     * @param ioPriority - the I/O priority of the request
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     closeAsync(ioPriority, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_file_enumerator_close_async", [
             {
@@ -74,6 +123,19 @@ export class FileEnumerator extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
+     *
+     * If the file enumerator was already closed when g_file_enumerator_close_async()
+     * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and
+     * return %FALSE. If the file enumerator had pending operation when the close
+     * operation was started, then this function will report %G_IO_ERROR_PENDING, and
+     * return %FALSE.  If `cancellable` was not %NULL, then the operation may have been
+     * cancelled by triggering the cancellable object from another thread. If the operation
+     * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be
+     * returned.
+     * @param result - a #GAsyncResult.
+     */
     closeFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_file_enumerator_close_finish", [
@@ -102,6 +164,22 @@ export class FileEnumerator extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Return a new #GFile which refers to the file named by `info` in the source
+     * directory of @enumerator.  This function is primarily intended to be used
+     * inside loops with g_file_enumerator_next_file().
+     *
+     * To use this, %G_FILE_ATTRIBUTE_STANDARD_NAME must have been listed in the
+     * attributes list used when creating the #GFileEnumerator.
+     *
+     * This is a convenience method that's equivalent to:
+     * |[<!-- language="C" -->
+     * gchar *name = g_file_info_get_name (info);
+     * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
+     * name);
+     * ]|
+     * @param info - a #GFileInfo gotten from g_file_enumerator_next_file()
+     */
     getChild(info) {
         const ptr = call("libgio-2.0.so.0", "g_file_enumerator_get_child", [
             {
@@ -115,6 +193,9 @@ export class FileEnumerator extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, File);
     }
+    /**
+     * Get the #GFile container which is being enumerated.
+     */
     getContainer() {
         const ptr = call("libgio-2.0.so.0", "g_file_enumerator_get_container", [
             {
@@ -124,6 +205,9 @@ export class FileEnumerator extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, File);
     }
+    /**
+     * Checks if the file enumerator has pending operations.
+     */
     hasPending() {
         return call("libgio-2.0.so.0", "g_file_enumerator_has_pending", [
             {
@@ -132,6 +216,9 @@ export class FileEnumerator extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if the file enumerator has been closed.
+     */
     isClosed() {
         return call("libgio-2.0.so.0", "g_file_enumerator_is_closed", [
             {
@@ -140,6 +227,48 @@ export class FileEnumerator extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * This is a version of g_file_enumerator_next_file() that's easier to
+     * use correctly from C programs.  With g_file_enumerator_next_file(),
+     * the gboolean return value signifies "end of iteration or error", which
+     * requires allocation of a temporary #GError.
+     *
+     * In contrast, with this function, a %FALSE return from
+     * g_file_enumerator_iterate() *always* means
+     * "error".  End of iteration is signaled by `out_info` or `out_child` being %NULL.
+     *
+     * Another crucial difference is that the references for `out_info` and
+     * `out_child` are owned by `direnum` (they are cached as hidden
+     * properties).  You must not unref them in your own code.  This makes
+     * memory management significantly easier for C code in combination
+     * with loops.
+     *
+     * Finally, this function optionally allows retrieving a #GFile as
+     * well.
+     *
+     * You must specify at least one of `out_info` or @out_child.
+     *
+     * The code pattern for correctly using g_file_enumerator_iterate() from C
+     * is:
+     *
+     * |[
+     * direnum = g_file_enumerate_children (file, ...);
+     * while (TRUE)
+     * {
+     * GFileInfo *info;
+     * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
+     * goto out;
+     * if (!info)
+     * break;
+     * ... do stuff with "info"; do not unref it! ...
+     * }
+     *
+     * out:
+     * g_object_unref (direnum); // Note: frees the last `info` ]|
+     * @param outInfo - Output location for the next #GFileInfo, or %NULL
+     * @param outChild - Output location for the next #GFile, or %NULL
+     * @param cancellable - a #GCancellable
+     */
     iterate(outInfo, outChild, cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_file_enumerator_iterate", [
@@ -179,6 +308,20 @@ export class FileEnumerator extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Returns information for the next file in the enumerated object.
+     * Will block until the information is available. The #GFileInfo
+     * returned from this function will contain attributes that match the
+     * attribute string that was passed when the #GFileEnumerator was created.
+     *
+     * See the documentation of #GFileEnumerator for information about the
+     * order of returned files.
+     *
+     * On error, returns %NULL and sets `error` to the error. If the
+     * enumerator is at the end, %NULL will be returned and `error` will
+     * be unset.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     nextFile(cancellable) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_file_enumerator_next_file", [
@@ -210,6 +353,77 @@ export class FileEnumerator extends GObject.GObject {
             return null;
         return getObject(ptr, FileInfo);
     }
+    /**
+     * Request information for a number of files from the enumerator asynchronously.
+     * When all I/O for the operation is finished the `callback` will be called with
+     * the requested information.
+     *
+     * See the documentation of #GFileEnumerator for information about the
+     * order of returned files.
+     *
+     * Once the end of the enumerator is reached, or if an error occurs, the
+     * `callback` will be called with an empty list. In this case, the previous call
+     * to g_file_enumerator_next_files_async() will typically have returned fewer
+     * than `num_files` items.
+     *
+     * If a request is cancelled the callback will be called with
+     * %G_IO_ERROR_CANCELLED.
+     *
+     * This leads to the following pseudo-code usage:
+     * |[
+     * g_autoptr(GFile) dir = get_directory ();
+     * g_autoptr(GFileEnumerator) enumerator = NULL;
+     * g_autolist(GFileInfo) files = NULL;
+     * g_autoptr(GError) local_error = NULL;
+     *
+     * enumerator = yield g_file_enumerate_children_async (dir,
+     * G_FILE_ATTRIBUTE_STANDARD_NAME ","
+     * G_FILE_ATTRIBUTE_STANDARD_TYPE,
+     * G_FILE_QUERY_INFO_NONE,
+     * G_PRIORITY_DEFAULT,
+     * cancellable,
+     * …,
+     * &local_error);
+     * if (enumerator == NULL)
+     * g_error ("Error enumerating: %s", local_error->message);
+     *
+     * // Loop until no files are returned, either because the end of the enumerator
+     * // has been reached, or an error was returned.
+     * do
+     * {
+     * files = yield g_file_enumerator_next_files_async (enumerator,
+     * 5,  // number of files to request
+     * G_PRIORITY_DEFAULT,
+     * cancellable,
+     * …,
+     * &local_error);
+     *
+     * // Process the returned files, but don’t assume that exactly 5 were returned.
+     * for (GList *l = files; l != NULL; l = l->next)
+     * {
+     * GFileInfo *info = l->data;
+     * handle_file_info (info);
+     * }
+     * }
+     * while (files != NULL);
+     *
+     * if (local_error != NULL &&
+     * !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
+     * g_error ("Error while enumerating: %s", local_error->message);
+     * ]|
+     *
+     * During an async request no other sync and async calls are allowed, and will
+     * result in %G_IO_ERROR_PENDING errors.
+     *
+     * Any outstanding I/O request with higher priority (lower numerical value) will
+     * be executed before an outstanding request with lower priority. Default
+     * priority is %G_PRIORITY_DEFAULT.
+     * @param numFiles - the number of file info objects to request
+     * @param ioPriority - the I/O priority of the request
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     nextFilesAsync(numFiles, ioPriority, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_file_enumerator_next_files_async", [
             {
@@ -241,6 +455,10 @@ export class FileEnumerator extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
+     * @param result - a #GAsyncResult.
+     */
     nextFilesFinish(result) {
         const error = { value: null };
         const ptrs = call("libgio-2.0.so.0", "g_file_enumerator_next_files_finish", [
@@ -274,6 +492,10 @@ export class FileEnumerator extends GObject.GObject {
         }
         return ptrs.map((ptr) => getObject(ptr, FileInfo));
     }
+    /**
+     * Sets the file enumerator as having pending operations.
+     * @param pending - a boolean value.
+     */
     setPending(pending) {
         call("libgio-2.0.so.0", "g_file_enumerator_set_pending", [
             {

package/dist/generated/gio/file-icon.d.ts

@@ -6,17 +6,83 @@ import { Icon } from "./icon.js";
 import { InputStream } from "./input-stream.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GFileIcon` specifies an icon by pointing to an image file
+ * to be used as icon.
+ *
+ * It implements [iface@Gio.LoadableIcon].
+ */
 export declare class FileIcon extends GObject.GObject {
+    /**
+     * Creates a new icon for a file.
+     * @param file - a #GFile.
+     */
     constructor(file: File);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the #GFile associated with the given @icon.
+     */
     getFile(): File;
+    /**
+     * Checks if two icons are equal.
+     * @param icon2 - pointer to the second #GIcon.
+     */
     equal(icon2?: Icon | null): boolean;
+    /**
+     * Gets a hash for an icon.
+     */
     hash(): number;
+    /**
+     * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
+     * back by calling g_icon_deserialize() on the returned value.
+     * As serialization will avoid using raw icon data when possible, it only
+     * makes sense to transfer the #GVariant between processes on the same machine,
+     * (as opposed to over the network), and within the same file system namespace.
+     */
     serialize(): GLib.Variant | null;
+    /**
+     * Generates a textual representation of `icon` that can be used for
+     * serialization such as when passing `icon` to a different process or
+     * saving it to persistent storage. Use g_icon_new_for_string() to
+     * get `icon` back from the returned string.
+     *
+     * The encoding of the returned string is proprietary to #GIcon except
+     * in the following two cases
+     *
+     * - If `icon` is a #GFileIcon, the returned string is a native path
+     * (such as `/path/to/my icon.png`) without escaping
+     * if the #GFile for `icon` is a native file.  If the file is not
+     * native, the returned string is the result of g_file_get_uri()
+     * (such as `sftp://path/to/my%20icon.png`).
+     *
+     * - If `icon` is a #GThemedIcon with exactly one name and no fallbacks,
+     * the encoding is simply the name (such as `network-server`).
+     */
     toString(): string | null;
+    /**
+     * Loads a loadable icon. For the asynchronous version of this function,
+     * see g_loadable_icon_load_async().
+     * @param size - an integer.
+     * @param type - a location to store the type of the loaded
+     * @param cancellable - optional #GCancellable object, %NULL to
+     */
     load(size: number, type?: Ref<string> | null, cancellable?: Cancellable | null): InputStream;
+    /**
+     * Loads an icon asynchronously. To finish this function, see
+     * g_loadable_icon_load_finish(). For the synchronous, blocking
+     * version of this function, see g_loadable_icon_load().
+     * @param size - an integer.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     loadAsync(size: number, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
+     * @param res - a #GAsyncResult.
+     * @param type - a location to store the type of the loaded
+     */
     loadFinish(res: AsyncResult, type?: Ref<string> | null): InputStream;
     connect(signal: "notify", handler: (self: FileIcon, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/file-icon.js

@@ -4,6 +4,12 @@ import { File } from "./file.js";
 import { InputStream } from "./input-stream.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GFileIcon` specifies an icon by pointing to an image file
+ * to be used as icon.
+ *
+ * It implements [iface@Gio.LoadableIcon].
+ */
 export class FileIcon extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -17,6 +23,9 @@ export class FileIcon extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the #GFile associated with the given @icon.
+     */
     getFile() {
         const ptr = call("libgio-2.0.so.0", "g_file_icon_get_file", [
             {
@@ -26,6 +35,10 @@ export class FileIcon extends GObject.GObject {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, File);
     }
+    /**
+     * Checks if two icons are equal.
+     * @param icon2 - pointer to the second #GIcon.
+     */
     equal(icon2) {
         return call("libgio-2.0.so.0", "g_icon_equal", [
             {
@@ -39,6 +52,9 @@ export class FileIcon extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets a hash for an icon.
+     */
     hash() {
         return call("libgio-2.0.so.0", "g_icon_hash", [
             {
@@ -47,6 +63,13 @@ export class FileIcon extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
+     * back by calling g_icon_deserialize() on the returned value.
+     * As serialization will avoid using raw icon data when possible, it only
+     * makes sense to transfer the #GVariant between processes on the same machine,
+     * (as opposed to over the network), and within the same file system namespace.
+     */
     serialize() {
         const ptr = call("libgio-2.0.so.0", "g_icon_serialize", [
             {
@@ -63,6 +86,24 @@ export class FileIcon extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.Variant);
     }
+    /**
+     * Generates a textual representation of `icon` that can be used for
+     * serialization such as when passing `icon` to a different process or
+     * saving it to persistent storage. Use g_icon_new_for_string() to
+     * get `icon` back from the returned string.
+     *
+     * The encoding of the returned string is proprietary to #GIcon except
+     * in the following two cases
+     *
+     * - If `icon` is a #GFileIcon, the returned string is a native path
+     * (such as `/path/to/my icon.png`) without escaping
+     * if the #GFile for `icon` is a native file.  If the file is not
+     * native, the returned string is the result of g_file_get_uri()
+     * (such as `sftp://path/to/my%20icon.png`).
+     *
+     * - If `icon` is a #GThemedIcon with exactly one name and no fallbacks,
+     * the encoding is simply the name (such as `network-server`).
+     */
     toString() {
         return call("libgio-2.0.so.0", "g_icon_to_string", [
             {
@@ -71,6 +112,13 @@ export class FileIcon extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Loads a loadable icon. For the asynchronous version of this function,
+     * see g_loadable_icon_load_async().
+     * @param size - an integer.
+     * @param type - a location to store the type of the loaded
+     * @param cancellable - optional #GCancellable object, %NULL to
+     */
     load(size, type, cancellable) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_loadable_icon_load", [
@@ -109,6 +157,15 @@ export class FileIcon extends GObject.GObject {
         }
         return getObject(ptr, InputStream);
     }
+    /**
+     * Loads an icon asynchronously. To finish this function, see
+     * g_loadable_icon_load_finish(). For the synchronous, blocking
+     * version of this function, see g_loadable_icon_load().
+     * @param size - an integer.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     * @param callback - a #GAsyncReadyCallback
+     * @param userData - the data to pass to callback function
+     */
     loadAsync(size, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_loadable_icon_load_async", [
             {
@@ -136,6 +193,11 @@ export class FileIcon extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
+     * @param res - a #GAsyncResult.
+     * @param type - a location to store the type of the loaded
+     */
     loadFinish(res, type) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_loadable_icon_load_finish", [