From b21a3910a967170c1a022f22ffa8ecb98c308f37 Mon Sep 17 00:00:00 2001
From: Albrecht Schlosser <albrechts.fltk@online.de>
Date: Wed, 31 Jan 2024 18:50:25 +0100
Subject: [PATCH] Improve documentation of Fl_Native_File_Chooser

Document restrictions imposed by the new system file chooser dialogs,
particularly by 'kdialog' and 'zenity' (Unix/X11/Wayland only).
---
 FL/Fl_Native_File_Chooser.H    |  4 ++-
 src/Fl_Native_File_Chooser.cxx | 45 +++++++++++++++++++++++++++-------
 2 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/FL/Fl_Native_File_Chooser.H b/FL/Fl_Native_File_Chooser.H
index fc54ef354..721d0c1f4 100644
--- a/FL/Fl_Native_File_Chooser.H
+++ b/FL/Fl_Native_File_Chooser.H
@@ -103,7 +103,7 @@ class Fl_Native_File_Chooser_Driver;
 
  <B>Platform Specific Caveats</B>
 
- - Under X11/Wayland,  what dialog opens is determined as follows:
+ - Under X11/Wayland the dialog is chosen as follows:
  -# If command \p zenity is available at run-time and if \p Fl::option(OPTION_FNFC_USES_ZENITY) is
  not turned off, the \p zenity -based dialog opens. This is expected to be more appropriate
  than other dialog forms for sandboxed apps.
@@ -119,6 +119,8 @@ class Fl_Native_File_Chooser_Driver;
  at the start of main(), to enable the nicer looking file browser widgets.
  Use the static public attributes of class Fl_File_Chooser to localize the browser.
 
+ \todo Improve documentation about selection of native file choosers on X11/Wayland.\n
+
  - Some operating systems support certain OS specific options; see
  Fl_Native_File_Chooser::options() for a list.
 
diff --git a/src/Fl_Native_File_Chooser.cxx b/src/Fl_Native_File_Chooser.cxx
index d9c99b265..2cafb019b 100644
--- a/src/Fl_Native_File_Chooser.cxx
+++ b/src/Fl_Native_File_Chooser.cxx
@@ -1,8 +1,8 @@
 //
 // FLTK native OS file chooser widget
 //
-// Copyright 1998-2016 by Bill Spitzak and others.
 // Copyright 2004 Greg Ercolano.
+// Copyright 1998-2024 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -184,20 +184,47 @@ int Fl_Native_File_Chooser::filters() const {
 }
 
 /**
- Sets which filter will be initially selected.
+  Sets which filter will be initially selected.
 
- The first filter is indexed as 0.
- If filter_value()==filters(), then "All Files" was chosen.
- If filter_value() > filters(), then a custom filter was set.
- */
+  The first filter is indexed as 0.
+  If filter_value() == filters(), then "All Files" was chosen.
+  If filter_value()  > filters(), then a custom filter was set.
+
+  Some "native" file choosers don't support this way to set the initial
+  filter type, particularly the system dialog based browsers:
+
+    - kdialog (KDE system dialog)
+    - zenity (another system dialog based chooser).
+
+  Note: this list may not be complete.
+
+  As far as we know these dialogs use the \b first item in the list of
+  filter values as the initial filter presented to the user.
+
+  \see filter(const char *f)
+*/
 void Fl_Native_File_Chooser::filter_value(int i) {
   platform_fnfc->filter_value(i);
 }
 
 /**
- Returns which filter value was last selected by the user.
- This is only valid if the chooser returns success.
- */
+  Returns which filter value was last selected by the user.
+
+  This is only valid if the chooser returns success and if the particular
+  file chooser supports it. Otherwise the value is not changed.
+
+  Some "native" file choosers don't support returning the filter selection
+  by the user, particularly the system dialog based browsers:
+
+    - kdialog (KDE system dialog)
+    - zenity (another system dialog based chooser).
+
+  Note: this list may not be complete.
+
+  These system file chooser dialogs don't return the filter value chosen by the user.
+
+  \see filter(const char *f)
+*/
 int Fl_Native_File_Chooser::filter_value() const {
   return platform_fnfc->filter_value();
 }