14 files changed, 534 insertions, 125 deletions

diff --git a/FL/Fl_Button.H b/FL/Fl_Button.H
index 460b851b0..dc594c1e1 100644
--- a/FL/Fl_Button.H
+++ b/FL/Fl_Button.H
@@ -3,7 +3,7 @@
 //
 // Button header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -40,6 +40,40 @@
 
 extern FL_EXPORT int fl_old_shortcut(const char*);
 
+/**
+  \class Fl_Button
+  \brief Buttons generate callbacks when they are clicked by the user.
+  
+  You control exactly when and how by changing the values for type() and
+  when().  Buttons can also generate callbacks in response to \c FL_SHORTCUT
+  events.  The button can either have an explicit shortcut(int s) value or a
+  letter shortcut can be indicated in the label() with an '\&' character
+  before it.  For the label shortcut it does not matter if \e Alt is held
+  down, but if you have an input field in the same window, the user will have
+  to hold down the \e Alt key so that the input field does not eat the event
+  first as an \c FL_KEYBOARD event.
+
+  \todo Refactor the doxygen comments for Fl_Button type() documentation.
+
+  For an Fl_Button object, the type() call returns one of:
+  \li \c FL_NORMAL_BUTTON (0): value() remains unchanged after button press.
+  \li \c FL_TOGGLE_BUTTON: value() is inverted after button press.
+  \li \c FL_RADIO_BUTTON: value() is set to 1 after button press, and all other
+         buttons in the current group with <tt>type() == FL_RADIO_BUTTON</tt>
+	 are set to zero.
+
+  \todo Refactor the doxygen comments for Fl_Button when() documentation.
+
+  For an Fl_Button object, the following when() values are useful, the default
+  being \c FL_WHEN_RELEASE:
+  \li \c 0: The callback is not done, instead changed() is turned on.
+  \li \c FL_WHEN_RELEASE: The callback is done after the user successfully
+         clicks the button, or when a shortcut is typed.
+  \li \c FL_WHEN_CHANGED: The callback is done each time the value() changes
+         (when the user pushes and releases the button, and as the mouse is
+	 dragged around in and out of the button).
+*/
+
 class FL_EXPORT Fl_Button : public Fl_Widget {
 
   int shortcut_;
@@ -54,20 +88,77 @@ protected:
 public:
 
   virtual int handle(int);
-  Fl_Button(int,int,int,int,const char * = 0);
-  int value(int);
+
+  Fl_Button(int X, int Y, int W, int H, const char *L = 0);
+
+  int value(int v);
+
+  /**
+    Returns the current value of the button (0 or 1).
+   */
   char value() const {return value_;}
+
+  /**
+    Same as \c value(1).
+    \see value(int v)
+   */
   int set() {return value(1);}
+
+  /**
+    Same as \c value(0).
+    \see value(int v)
+   */
   int clear() {return value(0);}
+
   void setonly(); // this should only be called on FL_RADIO_BUTTONs
+
+  /**
+    Returns the current shortcut key for the button.
+    \retval int
+   */
   int shortcut() const {return shortcut_;}
+
+  /**
+    Sets the shortcut key to \c s.
+    Setting this overrides the use of '\&' in the label().
+    The value is a bitwise OR of a key and a set of shift flags, for example:
+    <tt>FL_ALT | 'a'</tt>, or
+    <tt>FL_ALT | (FL_F + 10)</tt>, or just
+    <tt>'a'</tt>.
+    A value of 0 disables the shortcut.
+
+    The key can be any value returned by Fl::event_key(), but will usually be
+    an ASCII letter.  Use a lower-case letter unless you require the shift key
+    to be held down.
+
+    The shift flags can be any set of values accepted by Fl::event_state().
+    If the bit is on, that shift key must be pushed.  Meta, Alt, Ctrl, and
+    Shift must be off if they are not in the shift flags (zero for the other
+    bits indicates a "don't care" setting).
+    \param[in] s bitwise OR of key and shift flags
+   */
   void shortcut(int s) {shortcut_ = s;}
+
+  /**
+    Returns the current down box type, which is drawn when value() is non-zero.
+    \retval Fl_Boxtype
+   */
   Fl_Boxtype down_box() const {return (Fl_Boxtype)down_box_;}
+
+  /**
+    Sets the down box type. The default value of 0 causes FLTK to figure out
+    the correct matching down version of box().
+    \param[in] b down box type
+   */
   void down_box(Fl_Boxtype b) {down_box_ = b;}
 
-  // back compatibility:
+  /// (for backwards compatibility)
   void shortcut(const char *s) {shortcut(fl_old_shortcut(s));}
+
+  /// (for backwards compatibility)
   Fl_Color down_color() const {return selection_color();}
+
+  /// (for backwards compatibility)
   void down_color(unsigned c) {selection_color(c);}
 };
 
