Add another example for commandline handling

Also, clarify some aspects in the documentation.

gio/gapplication.c

@@ -1065,18 +1065,18 @@ 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 handle_command_line() virtual function is invoked.  This
+ * 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).
  *
  * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
- * flag set then the default implementation of handle_command_line()
+ * flag set then the default implementation of local_command_line()
  * always returns %FALSE immediately, resulting in the commandline
  * always being handled in the primary instance.
  *
- * Otherwise, the default implementation of handle_command_line() tries
+ * Otherwise, the default implementation of local_command_line() tries
  * to do a couple of things that are probably reasonable for most
  * applications.  First, g_application_register() is called to attempt
  * to register the application.  If that works, then the command line
@@ -1086,7 +1086,9 @@ g_application_open (GApplication  *application,
  * are assumed to be filenames and g_application_open() is called.
  *
  * If you are interested in doing more complicated local handling of the
- * commandline then you should override handle_command_line().
+ * commandline then you should implement your own #GApplication subclass
+ * and override local_command_line(). See
+ * <xref linkend="gapplication-example-cmdline2"/> for an example.
  *
  * If, after the above is done, the use count of the application is zero
  * then the exit status is returned immediately.  If the use count is

gio/gapplication.h

@@ -66,9 +66,10 @@ struct _GApplication
  * @open: invoked on the primary instance when there are files to open
  * @command_line: invoked on the primary instance when a command-line is
  *   not handled locally
- * @local_command_line: invoked (locally) when the process has been invoked 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.
+ * @local_command_line: invoked (locally) when the process has been invoked
+ *     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

gio/gapplicationcommandline.c

@@ -53,7 +53,9 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * of this object (ie: the process exits when the last reference is
  * dropped).
  *
- * <example id="gapplication-example-open"><title>Handling commandline arguments with GApplication</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ *
+ * <example id="gapplication-example-cmdline2"><title>Complicated commandline handling</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
  **/
 
 enum

gio/tests/Makefile.am

@@ -87,6 +87,7 @@ SAMPLE_PROGS = 				\
 	proxy				\
 	gapplication-example-open	\
 	gapplication-example-cmdline	\
+	gapplication-example-cmdline2	\
 	$(NULL)
 
 
@@ -315,6 +316,9 @@ gapplication_example_open_LDADD   = $(progs_ldadd)
 gapplication_example_cmdline_SOURCES = gapplication-example-cmdline.c
 gapplication_example_cmdline_LDADD   = $(progs_ldadd)
 
+gapplication_example_cmdline2_SOURCES = gapplication-example-cmdline2.c
+gapplication_example_cmdline2_LDADD   = $(progs_ldadd)
+
 schema_tests = \
 	schema-tests/array-default-not-in-choices.gschema.xml		\
 	schema-tests/bad-choice.gschema.xml				\

gio/tests/gapplication-example-cmdline2.c

@@ -0,0 +1,106 @@
+#include <gio/gio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int
+command_line (GApplication            *application,
+              GApplicationCommandLine *cmdline)
+{
+  gchar **argv;
+  gint argc;
+  gint i;
+
+  g_application_hold (application);
+
+  argv = g_application_command_line_get_arguments (cmdline, &argc);
+
+  for (i = 0; i < argc; i++)
+    g_print ("handling argument %s remotely\n", argv[i]);
+
+  g_strfreev (argv);
+
+  g_application_release (application);
+
+  return 0;
+}
+
+static gboolean
+test_local_cmdline (GApplication   *application,
+                    gchar        ***arguments,
+                    gint           *exit_status)
+{
+  gint i, j;
+  gchar **argv;
+
+  argv = *arguments;
+
+  for (i = 0; argv[i]; i++)
+    {
+      if (g_str_has_prefix (argv[i], "--local-"))
+        {
+          g_print ("handling argument %s locally\n", argv[i]);
+          for (j = i + 1; argv[j]; j++)
+            {
+              argv[j - 1] = argv[j];
+              argv[j] = NULL;
+            }
+        }
+    }
+
+  *exit_status = 0;
+
+  return FALSE;
+}
+
+typedef GApplication TestApplication;
+typedef GApplicationClass TestApplicationClass;
+
+G_DEFINE_TYPE (TestApplication, test_application, G_TYPE_APPLICATION)
+
+static void
+test_application_finalize (GObject *object)
+{
+  G_OBJECT_CLASS (test_application_parent_class)->finalize (object);
+}
+
+static void
+test_application_init (TestApplication *app)
+{
+}
+
+static void
+test_application_class_init (TestApplicationClass *class)
+{
+  G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
+}
+
+GApplication *
+test_application_new (const gchar       *application_id,
+                      GApplicationFlags  flags)
+{
+  g_return_val_if_fail (g_application_id_is_valid (application_id), NULL);
+
+  g_type_init ();
+
+  return g_object_new (test_application_get_type (),
+                       "application-id", application_id,
+                       "flags", flags,
+                       NULL);
+}
+
+int
+main (int argc, char **argv)
+{
+  GApplication *app;
+  int status;
+
+  app = test_application_new ("org.gtk.TestApplication", 0);
+  g_application_set_inactivity_timeout (app, 10000);
+  g_signal_connect (app, "command-line", G_CALLBACK (command_line), NULL);
+
+  status = g_application_run (app, argc, argv);
+
+  g_object_unref (app);
+
+  return status;
+}