@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/app-info.d.ts

@@ -3,33 +3,254 @@ import { AsyncResult } from "./async-result.js";
 import { Cancellable } from "./cancellable.js";
 import { File } from "./file.js";
 import { Icon } from "./icon.js";
+/**
+ * Information about an installed application and methods to launch
+ * it (with file arguments).
+ *
+ * `GAppInfo` and `GAppLaunchContext` are used for describing and launching
+ * applications installed on the system.
+ *
+ * As of GLib 2.20, URIs will always be converted to POSIX paths
+ * (using [method@Gio.File.get_path]) when using [method@Gio.AppInfo.launch]
+ * even if the application requested an URI and not a POSIX path. For example
+ * for a desktop-file based application with the following Exec key:
+ *
+ * ```
+ * Exec=totem %U
+ * ```
+ *
+ * and a single URI, `sftp://foo/file.avi`, then
+ * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will only work
+ * if a set of suitable GIO extensions (such as GVfs 2.26 compiled with FUSE
+ * support), is available and operational; if this is not the case, the URI
+ * will be passed unmodified to the application. Some URIs, such as `mailto:`,
+ * of course cannot be mapped to a POSIX path (in GVfs there’s no FUSE mount
+ * for it); such URIs will be passed unmodified to the application.
+ *
+ * Specifically for GVfs 2.26 and later, the POSIX URI will be mapped
+ * back to the GIO URI in the [iface@Gio.File] constructors (since GVfs
+ * implements the GVfs extension point). As such, if the application
+ * needs to examine the URI, it needs to use [method@Gio.File.get_uri]
+ * or similar on [iface@Gio.File]. In other words, an application cannot
+ * assume that the URI passed to e.g. [func@Gio.File.new_for_commandline_arg]
+ * is equal to the result of [method@Gio.File.get_uri]. The following snippet
+ * illustrates this:
+ *
+ * ```c
+ * GFile *f;
+ * char *uri;
+ *
+ * file = g_file_new_for_commandline_arg (uri_from_commandline);
+ *
+ * uri = g_file_get_uri (file);
+ * strcmp (uri, uri_from_commandline) == 0;
+ * g_free (uri);
+ *
+ * if (g_file_has_uri_scheme (file, "cdda"))
+ * {
+ * // do something special with uri
+ * }
+ * g_object_unref (file);
+ * ```
+ *
+ * This code will work when both `cdda://sr0/Track 1.wav` and
+ * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
+ * application. It should be noted that it’s generally not safe
+ * for applications to rely on the format of a particular URIs.
+ * Different launcher applications (e.g. file managers) may have
+ * different ideas of what a given URI means.
+ */
 export declare class AppInfo {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): AppInfo;
+    /**
+     * Adds a content type to the application information to indicate the
+     * application is capable of opening files with the given content type.
+     * @param contentType - a string.
+     */
     addSupportsType(contentType: string): boolean;
+    /**
+     * Obtains the information whether the [iface@Gio.AppInfo] can be deleted.
+     * See [method@Gio.AppInfo.delete].
+     */
     canDelete(): boolean;
+    /**
+     * Checks if a supported content type can be removed from an application.
+     */
     canRemoveSupportsType(): boolean;
+    /**
+     * Tries to delete a [iface@Gio.AppInfo].
+     *
+     * On some platforms, there may be a difference between user-defined
+     * [iface@Gio.AppInfo]s which can be deleted, and system-wide ones which cannot.
+     * See [method@Gio.AppInfo.can_delete].
+     */
     delete(): boolean;
+    /**
+     * Creates a duplicate of a [iface@Gio.AppInfo].
+     */
     dup(): AppInfo;
+    /**
+     * Checks if two [iface@Gio.AppInfo]s are equal.
+     *
+     * Note that the check *may not* compare each individual field, and only does
+     * an identity check. In case detecting changes in the contents is needed,
+     * program code must additionally compare relevant fields.
+     * @param appinfo2 - the second [iface@Gio.AppInfo].
+     */
     equal(appinfo2: AppInfo): boolean;
+    /**
+     * Gets the commandline with which the application will be
+     * started.
+     */
     getCommandline(): string | null;
+    /**
+     * Gets a human-readable description of an installed application.
+     */
     getDescription(): string | null;
+    /**
+     * Gets the display name of the application. The display name is often more
+     * descriptive to the user than the name itself.
+     */
     getDisplayName(): string;
