docs: Move the GApplicationCommandline SECTION

Move the contents to the struct docs.

Helps: #3037
This commit is contained in:
Matthias Clasen 2023-09-25 21:07:47 -04:00 committed by Philip Withnall
parent 75de7e8628
commit 840cfd1ab7

View File

@ -40,15 +40,13 @@
#endif #endif
/** /**
* SECTION:gapplicationcommandline * GApplicationCommandLine:
* @title: GApplicationCommandLine
* @short_description: A command-line invocation of an application
* @include: gio/gio.h
* @see_also: #GApplication
* *
* #GApplicationCommandLine represents a command-line invocation of * `GApplicationCommandLine` represents a command-line invocation of
* an application. It is created by #GApplication and emitted * an application.
* in the #GApplication::command-line signal and virtual function. *
* It is created by [struct@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 * The class contains the list of arguments that the program was invoked
* with. It is also possible to query if the commandline invocation was * with. It is also possible to query if the commandline invocation was
@ -56,20 +54,20 @@
* invocation) or remote (ie: some other process forwarded the * invocation) or remote (ie: some other process forwarded the
* commandline to this process). * commandline to this process).
* *
* The GApplicationCommandLine object can provide the @argc and @argv * The `GApplicationCommandLine` object can provide the @argc and @argv
* parameters for use with the #GOptionContext command-line parsing API, * parameters for use with the [struct@Glib.OptionContext] command-line parsing API,
* with the g_application_command_line_get_arguments() function. See * with the [method@Gio.ApplicationCommandLine.get_arguments] function. See
* [gapplication-example-cmdline3.c][gapplication-example-cmdline3] * [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
* for an example. * for an example.
* *
* The exit status of the originally-invoked process may be set and * The exit status of the originally-invoked process may be set and
* messages can be printed to stdout or stderr of that process. The * messages can be printed to stdout or stderr of that process. The
* lifecycle of the originally-invoked process is tied to the lifecycle * life-cycle of the originally-invoked process is tied to the lifecycle
* of this object (ie: the process exits when the last reference is * of this object (ie: the process exits when the last reference is
* dropped). * dropped).
* *
* The main use for #GApplicationCommandLine (and the * The main use for `GApplicationCommandLine` (and the
* #GApplication::command-line signal) is 'Emacs server' like use cases: * [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 * You can set the `EDITOR` environment variable to have e.g. git use
* your favourite editor to edit commit messages, and if you already * your favourite editor to edit commit messages, and if you already
* have an instance of the editor running, the editing will happen * have an instance of the editor running, the editing will happen
@ -78,11 +76,12 @@
* does not return until the editing is done. * does not return until the editing is done.
* *
* Normally, the commandline is completely handled in the * Normally, the commandline is completely handled in the
* #GApplication::command-line handler. The launching instance exits * [signal@Gio.Application.command-line handler]. The launching instance exits
* once the signal handler in the primary instance has returned, and * once the signal handler in the primary instance has returned, and
* the return value of the signal handler becomes the exit status * the return value of the signal handler becomes the exit status
* of the launching instance. * of the launching instance.
* |[<!-- language="C" --> *
* ```c
* static int * static int
* command_line (GApplication *application, * command_line (GApplication *application,
* GApplicationCommandLine *cmdline) * GApplicationCommandLine *cmdline)
@ -104,13 +103,15 @@
* *
* return 0; * return 0;
* } * }
* ]| * ```
*
* The complete example can be found here: * 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) * [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 * In more complicated cases, the handling of the commandline can be
* split between the launcher and the primary instance. * split between the launcher and the primary instance.
* |[<!-- language="C" --> *
* ```c
* static gboolean * static gboolean
* test_local_cmdline (GApplication *application, * test_local_cmdline (GApplication *application,
* gchar ***arguments, * gchar ***arguments,
@ -156,18 +157,19 @@
* *
* ... * ...
* } * }
* ]| * ```
*
* In this example of split commandline handling, options that start * In this example of split commandline handling, options that start
* with `--local-` are handled locally, all other options are passed * with `--local-` are handled locally, all other options are passed
* to the #GApplication::command-line handler which runs in the primary * to the [signal@Gio.Application.command-line] handler which runs in the primary
* instance. * instance.
* *
* The complete example can be found here: * 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) * [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 * If handling the commandline requires a lot of work, it may be better to defer it.
* be better to defer it. *
* |[<!-- language="C" --> * ```c
* static gboolean * static gboolean
* my_cmdline_handler (gpointer data) * my_cmdline_handler (gpointer data)
* { * {
@ -197,10 +199,11 @@
* *
* return 0; * return 0;
* } * }
* ]| * ```
*
* In this example the commandline is not completely handled before * In this example the commandline is not completely handled before
* the #GApplication::command-line handler returns. Instead, we keep * the [signal@Gio.Application.command-line] handler returns. Instead, we keep
* a reference to the #GApplicationCommandLine object and handle it * a reference to the `GApplicationCommandLine` object and handle it
* later (in this example, in an idle). Note that it is necessary to * later (in this example, in an idle). Note that it is necessary to
* hold the application until you are done with the commandline. * hold the application until you are done with the commandline.
* *
@ -208,13 +211,6 @@
* [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) * [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
*/ */
/**
* GApplicationCommandLine:
*
* #GApplicationCommandLine is an opaque data structure and can only be accessed
* using the following functions.
*/
/** /**
* GApplicationCommandLineClass: * GApplicationCommandLineClass:
* *