Tweak GApplication docs

gio/gapplication.c

@@ -74,6 +74,15 @@
  * When invoking an action by calling g_action_group_activate_action() on
  * the application, it is always invoked in the primary instance.
  *
+ * There is a number of different entry points into a #GApplication:
+ * <itemizedlist>
+ * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
+ * <listitem>via 'Open' (i.e. opening some files)</listitem>
+ * <listitem>via activating an action</listitem>
+ * </itemizedlist>
+ * The #GApplication::startup signal lets you handle the application
+ * initialization for all of these in a single place.
+ *
  * <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">

gio/tests/gapplication-example-actions.c

@@ -5,9 +5,7 @@
 static void
 activate (GApplication *application)
 {
-  g_application_hold (application);
   g_print ("activated\n");
-  g_application_release (application);
 }
 
 static void
@@ -17,9 +15,7 @@ activate_action (GAction  *action,
 {
   GApplication *application = data;
 
-  g_application_hold (application);
   g_print ("action %s activated\n", g_action_get_name (action));
-  g_application_release (application);
 }
 
 static void
@@ -31,7 +27,6 @@ activate_toggle_action (GAction  *action,
   GVariant *state;
   gboolean b;
 
-  g_application_hold (application);
   g_print ("action %s activated\n", g_action_get_name (action));
 
   state = g_action_get_state (action);
@@ -39,8 +34,6 @@ activate_toggle_action (GAction  *action,
   g_variant_unref (state);
   g_action_set_state (action, g_variant_new_boolean (!b));
   g_print ("state change %d -> %d\n", b, !b);
-
-  g_application_release (application);
 }
 
 static void

gio/tests/gapplication-example-cmdline.c

@@ -10,8 +10,6 @@ command_line (GApplication            *application,
   gint argc;
   gint i;
 
-  g_application_hold (application);
-
   argv = g_application_command_line_get_arguments (cmdline, &argc);
 
   g_application_command_line_print (cmdline,
@@ -23,8 +21,6 @@ command_line (GApplication            *application,
 
   g_strfreev (argv);
 
-  g_application_release (application);
-
   return 0;
 }
 

gio/tests/gapplication-example-cmdline2.c

@@ -10,8 +10,6 @@ command_line (GApplication            *application,
   gint argc;
   gint i;
 
-  g_application_hold (application);
-
   argv = g_application_command_line_get_arguments (cmdline, &argc);
 
   for (i = 0; i < argc; i++)
@@ -19,8 +17,6 @@ command_line (GApplication            *application,
 
   g_strfreev (argv);
 
-  g_application_release (application);
-
   return 0;
 }
 

gio/tests/gapplication-example-open.c

@@ -5,9 +5,13 @@
 static void
 activate (GApplication *application)
 {
-  g_application_hold (application);
   g_print ("activated\n");
-  g_application_release (application);
+
+  /* Note: when doing a longer-lasting action here that returns
+   * to the mainloop, you should use g_application_hold() and
+   * g_application_release() to keep the application alive until
+   * the action is completed.
+   */
 }
 
 static void
@@ -18,8 +22,6 @@ open (GApplication  *application,
 {
   gint i;
 
-  g_application_hold (application);
-
   for (i = 0; i < n_files; i++)
     {
       gchar *uri = g_file_get_uri (files[i]);
@@ -27,7 +29,11 @@ open (GApplication  *application,
       g_free (uri);
     }
 
-  g_application_release (application);
+  /* Note: when doing a longer-lasting action here that returns
+   * to the mainloop, you should use g_application_hold() and
+   * g_application_release() to keep the application alive until
+   * the action is completed.
+   */
 }
 
 int