@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/app-launch-context.d.ts

@@ -3,13 +3,66 @@ import { File } from "./file.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 export declare class AppLaunchContext extends GObject.GObject {
+    /**
+     * Creates a new application launch context. This is not normally used,
+     * instead you instantiate a subclass of this, such as
+     * `GdkAppLaunchContext`.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the display string for the @context. This is used to ensure new
+     * applications are started on the same display as the launching
+     * application, by setting the `DISPLAY` environment variable.
+     * @param info - the app info
+     * @param files - a list of [iface@Gio.File] objects
+     */
     getDisplay(info: AppInfo, files: File[]): string | null;
+    /**
+     * Gets the complete environment variable list to be passed to
+     * the child process when `context` is used to launch an application.
+     * This is a `NULL`-terminated array of strings, where each string has
+     * the form `KEY=VALUE`.
+     */
     getEnvironment(): string[];
+    /**
+     * Initiates startup notification for the application and returns the
+     * `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation,
+     * if supported.
+     *
+     * The returned token may be referred to equivalently as an ‘activation token’
+     * (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology).
+     * The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst).
+     *
+     * Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1),
+     * and startup notification IDs are defined in the
+     * [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
+     *
+     * Support for the XDG Activation Protocol was added in GLib 2.76.
+     * Since GLib 2.82 `info` and `files` can be `NULL`. If that’s not supported by the backend,
+     * the returned token will be `NULL`.
+     * @param info - the app info
+     * @param files - a list of [iface@Gio.File] objects
+     */
     getStartupNotifyId(info?: AppInfo | null, files?: File[] | null): string | null;
+    /**
+     * Called when an application has failed to launch, so that it can cancel
+     * the application startup notification started in
+     * [method@Gio.AppLaunchContext.get_startup_notify_id].
+     * @param startupNotifyId - the startup notification id that was returned by
+     */
     launchFailed(startupNotifyId: string): void;
+    /**
+     * Arranges for `variable` to be set to `value` in the child’s environment when
+     * `context` is used to launch an application.
+     * @param variable - the environment variable to set
+     * @param value - the value for to set the variable to.
+     */
     setenv(variable: string, value: string): void;
+    /**
+     * Arranges for `variable` to be unset in the child’s environment when `context` is used to launch an application.
+     * @param variable - the environment variable to remove
+     */
     unsetenv(variable: string): void;
     connect(signal: "launch-failed", handler: (self: AppLaunchContext, startupNotifyId: string) => void, after?: boolean): number;
     connect(signal: "launch-started", handler: (self: AppLaunchContext, info: AppInfo, platformData: GLib.Variant) => void, after?: boolean): number;

package/dist/generated/gio/app-launch-context.js