diff --git a/FL/Fl_Chart.H b/FL/Fl_Chart.H
index 70df559d8..b0a4d813a 100644
--- a/FL/Fl_Chart.H
+++ b/FL/Fl_Chart.H
@@ -3,7 +3,7 @@
 //
 // Forms chart header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -52,6 +52,28 @@ struct FL_CHART_ENTRY {
    char str[FL_CHART_LABEL_MAX+1];
 };
 
+/**
+  \class Fl_Chart
+  \brief Fl_Chart displays simple charts.
+  It is provided for Forms compatibility.
+
+  \image html charts.gif
+
+  \todo Refactor Fl_Chart::type() information.
+
+  The type of an Fl_Chart object can be set using type(uchar t) to:
+  \li \c FL_BAR_CHART: Each sample value is drawn as a vertical bar.
+  \li \c FL_FILLED_CHART: The chart is filled from the bottom of the graph
+         to the sample values.
+  \li \c FL_HORBAR_CHART: Each sample value is drawn as a horizontal bar.
+  \li \c FL_LINE_CHART: The chart is drawn as a polyline with vertices at
+         each sample value.
+  \li \c FL_PIE_CHART: A pie chart is drawn with each sample value being
+         drawn as a proportionate slice in the circle.
+  \li \c FL_SPECIALPIE_CHART: Like \c FL_PIE_CHART, but the first slice is
+         separated from the pie.
+  \li \c FL_SPIKE_CHART: Each sample value is drawn as a vertical line.
+ */
 class FL_EXPORT Fl_Chart : public Fl_Widget {
     int numb;
     int maxnumb;
@@ -65,25 +87,57 @@ class FL_EXPORT Fl_Chart : public Fl_Widget {
 protected:
     void draw();
 public:
-    Fl_Chart(int,int,int,int,const char * = 0);
+    Fl_Chart(int X, int Y, int W, int H, const char *L = 0);
+
     ~Fl_Chart();
+
     void clear();
-    void add(double, const char * =0, unsigned=0);
-    void insert(int, double, const char * =0, unsigned=0);
-    void replace(int, double, const char * =0, unsigned=0);
+
+    void add(double val, const char *str = 0, unsigned col = 0);
+
+    void insert(int ind, double val, const char *str = 0, unsigned col = 0);
+
+    void replace(int ind, double val, const char *str = 0, unsigned col = 0);
+
+    /**
+      Gets the lower and upper bounds of the chart values.
+      \param[out] a, b are set to lower, upper
+     */
     void bounds(double *a,double *b) const {*a = min; *b = max;}
+
     void bounds(double a,double b);
+
+    /**
+      Returns the number of data values in the chart.
+     */
     int size() const {return numb;}
+
     void size(int W, int H) { Fl_Widget::size(W, H); }
+
+    /**
+      Get the maximum number of data values for a chart.
+     */
     int maxsize() const {return maxnumb;}
-    void maxsize(int);
+
+    void maxsize(int m);
+
     Fl_Font textfont() const {return textfont_;}
     void textfont(Fl_Font s) {textfont_ = s;}
     Fl_Fontsize textsize() const {return textsize_;}
     void textsize(Fl_Fontsize s) {textsize_ = s;}
     Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
     void textcolor(unsigned n) {textcolor_ = n;}
+
+    /**
+      Get whether the chart will automatically adjust the bounds of the chart.
+      \returns non-zero if auto-sizing is enabled and zero if disabled.
+     */
     uchar autosize() const {return autosize_;}
+
+    /**
+      Set whether the chart will automatically adjust the bounds of the chart.
+      \param n non-zero to enable automatic resizing, zero to disable.
+     */
     void autosize(uchar n) {autosize_ = n;}
 };
 
diff --git a/FL/Fl_Check_Button.H b/FL/Fl_Check_Button.H
index 66b29bd8a..55ec6a0ed 100644
--- a/FL/Fl_Check_Button.H
+++ b/FL/Fl_Check_Button.H
@@ -3,7 +3,7 @@
 //
 // Check button header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -30,9 +30,24 @@
 
 #include "Fl_Light_Button.H"
 
+/**
+  \class Fl_Check_Button
+  \brief A button with an "checkmark" to show its status.
+
+  \image html Fl_Check_Button.gif
+
+  Buttons generate callbacks when they are clicked by the user. You control
+  exactly when and how by changing the values for type() and when().
+
+  The Fl_Check_Button subclass displays its "ON" state by showing a "checkmark"
+  rather than drawing itself pushed in.
+  
+  \todo Refactor Fl_Check_Button doxygen comments (add color() info etc?)
+  \todo Generate Fl_Check_Button.gif with visible checkmark.
+ */
 class FL_EXPORT Fl_Check_Button : public Fl_Light_Button {
 public:
-  Fl_Check_Button(int x,int y,int w,int h,const char *l = 0);
+  Fl_Check_Button(int X, int Y, int W, int H, const char *L = 0);
 };
 
 #endif
diff --git a/FL/Fl_Choice.H b/FL/Fl_Choice.H
index cf9beae35..f3cfd8beb 100644
--- a/FL/Fl_Choice.H
+++ b/FL/Fl_Choice.H
@@ -3,7 +3,7 @@
 //
 // Choice header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -30,15 +30,72 @@
 
 #include "Fl_Menu_.H"
 
+/**
+  \class Fl_Choice
+  \brief A button that is used to pop up a menu.
+
+  This is a button that, when pushed, pops up a menu (or hierarchy of menus)
+  defined by an array of Fl_Menu_Item objects.
+  Motif calls this an OptionButton.
+
+  The only difference between this and a Fl_Menu_Button is that the name of
+  the most recent chosen menu item is displayed inside the box, while the
+  label is displayed outside the box. However, since the use of this is most
+  often to control a single variable rather than do individual callbacks,
+  some of the Fl_Menu_Button methods are redescribed here in those terms.
+
+  When the user picks an item off the menu the value() is set to that item
+  and then the item's callback is done with the menu_button as the
+  \c Fl_Widget* argument. If the item does not have a callback the
+  menu_button's callback is done instead.
+
+  All three mouse buttons pop up the menu. The Forms behavior of the first
+  two buttons to increment/decrement the choice is not implemented.  This
+  could be added with a subclass, however.
+
+  The menu will also pop up in response to shortcuts indicated by putting
+  a '\&' character in the label().  See Fl_Button::shortcut(int s) for a
+  description of this.
+
+  Typing the shortcut() of any of the items will do exactly the same as when
+  you pick the item with the mouse.  The '\&' character in item names are
+  only looked at when the menu is popped up, however.
+
+  \image html choice.gif
+
+  \todo Refactor the doxygen comments for Fl_Choice changed() documentation.
+
+  \li <tt>int Fl_Widget::changed() const</tt>
+      This value is true the user picks a different value. <em>It is turned
+      off by value() and just before doing a callback (the callback can turn
+      it back on if desired).</em>
+  \li <tt>void Fl_Widget::set_changed()</tt>
+      This method sets the changed() flag.
+  \li <tt>void Fl_Widget::clear_changed()</tt>
+      This method clears the changed() flag.
+  \li <tt>Fl_Boxtype Fl_Choice::down_box() const</tt>
+      Gets the current down box, which is used when the menu is popped up.
+      The default down box type is \c FL_DOWN_BOX.
+  \li <tt>void Fl_Choice::down_box(Fl_Boxtype b)</tt>
+      Sets the current down box type to \p b.
+ */
 class FL_EXPORT Fl_Choice : public Fl_Menu_ {
 protected:
   void draw();
 public:
   int handle(int);
-  Fl_Choice(int,int,int,int,const char * = 0);
-  int value(const Fl_Menu_Item*);
-  int value(int i);
+
+  Fl_Choice(int X, int Y, int W, int H, const char *L = 0);
+
+  /**
+    Gets the index of the last item chosen by the user.
+    The index is zero initially.
+   */
   int value() const {return Fl_Menu_::value();}
+
+  int value(int v);
+
+  int value(const Fl_Menu_Item* v);
 };
 
 #endif
diff --git a/FL/Fl_Clock.H b/FL/Fl_Clock.H
index f1bc513e7..185c93b0b 100644
--- a/FL/Fl_Clock.H
+++ b/FL/Fl_Clock.H
@@ -3,7 +3,7 @@
 //
 // Clock header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -42,16 +42,16 @@
 #define FL_ANALOG_CLOCK FL_SQUARE_CLOCK
 #define FL_DIGITAL_CLOCK FL_SQUARE_CLOCK // nyi
 
-// a Fl_Clock_Output can be used to display a program-supplied time:
-
 /**
- * This widget can be used to display a program-supplied time.
- * The time shown on the clock is not updated. 
- * To display the current time, use Fl_Clock</A> instead.
- *
- * <table align=CENTER border=5 cellpadding=5 ><TR><TD> \image html clock.gif  </TD>
- *
- * <TD> \image html round_clock.gif </TD> </TR> </table>
+  \class Fl_Clock_Output
+  \brief This widget can be used to display a program-supplied time.
+  
+  The time shown on the clock is not updated. To display the current time,
+  use Fl_Clock instead.
+
+  \image html clock.gif 
+ 
+  \image html round_clock.gif
  */
 class FL_EXPORT Fl_Clock_Output : public Fl_Widget {
   int hour_, minute_, second_;
@@ -61,57 +61,35 @@ protected:
   void draw(int, int, int, int);
   void draw();
 public:
-  
-  /**
-   * Creates a new Fl_Clock_Output widget.
-   * Create an Fl_Clock_Output widget using the given position, 
-   * size, and label string. The default boxtype is FL_NO_BOX.
-   *
-   * \param[in] x, y, w, h position and size of the widget
-   * \param[in] label widget label, default is no label
-   */
-  Fl_Clock_Output(int x,int y,int w,int h, const char *l = 0);
 
-  /**
-   * Set the displayed time.
-   * Set the time in seconds since the UNIX epoch (January 1, 1970).
-   * \see value()
-   */
+  Fl_Clock_Output(int X, int Y, int W, int H, const char *L = 0);
+
   void value(ulong v);	// set to this Unix time
   
+  void value(int H, int m, int s);
+
   /**
-   * Set the displayed time.
-   * Set the time in hours, minutes, and seconds.
-   * \param[in] hour, minute, second displayed time
-   * \see hour(), minute(), second()
-   */
-  void value(int hour, int minute, int second);
-  
-  /**
-   * Returns the displayed time.
-   * Returns the time in seconds since the UNIX epoch (January 1, 1970).
-   * \see value(ulong)
+    Returns the displayed time.
+    Returns the time in seconds since the UNIX epoch (January 1, 1970).
+    \see value(ulong)
    */
   ulong value() const {return value_;}
 
   /**
-   * Returns the displayed time.
-   * Returns the displayed hour (0 to 23).
-   * \see value(), minute(), second()
+    Returns the displayed hour (0 to 23).
+    \see value(), minute(), second()
    */
   int hour() const {return hour_;}
 
   /**
-   * Returns the displayed time.
-   * Returns the displayed minute (0 to 59).
-   * \see value(), hour(), second()
+    Returns the displayed minute (0 to 59).
+    \see value(), hour(), second()
    */
   int minute() const {return minute_;}
 
   /**
-   * Returns the displayed time.
-   * Returns the displayed second (0 to 60, 60=leap second).
-   * \see value(), hour(), minute()
+    Returns the displayed second (0 to 60, 60=leap second).
+    \see value(), hour(), minute()
    */
   int second() const {return second_;}
 };
@@ -119,43 +97,25 @@ public:
 // a Fl_Clock displays the current time always by using a timeout:
 
 /**
- * This widget provides a round analog clock display.
- * Fl_Clock is provided for Forms compatibility. 
- * It installs a 1-second timeout callback using Fl::add_timeout().
- *
- * <table align=CENTER border=5 cellpadding=5 ><TR><TD>\image html clock.gif </TD>
- * 
- * <TD> \image html round_clock.gif </TD></TR></table>
+  \class Fl_Clock
+  \brief This widget provides a round analog clock display.
+
+  Fl_Clock is provided for Forms compatibility. 
+  It installs a 1-second timeout callback using Fl::add_timeout().
+
+  \image html clock.gif 
+
+  \image html round_clock.gif
  */
 class FL_EXPORT Fl_Clock : public Fl_Clock_Output {
 public:
   int handle(int);
   void update();
 
-  /**
-   * Creates a new Fl_Clock widget.
-   * Create an Fl_Clock widget using the given position, 
-   * size, and label string. The default boxtype is FL_NO_BOX.
-   *
-   * \param[in] x, y, w, h position and size of the widget
-   * \param[in] label widget label, default is no label
-   */
-  Fl_Clock(int x,int y,int w,int h, const char *l = 0);
+  Fl_Clock(int X, int Y, int W, int H,  const char *L = 0);
   
-  /**
-   * Creates a new Fl_Clock widget.
-   * Create an Fl_Clock widget using the given position, 
-   * size, and label string.
-   *
-   * \param[in] t boxtype
-   * \param[in] x, y, w, h position and size of the widget
-   * \param[in] label widget label, default is no label
-   */
-  Fl_Clock(uchar t,int x,int y,int w,int h, const char *l);
+  Fl_Clock(uchar t, int X, int Y, int W, int H, const char *L);
   
-  /**
-   * The destructor removes the clock.
-   */
   ~Fl_Clock();
 };
 
diff --git a/FL/Fl_Color_Chooser.H b/FL/Fl_Color_Chooser.H
index 6630d4187..3fdd3f6e6 100644
--- a/FL/Fl_Color_Chooser.H
+++ b/FL/Fl_Color_Chooser.H
@@ -3,7 +3,7 @@
 //
 // Color chooser header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -66,6 +66,19 @@ public:
   Flcc_Value_Input(int X, int Y, int W, int H) : Fl_Value_Input(X,Y,W,H) {}
 };
 
