Doxygen Documentation WP2 done.

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

15 files changed, 787 insertions, 24 deletions

diff --git a/FL/Fl_Browser.H b/FL/Fl_Browser.H
index 6b05f824c..447150a4a 100644
--- a/FL/Fl_Browser.H
+++ b/FL/Fl_Browser.H
@@ -36,6 +36,35 @@
 
 struct FL_BLINE;
 
+/**
+  The Fl_Browser widget displays a scrolling list of text
+  lines, and manages all the storage for the text.  This is not a text
+  editor or spreadsheet!  But it is useful for showing a vertical list of
+  named objects to the user.
+  <P>Each line in the browser is identified by number. <I>The numbers
+  start at one</I> (this is so that zero can be reserved for &quot;no line&quot; in
+  the selective browsers). <I>Unless otherwise noted, the methods do not
+  check to see if the passed line number is in range and legal.  It must
+  always be greater than zero and &lt;= size().</I></P>
+  <P>Each line contains a null-terminated string of text and a void *
+  data pointer.  The text string is displayed, the void *
+  pointer can be used by the callbacks to reference the object the text
+  describes. </P>
+  <P>The base does nothing when the user clicks on it.  The
+  subclasses 
+  Fl_Select_Browser, 
+  Fl_Hold_Browser, and 
+  Fl_Multi_Browser react to user clicks to select lines in
+  the browser and do callbacks. </P>
+  <P>The base called 
+  Fl_Browser_ provides the scrolling and selection mechanisms of
+  this and all the subclasses, but the dimensions and appearance of each
+  item are determined by the subclass. You can use Fl_Browser_
+  to display information other than text, or text that is dynamically
+  produced from your own data structures. If you find that loading the
+  browser is a lot of work or is inefficient, you may want to make a
+  subof Fl_Browser_.
+*/
 class FL_EXPORT Fl_Browser : public Fl_Browser_ {
 
   FL_BLINE *first;		// the array of lines
@@ -78,14 +107,25 @@ public:
   void swap(int a, int b);
   void clear();
 
+  /**
+    Returns how many lines are in the browser.  The last line number is
+    equal to this.
+  */
   int size() const {return lines;}
   void size(int W, int H) { Fl_Widget::size(W, H); }
 
   int topline() const ;
   enum Fl_Line_Position { TOP, BOTTOM, MIDDLE };
   void lineposition(int, Fl_Line_Position);
+  /**
+    The first form returns the current top line in the browser. If there
+    is no vertical scrollbar then this will always return 1.
+    <P>The second form scrolls the browser so the top line in the browser is n.
+  */
   void topline(int l) { lineposition(l, TOP); }
+  /**    Scrolls the browser so the bottom line in the browser is n.  */
   void bottomline(int l) { lineposition(l, BOTTOM); }
+  /**    Scrolls the browser so the middle line in the browser is n.  */
   void middleline(int l) { lineposition(l, MIDDLE); }
 
   int select(int, int=1);
@@ -104,13 +144,72 @@ public:
   void data(int, void* v);
 
   Fl_Browser(int, int, int, int, const char* = 0);
+  /** The destructor deletes all list items and destroys the browser.*/
   ~Fl_Browser() { clear(); }
 
+  /**
+    The first form gets the current format code prefix character, which by
+    default is @. A string of formatting codes at the start of
+    each column are stripped off and used to modify how the rest of the
+    line is printed:
+    <UL>
+    <LI>@. Print rest of line, don't look for more '@' signs </LI>
+    <LI>@@ Print rest of line starting with '@' </LI>
+    <LI>@l Use a <BIG>large</BIG> (24 point) font </LI>
+    <LI>@m Use a <BIG>medium large</BIG> (18 point) font </LI>
+    <LI>@s Use a <SMALL>small</SMALL> (11 point) font </LI>
+    <LI>@b Use a <B>bold</B> font (adds FL_BOLD to font) </LI>
+    <LI>@i Use an <I>italic</I> font (adds FL_ITALIC to font) </LI>
+    <LI>@f or @t Use a fixed-pitch
+    font (sets font to FL_COURIER) </LI>
+    <LI>@c Center the line horizontally </LI>
+    <LI>@r Right-justify the text </LI>
+    <LI>@B0, @B1, ... @B255 Fill the backgound with
+    fl_color(n) </LI>
+    <LI>@C0, @C1, ... @C255 Use fl_color(n) to draw the text </LI>
+    <LI>@F0, @F1, ...  Use fl_font(n) to draw the text </LI>
+    <LI>@S1, @S2, ...  Use point size n to draw the text </LI>
+    <LI>@u or @_ Underline the text. </LI>
+    <LI>@- draw an engraved line through the middle. </LI>
+    </UL>
+    Notice that the @. command can be used to reliably
+    terminate the parsing.  To print a random string in a random color, use 
+    sprintf(&quot;@C%d@.%s&quot;, color, string) and it will work even if the
+    string starts with a digit or has the format character in it.
+    <P>The second form sets the current prefix to c.  Set the
+    prefix to 0 to disable formatting.
+  */
   char format_char() const {return format_char_;}
+  /**    See uchar Fl_Browser::format_char() const   */
   void format_char(char c) {format_char_ = c;}
+  /**
+    The first form gets the current column separator character. By default
+    this is '\t' (tab).
+    <P>The second form sets the column separator to c. This will
+    only have an effect if you also set column_widths().
+  */
   char column_char() const {return column_char_;}
+  /**
+    The first form gets the current column separator character. By default
+    this is '\t' (tab).
+    <P>The second form sets the column separator to c. This will
+    only have an effect if you also set column_widths().
+  */
   void column_char(char c) {column_char_ = c;}
+  /**
+    The first form gets the current column width array.  This array is
+    zero-terminated and specifies the widths in pixels of each column. The
+    text is split at each column_char() and each part is formatted
+    into it's own column.  After the last column any remaining text is
+    formatted into the space between the last column and the right edge of
+    the browser, even if the text contains instances of column_char()
+    .  The default value is a one-element array of just a zero, which makes
+    there are no columns.
+    <P>The second form sets the current array to w.  Make sure the
+    last entry is zero.
+  */
   const int* column_widths() const {return column_widths_;}
+  /**    See const int *Fl_Browser::column_widths() const   */
   void column_widths(const int* l) {column_widths_ = l;}
 
   int displayed(int n) const {return Fl_Browser_::displayed(find_line(n));}
diff --git a/FL/Fl_Browser_.H b/FL/Fl_Browser_.H
index 7db4be5c3..f8ee3ca1c 100644
--- a/FL/Fl_Browser_.H
+++ b/FL/Fl_Browser_.H
@@ -45,6 +45,21 @@
 #define FL_HOLD_BROWSER		2
 #define FL_MULTI_BROWSER	3
 
+/**
+  This is the base for browsers.  To be useful it must be
+  subclassed and several virtual functions defined.  The Forms-compatible
+  browser and the file chooser's browser are subclassed off of this.
+  <P>This has been designed so that the subhas complete control
+  over the storage of the data, although because next() and 
+  prev() functions are used to index, it works best as a linked list
+  or as a large block of characters in which the line breaks must be
+  searched for. </P>
+  <P>A great deal of work has been done so that the &quot;height&quot; of a data
+  object does not need to be determined until it is drawn.  This is
+  useful if actually figuring out the size of an object requires
+  accessing image data or doing stat() on a file or doing some
+  other slow operation.
+*/
 class FL_EXPORT Fl_Browser_ : public Fl_Group {
   int position_;	// where user wants it scrolled to
   int real_position_;	// the current vertical scrolling position
@@ -68,12 +83,30 @@ class FL_EXPORT Fl_Browser_ : public Fl_Group {
 protected:
 
   // All of the following must be supplied by the subclass:
-  virtual void *item_first() const = 0;
-  virtual void *item_next(void *) const = 0;
-  virtual void *item_prev(void *) const = 0;
+  /** This method must be provided by the subclass to return the first item in  the list. */
+    virtual void *item_first() const = 0;
+  /** This method must be provided by the subclass to return the item in the list after p. */
+    virtual void *item_next(void *) const = 0;
+  /** This method must be provided by the subclass to return the item in the list before p. */
+    virtual void *item_prev(void *) const = 0;
+  /** 
+    This method must be provided by the subclass to return the height of the
+    item p in pixels.  Allow for two additional pixels for the list
+    selection box.
+  */
   virtual int item_height(void *) const = 0;
+  /**
+    This method must be provided by the subclass to return the width of the
+    item p in pixels.  Allow for two additional pixels for the list
+    selection box.
+  */
   virtual int item_width(void *) const = 0;
   virtual int item_quick_height(void *) const ;
+  /**
+    This method must be provided by the subclass to draw the item
+    p in the area indicated by x, y, w,
+    and h.
+  */
   virtual void item_draw(void *,int,int,int,int) const = 0;
   // you don't have to provide these but it may help speed it up:
   virtual int full_width() const ;	// current width of all items
@@ -84,7 +117,16 @@ protected:
   virtual int item_selected(void *) const ;
 
   // things the subclass may want to call:
+  /**  Returns the item the appears at the top of the list.  */
   void *top() const {return top_;}
+  /**
+    Returns the item currently selected, or NULL if there is no selection.
+    
+    <P>For multiple selection browsers this call returns the currently focused item,
+    even if it is not selected. To find all selected items, call 
+    
+    Fl_Multi_Browser::selected() for every item in question.
+  */
   void *selection() const {return selection_;}
   void new_list(); // completely clobber all data, as though list replaced
   void deleting(void *a); // get rid of any pointers to a
@@ -93,10 +135,17 @@ protected:
   void inserting(void *a,void *b); // insert b near a
   int displayed(void *) const ; // true if this line is visible
   void redraw_line(void *); // minimal update, no change in size
+  /**    This method will cause the entire list to be redrawn.  */
   void redraw_lines() {damage(FL_DAMAGE_SCROLL);} // redraw all of them
   void bbox(int&,int&,int&,int&) const;
   int leftedge() const;	// x position after scrollbar & border
   void *find_item(int my); // item under mouse
+  /**
+    The first form draws the list within the normal widget bounding box.
+    
+    <P>The second form draws the contents of the browser within the
+    specified bounding box.
+  */
   void draw(int,int,int,int);
   int handle(int,int,int,int,int);
 
@@ -114,13 +163,51 @@ public:
   int select(void *,int=1,int docallbacks=0);
   int select_only(void *,int docallbacks=0);
   int deselect(int docallbacks=0);
+  /**
+    Gets or sets the vertical scrolling position of the list,
+    which is the pixel offset of the list items within the list
+    area.
+  */
   int position() const {return position_;}
+  /**
+    Gets or sets the horizontal scrolling position of the list,
+    which is the pixel offset of the list items within the list
+    area.
+  */
   int hposition() const {return hposition_;}
   void position(int); // scroll to here
   void hposition(int); // pan to here
   void display(void*); // scroll so this item is shown
-
+  /** See Fl_Browser_::has_scrollbar(uchar) */
   uchar has_scrollbar() const {return has_scrollbar_;}
+  /**
+    By default you can scroll in both directions, and the scrollbars
+    disappear if the data will fit in the widget.  has_scrollbar() changes
+    this based on the value of h:
+  
+    <UL>
+  
+  	<LI>0 - No scrollbars.
+  
+  	<LI>Fl_Browser_::HORIZONTAL - Only a horizontal
+  	scrollbar.
+  
+  	<LI>Fl_Browser_::VERTICAL - Only a vertical
+  	scrollbar.
+  
+  	<LI>Fl_Browser_::BOTH - The default is both
+  	scrollbars.
+  
+  	<LI>Fl_Browser_::HORIZONTAL_ALWAYS - Horizontal
+  	scrollbar always on, vertical always off.
+  
+  	<LI>Fl_Browser_::VERTICAL_ALWAYS - Vertical
+  	scrollbar always on, horizontal always off.
+  
+  	<LI>Fl_Browser_::BOTH_ALWAYS - Both always on.
+  
+    </UL>
+  */
   void has_scrollbar(uchar i) {has_scrollbar_ = i;}
   enum { // values for has_scrollbar()
     HORIZONTAL = 1,
@@ -132,18 +219,46 @@ public:
     BOTH_ALWAYS = 7
   };
 
+  /**
+    The first form gets the default text font for the lines in the
+    browser.
+    
+    <P>The second form sets the default text font to font
+  */
   Fl_Font textfont() const {return textfont_;}
+  /**
+    The first form gets the default text font for the lines in the
+    browser.
+    
+    <P>The second form sets the default text font to font
+  */
   void textfont(Fl_Font s) {textfont_ = s;}
+  /**
+    The first form gets the default text size for the lines in the
+    browser.
+    
+    <P>The second form sets the default text size to size
+  */
   Fl_Fontsize textsize() const {return textsize_;}
   void textsize(Fl_Fontsize s) {textsize_ = s;}
+  /**
+    The first form gets the default text color for the lines in the
+    browser.
+    
+    <P>The second form sets the default text color to color
+  */
   Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
   void textcolor(unsigned n) {textcolor_ = n;}
 
+  /**    Sets or gets the width of any scrollbars that are used.  */
   static void scrollbar_width(int b) {scrollbar_width_ = b;}
+  /**    Sets or gets the width of any scrollbars that are used.  */
   static int scrollbar_width() {return scrollbar_width_;}
 
   // for back compatability:
+  /**    This method moves the vertical scrollbar to the righthand side of the list.  */
   void scrollbar_right() {scrollbar.align(FL_ALIGN_RIGHT);}
+  /**    This method moves the vertical scrollbar to the lefthand side of the list.  */
   void scrollbar_left() {scrollbar.align(FL_ALIGN_LEFT);}
 
 };
diff --git a/FL/Fl_Check_Browser.H b/FL/Fl_Check_Browser.H
index 713f5cd56..a69e69288 100644
--- a/FL/Fl_Check_Browser.H
+++ b/FL/Fl_Check_Browser.H
@@ -31,6 +31,10 @@
 #include "Fl.H"
 #include "Fl_Browser_.H"
 
+/**
+  The Fl_Check_Browser widget displays a scrolling list of text
+  lines that may be selected and/or checked by the user.
+*/
 class FL_EXPORT Fl_Check_Browser : public Fl_Browser_ {
   /* required routines for Fl_Browser_ subclass: */
 
@@ -69,6 +73,7 @@ class FL_EXPORT Fl_Check_Browser : public Fl_Browser_ {
   public:
 
   Fl_Check_Browser(int x, int y, int w, int h, const char *l = 0);
+   /** The destructor deletes all list items and destroys the browser. */
   ~Fl_Check_Browser() { clear(); }
   int add(char *s);               // add an (unchecked) item
   int add(char *s, int b);        // add an item and set checked
@@ -76,14 +81,22 @@ class FL_EXPORT Fl_Check_Browser : public Fl_Browser_ {
   int remove(int item);           // delete an item. Returns nitems()
 
   // inline const char * methods to avoid breaking binary compatibility...
+   /** See int Fl_Check_Browser::add(char *s) */
   int add(const char *s) { return add((char *)s); }
+  /** See int Fl_Check_Browser::add(char *s) */
   int add(const char *s, int b) { return add((char *)s, b); }
 
   void clear();                   // delete all items
+  /**
+    Returns how many lines are in the browser.  The last line number is equal to
+    this.
+  */
   int nitems() const { return nitems_; }
+  /**    Returns how many items are currently checked.  */
   int nchecked() const { return nchecked_; }
   int checked(int item) const;
   void checked(int item, int b);
+  /**    Equivalent to Fl_Check_Browser::checked(item, 1).  */
   void set_checked(int item) { checked(item, 1); }
   void check_all();
   void check_none();
diff --git a/FL/Fl_File_Browser.H b/FL/Fl_File_Browser.H
index aed0647d5..747bd5c9e 100644
--- a/FL/Fl_File_Browser.H
+++ b/FL/Fl_File_Browser.H
@@ -41,6 +41,7 @@
 // Fl_File_Browser class...
 //
 
+/** The Fl_File_Browser widget displays a list of filenames, optionally with file-specific icons. */
 class FL_EXPORT Fl_File_Browser : public Fl_Browser
 {
   int		filetype_;
@@ -57,20 +58,55 @@ class FL_EXPORT Fl_File_Browser : public Fl_Browser
 public:
   enum { FILES, DIRECTORIES };
 
+  /**
+    The constructor creates the Fl_File_Browser widget at the specified position and size.
+    The destructor destroys the widget and frees all memory that has been allocated.
+  */
   Fl_File_Browser(int, int, int, int, const char * = 0);
 
+  /**    Sets or gets the size of the icons. The default size is 20 pixels.  */
   uchar		iconsize() const { return (iconsize_); };
+  /**    Sets or gets the size of the icons. The default size is 20 pixels.  */
   void		iconsize(uchar s) { iconsize_ = s; redraw(); };
 
+  /**
+    Sets or gets the filename filter. The pattern matching uses
+    the fl_filename_match()
+    function in FLTK.
+  */
   void	filter(const char *pattern);
+  /**
+    Sets or gets the filename filter. The pattern matching uses
+    the fl_filename_match()
+    function in FLTK.
+  */
   const char	*filter() const { return (pattern_); };
 
+  /**
+    Loads the specified directory into the browser. If icons have been
+    loaded then the correct icon is associated with each file in the list.
+    
+    <P>The sort argument specifies a sort function to be used with
+    fl_filename_list().
+  */
   int		load(const char *directory, Fl_File_Sort_F *sort = fl_numericsort);
 
   Fl_Fontsize  textsize() const { return Fl_Browser::textsize(); };
   void		textsize(Fl_Fontsize s) { Fl_Browser::textsize(s); iconsize_ = (uchar)(3 * s / 2); };
 
+  /**
+    Sets or gets the file browser type, FILES or
+    DIRECTORIES. When set to FILES, both
+    files and directories are shown. Otherwise only directories are
+    shown.
+  */
   int		filetype() const { return (filetype_); };
+  /**
+    Sets or gets the file browser type, FILES or
+    DIRECTORIES. When set to FILES, both
+    files and directories are shown. Otherwise only directories are
+    shown.
+  */
   void		filetype(int t) { filetype_ = t; };
 };
 
diff --git a/FL/Fl_Hold_Browser.H b/FL/Fl_Hold_Browser.H
index 6b5545b34..e09d52be6 100644
--- a/FL/Fl_Hold_Browser.H
+++ b/FL/Fl_Hold_Browser.H
@@ -30,9 +30,24 @@
 
 #include "Fl_Browser.H"
 
+/**
+  The Fl_Hold_Browser is a subclass of Fl_Browser
+  which lets the user select a single item, or no items by clicking on
+  the empty space.  As long as the mouse button is held down the item
+  pointed to by it is highlighted, and this highlighting remains on when
+  the mouse button is released. Normally the callback is done when the
+  user releases the mouse, but you can change this with when().
+  <P>See Fl_Browser for methods to add and remove lines from the browser.
+*/
 class Fl_Hold_Browser : public Fl_Browser {
 public:
-    Fl_Hold_Browser(int X,int Y,int W,int H,const char *l=0)
+  /**
+    Creates a new Fl_Hold_Browser widget using the given
+    position, size, and label string. The default boxtype is FL_DOWN_BOX.
+    The constructor specializes Fl_Browser() by setting the type to FL_HOLD_BROWSER.
+    The destructor destroys the widget and frees all memory that has been allocated.
+ */
+  Fl_Hold_Browser(int X,int Y,int W,int H,const char *l=0)
 	: Fl_Browser(X,Y,W,H,l) {type(FL_HOLD_BROWSER);}
 };
 
diff --git a/FL/Fl_Multi_Browser.H b/FL/Fl_Multi_Browser.H
index 17b31f3e9..0bd1c1f7c 100644
--- a/FL/Fl_Multi_Browser.H
+++ b/FL/Fl_Multi_Browser.H
@@ -30,8 +30,24 @@
 
 #include "Fl_Browser.H"
 
+/**
+  The Fl_Multi_Browser class is a subclass of Fl_Browser
+  which lets the user select any set of the lines.  The user interface
+  is Macintosh style: clicking an item turns off all the others and
+  selects that one, dragging selects all the items the mouse moves over,
+  and shift + click toggles the items. This is different then how forms
+  did it.  Normally the callback is done when the user releases the
+  mouse, but you can change this with when().
+  <P>See Fl_Browser for methods to add and remove lines from the browser.
+*/
 class Fl_Multi_Browser : public Fl_Browser {
 public:
+  /**
+      Creates a new Fl_Multi_Browser widget using the given
+    position, size, and label string. The default boxtype is FL_DOWN_BOX.
+    The constructor specializes Fl_Browser() by setting the type to FL_MULTI_BROWSER.
+    The destructor destroys the widget and frees all memory that has been allocated.
+  */
     Fl_Multi_Browser(int X,int Y,int W,int H,const char *L=0)
 	: Fl_Browser(X,Y,W,H,L) {type(FL_MULTI_BROWSER);}
 };
diff --git a/FL/Fl_Select_Browser.H b/FL/Fl_Select_Browser.H
index c055e76d2..304fac9be 100644
--- a/FL/Fl_Select_Browser.H
+++ b/FL/Fl_Select_Browser.H
@@ -30,9 +30,23 @@
 
 #include "Fl_Browser.H"
 
+/**
+  The class is a subclass of Fl_Browser
+  which lets the user select a single item, or no items by clicking on
+  the empty space.  As long as the mouse button is held down on an 
+  unselected item it is highlighted. Normally the callback is done when the
+  user presses the mouse, but you can change this with when().
+  <P>See Fl_Browser for  methods to add and remove lines from the browser.
+*/
 class Fl_Select_Browser : public Fl_Browser {
 public:
-    Fl_Select_Browser(int X,int Y,int W,int H,const char *l=0)
+  /** 
+    Creates a new Fl_Select_Browser widget using the given
+    position, size, and label string. The default boxtype is FL_DOWN_BOX.
+    The constructor specializes Fl_Browser() by setting the type to FL_SELECT_BROWSER.
+    The destructor destroys the widget and frees all memory that has been allocated.
+  */
+  Fl_Select_Browser(int X,int Y,int W,int H,const char *l=0)
 	: Fl_Browser(X,Y,W,H,l) {type(FL_SELECT_BROWSER);}
 };
 
diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index 41deefba5..fab179f7b 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -811,7 +811,8 @@ public:
   void damage(uchar c, int x, int y, int w, int h);
 
   void draw_label(int, int, int, int, Fl_Align) const;
-  void measure_label(int& xx, int& yy) {label_.measure(xx,yy);}
+  /** Sets width ww, height hh accordingly with the labeltype size, label with images will return w() h() of the image. */
+  void measure_label(int& ww, int& hh) {label_.measure(ww, hh);}
 
   /** Returns a pointer to the primary Fl_Window widget.
    *  \retval  NULL if no window is associated with this widget.  
diff --git a/documentation/todo_filelist_doc.txt b/documentation/todo_filelist_doc.txt
index 8264639b7..fca8239e8 100644
--- a/documentation/todo_filelist_doc.txt
+++ b/documentation/todo_filelist_doc.txt
@@ -10,7 +10,7 @@ header. Most other stuff goes into the source.
 In Progress Work List (add your WP and name here):
 
   - WP1  (Fabien) DONE
-  - WP2  (Fabien)
+  - WP2  (Fabien) DONE
   - WP3
   - WP4
   - WP5
diff --git a/src/Fl_Browser.cxx b/src/Fl_Browser.cxx
index 5e24bbce9..c7325b583 100644
--- a/src/Fl_Browser.cxx
+++ b/src/Fl_Browser.cxx
@@ -128,11 +128,16 @@ FL_BLINE* Fl_Browser::_remove(int line) {
   return(ttt);
 }
 
+/**  Remove line n and make the browser one line shorter.*/
 void Fl_Browser::remove(int line) {
   if (line < 1 || line > lines) return;
   free(_remove(line));
 }
 
+/**
+  Insert a new line <I>before</I> line n.  If n &gt; 
+  size() then the line is added to the end.
+*/
 void Fl_Browser::insert(int line, FL_BLINE* t) {
   if (!first) {
     t->prev = t->next = 0;
@@ -173,11 +178,25 @@ void Fl_Browser::insert(int line, const char* newtext, void* d) {
   insert(line, t);
 }
 
+/**
+  Line from is removed and reinserted at to; to
+  is calculated after the line is removed.
+*/
 void Fl_Browser::move(int to, int from) {
   if (from < 1 || from > lines) return;
   insert(to, _remove(from));
 }
 
+/**
+  The first form returns the text for line n.  If n is
+  out of range it returns NULL.
+  <P>The second form sets the text for line n.
+*/
+/**
+  The first form returns the text for line n.  If n is
+  out of range it returns NULL.
+  <P>The second form sets the text for line n.
+*/
 void Fl_Browser::text(int line, const char* newtext) {
   if (line < 1 || line > lines) return;
   FL_BLINE* t = find_line(line);
@@ -200,6 +219,16 @@ void Fl_Browser::text(int line, const char* newtext) {
   redraw_line(t);
 }
 
+/**
+  The first form returns the data for line n.  If n is
+  out of range this returns NULL.
+  <P>The second form sets the data for line n.
+*/
+/**
+  The first form returns the data for line n.  If n is
+  out of range this returns NULL.
+  <P>The second form sets the data for line n.
+*/
 void Fl_Browser::data(int line, void* d) {
   if (line < 1 || line > lines) return;
   find_line(line)->data = d;
@@ -392,8 +421,9 @@ void Fl_Browser::item_draw(void* v, int X, int Y, int W, int H) const {
 
 static const int no_columns[1] = {0};
 
+/**  The constructor makes an empty browser.*/
 Fl_Browser::Fl_Browser(int X, int Y, int W, int H, const char*l)
-  : Fl_Browser_(X, Y, W, H, l) {
+: Fl_Browser_(X, Y, W, H, l) {
   column_widths_ = no_columns;
   lines = 0;
   full_height_ = 0;
@@ -427,10 +457,16 @@ void Fl_Browser::lineposition(int line, Fl_Line_Position pos) {
   position(final);
 }
 
+/**
+  The first form returns the current top line in the browser. If there
+  is no vertical scrollbar then this will always return 1.
+  <P>The second form scrolls the browser so the top line in the browser is n.
+*/
 int Fl_Browser::topline() const {
   return lineno(top());
 }
 
+/**  Remove all the lines in the browser.*/
 void Fl_Browser::clear() {
   for (FL_BLINE* l = first; l;) {
     FL_BLINE* n = l->next;
@@ -443,6 +479,12 @@ void Fl_Browser::clear() {
   new_list();
 }
 
+/**
+  Add a new line to the end of the browser.  The text is copied using
+  the strdup() function.  It may also be NULL to make a
+  blank line.  The void * argument is returned as the data()
+  of the new item.
+*/
 void Fl_Browser::add(const char* newtext, void* d) {
   insert(lines+1, newtext, d);
   //Fl_Browser_::display(last);
@@ -463,11 +505,13 @@ int Fl_Browser::select(int line, int v) {
   return Fl_Browser_::select(find_line(line), v);
 }
 
+/**  Return 1 if line n is selected, 0 if it not selected.*/
 int Fl_Browser::selected(int line) const {
   if (line < 1 || line > lines) return 0;
   return find_line(line)->flags & SELECTED;
 }
 
+/**  Makes line n visible for selection.*/
 void Fl_Browser::show(int line) {
   FL_BLINE* t = find_line(line);
   if (t->flags & NOTDISPLAYED) {
@@ -477,6 +521,10 @@ void Fl_Browser::show(int line) {
   }
 }
 
+/**
+  Makes line n invisible, preventing selection by the user.
+  The line can still be selected under program control.
+*/
 void Fl_Browser::hide(int line) {
   FL_BLINE* t = find_line(line);
   if (!(t->flags & NOTDISPLAYED)) {
@@ -491,6 +539,7 @@ void Fl_Browser::display(int line, int v) {
   if (v) show(line); else hide(line);
 }
 
+/**  Returns a non-zero value if line n is visible.*/
 int Fl_Browser::visible(int line) const {
   if (line < 1 || line > lines) return 0;
   return !(find_line(line)->flags&NOTDISPLAYED);
@@ -540,6 +589,7 @@ void Fl_Browser::swap(FL_BLINE *a, FL_BLINE *b) {
   cache = 0;
 }
 
+/**  Swaps two lines in the browser.*/
 void Fl_Browser::swap(int ai, int bi) {
   if (ai < 1 || ai > lines || bi < 1 || bi > lines) return;
   FL_BLINE* a = find_line(ai);
diff --git a/src/Fl_Browser_.cxx b/src/Fl_Browser_.cxx
index 9a6b8f801..2bc6ce99f 100644
--- a/src/Fl_Browser_.cxx
+++ b/src/Fl_Browser_.cxx
@@ -94,6 +94,10 @@ void Fl::scrollbar_size(int W) {
 }
 
 // return where to draw the actual box:
+/**
+  This method returns the bounding box for the interior of the list, inside
+  the scrollbars.
+*/
 void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const {
   Fl_Boxtype b = box() ? box() : FL_DOWN_BOX;
   X = x()+Fl::box_dx(b);
@@ -112,6 +116,10 @@ void Fl_Browser_::bbox(int& X, int& Y, int& W, int& H) const {
   if (H < 0) H = 0;
 }
 
+/**
+  This method returns the X position of the left edge of the list area
+  after adjusting for the scrollbar and border, if any.
+*/
 int Fl_Browser_::leftedge() const {
   int X, Y, W, H; bbox(X, Y, W, H);
   return X;
@@ -120,6 +128,7 @@ int Fl_Browser_::leftedge() const {
 // The scrollbars may be moved again by draw(), since each one's size
 // depends on whether the other is visible or not.  This skips over
 // Fl_Group::resize since it moves the scrollbars uselessly.
+/**  Repositions and/or resizes the browser.*/
 void Fl_Browser_::resize(int X, int Y, int W, int H) {
   Fl_Widget::resize(X, Y, W, H);
   // move the scrollbars so they can respond to events:
@@ -133,6 +142,10 @@ void Fl_Browser_::resize(int X, int Y, int W, int H) {
 }
 
 // Cause minimal update to redraw the given item:
+/**
+  This method should be called when the contents of an item have changed
+  but not changed the height of the item.
+*/
 void Fl_Browser_::redraw_line(void* l) {
   if (!redraw1 || redraw1 == l) {redraw1 = l; damage(FL_DAMAGE_EXPOSE);}
   else if (!redraw2 || redraw2 == l) {redraw2 = l; damage(FL_DAMAGE_EXPOSE);}
@@ -195,6 +208,11 @@ void Fl_Browser_::update_top() {
 
 // Change position(), top() will update when update_top() is called
 // (probably by draw() or handle()):
+/**
+  Gets or sets the vertical scrolling position of the list,
+  which is the pixel offset of the list items within the list
+  area.
+*/
 void Fl_Browser_::position(int yy) {
   if (yy < 0) yy = 0;
   if (yy == position_) return;
@@ -202,6 +220,11 @@ void Fl_Browser_::position(int yy) {
   if (yy != real_position_) redraw_lines();
 }
 
+/**
+  Gets or sets the horizontal scrolling position of the list,
+  which is the pixel offset of the list items within the list
+  area.
+*/
 void Fl_Browser_::hposition(int xx) {
   if (xx < 0) xx = 0;
   if (xx == hposition_) return;
@@ -210,6 +233,10 @@ void Fl_Browser_::hposition(int xx) {
 }
 
 // Tell whether item is currently displayed:
+/**
+  This method returns non-zero if item p is currently visible in
+  the list.
+*/
 int Fl_Browser_::displayed(void* p) const {
   int X, Y, W, H; bbox(X, Y, W, H);
   int yy = H+offset_;
@@ -222,6 +249,7 @@ int Fl_Browser_::displayed(void* p) const {
 
 // Ensure this item is displayed:
 // Messy because we have no idea if it is before top or after bottom:
+/**  Displays item p, scrolling the list as necessary.*/
 void Fl_Browser_::display(void* p) {
 
   // First special case - want to display first item in the list?
@@ -304,6 +332,12 @@ void Fl_Browser_::display(void* p) {
 
 // redraw, has side effect of updating top and setting scrollbar:
 
+/**
+  The first form draws the list within the normal widget bounding box.
+  
+  <P>The second form draws the contents of the browser within the
+  specified bounding box.
+*/
 void Fl_Browser_::draw() {
   int drawsquare = 0;
   update_top();
@@ -455,6 +489,11 @@ J1:
 }
 
 // Quick way to delete and reset everything:
+/**
+  This method should be called when the list data is completely replaced
+  or cleared. It informs the Fl_Browser_ widget that any cached
+  information it has concerning the items is invalid.
+*/
 void Fl_Browser_::new_list() {
   top_ = 0;
   position_ = real_position_ = 0;
@@ -468,6 +507,11 @@ void Fl_Browser_::new_list() {
 
 // Tell it that this item is going away, and that this must remove
 // all pointers to it:
+/**
+  This method should be used when an item is deleted from the list.
+  It allows the Fl_Browser_ to discard any cached data it has
+  on the item.
+*/
 void Fl_Browser_::deleting(void* l) {
   if (displayed(l)) {
     redraw_lines();
@@ -487,6 +531,10 @@ void Fl_Browser_::deleting(void* l) {
   if (l == max_width_item) {max_width_item = 0; max_width = 0;}
 }
 
+/**
+  This method should be used when an item is replaced in the list.
+  It allows the Fl_Browser_ to update its cache data as needed.
+*/
 void Fl_Browser_::replacing(void* a, void* b) {
   redraw_line(a);
   if (a == selection_) selection_ = b;
@@ -503,11 +551,19 @@ void Fl_Browser_::swapping(void* a, void* b) {
   else if (b == top_) top_ = a;
 }
 
+/**
+  This method should be used when an item is added to the list.
+  It allows the Fl_Browser_ to update its cache data as needed.
+*/
 void Fl_Browser_::inserting(void* a, void* b) {
   if (displayed(a)) redraw_lines();
   if (a == top_) top_ = b;
 }
 
+/**
+  This method returns the item under mouse at my. If no item is
+  displayed at that position then NULL is returned.
+*/
 void* Fl_Browser_::find_item(int my) {
   update_top();
   int X, Y, W, H; bbox(X, Y, W, H);
@@ -521,6 +577,13 @@ void* Fl_Browser_::find_item(int my) {
   return 0;
 }
 
+/**
+  Sets the selection state of item p to s and
+  returns 1 if the state changed or 0 if it did not.
+  
+  <P>If docb is non-zero, select tries to call the callback
+  function for the widget.
+*/
 int Fl_Browser_::select(void* l, int i, int docallbacks) {
   if (type() == FL_MULTI_BROWSER) {
     if (selection_ != l) {
@@ -553,6 +616,13 @@ int Fl_Browser_::select(void* l, int i, int docallbacks) {
   return 1;
 }
 
+/**
+  Deselects all items in the list and returns 1 if the state changed
+  or 0 if it did not.
+  
+  <P>If docb is non-zero, deselect tries to call the
+  callback function for the widget.
+*/
 int Fl_Browser_::deselect(int docallbacks) {
   if (type() == FL_MULTI_BROWSER) {
     int change = 0;
@@ -568,6 +638,13 @@ int Fl_Browser_::deselect(int docallbacks) {
   }
 }
 
+/**
+  Selects item p and returns 1 if the state changed or 0 if it did
+  not. Any other items in the list are deselected.
+  
+  <P>If docb is non-zero, select_only tries to call the
+  callback function for the widget.
+*/
 int Fl_Browser_::select_only(void* l, int docallbacks) {
   if (!l) return deselect(docallbacks);
   int change = 0;
@@ -579,7 +656,7 @@ int Fl_Browser_::select_only(void* l, int docallbacks) {
   display(l);
   return change;
 }
-
+/** Handles an event within the normal widget bounding box. */
 int Fl_Browser_::handle(int event) {
   // must do shortcuts first or the scrollbar will get them...
   if (event == FL_ENTER || event == FL_LEAVE) return 1;
@@ -796,6 +873,7 @@ J1:
   return 0;
 }
 
+/** The constructor makes an empty browser.*/
 Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
   : Fl_Group(X, Y, W, H, l),
     scrollbar(0, 0, 0, 0, 0), // they will be resized by draw()
@@ -826,14 +904,32 @@ Fl_Browser_::Fl_Browser_(int X, int Y, int W, int H, const char* l)
 
 // Default versions of some of the virtual functions:
 
+/**
+  This method may be provided by the subclass to return the height of the
+  item p in pixels.  Allow for two additional pixels for the list
+  selection box.  This method differs from
+  item_height in that it is only
+  called for selection and scrolling operations. The default implementation
+  calls item_height.
+*/
 int Fl_Browser_::item_quick_height(void* l) const {
   return item_height(l);
 }
 
+/**
+  This method may be provided to return the average height of all items, to
+  be used for scrolling. The default implementation uses the height of the first
+  item.
+*/
 int Fl_Browser_::incr_height() const {
   return item_quick_height(item_first());
 }
 
+/**
+  This method may be provided by the subclass to indicate the full height
+  of the item list in pixels. The default implementation computes the full
+  height from the item heights.
+*/
 int Fl_Browser_::full_height() const {
   int t = 0;
   for (void* p = item_first(); p; p = item_next(p))
@@ -841,12 +937,27 @@ int Fl_Browser_::full_height() const {
   return t;
 }
 
+/**
+  This method may be provided by the subclass to indicate the full width
+  of the item list in pixels. The default implementation computes the full
+  width from the item widths.
+*/
 int Fl_Browser_::full_width() const {
   return max_width;
 }
 
+/**
+  This method must be implemented by the subclass if it supports
+  multiple selections in the browser. The s argument specifies the
+  selection state for item p: 0 = off, 1 = on.
+*/
 void Fl_Browser_::item_select(void*, int) {}
 
+/**
+  This method must be implemented by the subclass if it supports
+  multiple selections in the browser. The method should return 1 if p
+  is selected and 0 otherwise.
+*/
 int Fl_Browser_::item_selected(void* l) const {return l==selection_;}
 
 //
diff --git a/src/Fl_Browser_load.cxx b/src/Fl_Browser_load.cxx
index 7e99a56b7..9112074a9 100644
--- a/src/Fl_Browser_load.cxx
+++ b/src/Fl_Browser_load.cxx
@@ -30,6 +30,14 @@
 #include <stdio.h>
 #include <FL/fl_utf8.H>
 
+/**
+  Clears the browser and reads the file, adding each line from the file
+  to the browser.  If the filename is NULL or a zero-length
+  string then this just clears the browser.  This returns zero if there
+  was any error in opening or reading the file, in which case errno
+  is set to the system error.  The data() of each line is set
+  to NULL.
+*/
 int Fl_Browser::load(const char *filename) {
 #define MAXFL_BLINE 1024
     char newtext[MAXFL_BLINE];
diff --git a/src/Fl_Check_Browser.cxx b/src/Fl_Check_Browser.cxx
index a95feabee..4476df196 100644
--- a/src/Fl_Check_Browser.cxx
+++ b/src/Fl_Check_Browser.cxx
@@ -85,7 +85,8 @@ int Fl_Check_Browser::lineno(cb_item *p0) const {
 }
 
 Fl_Check_Browser::Fl_Check_Browser(int X, int Y, int W, int H, const char *l)
-	: Fl_Browser_(X, Y, W, H, l) {
+/**  The constructor makes an empty browser.*/
+: Fl_Browser_(X, Y, W, H, l) {
 	type(FL_SELECT_BROWSER);
 	when(FL_WHEN_NEVER);
 	first = last = 0;
@@ -164,11 +165,16 @@ int Fl_Check_Browser::item_selected(void *v) const {
 	cb_item *i = (cb_item *)v;
 	return i->selected;
 }
-
+/**
+    Add a new unchecked line to the end of the browser.  The text is copied
+    using the strdup() function.  It may also be NULL to make
+    a blank line.  The second form can set the item checked.
+*/
 int Fl_Check_Browser::add(char *s) {
 	return (add(s, 0));
 }
 
+/** See int Fl_Check_Browser::add(char *s) */
 int Fl_Check_Browser::add(char *s, int b) {
 	cb_item *p = (cb_item *)malloc(sizeof(cb_item));
 	p->next = 0;
@@ -193,6 +199,10 @@ int Fl_Check_Browser::add(char *s, int b) {
 	return (nitems_);
 }
 
+/**
+  Remove line n and make the browser one line shorter. Returns the 
+  number of lines left in the browser.
+*/
 int Fl_Check_Browser::remove(int item) {
   cb_item *p = find_item(item);
   
@@ -225,6 +235,7 @@ int Fl_Check_Browser::remove(int item) {
   return (nitems_);
 }
 
+/**  Remove every item from the browser.*/
 void Fl_Check_Browser::clear() {
 	cb_item *p = first;
 	cb_item *next;
@@ -246,6 +257,7 @@ void Fl_Check_Browser::clear() {
 	cached_item = -1;
 }
 
+/** Gets the current status of item item. */
 int Fl_Check_Browser::checked(int i) const {
 	cb_item *p = find_item(i);
 
@@ -253,6 +265,7 @@ int Fl_Check_Browser::checked(int i) const {
 	return 0;
 }
 
+/** Sets the check status of item item to b. */
 void Fl_Check_Browser::checked(int i, int b) {
 	cb_item *p = find_item(i);
 
@@ -267,10 +280,12 @@ void Fl_Check_Browser::checked(int i, int b) {
 	}
 }
 
+/**  Returns the index of the currently selected item.*/
 int Fl_Check_Browser::value() const {
 	return lineno((cb_item *)selection());
 }
 
+/**  Return a pointer to an internal buffer holding item item's text.*/
 char *Fl_Check_Browser::text(int i) const {
 	cb_item *p = find_item(i);
 
@@ -278,6 +293,7 @@ char *Fl_Check_Browser::text(int i) const {
 	return 0;
 }
 
+/**  Sets all the items checked.*/
 void Fl_Check_Browser::check_all() {
 	cb_item *p;
 
@@ -288,6 +304,7 @@ void Fl_Check_Browser::check_all() {
 	redraw();
 }
 
+/**  Sets all the items unchecked.*/
 void Fl_Check_Browser::check_none() {
 	cb_item *p;
 
diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx
index c7d481df4..8447ab080 100644
--- a/src/Fl_File_Chooser2.cxx
+++ b/src/Fl_File_Chooser2.cxx
@@ -24,6 +24,276 @@
 //
 //     http://www.fltk.org/str.php
 //
+
+// fabien: ATTENTION: Only Out Of Source Gen. because cxx/H files are autogenerated by fluid.
+
+/** \class Fl_File_Chooser
+  The Fl_File_Chooser widget displays a standard file selection
+  dialog that supports various selection modes.
+  
+  <CENTER>\image html Fl_File_Chooser.jpg</CENTER>
+  
+  <P>The Fl_File_Chooser class also exports several static values
+  that may be used to localize or customize the appearance of all file chooser
+  dialogs:
+  
+  <CENTER><TABLE BORDER="1">
+  <TR>
+  	<TH>Member</TH>
+  	<TH>Default value</TH>
+  </TR>
+  <TR>
+  	<TD>add_favorites_label</TD>
+  	<TD>"Add to Favorites"</TD>
+  </TR>
+  <TR>
+  	<TD>all_files_label</TD>
+  	<TD>"All Files (*)"</TD>
+  </TR>
+  <TR>
+  	<TD>custom_filter_label</TD>
+  	<TD>"Custom Filter"</TD>
+  </TR>
+  <TR>
+  	<TD>existing_file_label</TD>
+  	<TD>"Please choose an existing file!"</TD>
+  </TR>
+  <TR>
+  	<TD>favorites_label</TD>
+  	<TD>"Favorites"</TD>
+  </TR>
+  <TR>
+  	<TD>filename_label</TD>
+  	<TD>"Filename:"</TD>
+  </TR>
+  <TR>
+  	<TD>filesystems_label</TD>
+  	<TD>"My Computer" (WIN32)<BR>
+  	"File Systems" (all others)</TD>
+  </TR>
+  <TR>
+  	<TD>manage_favorites_label</TD>
+  	<TD>"Manage Favorites"</TD>
+  </TR>
+  <TR>
+  	<TD>new_directory_label</TD>
+  	<TD>"New Directory?"</TD>
+  </TR>
+  <TR>
+  	<TD>new_directory_tooltip</TD>
+  	<TD>"Create a new directory."</TD>
+  </TR>
+  <TR>
+  	<TD>preview_label</TD>
+  	<TD>"Preview"</TD>
+  </TR>
+  <TR>
+  	<TD>save_label</TD>
+  	<TD>"Save"</TD>
+  </TR>
+  <TR>
+  	<TD>show_label</TD>
+  	<TD>"Show:"</TD>
+  </TR>
+  <TR>
+  	<TD>sort</TD>
+  	<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.
+*/
+
+/** \fn Fl_File_Chooser::Fl_File_Chooser(const char *pathname, const char *pattern, int type, const char *title)
+  The constructor creates the Fl_File_Chooser dialog pictured
+  above. The pathname argument can be a directory name or a
+  complete file name (in which case the corresponding file is highlighted
+  in the list and in the filename input field.)
+  
+  <P>The pattern argument can be a NULL
+  string or "*" to list all files, or it can be a
+  series of descriptions and filter strings separated by tab
+  characters (\t). The format of filters is either
+  "Description text (patterns)" or just "patterns". A file chooser
+  that provides filters for HTML and image files might look like:
+  
+  <UL><PRE>
+  "HTML Files (*.html)\tImage Files (*.{bmp,gif,jpg,png})"
+  </PRE></UL>
+  
+  <P>The file chooser will automatically add the "All Files (*)"
+  pattern to the end of the string you pass if you do not provide
+  one. The first filter in the string is the default filter.
+  
+  <P>See the FLTK documentation on fl_filename_match()
+  for the kinds of pattern strings that are supported.
+  
+  <P>The type argument can be one of the following:
+  
+  <UL>
+  	<LI>SINGLE - allows the user to select a
+  	single, existing file.
+  	<LI>MULTI - allows the user to select one
+  	or more existing files.
+  	<LI>CREATE - allows the user to select a
+  	single, existing file or specify a new filename.
+  	<LI>DIRECTORY - allows the user to select a
+  	single, existing directory.
+  </UL>
+  
+  <P>The title argument is used to set the title bar text for the
+  Fl_File_Chooser window.
+*/
+
+/** \fn Fl_File_Chooser::~Fl_File_Chooser()
+  Destroys the widget and frees all memory used by it.*/
+
+/** \fn void Fl_File_Chooser::color(Fl_Color c)
+  Sets or gets the background color of the Fl_File_Browser list.*/
+
+/** \fn Fl_Color Fl_File_Chooser::color()
+  Sets or gets the background color of the Fl_File_Browser list.*/
+
+/** \fn int Fl_File_Chooser::count()
+  Returns the number of selected files.*/
+
+/** \fn void Fl_File_Chooser::directory(const char *pathname)
+  Sets or gets the current directory.*/
+
+/** \fn const char *Fl_File_Chooser::directory()
+  Sets or gets the current directory.*/
+
+/** \fn void Fl_File_Chooser::filter(const char *pattern)
+  Sets or gets the current filename filter patterns. The filter
+  patterns use fl_filename_match().
+  Multiple patterns can be used by separating them with tabs, like
+  "*.jpg\t*.png\t*.gif\t*". In addition, you can provide
+  human-readable labels with the patterns inside parenthesis, like
+  "JPEG&nbsp;Files&nbsp;(*.jpg)\tPNG&nbsp;Files&nbsp;(*.png)\tGIF&nbsp;Files&nbsp;(*.gif)\tAll&nbsp;Files&nbsp;(*)".
+  Use filter(NULL) to show all files.
+*/
+
+/** \fn const char *Fl_File_Chooser::filter()
+  See void filter(const char *pattern)*/
+
+/** \fn void Fl_File_Chooser::filter_value(int f)
+  Sets or gets the current filename filter selection.*/
+
+/** \fn int Fl_File_Chooser::filter_value()
+  Sets or gets the current filename filter selection.*/
+
+/** \fn void Fl_File_Chooser::hide()
+  Hides the Fl_File_Chooser window.*/
+
+/** \fn void Fl_File_Chooser::iconsize(uchar s)
+  Sets or gets the size of the icons in the Fl_File_Browser.  By
+  default the icon size is set to 1.5 times the textsize().
+*/
+
+/** \fn uchar Fl_File_Chooser::iconsize()
+  Sets or gets the size of the icons in the Fl_File_Browser.  By
+  default the icon size is set to 1.5 times the textsize().
+*/
+
+/** \fn void Fl_File_Chooser::label(const char *l)
+  Sets or gets the title bar text for the Fl_File_Chooser.*/
+
+/** \fn const char *Fl_File_Chooser::label()
+  Sets or gets the title bar text for the Fl_File_Chooser.*/
+
+/** \fn void Fl_File_Chooser::ok_label(const char *l)
+  Sets or gets the label for the "ok" button in the
+  Fl_File_Chooser.
+*/
+
+/** \fn const char *Fl_File_Chooser::ok_label()
+  Sets or gets the label for the "ok" button in the
+  Fl_File_Chooser.
+*/
+
+/** \fn int Fl_File_Chooser::preview() const
+   Returns the current state of the preview box. */
+
+/** \fn void Fl_File_Chooser::rescan()
+  Reloads the current directory in the Fl_File_Browser.*/
+
+/** \fn void Fl_File_Chooser::show()
+  Shows the Fl_File_Chooser window.*/
+
+/** \fn void Fl_File_Chooser::textcolor(Fl_Color c)
+  Sets or gets the current Fl_File_Browser text color.*/
+
+/** \fn Fl_Color Fl_File_Chooser::textcolor()
+  Sets or gets the current Fl_File_Browser text color.*/
+
+/** \fn void Fl_File_Chooser::textfont(Fl_Font f)
+  Sets or gets the current Fl_File_Browser text font.*/
+
+/** \fn Fl_Font Fl_File_Chooser::textfont()
+  Sets or gets the current Fl_File_Browser text font.*/
+
+/** \fn void Fl_File_Chooser::textsize(Fl_Fontsize s)
+  Sets or gets the current Fl_File_Browser text size.*/
+
+/** \fn Fl_Fontsize Fl_File_Chooser::textsize()
+  Sets or gets the current Fl_File_Browser text size.*/
+
+/** \fn void Fl_File_Chooser::type(int t)
+  Sets or gets the current type of Fl_File_Chooser.*/
+
+/** \fn int Fl_File_Chooser::type()
+  Sets or gets the current type of Fl_File_Chooser.*/
+
+/** \fn const char *Fl_File_Chooser::value(const char *pathname)
+  Sets or gets the current value of the selected file.
+  
+  <P>In the second form, <i>file</i> is a <i>1</i>-based index into a list of
+  file names. The number of selected files is returned by
+  Fl_File_Chooser::count().
+  
+  <P>This sample code loops through all selected files:
+  <PRE>
+  // Get list of filenames user selected from a MULTI chooser
+  for ( int t=1; t&lt;=chooser-&gt;count(); t++ ) {
+     const char *filename = chooser-&gt;value(t);
+     ..
+  }
+  </PRE>
+*/
+
+/** \fn const char *Fl_File_Chooser::value(int file)
+  See const char *value(const char *pathname)*/
+
+/** \fn const char *Fl_File_Chooser::value()
+  See const char *value(const char *pathname)*/
+
+/** \fn int Fl_File_Chooser::visible()
+  Returns 1 if the Fl_File_Chooser window is visible.*/
+
+/** \fn Fl_Widget* Fl_File_Chooser::add_extra(Fl_Widget*)
+  Adds extra widget at the bottom of Fl_File_Chooser window.
+  Returns pointer for previous extra widget or NULL if not set previously.
+  If argument is NULL only remove previous extra widget.<BR>
+  <I>NOTE! Fl_File_Chooser doesn't delete extra widget in destructor! To prevent memory leakage don't forget
+   delete unused extra widgets by yourself.</I>
+*/
+  /** \fn int Fl_File_Chooser::shown()
+    Returns non-zero if the file chooser main window show() has been called (but not hide()
+    see Fl_Window::shown()
+  */
+
+  /** \fn void Fl_File_Chooser::callback(void (*cb)(Fl_File_Chooser *, void *), void *d = 0)
+    Sets the file chooser callback cb and associated data d */
+
+  /** \fn void Fl_File_Chooser::user_data(void *d)
+    Sets the file chooser user data d */
+
+  /** \fn void * Fl_File_Chooser::user_data() const
+    Gets the file chooser user data d */
+
+// *** END OF OUT OF SOURCE DOC ***
+
 // Contents:
 //
 //   Fl_File_Chooser::count()             - Return the number of selected files.
@@ -794,12 +1064,9 @@ Fl_File_Chooser::newdir()
 }
 
 
-//
-// 'Fl_File_Chooser::preview()' - Enable or disable the preview tile.
-//
 
-void
-Fl_File_Chooser::preview(int e)// I - 1 = enable preview, 0 = disable preview
+/** Enable or disable the preview tile. 1 = enable preview, 0 = disable preview. */
+void Fl_File_Chooser::preview(int e)
 {
   previewButton->value(e);
   prefs_.set("preview", e);
@@ -868,12 +1135,11 @@ Fl_File_Chooser::rescan()
 }
 
 //
-// 'Fl_File_Chooser::rescan_keep_filename()' - Rescan the current directory
-// without clearing the filename, then select the file if it is in the list
-//
-
-void
-Fl_File_Chooser::rescan_keep_filename()
+/**  
+  Rescan the current directory  without clearing the filename, 
+  then select the file if it is in the list
+*/
+void Fl_File_Chooser::rescan_keep_filename()
 {
   // if no filename was set, this is likely a diretory browser
   const char *fn = fileName->value();
diff --git a/src/glut_font.cxx b/src/glut_font.cxx
index 6053d733a..788e9dee4 100644
--- a/src/glut_font.cxx
+++ b/src/glut_font.cxx
@@ -114,8 +114,10 @@ void glutStrokeString(void* fontID, const unsigned char *string) {
   * A newline will simply translate the next character's insertion
   * point back to the start of the line and down one line.
   */
-
+#if !defined(WIN32) || defined(CYGWIN)
 #warning FIXME This needs to be UTF aware now
+#endif
+
   while ((c = *string++) != 0) {
     if (c < font->Quantity) {
       if (c == '\n') {