@@ -1,6 +1,11 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import * as GObject from "../gobject/index.js";
+/**
+ * Integrating the launch with the launching application. This is used to
+ * handle for instance startup notification and launching the new application
+ * on the same screen as the launching window.
+ */
 const SIGNAL_META = {
     "launch-failed": {
         params: [{ type: { type: "string", borrowed: false } }],
@@ -22,6 +27,11 @@ const SIGNAL_META = {
     },
 };
 export class AppLaunchContext extends GObject.GObject {
+    /**
+     * Creates a new application launch context. This is not normally used,
+     * instead you instantiate a subclass of this, such as
+     * `GdkAppLaunchContext`.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -31,6 +41,13 @@ export class AppLaunchContext extends GObject.GObject {
             borrowed: false,
         });
     }
+    /**
+     * Gets the display string for the @context. This is used to ensure new
+     * applications are started on the same display as the launching
+     * application, by setting the `DISPLAY` environment variable.
+     * @param info - the app info
+     * @param files - a list of [iface@Gio.File] objects
+     */
     getDisplay(info, files) {
         return call("libgio-2.0.so.0", "g_app_launch_context_get_display", [
             {
@@ -51,6 +68,12 @@ export class AppLaunchContext extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Gets the complete environment variable list to be passed to
+     * the child process when `context` is used to launch an application.
+     * This is a `NULL`-terminated array of strings, where each string has
+     * the form `KEY=VALUE`.
+     */
     getEnvironment() {
         return call("libgio-2.0.so.0", "g_app_launch_context_get_environment", [
             {
@@ -59,6 +82,25 @@ export class AppLaunchContext extends GObject.GObject {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Initiates startup notification for the application and returns the
+     * `XDG_ACTIVATION_TOKEN` or `DESKTOP_STARTUP_ID` for the launched operation,
+     * if supported.
+     *
+     * The returned token may be referred to equivalently as an ‘activation token’
+     * (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology).
+     * The two [are interoperable](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst).
+     *
+     * Activation tokens are defined in the [XDG Activation Protocol](https://wayland.app/protocols/xdg-activation-v1),
+     * and startup notification IDs are defined in the
+     * [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
+     *
+     * Support for the XDG Activation Protocol was added in GLib 2.76.
+     * Since GLib 2.82 `info` and `files` can be `NULL`. If that’s not supported by the backend,
+     * the returned token will be `NULL`.
+     * @param info - the app info
+     * @param files - a list of [iface@Gio.File] objects
+     */
     getStartupNotifyId(info, files) {
         return call("libgio-2.0.so.0", "g_app_launch_context_get_startup_notify_id", [
             {
@@ -81,6 +123,12 @@ export class AppLaunchContext extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Called when an application has failed to launch, so that it can cancel
+     * the application startup notification started in
+     * [method@Gio.AppLaunchContext.get_startup_notify_id].
+     * @param startupNotifyId - the startup notification id that was returned by
+     */
     launchFailed(startupNotifyId) {
         call("libgio-2.0.so.0", "g_app_launch_context_launch_failed", [
             {
@@ -93,6 +141,12 @@ export class AppLaunchContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Arranges for `variable` to be set to `value` in the child’s environment when
+     * `context` is used to launch an application.
+     * @param variable - the environment variable to set
+     * @param value - the value for to set the variable to.
+     */
     setenv(variable, value) {
         call("libgio-2.0.so.0", "g_app_launch_context_setenv", [
             {
@@ -109,6 +163,10 @@ export class AppLaunchContext extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Arranges for `variable` to be unset in the child’s environment when `context` is used to launch an application.
+     * @param variable - the environment variable to remove
+     */
     unsetenv(variable) {
         call("libgio-2.0.so.0", "g_app_launch_context_unsetenv", [
             {

package/dist/generated/gio/application-command-line.d.ts

@@ -3,22 +3,361 @@ 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";
+/**
+ * `GApplicationCommandLine` represents a command-line invocation of
+ * an application.
+ *
+ * It is created by [class@Gio.Application] and emitted
+ * in the [signal@Gio.Application::command-line] signal and virtual function.
+ *
+ * The class contains the list of arguments that the program was invoked
+ * with. It is also possible to query if the commandline invocation was
+ * local (ie: the current process is running in direct response to the
+ * invocation) or remote (ie: some other process forwarded the
+ * commandline to this process).
+ *
+ * The `GApplicationCommandLine` object can provide the `argc` and `argv` parameters for use with the [struct@GLib.OptionContext] command-line parsing API,
+ * with the [method@Gio.ApplicationCommandLine.get_arguments] function. See
+ * [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
+ * for an example.
+ *
+ * The exit status of the originally-invoked process may be set and
+ * messages can be printed to stdout or stderr of that process.
+ *
+ * For remote invocation, the originally-invoked process exits when
+ * [method@Gio.ApplicationCommandLine.done] method is called. This method is
+ * also automatically called when the object is disposed.
+ *
+ * The main use for `GApplicationCommandLine` (and the
+ * [signal@Gio.Application::command-line] signal) is 'Emacs server' like use cases:
+ * You can set the `EDITOR` environment variable to have e.g. git use
+ * your favourite editor to edit commit messages, and if you already
+ * have an instance of the editor running, the editing will happen
+ * in the running instance, instead of opening a new one. An important
+ * aspect of this use case is that the process that gets started by git
+ * does not return until the editing is done.
+ *
+ * Normally, the commandline is completely handled in the
+ * [signal@Gio.Application::command-line] handler. The launching instance exits
+ * once the signal handler in the primary instance has returned, and
+ * the return value of the signal handler becomes the exit status
+ * of the launching instance.
+ *
+ * ```c
+ * static int
+ * command_line (GApplication            *application,
+ * GApplicationCommandLine *cmdline)
+ * {
+ * gchar **argv;
+ * gint argc;
+ * gint i;
+ *
+ * argv = g_application_command_line_get_arguments (cmdline, &argc);
+ *
+ * g_application_command_line_print (cmdline,
+ * "This text is written back\n"
+ * "to stdout of the caller\n");
+ *
+ * for (i = 0; i < argc; i++)
+ * g_print ("argument %d: %s\n", i, argv[i]);
+ *
+ * g_strfreev (argv);
+ *
+ * return 0;
+ * }
+ * ```
+ *
+ * The complete example can be found here:
+ * [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c)
+ *
+ * In more complicated cases, the handling of the commandline can be
+ * split between the launcher and the primary instance.
+ *
+ * ```c
+ * static gboolean
+ * test_local_cmdline (GApplication   *application,
+ * gchar        ***arguments,
+ * gint           *exit_status)
+ * {
+ * gint i, j;
+ * gchar **argv;
+ *
+ * argv = *arguments;
+ *
+ * if (argv[0] == NULL)
+ * {
+ * *exit_status = 0;
+ * return FALSE;
+ * }
+ *
+ * i = 1;
+ * while (argv[i])
+ * {
+ * if (g_str_has_prefix (argv[i], "--local-"))
+ * {
+ * g_print ("handling argument %s locally\n", argv[i]);
+ * g_free (argv[i]);
+ * for (j = i; argv[j]; j++)
+ * argv[j] = argv[j + 1];
+ * }
+ * else
+ * {
+ * g_print ("not handling argument %s locally\n", argv[i]);
+ * i++;
+ * }
+ * }
+ *
+ * *exit_status = 0;
+ *
+ * return FALSE;
+ * }
+ *
+ * static void
+ * test_application_class_init (TestApplicationClass *class)
+ * {
+ * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
+ *
+ * ...
+ * }
+ * ```
+ *
+ * In this example of split commandline handling, options that start
+ * with `--local-` are handled locally, all other options are passed
+ * to the [signal@Gio.Application::command-line] handler which runs in the primary
+ * instance.
+ *
+ * The complete example can be found here:
+ * [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c)
+ *
+ * If handling the commandline requires a lot of work, it may be better to defer it.
+ *
+ * ```c
+ * static gboolean
+ * my_cmdline_handler (gpointer data)
+ * {
+ * GApplicationCommandLine *cmdline = data;
+ *
+ * // do the heavy lifting in an idle
+ *
+ * g_application_command_line_set_exit_status (cmdline, 0);
+ * g_object_unref (cmdline); // this releases the application
+ *
+ * return G_SOURCE_REMOVE;
+ * }
+ *
+ * static int
+ * command_line (GApplication            *application,
+ * GApplicationCommandLine *cmdline)
+ * {
+ * // keep the application running until we are done with this commandline
+ * g_application_hold (application);
+ *
+ * g_object_set_data_full (G_OBJECT (cmdline),
+ * "application", application,
+ * (GDestroyNotify)g_application_release);
+ *
+ * g_object_ref (cmdline);
+ * g_idle_add (my_cmdline_handler, cmdline);
+ *
+ * return 0;
+ * }
+ * ```
+ *
+ * In this example the commandline is not completely handled before
+ * the [signal@Gio.Application::command-line] handler returns. Instead, we keep
+ * a reference to the `GApplicationCommandLine` object and handle it
+ * later (in this example, in an idle). Note that it is necessary to
+ * hold the application until you are done with the commandline.
+ *
+ * The complete example can be found here:
+ * [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
+ */
 export declare class ApplicationCommandLine extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Creates a #GFile corresponding to a filename that was given as part
+     * of the invocation of @cmdline.
+     *
+     * This differs from g_file_new_for_commandline_arg() in that it
+     * resolves relative pathnames using the current working directory of
+     * the invoking process rather than the local process.
+     * @param arg - an argument from @cmdline
+     */
     createFileForArg(arg: string): File;
+    /**
+     * Signals that command line processing is completed.
+     *
+     * For remote invocation, it causes the invoking process to terminate.
+     *
+     * For local invocation, it does nothing.
+     *
+     * This method should be called in the [signal@Gio.Application::command-line]
+     * handler, after the exit status is set and all messages are printed.
+     *
+     * After this call, g_application_command_line_set_exit_status() has no effect.
+     * Subsequent calls to this method are no-ops.
+     *
+     * This method is automatically called when the #GApplicationCommandLine
+     * object is disposed — so you can omit the call in non-garbage collected
+     * languages.
+     */
     done(): void;
+    /**
+     * Gets the list of arguments that was passed on the command line.
+     *
+     * The strings in the array may contain non-UTF-8 data on UNIX (such as
+     * filenames or arguments given in the system locale) but are always in
+     * UTF-8 on Windows.
+     *
+     * If you wish to use the return value with #GOptionContext, you must
+     * use g_option_context_parse_strv().
+     *
+     * The return value is %NULL-terminated and should be freed using
+     * g_strfreev().
+     * @param argc - the length of the arguments array, or %NULL
+     */
     getArguments(argc?: Ref<number> | null): string[];
+    /**
+     * Gets the working directory of the command line invocation.
+     * The string may contain non-utf8 data.
+     *
+     * It is possible that the remote application did not send a working
+     * directory, so this may be %NULL.
+     *
+     * The return value should not be modified or freed and is valid for as
+     * long as `cmdline` exists.
+     */
     getCwd(): string | null;
+    /**
+     * Gets the contents of the 'environ' variable of the command line
+     * invocation, as would be returned by g_get_environ(), ie as a
+     * %NULL-terminated list of strings in the form 'NAME=VALUE'.
+     * The strings may contain non-utf8 data.
+     *
+     * The remote application usually does not send an environment.  Use
+     * %G_APPLICATION_SEND_ENVIRONMENT to affect that.  Even with this flag
+     * set it is possible that the environment is still not available (due
+     * to invocation messages from other applications).
+     *
+     * The return value should not be modified or freed and is valid for as
+     * long as `cmdline` exists.
+     *
+     * See g_application_command_line_getenv() if you are only interested
+     * in the value of a single environment variable.
+     */
     getEnviron(): string[];
+    /**
+     * Gets the exit status of @cmdline.  See
+     * g_application_command_line_set_exit_status() for more information.
+     */
     getExitStatus(): number;
+    /**
+     * Determines if `cmdline` represents a remote invocation.
+     */
     getIsRemote(): boolean;
+    /**
+     * Gets the options that were passed to g_application_command_line().
+     *
+     * If you did not override local_command_line() then these are the same
+     * options that were parsed according to the #GOptionEntrys added to the
+     * application with g_application_add_main_option_entries() and possibly
+     * modified from your GApplication::handle-local-options handler.
+     *
+     * If no options were sent then an empty dictionary is returned so that
+     * you don't need to check for %NULL.
+     *
+     * The data has been passed via an untrusted external process, so the types of
+     * all values must be checked before being used.
+     */
     getOptionsDict(): GLib.VariantDict;
+    /**
+     * Gets the platform data associated with the invocation of @cmdline.
+     *
+     * This is a #GVariant dictionary containing information about the
+     * context in which the invocation occurred.  It typically contains
+     * information like the current working directory and the startup
+     * notification ID.
+     *
+     * It comes from an untrusted external process and hence the types of all
+     * values must be validated before being used.
+     *
+     * For local invocation, it will be %NULL.
+     */
     getPlatformData(): GLib.Variant | null;
+    /**
+     * Gets the stdin of the invoking process.
+     *
+     * The #GInputStream can be used to read data passed to the standard
+     * input of the invoking process.
+     * This doesn't work on all platforms.  Presently, it is only available
+     * on UNIX when using a D-Bus daemon capable of passing file descriptors.
+     * If stdin is not available then %NULL will be returned.  In the
+     * future, support may be expanded to other platforms.
+     *
+     * You must only call this function once per commandline invocation.
+     */
     getStdin(): InputStream | null;
+    /**
+     * Gets the value of a particular environment variable of the command
+     * line invocation, as would be returned by g_getenv().  The strings may
+     * contain non-utf8 data.
+     *
+     * The remote application usually does not send an environment.  Use
+     * %G_APPLICATION_SEND_ENVIRONMENT to affect that.  Even with this flag
+     * set it is possible that the environment is still not available (due
+     * to invocation messages from other applications).
+     *
+     * The return value should not be modified or freed and is valid for as
+     * long as `cmdline` exists.
+     * @param name - the environment variable to get
+     */
     getenv(name: string): string | null;
+    /**
+     * Prints a message using the stdout print handler in the invoking process.
+     *
+     * Unlike g_application_command_line_print(), `message` is not a `printf()`-style
+     * format string. Use this function if `message` contains text you don't have
+     * control over, that could include `printf()` escape sequences.
+     * @param message - the message
+     */
     printLiteral(message: string): void;
+    /**
+     * Prints a message using the stderr print handler in the invoking process.
+     *
+     * Unlike g_application_command_line_printerr(), `message` is not
+     * a `printf()`-style format string. Use this function if `message` contains text
+     * you don't have control over, that could include `printf()` escape sequences.
+     * @param message - the message
+     */
     printerrLiteral(message: string): void;
+    /**
+     * Sets the exit status that will be used when the invoking process
+     * exits.
+     *
+     * The return value of the #GApplication::command-line signal is
+     * passed to this function when the handler returns.  This is the usual
+     * way of setting the exit status.
+     *
+     * In the event that you want the remote invocation to continue running
+     * and want to decide on the exit status in the future, you can use this
+     * call.  For the case of a remote invocation, the remote process will
+     * typically exit when the last reference is dropped on @cmdline.  The
+     * exit status of the remote process will be equal to the last value
+     * that was set with this function.
+     *
+     * In the case that the commandline invocation is local, the situation
+     * is slightly more complicated.  If the commandline invocation results
+     * in the mainloop running (ie: because the use-count of the application
+     * increased to a non-zero value) then the application is considered to
+     * have been 'successful' in a certain sense, and the exit status is
+     * always zero.  If the application use count is zero, though, the exit
+     * status of the local #GApplicationCommandLine is used.
+     *
+     * This method is a no-op if g_application_command_line_done() has
+     * been called.
+     * @param exitStatus - the exit status
+     */
     setExitStatus(exitStatus: number): void;
     connect(signal: "notify", handler: (self: ApplicationCommandLine, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;