From 701f00f12515dfad2092842f34ccbf11679406e3 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 1 Feb 2014 15:11:00 -0500 Subject: [PATCH] GApplicationCommandline: Shorten embedded examples Just show relevant fragments of the three examples inline, and link to the full sources. This lets us get rid of xinclude markup. --- gio/gapplicationcommandline.c | 173 +++++++++++++++++++++++++++++------------- 1 file changed, 121 insertions(+), 52 deletions(-) diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c index e809625..b0c76e5 100644 --- a/gio/gapplicationcommandline.c +++ b/gio/gapplicationcommandline.c @@ -74,58 +74,127 @@ * aspect of this use case is that the process that gets started by git * does not return until the editing is done. * - * Handling commandline arguments with GApplication - * - * A simple example where the commandline is completely handled - * 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. - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * - * - * Split commandline handling - * - * An 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 - * instance. - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * - * - * Deferred commandline handling - * - * An example of deferred commandline handling. Here, 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 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 - * commandline arguments. Note that it is necessary to disable the - * built-in help-handling of #GOptionContext, since it calls exit() - * after printing help, which is not what you want to happen in - * the primary instance. - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * - **/ + * Normally, the commandline is completely handled 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. + * |[ + * static int + * command_line (GApplication *application, + * GApplicationCommandLine *cmdline) + * { + * gchar **argv; + * gint argc; + * gint i; + * + * argv = g_application_command_line_get_arguments (cmdline, &argc); + * + * g_application_command_line_print (cmdline, + * "This text is written back\n" + * "to stdout of the caller\n"); + * + * for (i = 0; i < argc; i++) + * g_print ("argument %d: %s\n", i, argv[i]); + * + * g_strfreev (argv); + * + * return 0; + * } + * ]| + * The complete example can be found here: gapplication-example-cmdline.c + * + * In more complicated cases, the handling of the comandline can be + * split between the launcher and the primary instance. + * |[ + * static gboolean + * test_local_cmdline (GApplication *application, + * gchar ***arguments, + * gint *exit_status) + * { + * gint i, j; + * gchar **argv; + * + * argv = *arguments; + * + * i = 1; + * while (argv[i]) + * { + * if (g_str_has_prefix (argv[i], "--local-")) + * { + * g_print ("handling argument %s locally\n", argv[i]); + * g_free (argv[i]); + * for (j = i; argv[j]; j++) + * argv[j] = argv[j + 1]; + * } + * else + * { + * g_print ("not handling argument %s locally\n", argv[i]); + * i++; + * } + * } + * + * *exit_status = 0; + * + * return FALSE; + * } + * + * static void + * test_application_class_init (TestApplicationClass *class) + * { + * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline; + * + * ... + * } + * ]| + * 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 instance. + * + * The complete example can be found here: gapplication-example-cmdline2.c + * + * If handling the commandline requires a lot of work, it may + * be better to defer it. + * |[ + * static gboolean + * my_cmdline_handler (gpointer data) + * { + * GApplicationCommandLine *cmdline = data; + * + * /* do the heavy lifting in an idle */ + * + * g_application_command_line_set_exit_status (cmdline, 0); + * g_object_unref (cmdline); /* this releases the application */ + * + * return G_SOURCE_REMOVE; + * } + * + * static int + * command_line (GApplication *application, + * GApplicationCommandLine *cmdline) + * { + * /* keep the application running until we are done with this commandline */ + * g_application_hold (application); + * + * g_object_set_data_full (G_OBJECT (cmdline), + * "application", application, + * (GDestroyNotify)g_application_release); + * + * g_object_ref (cmdline); + * g_idle_add (my_cmdline_handler, cmdline); + * + * 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 + * later (in this example, in an idle). Note that it is necessary to + * hold the application until you are done with the commandline. + * + * The complete example can be found here: gapplication-example-cmdline3.c + */ /** * GApplicationCommandLineClass: -- 2.7.4