From: Daniel Boles <dboles@src.gnome.org>
Date: Mon, 18 Sep 2017 23:05:09 +0000 (+0100)
Subject: Window: Clarify documentation of set_application()
X-Git-Tag: archive/raspbian/3.24.39-1+rpi1~1^2~65^2~39^2~162
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=47879de0901bb5521b6fa697be29d0b1adc499f8;p=gtk%2B3.0.git

Window: Clarify documentation of set_application()

Clarify that ::destroy, not ::hide*, removes a window from its app, by
replacing the mention of open windows with the blurb on destruction from
:application, completing commit 7db4bee4b62bc9b6f20ba4e599e8d030314984fd

Also link to the equivalent gtk_application_(add|remove)_window() calls,
since Application.add_window() already links back to Window:application.

* unless you use gtkmm…

https://bugzilla.gnome.org/show_bug.cgi?id=639931
---

diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 72db9a8e0f..9f1e52ab04 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -3515,12 +3515,20 @@ gtk_window_release_application (GtkWindow *window)
 /**
  * gtk_window_set_application:
  * @window: a #GtkWindow
- * @application: (allow-none): a #GtkApplication, or %NULL
+ * @application: (allow-none): a #GtkApplication, or %NULL to unset
  *
  * Sets or unsets the #GtkApplication associated with the window.
  *
- * The application will be kept alive for at least as long as the window
- * is open.
+ * The application will be kept alive for at least as long as it has any windows
+ * associated with it (see g_application_hold() for a way to keep it alive
+ * without windows).
+ *
+ * Normally, the connection between the application and the window will remain
+ * until the window is destroyed, but you can explicitly remove it by setting
+ * the @application to %NULL.
+ *
+ * This is equivalent to calling gtk_application_remove_window() and/or
+ * gtk_application_add_window() on the old/new applications as relevant.
  *
  * Since: 3.0
  **/