[gtk+/wip/session: 5/5] GtkApplication: document session management API

[Matthias Clasen <matthiasc src gnome org>]

commit 58b93f724e1fa7a0e11c4854580eb14afdd6d5d6
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jan 3 15:38:00 2012 -0500

    GtkApplication: document session management API

 docs/reference/gtk/gtk3-sections.txt |    8 ++
 gtk/gtkapplication.c                 |  174 +++++++++++++++++++++++++++++++++-
 2 files changed, 179 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index 02e7ce5..2bf277e 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -7007,6 +7007,14 @@ gtk_application_remove_window
 gtk_application_get_windows
 
 <SUBSECTION>
+GtkApplicationFlags
+gtk_application_quit_response
+GtkApplicationInhibitFlags
+gtk_application_inhibit
+gtk_application_uninhibit
+gtk_application_is_inhibited
+
+<SUBSECTION>
 gtk_application_get_app_menu
 gtk_application_set_app_menu
 gtk_application_get_menubar
diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c
index 661d8e5..3857f23 100644
--- a/gtk/gtkapplication.c
+++ b/gtk/gtkapplication.c
@@ -55,9 +55,10 @@
  * a one-size-fits-all application model.
  *
  * Currently, GtkApplication handles GTK+ initialization, application
- * uniqueness, provides some basic scriptability and desktop shell integration
- * by exporting actions and menus and manages a list of toplevel windows whose
- * life-cycle is automatically tied to the life-cycle of your application.
+ * uniqueness, session management, provides some basic scriptability and
+ * desktop shell integration by exporting actions and menus and manages a
+ * list of toplevel windows whose life-cycle is automatically tied to the
+ * life-cycle of your application.
  *
  * While GtkApplication works fine with plain #GtkWindows, it is recommended
  * to use it together with #GtkApplicationWindow.
@@ -98,6 +99,18 @@
  * </xi:include>
  * </programlisting>
  * </example>
+ *
+ * GtkApplication automatically registers with a session manager
+ * of the users session (unless you use the %GTK_APPLICATION_NO_SESSION
+ * flag) and allows to intercept the session end by connecting to
+ * the #GtkApplication::quit-requested signal. An application can
+ * block various ways to end the session with the gtk_application_inhibit()
+ * function. Typical use cases for this kind of inhibiting are
+ * long-running, uninterruptible operations, such as burning a CD
+ * or performing a disk backup. The session manager may not honor
+ * the inhibitor, but it can be expected to inform the user about
+ * the negative consequences of ending the session while inhibitors
+ * are present.
  */
 
 enum {
@@ -553,16 +566,68 @@ gtk_application_class_init (GtkApplicationClass *class)
                   g_cclosure_marshal_VOID__OBJECT,
                   G_TYPE_NONE, 1, GTK_TYPE_WINDOW);
 
