luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-25 03:32:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

GApplication: More documentation tweaks

Browse Source
This commit is contained in:
Matthias Clasen 2011-03-04 01:53:56 -05:00
parent fe4d9ab763
commit 841d2a3fff
2 changed files with 38 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
gio/gapplication.c
View File

@ -105,7 +105,11 @@
* data</firstterm> from the launching instance to the primary instance,
* in the form of a #GVariant dictionary mapping strings to variants.
* To use platform data, override the @before_emit or @after_emit virtual
* functions in your #GApplication subclass.
* functions in your #GApplication subclass. When dealing with
* #GApplicationCommandline objects, the platform data is directly
* available via g_application_command_line_get_cwd(),
* g_application_command_line_get_environ() and
* g_application_command_line_get_platform_data().
*
* As the name indicates, the platform data may vary depending on the
* operating system, but it always includes the current directory (key
@ -115,7 +119,12 @@
* #G_APPLICATION_SEND_ENVIONMENT flag is set. GApplication subclasses
* can add their own platform data by overriding the @add_platform_data
* virtual function. For instance, #GtkApplication adds startup notification
* information in this way.
* data in this way.
*
* To parse commandline arguments you may handle the
* #GApplication::command-line signal or override the local_command_line()
* vfunc, to parse them in either the primary instance or the local instance,
* respectively.
*
* <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
* <programlisting>
@ -1168,10 +1177,13 @@ g_application_open (GApplication *application,
* required.
*
* First, the local_command_line() virtual function is invoked.
* This function always runs on the local instance. It gets passed
* a pointer to a copy of @argv and is expected to remove the arguments
* This function always runs on the local instance. It gets passed a pointer
* to a %NULL-terminated copy of @argv and is expected to remove the arguments
* that it handled (shifting up remaining arguments). See
* <xref linkend="gapplication-example-cmdline2"/> for an example.
* <xref linkend="gapplication-example-cmdline2"/> for an example of
* parsing @argv manually. Alternatively, you may use the #GOptionContext API,
* after setting <literal>argc = g_strv_length (argv);</literal>.
*
* The last argument to local_command_line() is a pointer to the @status
* variable which can used to set the exit status that is returned from
* g_application_run().

36
gio/gapplicationcommandline.c
View File

@ -49,7 +49,7 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
* 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
* <xref linkend="gapplication-example-cmdline3"> for an example.
* <xref linkend="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
@ -59,7 +59,7 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
*
* The main use for #GApplicationCommandline (and the
* #GApplication::command-line signal) is 'Emacs server' like use cases:
* You can set the <envvar>EDITOR</envvar> environment variable to have
* You can set the <envar>EDITOR</envar> 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
@ -69,10 +69,10 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
* <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
* <para>
* A simple example where the commandline is completely handled
* in the ::command-line handler. The calling process exits once the
* signal handler in the main instance has returned, and the return
* value of the signal handler becomes the exit status of the calling
* process.
* in the #GApplication::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.
* </para>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
@ -85,7 +85,8 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
* <para>
* An example of split commandline handling. Options that start with
* <literal>--local-</literal> are handled locally, all other options are
* passed to the ::command-line handler which runs in the main instance.
* passed to the #GApplication::command-line handler which runs in the primary
* instance.
* </para>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
@ -97,10 +98,11 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
* <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
* <para>
* An example of deferred commandline handling. Here, the commandline is
* not completely handled in the ::command-line handler. 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.
* not completely handled before the #GApplication::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.
* </para>
* <para>
* This example also shows how to use #GOptionContext for parsing the
@ -329,8 +331,8 @@ g_application_command_line_get_arguments (GApplicationCommandLine *cmdline,
* g_application_command_line_get_cwd:
* @cmdline: a #GApplicationCommandLine
*
* Gets the working directory of the command line invocation. The
* string may contain non-utf8 data.
* 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.
@ -356,8 +358,9 @@ g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
* @cmdline: a #GApplicationCommandLine
*
* Gets the contents of the 'environ' variable of the command line
* invocation, as would be returned by g_get_environ(). The strings may
* contain non-utf8 data.
* 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
@ -367,6 +370,9 @@ g_application_command_line_get_cwd (GApplicationCommandLine *cmdline)
* 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.
*
* Returns: (array zero-terminated=1) (transfer none): the environment
* strings, or %NULL if they were not sent
*