+    /**
+     * Gets the executable’s name for the installed application.
+     *
+     * This is intended to be used for debugging or labelling what program is going
+     * to be run. To launch the executable, use [method@Gio.AppInfo.launch] and related
+     * functions, rather than spawning the return value from this function.
+     */
     getExecutable(): string;
+    /**
+     * Gets the icon for the application.
+     */
     getIcon(): Icon | null;
+    /**
+     * Gets the ID of an application. An id is a string that identifies the
+     * application. The exact format of the id is platform dependent. For instance,
+     * on Unix this is the desktop file id from the xdg menu specification.
+     *
+     * Note that the returned ID may be `NULL`, depending on how the `appinfo` has
+     * been constructed.
+     */
     getId(): string | null;
+    /**
+     * Gets the installed name of the application.
+     */
     getName(): string;
+    /**
+     * Retrieves the list of content types that `app_info` claims to support.
+     * If this information is not provided by the environment, this function
+     * will return `NULL`.
+     *
+     * This function does not take in consideration associations added with
+     * [method@Gio.AppInfo.add_supports_type], but only those exported directly by
+     * the application.
+     */
     getSupportedTypes(): string[];
+    /**
+     * Launches the application. Passes `files` to the launched application
+     * as arguments, using the optional `context` to get information
+     * about the details of the launcher (like what screen it is on).
+     * On error, `error` will be set accordingly.
+     *
+     * To launch the application without arguments pass a `NULL` `files` list.
+     *
+     * Note that even if the launch is successful the application launched
+     * can fail to start if it runs into problems during startup. There is
+     * no way to detect this.
+     *
+     * Some URIs can be changed when passed through a GFile (for instance
+     * unsupported URIs with strange formats like mailto:), so if you have
+     * a textual URI you want to pass in as argument, consider using
+     * [method@Gio.AppInfo.launch_uris] instead.
+     *
+     * The launched application inherits the environment of the launching
+     * process, but it can be modified with [method@Gio.AppLaunchContext.setenv]
+     * and [method@Gio.AppLaunchContext.unsetenv].
+     *
+     * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
+     * environment variable with the path of the launched desktop file and
+     * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
+     * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
+     * should it be inherited by further processes. The `DISPLAY`,
+     * `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment
+     * variables are also set, based on information provided in @context.
+     * @param files - a list of [iface@Gio.File] objects
+     * @param context - the launch context
+     */
     launch(files?: File[] | null, context?: AppLaunchContext | null): boolean;
+    /**
+     * Launches the application. This passes the `uris` to the launched application
+     * as arguments, using the optional `context` to get information
+     * about the details of the launcher (like what screen it is on).
+     * On error, `error` will be set accordingly. If the application only supports
+     * one URI per invocation as part of their command-line, multiple instances
+     * of the application will be spawned.
+     *
+     * To launch the application without arguments pass a `NULL` `uris` list.
+     *
+     * Note that even if the launch is successful the application launched
+     * can fail to start if it runs into problems during startup. There is
+     * no way to detect this.
+     * @param uris - a list of URIs to launch.
+     * @param context - the launch context
+     */
     launchUris(uris?: string[] | null, context?: AppLaunchContext | null): boolean;
+    /**
+     * Async version of [method@Gio.AppInfo.launch_uris].
+     *
+     * The `callback` is invoked immediately after the application launch, but it
+     * waits for activation in case of D-Bus–activated applications and also provides
+     * extended error information for sandboxed applications, see notes for
+     * [func@Gio.AppInfo.launch_default_for_uri_async].
+     * @param uris - a list of URIs to launch.
+     * @param context - the launch context
+     * @param cancellable - a [class@Gio.Cancellable]
+     * @param callback - a [type@Gio.AsyncReadyCallback] to call
+     * @param userData - data to pass to @callback
+     */
     launchUrisAsync(uris?: string[] | null, context?: AppLaunchContext | null, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finishes a [method@Gio.AppInfo.launch_uris_async] operation.
+     * @param result - the async result
+     */
     launchUrisFinish(result: AsyncResult): boolean;
+    /**
+     * Removes a supported type from an application, if possible.
+     * @param contentType - a string.
+     */
     removeSupportsType(contentType: string): boolean;
+    /**
+     * Sets the application as the default handler for the given file extension.
+     * @param extension - a string containing the file extension (without
+     */
     setAsDefaultForExtension(extension: string): boolean;
+    /**
+     * Sets the application as the default handler for a given type.
+     * @param contentType - the content type.
+     */
     setAsDefaultForType(contentType: string): boolean;
+    /**
+     * Sets the application as the last used application for a given type. This
+     * will make the application appear as first in the list returned by
+     * [func@Gio.AppInfo.get_recommended_for_type], regardless of the default
+     * application for that content type.
+     * @param contentType - the content type.
+     */
     setAsLastUsedForType(contentType: string): boolean;
+    /**
+     * Checks if the application info should be shown in menus that
+     * list available applications.
+     */
     shouldShow(): boolean;
+    /**
+     * Checks if the application accepts files as arguments.
+     */
     supportsFiles(): boolean;
+    /**
+     * Checks if the application supports reading files and directories from URIs.
+     */
     supportsUris(): boolean;
 }

