[glib] Add some examples to the GApplication docs

[Matthias Clasen <matthiasc src gnome org>]

commit 499d9ba8b8fec44282fac09426b61d027c166459
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Oct 23 02:27:39 2010 +0200

    Add some examples to the GApplication docs

 gio/gapplication.c                       |    9 +++++-
 gio/gapplicationcommandline.c            |    2 +
 gio/tests/Makefile.am                    |    8 +++++
 gio/tests/gapplication-example-cmdline.c |   47 ++++++++++++++++++++++++++++
 gio/tests/gapplication-example-open.c    |   50 ++++++++++++++++++++++++++++++
 5 files changed, 115 insertions(+), 1 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index c81c28c..6750abf 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -70,6 +70,13 @@
  *   <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
  *   <listitem>Application identifiers must not exceed 255 characters.</listitem>
  * </itemizedlist>
+ *
+ * GApplication provides convenient life cycle management by maintaining
+ * a <firstterm>use count</firstterm> for the primary application instance.
+ * The use count can be changed using g_application_hold() and
+ * g_application_release(). If it drops to zero, the application exits.
+ *
+ * <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"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
  */
 
 struct _GApplicationPrivate
@@ -912,7 +919,7 @@ g_application_register (GApplication  *application,
  * Increases the use count of @application.
  *
  * Use this function to indicate that the application has a reason to
- * continue to run.  For example, g_application_hold() is called by Gtk
+ * continue to run.  For example, g_application_hold() is called by GTK+ 
  * when a toplevel window is on the screen.
  *
  * To cancel the hold, call g_application_release().
diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c
index 53be6a1..96f6ebd 100644
--- a/gio/gapplicationcommandline.c
+++ b/gio/gapplicationcommandline.c
@@ -52,6 +52,8 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
  * lifecycle of the originally-invoked process is tied to the lifecycle
  * 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>
  **/
 
 enum
diff --git a/gio/tests/Makefile.am b/gio/tests/Makefile.am
index 6bd5f9d..883e291 100644
--- a/gio/tests/Makefile.am
+++ b/gio/tests/Makefile.am
@@ -85,6 +85,8 @@ SAMPLE_PROGS = 				\
 	gdbus-connection-flush-helper	\
 	appinfo-test			\
 	proxy				\
+	gapplication-example-open	\
+	gapplication-example-cmdline	\
 	$(NULL)
 
 
@@ -307,6 +309,12 @@ file_LDADD   = $(progs_ldadd)
 gapplication_SOURCES = gapplication.c gdbus-sessionbus.c
 gapplication_LDADD = $(progs_ldadd)
 
+gapplication_example_open_SOURCES = gapplication-example-open.c
+gapplication_example_open_LDADD   = $(progs_ldadd)
+
+gapplication_example_cmdline_SOURCES = gapplication-example-cmdline.c
+gapplication_example_cmdline_LDADD   = $(progs_ldadd)
+
 schema_tests = \
 	schema-tests/array-default-not-in-choices.gschema.xml		\
 	schema-tests/bad-choice.gschema.xml				\
diff --git a/gio/tests/gapplication-example-cmdline.c b/gio/tests/gapplication-example-cmdline.c
new file mode 100644
index 0000000..7c8f379
--- /dev/null
+++ b/gio/tests/gapplication-example-cmdline.c
@@ -0,0 +1,47 @@
+#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);
+
+  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);
+
+  g_application_release (application);
+
+  return 0;
+}
+
+int
+main (int argc, char **argv)
+{
+  GApplication *app;
+  int status;
+
+  app = g_application_new ("org.gtk.TestApplication",
+                           G_APPLICATION_HANDLES_COMMAND_LINE);
+  g_signal_connect (app, "command-line", G_CALLBACK (command_line), NULL);
+  g_application_set_inactivity_timeout (app, 10000);
+
+  status = g_application_run (app, argc, argv);
+
+  g_object_unref (app);
+
+  return status;
+}
diff --git a/gio/tests/gapplication-example-open.c b/gio/tests/gapplication-example-open.c
new file mode 100644
index 0000000..b2370f7
--- /dev/null
+++ b/gio/tests/gapplication-example-open.c
@@ -0,0 +1,50 @@
+#include <gio/gio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static void
+activate (GApplication *application)
+{
+  g_application_hold (application);
+  g_print ("activated\n");
+  g_application_release (application);
+}
+
+static void
+open (GApplication  *application,
+      GFile        **files,
+      gint           n_files,
+      const gchar   *hint)
+{
+  gint i;
+
+  g_application_hold (application);
+
+  for (i = 0; i < n_files; i++)
+    {
+      gchar *uri = g_file_get_uri (files[i]);
+      g_print ("open %s\n", uri);
+      g_free (uri);
+    }
+
+  g_application_release (application);
+}
+
+int
+main (int argc, char **argv)
+{
+  GApplication *app;
+  int status;
+
+  app = g_application_new ("org.gtk.TestApplication",
+                           G_APPLICATION_HANDLES_OPEN);
+  g_signal_connect (app, "activate", G_CALLBACK (activate), NULL);
+  g_signal_connect (app, "open", G_CALLBACK (open), NULL);
+  g_application_set_inactivity_timeout (app, 10000);
+
+  status = g_application_run (app, argc, argv);
+
+  g_object_unref (app);
+
+  return status;
+}