+/**
+  \class Fl_Color_Chooser
+  \brief The Fl_Color_Chooser widget provides a standard RGB color chooser.
+
+  You can place any number of these into a panel of your own design. This
+  widget contains the hue box, value slider, and rgb input fields from the
+  above diagram (it does not have the color chips or the Cancel or OK buttons).
+  The callback is done every time the user changes the rgb value. It is not
+  done if they move the hue control in a way that produces the \e same rgb
+  value, such as when saturation or value is zero.
+
+  \image html fl_color_chooser.jpg
+ */
 class FL_EXPORT Fl_Color_Chooser : public Fl_Group {
   Flcc_HueBox huebox;
   Flcc_ValueBox valuebox;
@@ -81,17 +94,54 @@ class FL_EXPORT Fl_Color_Chooser : public Fl_Group {
   static void mode_cb(Fl_Widget*, void*);
 public:
   int mode() {return choice.value();}
+
+  /**
+    Returns the current hue.
+    0 <= hue < 6. Zero is red, one is yellow, two is green, etc.
+    <em>This value is convienent for the internal calculations - some other
+    systems consider hue to run from zero to one, or from 0 to 360.</em>
+   */
   double hue() const {return hue_;}
+
+  /**
+    Returns the saturation.
+    0 <= saturation <= 1.
+   */
   double saturation() const {return saturation_;}
+
+  /**
+    Returns the value/brightness.
+    0 <= value <= 1.
+   */
   double value() const {return value_;}
+
+  /**
+    Returns the current red value.
+    0 <= r <= 1.
+   */
   double r() const {return r_;}
+
+  /**
+    Returns the current green value.
+    0 <= g <= 1.
+   */
   double g() const {return g_;}
+
+  /**
+    Returns the current blue value.
+    0 <= b <= 1.
+   */
   double b() const {return b_;}
-  int hsv(double,double,double);
-  int rgb(double,double,double);
-  static void hsv2rgb(double, double, double,double&,double&,double&);
-  static void rgb2hsv(double, double, double,double&,double&,double&);
-  Fl_Color_Chooser(int,int,int,int,const char* = 0);
+
+  int hsv(double H, double S, double V);
+
+  int rgb(double R, double G, double B);
+
+  static void hsv2rgb(double H, double S, double V, double& R, double& G, double& B);
+
+  static void rgb2hsv(double R, double G, double B, double& H, double& S, double& V);
+
+  Fl_Color_Chooser(int X, int Y, int W, int H, const char *L = 0);
 };
 
 FL_EXPORT int fl_color_chooser(const char* name, double& r, double& g, double& b);
diff --git a/FL/Fl_Counter.H b/FL/Fl_Counter.H
index 6cf1e6fee..6a7a60055 100644
--- a/FL/Fl_Counter.H
+++ b/FL/Fl_Counter.H
@@ -3,7 +3,7 @@
 //
 // Counter header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -38,6 +38,19 @@
 #define FL_NORMAL_COUNTER	0
 #define FL_SIMPLE_COUNTER	1
 
+/**
+  \class Fl_Counter
+  \brief Fl_Counter widget for Forms compatibility.
+
+  The Fl_Counter widget is provided for forms compatibility.
+  It controls a single floating point value.
+
+  \todo Refactor the doxygen comments for Fl_Counter type() documentation.
+
+  The type of an Fl_Counter object can be set using type(uchar t) to:
+  \li \c FL_NORMAL_COUNTER: Displays a counter with 4 arrow buttons.
+  \li \c FL_SIMPLE_COUNTER: Displays a counter with only 2 arrow buttons.
+ */
 class FL_EXPORT Fl_Counter : public Fl_Valuator {
 
   Fl_Font textfont_;
@@ -56,9 +69,17 @@ protected:
 public:
 
   int handle(int);
-  Fl_Counter(int,int,int,int,const char * = 0);
+
+  Fl_Counter(int X, int Y, int W, int H, const char* L = 0);
   ~Fl_Counter();
+
+  /**
+    Set the increment for the double-arrow buttons.
+    The default value is 1.0.
+    \param[in] a increment value
+   */
   void lstep(double a) {lstep_ = a;}
+
   void step(double a,double b) {Fl_Valuator::step(a); lstep_ = b;}
   void step(double a) {Fl_Valuator::step(a);}
   Fl_Font textfont() const {return textfont_;}
diff --git a/src/Fl_Button.cxx b/src/Fl_Button.cxx
index a3f0a8d6a..044d1e443 100644
--- a/src/Fl_Button.cxx
+++ b/src/Fl_Button.cxx
@@ -3,7 +3,7 @@
 //
 // Button widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2006 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -34,6 +34,12 @@
 // them are implemented by setting the type() value and testing it
 // here.  This includes Fl_Radio_Button and Fl_Toggle_Button
 
+/**
+  Sets the current value of the button.
+  A non-zero value sets the button to 1 (ON), and zero sets it to 0 (OFF).
+  \param[in] v button value.
+  \see set(), clear()
+ */
 int Fl_Button::value(int v) {
   v = v ? 1 : 0;
   oldval = v;
@@ -48,6 +54,10 @@ int Fl_Button::value(int v) {
   }
 }
 
+/**
+  Turns on this button and turns off all other radio buttons in the group
+  (calling \c value(1) or \c set() does not do this).
+ */
 void Fl_Button::setonly() { // set this radio button on, turn others off
   value(1);
   Fl_Group* g = (Fl_Group*)parent();
@@ -159,8 +169,13 @@ int Fl_Button::handle(int event) {
   }
 }
 
-Fl_Button::Fl_Button(int X, int Y, int W, int H, const char *l)
-: Fl_Widget(X,Y,W,H,l) {
+/**
+  The constructor creates the button using the given position, size and label.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Button::Fl_Button(int X, int Y, int W, int H, const char *L)
+: Fl_Widget(X,Y,W,H,L) {
   box(FL_UP_BOX);
   down_box(FL_NO_BOX);
   value_ = oldval = 0;
diff --git a/src/Fl_Chart.cxx b/src/Fl_Chart.cxx
index 48529924d..fad325f48 100644
--- a/src/Fl_Chart.cxx
+++ b/src/Fl_Chart.cxx
@@ -3,7 +3,7 @@
 //
 // Forms-compatible chart widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -285,8 +285,14 @@ void Fl_Chart::draw() {
 #define FL_CHART_LCOL		FL_LCOL
 #define FL_CHART_ALIGN		FL_ALIGN_BOTTOM
 
-Fl_Chart::Fl_Chart(int X, int Y, int W, int H,const char *l) :
-Fl_Widget(X,Y,W,H,l) {
+/**
+  Create a new Fl_Chart widget using the given position, size and label string.
+  The default boxstyle is \c FL_NO_BOX.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Chart::Fl_Chart(int X, int Y, int W, int H,const char *L) :
+Fl_Widget(X,Y,W,H,L) {
   box(FL_BORDER_BOX);
   align(FL_ALIGN_BOTTOM);
   numb       = 0;
@@ -300,15 +306,28 @@ Fl_Widget(X,Y,W,H,l) {
   entries    = (FL_CHART_ENTRY *)calloc(sizeof(FL_CHART_ENTRY), FL_CHART_MAX + 1);
 }
 
+/**
+  Destroys the Fl_Chart widget and all of its data.
+ */
 Fl_Chart::~Fl_Chart() {
   free(entries);
 }
 
+/**
+  Removes all values from the chart.
+ */
 void Fl_Chart::clear() {
   numb = 0;
   redraw();
 }
 
+/**
+  Add the data value \p val with optional label \p str and color \p col
+  to the chart.
+  \param[in] val data value
+  \param[in] str optional data label
+  \param[in] col optional data color
+ */
 void Fl_Chart::add(double val, const char *str, unsigned col) {
   /* Allocate more entries if required */
   if (numb >= sizenumb) {
@@ -331,6 +350,14 @@ void Fl_Chart::add(double val, const char *str, unsigned col) {
   redraw();
 }
 
+/**
+  Inserts a data value \p val at the given position \p ind.
+  Position 1 is the first data value.
+  \param[in] ind insertion position
+  \param[in] val data value
+  \param[in] str optional data label
+  \param[in] col optional data color
+ */
 void Fl_Chart::insert(int ind, double val, const char *str, unsigned col) {
   int i;
   if (ind < 1 || ind > numb+1) return;
@@ -353,6 +380,14 @@ void Fl_Chart::insert(int ind, double val, const char *str, unsigned col) {
   redraw();
 }
 
+/**
+  Replace a data value \p val at the given position \p ind.
+  Position 1 is the first data value.
+  \param[in] ind insertion position
+  \param[in] val data value
+  \param[in] str optional data label
+  \param[in] col optional data color
+ */
 void Fl_Chart::replace(int ind,double val, const char *str, unsigned col) {
   if (ind < 1 || ind > numb) return;
   entries[ind-1].val = float(val);
@@ -365,12 +400,22 @@ void Fl_Chart::replace(int ind,double val, const char *str, unsigned col) {
   redraw();
 }
 
-void Fl_Chart::bounds(double mymin, double mymax) {
-  this->min = mymin;
-  this->max = mymax;
+/**
+  Sets the lower and upper bounds of the chart values.
+  \param[in] a, b are used to set lower, upper
+ */
+void Fl_Chart::bounds(double a, double b) {
+  this->min = a;
+  this->max = b;
   redraw();
 }
 
+/**
+  Set the maximum number of data values for a chart.
+  If you do not call this method then the chart will be allowed to grow
+  to any size depending on available memory.
+  \param[in] m maximum number of data values allowed.
+ */
 void Fl_Chart::maxsize(int m) {
   int i;
   /* Fill in the new number */
diff --git a/src/Fl_Check_Button.cxx b/src/Fl_Check_Button.cxx
index addd33d38..38bf5188b 100644
--- a/src/Fl_Check_Button.cxx
+++ b/src/Fl_Check_Button.cxx
@@ -3,7 +3,7 @@
 //
 // Check button widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -28,12 +28,19 @@
 #include <FL/Fl.H>
 #include <FL/Fl_Check_Button.H>
 
+// TODO Correct incorrect Fl_Check_Button comments.
 // A subclass of Fl_Button that always draws as a diamond box.  This
 // diamond is smaller than the widget size and can be surchecked by
 // another box type, for compatibility with Forms.
 
-Fl_Check_Button::Fl_Check_Button(int X, int Y, int W, int H, const char *l)
-: Fl_Light_Button(X, Y, W, H, l) {
+/**
+  Creates a new Fl_Check_Button widget using the given position, size and
+  label string.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Check_Button::Fl_Check_Button(int X, int Y, int W, int H, const char *L)
+: Fl_Light_Button(X, Y, W, H, L) {
   box(FL_NO_BOX);
   down_box(FL_DOWN_BOX);
   selection_color(FL_FOREGROUND_COLOR);
diff --git a/src/Fl_Choice.cxx b/src/Fl_Choice.cxx
index 469658a07..243fe83e9 100644
--- a/src/Fl_Choice.cxx
+++ b/src/Fl_Choice.cxx
@@ -3,7 +3,7 @@
 //
 // Choice widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2006 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -112,8 +112,18 @@ void Fl_Choice::draw() {
   draw_label();
 }
 
-Fl_Choice::Fl_Choice(int X, int Y, int W, int H, const char *l)
-: Fl_Menu_(X,Y,W,H,l) {
+/**
+  Create a new Fl_Choice widget using the given position, size and label string.
+  The default boxtype is \c FL_UP_BOX.
+
+  The constructor sets menu() to NULL.
+  See Fl_Menu_ for the methods to set or change the menu.
+
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Choice::Fl_Choice(int X, int Y, int W, int H, const char *L)
+: Fl_Menu_(X,Y,W,H,L) {
   align(FL_ALIGN_LEFT);
   when(FL_WHEN_RELEASE);
   textfont(FL_HELVETICA);
@@ -121,12 +131,24 @@ Fl_Choice::Fl_Choice(int X, int Y, int W, int H, const char *l)
   down_box(FL_BORDER_BOX);
 }
 
+/**
+  Sets the currently selected value using a pointer to menu item.
+  Changing the selected value causes a redraw().
+  \param[in] v pointer to menu item in the menu item array.
+  \returns non-zero if the new value is different to the old one.
+ */
 int Fl_Choice::value(const Fl_Menu_Item *v) {
   if (!Fl_Menu_::value(v)) return 0;
   redraw();
   return 1;
 }
 
+/**
+  Sets the currently selected value using the index into the menu item array.
+  Changing the selected value causes a redraw().
+  \param[in] v index of value in the menu item array.
+  \returns non-zero if the new value is different to the old one.
+ */
 int Fl_Choice::value(int v) {
   if (v == -1) return value((const Fl_Menu_Item *)0);
   if (v < 0 || v >= (size() - 1)) return 0;
diff --git a/src/Fl_Clock.cxx b/src/Fl_Clock.cxx
index 7d724402e..b13223c5e 100644
--- a/src/Fl_Clock.cxx
+++ b/src/Fl_Clock.cxx
@@ -3,7 +3,7 @@
 //
 // Clock widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2006 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -112,6 +112,12 @@ void Fl_Clock_Output::draw() {
   draw_label();
 }
 
+/**
+  Set the displayed time.
+  Set the time in hours, minutes, and seconds.
+  \param[in] H, m, s displayed time
+  \see hour(), minute(), second()
+ */
 void Fl_Clock_Output::value(int H, int m, int s) {
   if (H!=hour_ || m!=minute_ || s!=second_) {
     hour_ = H; minute_ = m; second_ = s;
@@ -120,6 +126,12 @@ void Fl_Clock_Output::value(int H, int m, int s) {
   }
 }
 
+/**
+  Set the displayed time.
+  Set the time in seconds since the UNIX epoch (January 1, 1970).
+  \param[in] v seconds since epoch
+  \see value()
+ */
 void Fl_Clock_Output::value(ulong v) {
   value_ = v;
   struct tm *timeofday;
@@ -129,8 +141,14 @@ void Fl_Clock_Output::value(ulong v) {
   value(timeofday->tm_hour, timeofday->tm_min, timeofday->tm_sec);
 }
 
-Fl_Clock_Output::Fl_Clock_Output(int X, int Y, int W, int H, const char *l)
-: Fl_Widget(X, Y, W, H, l) {
+/**
+  Create a new Fl_Clock_Output widget with the given position, size and label.
+  The default boxtype is \c FL_NO_BOX.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Clock_Output::Fl_Clock_Output(int X, int Y, int W, int H, const char *L)
+: Fl_Widget(X, Y, W, H, L) {
   box(FL_UP_BOX);
   selection_color(fl_gray_ramp(5));
   align(FL_ALIGN_BOTTOM);
@@ -142,11 +160,24 @@ Fl_Clock_Output::Fl_Clock_Output(int X, int Y, int W, int H, const char *l)
 
 ////////////////////////////////////////////////////////////////
 
-Fl_Clock::Fl_Clock(int X, int Y, int W, int H, const char *l)
-  : Fl_Clock_Output(X, Y, W, H, l) {}
-
-Fl_Clock::Fl_Clock(uchar t, int X, int Y, int W, int H, const char *l)
-  : Fl_Clock_Output(X, Y, W, H, l) {
+/**
+  Create an Fl_Clock widget using the given position, size, and label string.
+  The default boxtype is \c FL_NO_BOX.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Clock::Fl_Clock(int X, int Y, int W, int H, const char *L)
+  : Fl_Clock_Output(X, Y, W, H, L) {}
+
+/**
+  Create an Fl_Clock widget using the given boxtype, position, size, and
+  label string.
+  \param[in] t boxtype
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Clock::Fl_Clock(uchar t, int X, int Y, int W, int H, const char *L)
+  : Fl_Clock_Output(X, Y, W, H, L) {
   type(t);
   box(t==FL_ROUND_CLOCK ? FL_NO_BOX : FL_UP_BOX);
 }
@@ -168,6 +199,9 @@ int Fl_Clock::handle(int event) {
   return Fl_Clock_Output::handle(event);
 }
   
+/**
+  The destructor removes the clock.
+ */
 Fl_Clock::~Fl_Clock() {
   Fl::remove_timeout(tick, this);
 }
diff --git a/src/Fl_Color_Chooser.cxx b/src/Fl_Color_Chooser.cxx
index d97b2b577..01e4edbe7 100644
--- a/src/Fl_Color_Chooser.cxx
+++ b/src/Fl_Color_Chooser.cxx
@@ -3,7 +3,7 @@
 //
 // Color chooser for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -47,6 +47,11 @@
 // you get this by defining this:
 #define UPDATE_HUE_BOX 1
 
+/**
+  This \e static method converts HSV colors to RGB colorspace.
+  \param[in] H, S, V color components
+  \param[out] R, G, B color components
+ */
 void Fl_Color_Chooser::hsv2rgb(
 	double H, double S, double V, double& R, double& G, double& B) {
   if (S < 5.0e-6) {
@@ -68,6 +73,11 @@ void Fl_Color_Chooser::hsv2rgb(
   }
 }
 
+/**
+  This \e static method converts RGB colors to HSV colorspace.
+  \param[in] R, G, B color components
+  \param[out] H, S, V color components
+ */
 void Fl_Color_Chooser::rgb2hsv(
 	double R, double G, double B, double& H, double& S, double& V) {
   double maxv = R > G ? R : G; if (B > maxv) maxv = B;
@@ -119,6 +129,12 @@ void Fl_Color_Chooser::set_valuators() {
   }
 }
 
+/**
+  Sets the current rgb color values.
+  Does not do the callback. Does not clamp (but out of range values will
+  produce psychedelic effects in the hue selector).
+  \param[in] R, G, B color components.
+ */
 int Fl_Color_Chooser::rgb(double R, double G, double B) {
   if (R == r_ && G == g_ && B == b_) return 0;
   r_ = R; g_ = G; b_ = B;
@@ -140,6 +156,12 @@ int Fl_Color_Chooser::rgb(double R, double G, double B) {
   return 1;
 }
 
+/**
+  Set the hsv values.
+  The passed values are clamped (or for hue, modulus 6 is used) to get
+  legal values. Does not do the callback.
+  \param[in] H, S, V color components.
+ */
 int Fl_Color_Chooser::hsv(double H, double S, double V) {
   H = fmod(H,6.0); if (H < 0.0) H += 6.0;
   if (S < 0.0) S = 0.0; else if (S > 1.0) S = 1.0;
@@ -413,6 +435,13 @@ void Fl_Color_Chooser::mode_cb(Fl_Widget* o, void*) {
 
 ////////////////////////////////////////////////////////////////
 
+/**
+  Creates a new Fl_Color_Chooser widget using the given position, size, and
+  label string.
+  The recommended dimensions are 200x95. The color is initialized to black.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
 Fl_Color_Chooser::Fl_Color_Chooser(int X, int Y, int W, int H, const char* L)
   : Fl_Group(0,0,195,115,L),
     huebox(0,0,115,115),
diff --git a/src/Fl_Counter.cxx b/src/Fl_Counter.cxx
index 656016e42..f0a79a417 100644
--- a/src/Fl_Counter.cxx
+++ b/src/Fl_Counter.cxx
@@ -3,7 +3,7 @@
 //
 // Counter widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2005 by Bill Spitzak and others.
+// Copyright 1998-2008 by Bill Spitzak and others.
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Library General Public
@@ -174,12 +174,21 @@ int Fl_Counter::handle(int event) {
   }
 }
 
+/**
+  Destroys the valuator.
+ */
 Fl_Counter::~Fl_Counter() {
   Fl::remove_timeout(repeat_callback, this);
 }
 
-Fl_Counter::Fl_Counter(int X, int Y, int W, int H, const char* l)
-  : Fl_Valuator(X, Y, W, H, l) {
+/**
+  Creates a new Fl_Counter widget using the given position, size, and label
+  string. The default type is FL_NORMAL_COUNTER.
+  \param[in] X, Y, W, H position and size of the widget
+  \param[in] L widget label, default is no label
+ */
+Fl_Counter::Fl_Counter(int X, int Y, int W, int H, const char* L)
+  : Fl_Valuator(X, Y, W, H, L) {
   box(FL_UP_BOX);
   selection_color(FL_INACTIVE_COLOR); // was FL_BLUE
   align(FL_ALIGN_BOTTOM);