From 406bafecc640ad002e33f90d99e5338fb0d3e88c Mon Sep 17 00:00:00 2001
From: Manolo Gouy <Manolo>
Date: Fri, 19 Oct 2012 09:23:05 +0000
Subject: [PATCH] Documented the fl_fopen() utility function.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@9702 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
---
 FL/Fl_Native_File_Chooser.H    | 5 +++++
 documentation/src/osissues.dox | 6 ++++++
 src/Fl_File_Chooser2.cxx       | 5 +++++
 src/fl_utf8.cxx                | 8 ++++++++
 4 files changed, 24 insertions(+)

diff --git a/FL/Fl_Native_File_Chooser.H b/FL/Fl_Native_File_Chooser.H
index fcc4b2bfb..32e500c6f 100644
--- a/FL/Fl_Native_File_Chooser.H
+++ b/FL/Fl_Native_File_Chooser.H
@@ -83,6 +83,11 @@
  }
  \endcode
  
+ The Fl_Native_File_Chooser widget transmits UTF-8 encoded filenames to its user. It is
+ recommended to open files that may have non-ASCII names with the fl_fopen() utility 
+ function that handles these names in a cross-platform way (whereas the standard 
+ fopen() function fails on the MSWindows platform to open files with a non-ASCII name).
+ 
  <B>Platform Specific Caveats</B>
  
  - Under X windows, it's best if you call Fl_File_Icon::load_system_icons()
diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox
index ded59bc89..58d960896 100644
--- a/documentation/src/osissues.dox
+++ b/documentation/src/osissues.dox
@@ -473,6 +473,12 @@ match is found, a global search is done (e.g.
 The Windows interface provides access to the WIN32 GDI
 state information and data structures.
 
+\subsection non_ascii_filenames Using filenames with non-ASCII characters
+
+In FLTK, all strings, including filenames, are UTF-8 encoded. The utility function
+fl_fopen() allows to open files potentially having non-ASCII names in a 
+cross-platform fashion, whereas the standard fopen() function fails to do so.
+
 \subsection osissues_win32_messages Handling Other WIN32 Messages
 
 By default a single WNDCLASSEX called "FLTK" is
diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx
index bed7b85b7..d192f636e 100644
--- a/src/Fl_File_Chooser2.cxx
+++ b/src/Fl_File_Chooser2.cxx
@@ -26,6 +26,11 @@
   
   \image html Fl_File_Chooser.jpg 
   \image latex  Fl_File_Chooser.jpg "Fl_File_Chooser" width=12cm
+ 
+ The Fl_File_Chooser widget transmits UTF-8 encoded filenames to its user. It is
+ recommended to open files that may have non-ASCII names with the fl_fopen() utility 
+ function that handles these names in a cross-platform way (whereas the standard 
+ fopen() function fails on the MSWindows platform to open files with a non-ASCII name).
   
   The Fl_File_Chooser class also exports several static values
   that may be used to localize or customize the appearance of all file chooser
diff --git a/src/fl_utf8.cxx b/src/fl_utf8.cxx
index fe67f3954..3b2f9a553 100644
--- a/src/fl_utf8.cxx
+++ b/src/fl_utf8.cxx
@@ -541,6 +541,14 @@ int fl_open(const char* f, int oflags, ...)
 #endif
 }
 
+/** Cross-platform function to open files with a UTF-8 encoded name.
+ 
+ This function is especially useful under the MSWindows platform where the 
+ standard fopen() function fails with UTF-8 encoded non-ASCII filenames.
+ \param f  the UTF-8 encoded filename
+ \param mode  same as the second argument of the standard fopen() function
+ \return  a FILE pointer upon successful completion, or NULL in case of error.
+ */
 FILE *fl_fopen(const char* f, const char *mode)
 {
 #if  defined (WIN32) && !defined(__CYGWIN__)