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

diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index 0a00e5a614a578b7745a6f9396493314ec65b5e9..a20d53674c1440297273a27f2bb175ae9ee9de30 100644 (file)
--- 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 f4e3feb8aa891beb6bcb6dcd1835f0607b2a8ee9..9df0743509136a55304b725106aa6d1783d17d4d 100644 (file)
--- 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,