+  /**
+   * GtkApplication::quit-requested:
+   * @application: the #GtkApplication
+   *
+   * Emitted when the session manager requests that the application
+   * exit (generally because the user is logging out). The application
+   * should decide whether or not it is willing to quit and then call
+   * g_application_quit_response(), passing %TRUE or %FALSE to give its
+   * answer to the session manager. It does not need to give an answer
+   * before returning from the signal handler; the answer can be given
+   * later on, but <emphasis>the application must not attempt to perform
+   * any actions or interact with the user</emphasis> in response to
+   * this signal. Any actions required for a clean shutdown should take
+   * place in response to the #GtkApplication::quit signal.
+   *
+   * The application should limit its operations until either the
+   * #GApplication::quit or #GtkApplication::quit-cancelled signals is
+   * emitted.
+   *
+   * If the application does not connect to this signal, then
+   * #GtkApplication will automatically return %TRUE on its behalf.
+   *
+   * Since: 3.4
+   */
   gtk_application_signals[QUIT_REQUESTED] =
     g_signal_new ("quit-requested", GTK_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
                   G_STRUCT_OFFSET (GtkApplicationClass, quit_requested),
                   NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
 
+  /**
+   * GtkApplication::quit-cancelled:
+   * @application: the #GtkApplication
+   *
+   * Emitted when the session manager decides to cancel a logout after
+   * the application has already agreed to quit. After receiving this
+   * signal, the application can go back to what it was doing before
+   * receiving the #GtkApplication::quit-requested signal.
+   *
+   * Since: 3.4
+   */
   gtk_application_signals[QUIT_CANCELLED] =
     g_signal_new ("quit-cancelled", GTK_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
                   G_STRUCT_OFFSET (GtkApplicationClass, quit_cancelled),
                   NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
 
+  /**
+   * GtkApplication::quit:
+   * @application: the #GtkApplication
+   *
+   * Emitted when the session manager wants the application to quit
+   * (generally because the user is logging out). The application
+   * should exit as soon as possible after receiving this signal; if
+   * it does not, the session manager may choose to forcibly kill it.
+   *
+   * Normally, an application would only be sent a ::quit if it
+   * agreed to quit in response to a #GtkApplication::quit-requested
+   * signal. However, this is not guaranteed; in some situations the
+   * session manager may decide to end the session without giving
+   * applications a chance to object.
+   *
+   * Since: 3.4
+   */
   gtk_application_signals[QUIT] =
     g_signal_new ("quit", GTK_TYPE_APPLICATION, G_SIGNAL_RUN_LAST,
                   G_STRUCT_OFFSET (GtkApplicationClass, quit),
@@ -885,6 +950,30 @@ gtk_application_get_menubar (GtkApplication *application)
 
 #ifdef GDK_WINDOWING_X11
 
+/**
+ * GtkApplicationFlags:
+ * @Gtk_APPLICATION_NO_SESSION: Don't register with the session manager.
+ *
+ * Flags that can be used in addition to #GApplicationFlags when creating
+ * a #GtkApplication.
+ *
+ * Since: 3.4
+ */
+
+/**
+ * GtkApplicationInhibitFlags:
+ * @GTK_APPLICATION_INHIBIT_LOGOUT: Inhibit logging out
+ * @GTK_APPLICATION_INHIBIT_SWITCH: Inhibit user switching
+ * @GTK_APPLICATION_INHIBIT_SUSPEND: Inhibit suspending the
+ *     session or computer
+ * @GTK_APPLICATION_INHIBIT_IDLE: Inhibit the session being
+ *     marked as idle
+ *
+ * Types of user actions that may be blocked by gtk_application_inhibit().
+ *
+ * Since: 3.4
+ */
+
 static void
 unregister_client (GtkApplication *app)
 {
@@ -1047,6 +1136,31 @@ gtk_application_startup_session_dbus (GtkApplication *app)
   g_signal_connect (app->priv->client_proxy, "g-signal", G_CALLBACK (client_proxy_signal), app);
 }
 
+/**
+ * gtk_application_quit_response:
+ * @application: the #GtkApplication
+ * @will_quit: whether the application agrees to quit
+ * @reason: (allow-none): a short human-readable string that explains
+ *     why quitting is not possible
+ *
+ * This function <emphasis>must</emphasis> be called in response to the
+ * #GtkApplication::quit-requested signal, to indicate whether or
+ * not the application is willing to quit. The application may call
+ * it either directly from the signal handler, or at some later point.
+ *
+ * It should be stressed that <emphasis>applications should not assume
+ * that they have the ability to block logout or shutdown</emphasis>,
+ * even when %FALSE is passed for @will_quit.
+ *
+ * After calling this method, the application should wait to receive
+ * either #GtkApplication::quit-cancelled or #GtkApplication::quit.
+ *
+ * If the application does not connect to #GtkApplication::quit-requested,
+ * #GtkApplication will call this method on its behalf (passing %TRUE
+ * for @will_quit).
+ *
+ * Since: 3.4
+ */
 void
 gtk_application_quit_response (GtkApplication *application,
                                gboolean        will_quit,
@@ -1065,6 +1179,39 @@ gtk_application_quit_response (GtkApplication *application,
                      NULL, NULL, NULL);
 }
 
+/**
+ * gtk_application_inhibit:
+ * @application: the #GApplication
+ * @window: (allow-none): a #GtkWindow, or %NULL
+ * @flags: what types of actions should be inhibited
+ * @reason: (allow-none): a short, human-readable string that explains
+ *     why these operations are inhibited
+ *
+ * Inform the session manager that certain types of actions should be
+ * inhibited.
+ *
+ * Applications should invoke this method when they begin an operation
+ * that should not be interrupted, such as creating a CD or DVD. The
+ * types of actions that may be blocked are specified by the @flags
+ * parameter. When the application completes the operation it should
+ * call g_application_uninhibit() to remove the inhibitor. Inhibitors
+ * are also cleared when the application exits.
+ *
+ * Applications should not expect that they will always be able to block
+ * the action. In most cases, users will be given the option to force
+ * the action to take place.
+ *
+ * Reasons should be short and to the point.
+ *
+ * If a window is passed, the session manager may point the user to
+ * this window to find out more about why the action is inhibited.
+ *
+ * Returns: A cookie that is used to uniquely identify this request.
+ *     It should be used as an argument to g_application_uninhibit()
+ *     in order to remove the request.
+ *
+ * Since: 3.4
+ */
 guint
 gtk_application_inhibit (GtkApplication             *application,
                          GtkWindow                  *window,
@@ -1110,6 +1257,15 @@ gtk_application_inhibit (GtkApplication             *application,
   return cookie;
 }
 
+/**
+ * gtk_application_uninhibit:
+ * @application: the #GApplication
+ * @cookie: a cookie that was returned by g_application_inhibit()
+ *
+ * Removes an inhibitor that has been established with g_application_inhibit().
+ *
+ * Since: 3.4
+ */
 void
 gtk_application_uninhibit (GtkApplication *application,
                            guint           cookie)
@@ -1139,6 +1295,18 @@ gtk_application_uninhibit (GtkApplication *application,
   g_variant_unref (res);
 }
 
+/**
+ * gtk_application_is_inhibited:
+ * @application: the #GApplication
+ * @flags: what types of actions should be queried
+ *
+ * Determines if any of the actions specified in @flags are
+ * currently inhibited (possibly by another application).
+ *
+ * Returns: %TRUE if any of the actions specified in @flags are inhibited
+ *
+ * Since: 3.4
+ */
 gboolean
 gtk_application_is_inhibited (GtkApplication             *application,
                               GtkApplicationInhibitFlags  flags)