Fixes problem with doxygen docs showing incorrect #include reference

at top of docs that was confusing users into #include'ing the wrong file.
Problem described here: http://fltk.org/newsgroups.php?gfltk.development+v:11617



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8377 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 54 insertions, 0 deletions

diff --git a/FL/Fl_Native_File_Chooser.H b/FL/Fl_Native_File_Chooser.H
index 448eaa8b9..c4129fd53 100644
--- a/FL/Fl_Native_File_Chooser.H
+++ b/FL/Fl_Native_File_Chooser.H
@@ -26,6 +26,60 @@
 //     http://www.fltk.org/str.php
 //
 
+/* \file
+   Fl_Native_File_Chooser widget. */
+
+/**
+  \class Fl_Native_File_Chooser
+
+  This class lets an FLTK application easily and consistently access 
+  the operating system's native file chooser. Some operating systems 
+  have very complex and specific file choosers that many users want 
+  access to specifically, instead of FLTK's default file chooser(s). 
+
+  In cases where there is no native file browser, FLTK's own file browser
+  is used instead.
+
+  To use this widget correctly, use the following include in your code:
+  \code
+  #include <FL/Fl_Native_File_Chooser.H>
+  \endcode
+  Do not include the other Fl_Native_File_Choser_XXX.H files in your code;
+  those are platform specific files that will be included automatically
+  depending on your build platform.
+
+  The following example shows how to pick a single file:
+  \code
+  // Create and post the local native file chooser
+  #include <FL/Fl_Native_File_Chooser.H>
+  [..]
+  Fl_Native_File_Chooser fnfc;
+  fnfc.title("Pick a file");
+  fnfc.type(Fl_Native_File_Chooser::BROWSE_FILE);
+  fnfc.filter("Text\t*.txt\n"
+              "C Files\t*.{cxx,h,c}");
+  fnfc.directory("/var/tmp");           // default directory to use
+  // Show native chooser
+  switch ( fnfc.show() ) {
+    case -1: printf("ERROR: %s\n", fnfc.errmsg());    break;  // ERROR
+    case  1: printf("CANCEL\n");                      break;  // CANCEL
+    default: printf("PICKED: %s\n", fnfc.filename()); break;  // FILE CHOSEN
+  }
+  \endcode
+
+  <B>Platform Specific Caveats</B>
+
+  - Under X windows, it's best if you call Fl_File_Icon::load_system_icons()
+    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.
+  - Some operating systems support certain OS specific options; see 
+    Fl_Native_File_Chooser::options() for a list.
+
+  \image html Fl_Native_File_Chooser.png "The Fl_Native_File_Chooser on different platforms."
+  \image latex Fl_Native_File_Chooser.png "The Fl_Native_File_Chooser on different platforms" width=14cm
+
+*/
 #ifndef FL_NATIVE_FILE_CHOOSER_H
 #define FL_NATIVE_FILE_CHOOSER_H