Doxygen Documentation WP2 done.

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

8 files changed, 316 insertions, 7 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.