Merge portals-gtk and portals-qt into portals, add a note about the u…

…se of portal-gtk
flatpak · Nov 22, 2022 · 0b8962f · 0b8962f
1 parent 8c55966
commit 0b8962f
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 17 deletions.
diff --git a/docs/desktop-integration.rst b/docs/desktop-integration.rst
@@ -38,13 +38,12 @@ including:
 - Showing notifications
 - Taking screenshots and screencasts
 
-Toolkits like GTK and Qt provide transparent support for portals:
+Toolkits like GTK and Qt provide transparent support for portals.
 
 .. toctree::
-   :maxdepth: 2
+  :maxdepth: 1
 
-   portals-gtk
-   portals-qt
+  portals
 
 If you are not using one of these toolkits, it is possible to access
 the portals API directly. See the `Portals API documentation

diff --git a/docs/portals-qt.rst b/docs/portals-qt.rst
diff --git a/docs/portals-gtk.rst → docs/portals.rst b/docs/portals-gtk.rst → docs/portals.rst
@@ -17,3 +17,20 @@ applications should do to benefit from this.
 - Use ``g_application_send_notification()`` to show notifications
 - Use the ``GtkApplication::screensaver-active`` property to monitor
   scrensaver status
+
+Additionally, xdg-desktop-portal-gtk is required for GTK themes and fonts.
+It is also used as a fallback for the filepicker if the main xdg-desktop-portal implementation doesn't support filepicking.
+
+Portal support in Qt and KDE
+=============================
+
+Qt and KDE libraries will transparently use portals for some functionality when
+they detect that they are being used inside a Flatpak sandbox. Here are some
+hints for what Qt or KDE applications should do to benefit from this.
+
+- Use ``QDesktopServices::openUrl(const QUrl &url)`` or ``KIO::OpenUrlJob`` to
+  open URIs or send an email when using ``mailto`` URL
+- Use ``QFileDialog`` class to open files and, as of Qt ``5.18.90``, directories. Avoid using
+  ``QFileDialog::DontUseNativeDialog``. Note that portals cannot currently
+  give access to directories on the host filesystem
+- Use ``KNotification::notify()`` to show notification