package/dist/generated/gio/app-info.js

@@ -1,6 +1,63 @@
 import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import { Icon } from "./icon.js";
+/**
+ * Information about an installed application and methods to launch
+ * it (with file arguments).
+ *
+ * `GAppInfo` and `GAppLaunchContext` are used for describing and launching
+ * applications installed on the system.
+ *
+ * As of GLib 2.20, URIs will always be converted to POSIX paths
+ * (using [method@Gio.File.get_path]) when using [method@Gio.AppInfo.launch]
+ * even if the application requested an URI and not a POSIX path. For example
+ * for a desktop-file based application with the following Exec key:
+ *
+ * ```
+ * Exec=totem %U
+ * ```
+ *
+ * and a single URI, `sftp://foo/file.avi`, then
+ * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will only work
+ * if a set of suitable GIO extensions (such as GVfs 2.26 compiled with FUSE
+ * support), is available and operational; if this is not the case, the URI
+ * will be passed unmodified to the application. Some URIs, such as `mailto:`,
+ * of course cannot be mapped to a POSIX path (in GVfs there’s no FUSE mount
+ * for it); such URIs will be passed unmodified to the application.
+ *
+ * Specifically for GVfs 2.26 and later, the POSIX URI will be mapped
+ * back to the GIO URI in the [iface@Gio.File] constructors (since GVfs
+ * implements the GVfs extension point). As such, if the application
+ * needs to examine the URI, it needs to use [method@Gio.File.get_uri]
+ * or similar on [iface@Gio.File]. In other words, an application cannot
+ * assume that the URI passed to e.g. [func@Gio.File.new_for_commandline_arg]
+ * is equal to the result of [method@Gio.File.get_uri]. The following snippet
+ * illustrates this:
+ *
+ * ```c
+ * GFile *f;
+ * char *uri;
+ *
+ * file = g_file_new_for_commandline_arg (uri_from_commandline);
+ *
+ * uri = g_file_get_uri (file);
+ * strcmp (uri, uri_from_commandline) == 0;
+ * g_free (uri);
+ *
+ * if (g_file_has_uri_scheme (file, "cdda"))
+ * {
+ * // do something special with uri
+ * }
+ * g_object_unref (file);
+ * ```
+ *
+ * This code will work when both `cdda://sr0/Track 1.wav` and
+ * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
+ * application. It should be noted that it’s generally not safe
+ * for applications to rely on the format of a particular URIs.
+ * Different launcher applications (e.g. file managers) may have
+ * different ideas of what a given URI means.
+ */
 export class AppInfo {
     ptr;
     constructor(ptr) {
@@ -9,6 +66,11 @@ export class AppInfo {
     static fromPtr(ptr) {
         return new AppInfo(ptr);
     }
+    /**
+     * Adds a content type to the application information to indicate the
+     * application is capable of opening files with the given content type.
+     * @param contentType - a string.
+     */
     addSupportsType(contentType) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_app_info_add_supports_type", [
@@ -37,6 +99,10 @@ export class AppInfo {
         }
         return result;
     }
+    /**
+     * Obtains the information whether the [iface@Gio.AppInfo] can be deleted.
+     * See [method@Gio.AppInfo.delete].
+     */
     canDelete() {
         return call("libgio-2.0.so.0", "g_app_info_can_delete", [
             {
@@ -45,6 +111,9 @@ export class AppInfo {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if a supported content type can be removed from an application.
+     */
     canRemoveSupportsType() {
         return call("libgio-2.0.so.0", "g_app_info_can_remove_supports_type", [
             {
@@ -53,6 +122,13 @@ export class AppInfo {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Tries to delete a [iface@Gio.AppInfo].
+     *
+     * On some platforms, there may be a difference between user-defined
+     * [iface@Gio.AppInfo]s which can be deleted, and system-wide ones which cannot.
+     * See [method@Gio.AppInfo.can_delete].
+     */
     delete() {
         return call("libgio-2.0.so.0", "g_app_info_delete", [
             {
@@ -61,6 +137,9 @@ export class AppInfo {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Creates a duplicate of a [iface@Gio.AppInfo].
+     */
     dup() {
         const ptr = call("libgio-2.0.so.0", "g_app_info_dup", [
             {
@@ -70,6 +149,14 @@ export class AppInfo {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, AppInfo);
     }
+    /**
+     * Checks if two [iface@Gio.AppInfo]s are equal.
+     *
+     * Note that the check *may not* compare each individual field, and only does
+     * an identity check. In case detecting changes in the contents is needed,
+     * program code must additionally compare relevant fields.
+     * @param appinfo2 - the second [iface@Gio.AppInfo].
+     */
     equal(appinfo2) {
         return call("libgio-2.0.so.0", "g_app_info_equal", [
             {
@@ -82,6 +169,10 @@ export class AppInfo {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the commandline with which the application will be
+     * started.
+     */
     getCommandline() {
         return call("libgio-2.0.so.0", "g_app_info_get_commandline", [
             {
@@ -90,6 +181,9 @@ export class AppInfo {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets a human-readable description of an installed application.
+     */
     getDescription() {
         return call("libgio-2.0.so.0", "g_app_info_get_description", [
             {
@@ -98,6 +192,10 @@ export class AppInfo {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the display name of the application. The display name is often more
+     * descriptive to the user than the name itself.
+     */
     getDisplayName() {
         return call("libgio-2.0.so.0", "g_app_info_get_display_name", [
             {
@@ -106,6 +204,13 @@ export class AppInfo {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the executable’s name for the installed application.
+     *
+     * This is intended to be used for debugging or labelling what program is going
+     * to be run. To launch the executable, use [method@Gio.AppInfo.launch] and related
+     * functions, rather than spawning the return value from this function.
+     */
     getExecutable() {
         return call("libgio-2.0.so.0", "g_app_info_get_executable", [
             {
@@ -114,6 +219,9 @@ export class AppInfo {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the icon for the application.
+     */
     getIcon() {
         const ptr = call("libgio-2.0.so.0", "g_app_info_get_icon", [
             {
@@ -125,6 +233,14 @@ export class AppInfo {
             return null;
         return getObject(ptr, Icon);
     }
+    /**
+     * Gets the ID of an application. An id is a string that identifies the
+     * application. The exact format of the id is platform dependent. For instance,
+     * on Unix this is the desktop file id from the xdg menu specification.
+     *
+     * Note that the returned ID may be `NULL`, depending on how the `appinfo` has
+     * been constructed.
+     */
     getId() {
         return call("libgio-2.0.so.0", "g_app_info_get_id", [
             {
@@ -133,6 +249,9 @@ export class AppInfo {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets the installed name of the application.
+     */
     getName() {
         return call("libgio-2.0.so.0", "g_app_info_get_name", [
             {
@@ -141,6 +260,15 @@ export class AppInfo {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Retrieves the list of content types that `app_info` claims to support.
+     * If this information is not provided by the environment, this function
+     * will return `NULL`.
+     *
+     * This function does not take in consideration associations added with
+     * [method@Gio.AppInfo.add_supports_type], but only those exported directly by
+     * the application.
+     */
     getSupportedTypes() {
         return call("libgio-2.0.so.0", "g_app_info_get_supported_types", [
             {
@@ -149,6 +277,37 @@ export class AppInfo {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Launches the application. Passes `files` to the launched application
+     * as arguments, using the optional `context` to get information
+     * about the details of the launcher (like what screen it is on).
+     * On error, `error` will be set accordingly.
+     *
+     * To launch the application without arguments pass a `NULL` `files` list.
+     *
+     * Note that even if the launch is successful the application launched
+     * can fail to start if it runs into problems during startup. There is
+     * no way to detect this.
+     *
+     * Some URIs can be changed when passed through a GFile (for instance
+     * unsupported URIs with strange formats like mailto:), so if you have
+     * a textual URI you want to pass in as argument, consider using
+     * [method@Gio.AppInfo.launch_uris] instead.
+     *
+     * The launched application inherits the environment of the launching
+     * process, but it can be modified with [method@Gio.AppLaunchContext.setenv]
+     * and [method@Gio.AppLaunchContext.unsetenv].
+     *
+     * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
+     * environment variable with the path of the launched desktop file and
+     * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
+     * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
+     * should it be inherited by further processes. The `DISPLAY`,
+     * `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment
+     * variables are also set, based on information provided in @context.
+     * @param files - a list of [iface@Gio.File] objects
+     * @param context - the launch context
+     */
     launch(files, context) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_app_info_launch", [
@@ -187,6 +346,22 @@ export class AppInfo {
         }
         return result;
     }
+    /**
+     * Launches the application. This passes the `uris` to the launched application
+     * as arguments, using the optional `context` to get information
+     * about the details of the launcher (like what screen it is on).
+     * On error, `error` will be set accordingly. If the application only supports
+     * one URI per invocation as part of their command-line, multiple instances
+     * of the application will be spawned.
+     *
+     * To launch the application without arguments pass a `NULL` `uris` list.
+     *
+     * Note that even if the launch is successful the application launched
+     * can fail to start if it runs into problems during startup. There is
+     * no way to detect this.
+     * @param uris - a list of URIs to launch.
+     * @param context - the launch context
+     */
     launchUris(uris, context) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_app_info_launch_uris", [
@@ -225,6 +400,19 @@ export class AppInfo {
         }
         return result;
     }
+    /**
+     * Async version of [method@Gio.AppInfo.launch_uris].
+     *
+     * The `callback` is invoked immediately after the application launch, but it
+     * waits for activation in case of D-Bus–activated applications and also provides
+     * extended error information for sandboxed applications, see notes for
+     * [func@Gio.AppInfo.launch_default_for_uri_async].
+     * @param uris - a list of URIs to launch.
+     * @param context - the launch context
+     * @param cancellable - a [class@Gio.Cancellable]
+     * @param callback - a [type@Gio.AsyncReadyCallback] to call
+     * @param userData - data to pass to @callback
+     */
     launchUrisAsync(uris, context, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_app_info_launch_uris_async", [
             {
@@ -262,6 +450,10 @@ export class AppInfo {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finishes a [method@Gio.AppInfo.launch_uris_async] operation.
+     * @param result - the async result
+     */
     launchUrisFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_app_info_launch_uris_finish", [
@@ -290,6 +482,10 @@ export class AppInfo {
         }
         return _result;
     }
+    /**
+     * Removes a supported type from an application, if possible.
+     * @param contentType - a string.
+     */
     removeSupportsType(contentType) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_app_info_remove_supports_type", [
@@ -318,6 +514,10 @@ export class AppInfo {
         }
         return result;
     }
+    /**
+     * Sets the application as the default handler for the given file extension.
+     * @param extension - a string containing the file extension (without
+     */
     setAsDefaultForExtension(extension) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_app_info_set_as_default_for_extension", [
@@ -346,6 +546,10 @@ export class AppInfo {
         }
         return result;
     }
+    /**
+     * Sets the application as the default handler for a given type.
+     * @param contentType - the content type.
+     */
     setAsDefaultForType(contentType) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_app_info_set_as_default_for_type", [
@@ -374,6 +578,13 @@ export class AppInfo {
         }
         return result;
     }
+    /**
+     * Sets the application as the last used application for a given type. This
+     * will make the application appear as first in the list returned by
+     * [func@Gio.AppInfo.get_recommended_for_type], regardless of the default
+     * application for that content type.
+     * @param contentType - the content type.
+     */
     setAsLastUsedForType(contentType) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_app_info_set_as_last_used_for_type", [
@@ -402,6 +613,10 @@ export class AppInfo {
         }
         return result;
     }
+    /**
+     * Checks if the application info should be shown in menus that
+     * list available applications.
+     */
     shouldShow() {
         return call("libgio-2.0.so.0", "g_app_info_should_show", [
             {
@@ -410,6 +625,9 @@ export class AppInfo {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if the application accepts files as arguments.
+     */
     supportsFiles() {
         return call("libgio-2.0.so.0", "g_app_info_supports_files", [
             {
@@ -418,6 +636,9 @@ export class AppInfo {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Checks if the application supports reading files and directories from URIs.
+     */
     supportsUris() {
         return call("libgio-2.0.so.0", "g_app_info_supports_uris", [
             {