doxygen comments for undocumented features of Fl_File_Chooser

- needed to use new doxygen comment feature in fluid to provide comments for
  the various static const char* member variables (eg add_favorites_label).
  I had not been able to work out how to add the comments "out-of-code" in
  src/Fl_File_Chooser2.cxx without getting unpredictable end-results.

- needed to add doxygen comments for newButton and previewButton to the
  "out-of-code" comments in src/Fl_File_Chooser2.cxx because the new doxygen
  comment feature in fluid doesn't extend to widget member variables :-(

- added some missing "out-of-code" comments about customization/copying.



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

4 files changed, 92 insertions, 22 deletions

diff --git a/FL/Fl_File_Chooser.H b/FL/Fl_File_Chooser.H
index 1f0216fa1..026395eee 100644
--- a/FL/Fl_File_Chooser.H
+++ b/FL/Fl_File_Chooser.H
@@ -25,9 +25,6 @@
 //     http://www.fltk.org/str.php
 //
 
-/** \file
-   Fl_File_Chooser widget . */
-
 // generated by Fast Light User Interface Designer (fluid) version 1.0300
 
 #ifndef Fl_File_Chooser_H
@@ -164,19 +161,62 @@ public:
   const char *value(int f = 1); 
   void value(const char *filename); 
   int visible();
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *add_favorites_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *all_files_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *custom_filter_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *existing_file_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *favorites_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *filename_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *filesystems_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *manage_favorites_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *new_directory_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *new_directory_tooltip; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *preview_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *save_label; 
+  /**
+     [standard text may be customized at run-time]
+  */
   static const char *show_label; 
+  /**
+     the sort function that is used when loading
+     the contents of a directory.
+  */
   static Fl_File_Sort_F *sort; 
 private:
   Fl_Widget* ext_group; 
diff --git a/src/Fl_File_Chooser.cxx b/src/Fl_File_Chooser.cxx
index 672d1a3ed..40df826cf 100644
--- a/src/Fl_File_Chooser.cxx
+++ b/src/Fl_File_Chooser.cxx
@@ -173,7 +173,7 @@ Fl_File_Chooser::Fl_File_Chooser(const char *d, const char *p, int t, const char
       { favoritesButton = new Fl_Menu_Button(290, 10, 155, 25, "Favorites");
         favoritesButton->down_box(FL_BORDER_BOX);
         favoritesButton->callback((Fl_Callback*)cb_favoritesButton);
-        favoritesButton->align(FL_ALIGN_LEFT|FL_ALIGN_INSIDE);
+        favoritesButton->align(Fl_Align(FL_ALIGN_LEFT|FL_ALIGN_INSIDE));
         favoritesButton->label(favorites_label);
       } // Fl_Menu_Button* favoritesButton
       { Fl_Button* o = newButton = new Fl_Button(455, 10, 25, 25);
@@ -194,7 +194,7 @@ Fl_File_Chooser::Fl_File_Chooser(const char *d, const char *p, int t, const char
       { previewBox = new Fl_Box(305, 45, 175, 225, "?");
         previewBox->box(FL_DOWN_BOX);
         previewBox->labelsize(100);
-        previewBox->align(FL_ALIGN_CLIP|FL_ALIGN_INSIDE);
+        previewBox->align(Fl_Align(FL_ALIGN_CLIP|FL_ALIGN_INSIDE));
       } // Fl_Box* previewBox
       o->end();
       Fl_Group::current()->resizable(o);
@@ -222,7 +222,7 @@ Fl_File_Chooser::Fl_File_Chooser(const char *d, const char *p, int t, const char
       } // Fl_File_Input* fileName
       { Fl_Box* o = new Fl_Box(10, 310, 105, 25, "Filename:");
         o->labelfont(1);
-        o->align(FL_ALIGN_RIGHT|FL_ALIGN_INSIDE);
+        o->align(Fl_Align(FL_ALIGN_RIGHT|FL_ALIGN_INSIDE));
         o->label(filename_label);
       } // Fl_Box* o
       { Fl_Group* o = new Fl_Group(10, 345, 470, 25);
diff --git a/src/Fl_File_Chooser.fl b/src/Fl_File_Chooser.fl
index beaef51c8..44f6b6499 100644
--- a/src/Fl_File_Chooser.fl
+++ b/src/Fl_File_Chooser.fl
@@ -379,33 +379,48 @@ else
   } {
     code {return window->visible();} {}
   }
-  decl {static const char *add_favorites_label;} {public
+  decl {static const char *add_favorites_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *all_files_label;} {public
+  decl {static const char *all_files_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *custom_filter_label;} {public
+  decl {static const char *custom_filter_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *existing_file_label;} {public
+  decl {static const char *existing_file_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *favorites_label;} {public
+  decl {static const char *favorites_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *filename_label;} {public
+  decl {static const char *filename_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *filesystems_label;} {public
+  decl {static const char *filesystems_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *manage_favorites_label;} {public
+  decl {static const char *manage_favorites_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *new_directory_label;} {public
+  decl {static const char *new_directory_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *new_directory_tooltip;} {public
+  decl {static const char *new_directory_tooltip;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *preview_label;} {public
+  decl {static const char *preview_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *save_label;} {public
+  decl {static const char *save_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static const char *show_label;} {public
+  decl {static const char *show_label;} {
+    comment {[standard text may be customized at run-time]} public
   }
-  decl {static Fl_File_Sort_F *sort;} {public
+  decl {static Fl_File_Sort_F *sort;} {
+    comment {the sort function that is used when loading
+the contents of a directory.} public
   }
   decl {Fl_Widget* ext_group;} {}
   decl {bool ext_managed;} {}
diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx
index 0484b5f3d..02dfdc665 100644
--- a/src/Fl_File_Chooser2.cxx
+++ b/src/Fl_File_Chooser2.cxx
@@ -100,8 +100,13 @@
   	<TD>fl_numericsort</TD>
   </TR>
   </TABLE></CENTER>
-  <P>The sort member specifies the sort function that is
-  used when loading the contents of a directory.
+  <P>The Fl_File_Chooser::sort member specifies the sort function that is
+  used when loading the contents of a directory and can be customized
+  at run-time.
+  <P>The Fl_File_Chooser class also exports the Fl_File_Chooser::newButton
+  and Fl_File_Chooser::previewButton widgets so that application developers
+  can control their appearance and use.  For more complex customization,
+  consider copying the FLTK file chooser code and changing it accordingly.
 */
 
 /** \fn Fl_File_Chooser::Fl_File_Chooser(const char *pathname, const char *pattern, int type, const char *title)
@@ -145,6 +150,16 @@
   Fl_File_Chooser window.
 */
 
+/** \var Fl_File_Chooser::newButton
+  The "new directory" button is exported so that application developers
+  can control the appearance and use.
+*/
+
+/** \var Fl_File_Chooser::previewButton
+  The "preview" button is exported so that application developers can
+  control the appearance and use.
+*/
+
 /** \fn Fl_File_Chooser::~Fl_File_Chooser()
   Destroys the widget and frees all memory used by it.*/