mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-09 19:06:15 +01:00
docs: Move the GApplicationCommandline SECTION
Move the contents to the struct docs. Helps: #3037
This commit is contained in:
parent
75de7e8628
commit
840cfd1ab7
@ -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:
|
||||
* ```
|
||||
*
|
||||
* 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:
|
||||
*
|
||||
|
Loading…
Reference in New Issue
Block a user