This commit adds some details regarding platform data.
* <itemizedlist>
* <listitem>via 'Activate' (i.e. just starting the application)</listitem>
* <listitem>via 'Open' (i.e. opening some files)</listitem>
+ * <listitem>by handling a command-line</listitem>
* <listitem>via activating an action</listitem>
* </itemizedlist>
* The #GApplication::startup signal lets you handle the application
* initialization for all of these in a single place.
*
+ * Regardless of which of these entry points is used to start the application,
+ * GApplication passes some <firstterm id="platform-data">platform
+ * 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.
+ *
+ * As the name indicates, the platform data may vary depending on the
+ * operating system, but it always includes the current directory (key
+ * "cwd"), and optionally the environment (ie the set of environment
+ * variables and their values) of the calling process (key "environ").
+ * The environment is only added to the platform data if the
+ * #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.
+ *
* <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c">
* This function is intended to be run from main() and its return value
* is intended to be returned by main().
*
- * First, the local_command_line() virtual function is invoked. This
- * function always runs on the local instance. If that function returns
- * %FALSE then the application is registered and the #GApplication::command-line
- * signal is emitted in the primary instance (which may or may not be
- * this instance).
+ * First, the local_command_line() virtual function is invoked.
+ * This function always runs on the local instance. If it returns
+ * %FALSE then the application is registered and the
+ * #GApplication::command-line signal is emitted in the primary
+ * instance (which may or may not be this instance).
*
* If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
* flag set then the default implementation of local_command_line()
* via commandline execution. The virtual function has the chance to
* inspect (and possibly replace) the list of command line arguments.
* See g_application_run() for more information.
- * @before_emit: invoked on the primary instance before 'activate', 'open' or any action invocation
- * @after_emit: invoked on the primary instance after 'activate', 'open' or any action invocation
- * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when
- * activating, opening or invoking actions
- * @quit_mainloop: invoked on the primary instance when the use count of the application drops to zero (and
- * after any inactivity timeout, if requested)
- * @run_mainloop: invoked on the primary instance from g_application_run() if the use-count is non-zero
+ * @before_emit: invoked on the primary instance before 'activate', 'open',
+ * 'command-line' or any action invocation, gets the 'platform data' from
+ * the calling instance
+ * @after_emit: invoked on the primary instance after 'activate', 'open',
+ * 'command-line' or any action invocation, gets the 'platform data' from
+ * the calling instance
+ * @add_platform_data: invoked (locally) to add 'platform data' to be sent to
+ * the primary instance when activating, opening or invoking actions
+ * @quit_mainloop: invoked on the primary instance when the use count of the
+ * application drops to zero (and after any inactivity timeout, if
+ * requested)
+ * @run_mainloop: invoked on the primary instance from g_application_run()
+ * if the use-count is non-zero
*
* Since: 2.28
*/
* fails if the service is already running, and the application will
* stay around for a while when the use count falls to zero.
* @G_APPLICATION_IS_LAUNCHER: Don't try to become the primary instance.
- * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the
- * primary instance)
+ * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in
+ * the primary instance). See g_application_run() for details.
* @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command line
- * arguments (in the primary instance)
+ * arguments (in the primary instance). See g_application_run() for details.
* @G_APPLICATION_SEND_ENVIRONMENT: Send the environment of the
- * launching process to the primary instance
+ * launching process to the primary instance. Set this flag if your
+ * application is expected to behave differently depending on certain
+ * environment variables. For instance, an editor might be expected
+ * to use the <envvar>GIT_COMMITTER_NAME</envvar> environment variable
+ * when editing a git commit message.
*
* Flags used to define the behaviour of a #GApplication.
*