From: Matthias Clasen Date: Fri, 4 Mar 2011 04:34:49 +0000 (-0500) Subject: GApplication: Improve documentation X-Git-Tag: 2.29.2~138 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=f05bce027e49ba3ba4dee042ed52837d0145a7bf;p=platform%2Fupstream%2Fglib.git GApplication: Improve documentation This commit adds some details regarding platform data. --- diff --git a/gio/gapplication.c b/gio/gapplication.c index 48f8065..f97312e 100644 --- a/gio/gapplication.c +++ b/gio/gapplication.c @@ -94,11 +94,29 @@ * * via 'Activate' (i.e. just starting the application) * via 'Open' (i.e. opening some files) + * by handling a command-line * via activating an action * * 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 platform + * data 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. + * * Opening files with a GApplication * * @@ -1146,11 +1164,11 @@ g_application_open (GApplication *application, * 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() diff --git a/gio/gapplication.h b/gio/gapplication.h index d6605f6..b178701 100644 --- a/gio/gapplication.h +++ b/gio/gapplication.h @@ -70,13 +70,19 @@ struct _GApplication * 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 */ diff --git a/gio/gioenums.h b/gio/gioenums.h index 84907fe..6203aca 100644 --- a/gio/gioenums.h +++ b/gio/gioenums.h @@ -1248,12 +1248,16 @@ typedef enum * 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 GIT_COMMITTER_NAME environment variable + * when editing a git commit message. * * Flags used to define the behaviour of a #GApplication. *