[gtk+] gtkshow: Prefer gtk_show_uri_on_window() which works for sandboxed apps

[Bastien Nocera <hadess src gnome org>]

commit 22ea1a535e889c53dd29c75797a2553d41cae1cb
Author: Bastien Nocera <hadess hadess net>
Date:   Wed Feb 15 13:35:13 2017 +0100

    gtkshow: Prefer gtk_show_uri_on_window() which works for sandboxed apps
    
    gtk_show_uri_on_window() will pass enough information for Portal helpers
    to allow dialogue parenting in Flatpak, gtk_show_uri() won't, so
    deprecate it.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=778678

 gtk/gtkshow.c |   35 +++++++++++++++++++++--------------
 gtk/gtkshow.h |    2 +-
 2 files changed, 22 insertions(+), 15 deletions(-)
---
diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index 0a00e5a..a20d536 100644
--- a/gtk/gtkshow.c
+++ b/gtk/gtkshow.c
@@ -33,18 +33,13 @@
  * @timestamp: a timestamp to prevent focus stealing
  * @error: a #GError that is returned in case of errors
  *
- * This is a convenience function for launching the default application
- * to show the uri. The uri must be of a form understood by GIO (i.e. you
- * need to install gvfs to get support for uri schemes such as http://
- * or ftp://, as only local files are handled by GIO itself).
- * Typical examples are
- * - `file:///home/gnome/pict.jpg`
- * - `http://www.gnome.org`
- * - `mailto:me gnome org`
+ * A convenience function for launching the default application
+ * to show the uri. Like gtk_show_uri_on_window(), but takes a screen
+ * as transient parent instead of a window.
  *
- * Ideally the timestamp is taken from the event triggering
- * the gtk_show_uri() call. If timestamp is not known you can take
- * %GDK_CURRENT_TIME.
+ * Note that this function is deprecated as it does not pass the necessary
+ * information for helpers to parent their dialog properly, when run from
+ * sandboxed applications for example.
  *
  * Returns: %TRUE on success, %FALSE on error
  *
@@ -114,9 +109,21 @@ window_handle_exported (GtkWindow  *window,
  * @timestamp: a timestamp to prevent focus stealing
  * @error: a #GError that is returned in case of errors
  *
- * A convenience function for launching the default application
- * to show the uri. Like gtk_show_uri(), but takes a window
- * as transient parent instead of a screen.
+ * This is a convenience function for launching the default application
+ * to show the uri. The uri must be of a form understood by GIO (i.e. you
+ * need to install gvfs to get support for uri schemes such as http://
+ * or ftp://, as only local files are handled by GIO itself).
+ * Typical examples are
+ * - `file:///home/gnome/pict.jpg`
+ * - `http://www.gnome.org`
+ * - `mailto:me gnome org`
+ *
+ * Ideally the timestamp is taken from the event triggering
+ * the gtk_show_uri() call. If timestamp is not known you can take
+ * %GDK_CURRENT_TIME.
+ *
+ * This is the recommended call to be used as it passes information
+ * necessary for sandbox helpers to parent their dialogs properly.
  *
  * Returns: %TRUE on success, %FALSE on error
  *
diff --git a/gtk/gtkshow.h b/gtk/gtkshow.h
index f4e3feb..9df0743 100644
--- a/gtk/gtkshow.h
+++ b/gtk/gtkshow.h
@@ -29,7 +29,7 @@
 
 G_BEGIN_DECLS
 
-GDK_AVAILABLE_IN_ALL
+GDK_DEPRECATED_IN_3_22_FOR(gtk_show_uri_on_window)
 gboolean gtk_show_uri  (GdkScreen   *screen,
                         const gchar *uri,
                         guint32      timestamp,