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,36 +40,34 @@
#endif
/**
* SECTION:gapplicationcommandline
* @title: GApplicationCommandLine
* @short_description: A command-line invocation of an application
* @include: gio/gio.h
* @see_also: #GApplication
* GApplicationCommandLine:
*
* #GApplicationCommandLine represents a command-line invocation of
* an application. It is created by #GApplication and emitted
* in the #GApplication::command-line signal and virtual function.
* `GApplicationCommandLine` represents a command-line invocation of
* an application.
*
* 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
* with. It is also possible to query if the commandline invocation was
* 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 #GOptionContext command-line parsing API,
* with the g_application_command_line_get_arguments() function. See
* 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][gapplication-example-cmdline3]
* 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. The
* lifecycle of the originally-invoked process is tied to the lifecycle
* messages can be printed to stdout or stderr of that process. The
* life-cycle of the originally-invoked process is tied to the lifecycle
* of this object (ie: the process exits when the last reference is
* dropped).
*
* The main use for #GApplicationCommandLine (and the
* #GApplication::command-line signal) is 'Emacs server' like use cases:
* 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
@ -78,11 +76,12 @@
* does not return until the editing is done.
*
* 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
* the return value of the signal handler becomes the exit status
* of the launching instance.
* |[<!-- language="C" -->
*
* ```c
* static int
* command_line (GApplication *application,
* GApplicationCommandLine *cmdline)
@ -104,13 +103,15 @@
*
* 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.
* |[<!-- language="C" -->
*
* ```c
* static gboolean
* test_local_cmdline (GApplication *application,
* gchar ***arguments,
@ -156,18 +157,19 @@
*
* ...
* }
* ]|
* ```
*
* In this example of split commandline handling, options that start
* 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.
*
* 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.
* |[<!-- language="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)
* {
@ -197,10 +199,11 @@
*
* return 0;
* }
* ]|
* ```
*
* In this example the commandline is not completely handled before
* the #GApplication::command-line handler returns. Instead, we keep
* a reference to the #GApplicationCommandLine object and handle it
* 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.
*
@ -208,13 +211,6 @@
* [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:
*