From: Matthias Clasen Date: Fri, 4 Mar 2011 06:53:56 +0000 (-0500) Subject: GApplication: More documentation tweaks X-Git-Tag: 2.29.2~131 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1485871ed5e8e9ce70b088cfedae4012032e5dca;p=platform%2Fupstream%2Fglib.git GApplication: More documentation tweaks --- diff --git a/gio/gapplication.c b/gio/gapplication.c index f4a47e1..6cacb1e 100644 --- a/gio/gapplication.c +++ b/gio/gapplication.c @@ -105,7 +105,11 @@ * 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. + * 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. * * Opening files with a GApplication * @@ -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 - * for an example. + * for an example of + * parsing @argv manually. Alternatively, you may use the #GOptionContext API, + * after setting argc = g_strv_length (argv);. + * * 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(). diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c index 7b0175a..b3c98f5 100644 --- a/gio/gapplicationcommandline.c +++ b/gio/gapplicationcommandline.c @@ -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 - * for an example. + * 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 EDITOR environment variable to have + * 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 * 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 * Handling commandline arguments with GApplication * * 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. * * * @@ -85,7 +85,8 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC * * An example of split commandline handling. Options that start with * --local- 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. * * * @@ -97,10 +98,11 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC * Deferred commandline handling * * 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. * * * 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 *