From 20025b41a432c91ce49dcd6de131ea1f67ce0463 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 11 Jun 2016 10:44:08 -0400 Subject: [PATCH] Add some docs Mention the portal case in the general native file chooser docs, and give some details. --- gtk/gtkfilechoosernative.c | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/gtk/gtkfilechoosernative.c b/gtk/gtkfilechoosernative.c index 7290f7aea6..6e347eb54f 100644 --- a/gtk/gtkfilechoosernative.c +++ b/gtk/gtkfilechoosernative.c @@ -51,7 +51,10 @@ * for use with “File/Open” or “File/Save as” commands. By default, this * just uses a #GtkFileChooserDialog to implement the actual dialog. * However, on certain platforms, such as Windows, the native platform - * file chooser is uses instead. + * file chooser is uses instead. When the application is running in a + * sandboxed environment without direct filesystem access (such as Flatpak), + * #GtkFileChooserNative may call the proper APIs (portals) to let the user + * choose a file and make it available to the application. * * While the API of #GtkFileChooserNative closely mirrors #GtkFileChooserDialog, the main * difference is that there is no access to any #GtkWindow or #GtkWidget for the dialog. @@ -170,6 +173,20 @@ * * If any of these features are used the regular #GtkFileChooserDialog * will be used in place of the native one. + * + * ## Portal details ## {#gtkfilechooserdialognative-portal} + * + * When the org.freedesktop.portal.FileChooser portal is available on the + * session bus, it is used to bring up an out-of-process file chooser. Depending + * on the kind of session the application is running in, this may or may not + * be a GTK+ file chooser. In this situation, the following things are not + * supported and will be silently ignored: + * + * * Extra widgets added with gtk_file_chooser_set_extra_widget(). + * + * * Use of custom previews by connecting to #GtkFileChooser::update-preview. + * + * * Any #GtkFileFilter added with a custom filter. */ enum {