Doxygen documentation WP8 Done. Reserved WP9, WP10. Will now check WP3 from engelsman and integrates it.

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

7 files changed, 205 insertions, 5 deletions

diff --git a/FL/Fl_Box.H b/FL/Fl_Box.H
index 3f6df7113..b6a1475fd 100644
--- a/FL/Fl_Box.H
+++ b/FL/Fl_Box.H
@@ -32,13 +32,27 @@
 #include "Fl_Widget.H"
 #endif
 
+/**
+  This widget simply draws its box, and possibly it's label.  Putting it
+  before some other widgets and making it big enough to surround them
+  will let you draw a frame around them.
+*/
 class FL_EXPORT Fl_Box : public Fl_Widget {
 protected:
   void draw();
 public:
-  Fl_Box(int X, int Y, int W, int H, const char *l=0)
+  /**
+    The first constructor sets box() to FL_NO_BOX, which
+    means it is invisible. However such widgets are useful as placeholders
+    or Fl_Group::resizable()
+    values.  To change the box to something visible, use box(n).
+    <P>The second form of the constructor sets the box to the specified box
+    type.
+  */
+    Fl_Box(int X, int Y, int W, int H, const char *l=0)
 	: Fl_Widget(X,Y,W,H,l) {}
-  Fl_Box(Fl_Boxtype b, int X, int Y, int W, int H, const char *l)
+  /**    See Fl_Box::Fl_Box(int x, int y, int w, int h, const char * = 0)   */
+    Fl_Box(Fl_Boxtype b, int X, int Y, int W, int H, const char *l)
 	: Fl_Widget(X,Y,W,H,l) {box(b);}
 
   virtual int handle(int);
diff --git a/FL/Fl_Repeat_Button.H b/FL/Fl_Repeat_Button.H
index 56e0a3bd7..0087198d1 100644
--- a/FL/Fl_Repeat_Button.H
+++ b/FL/Fl_Repeat_Button.H
@@ -30,10 +30,21 @@
 #include "Fl.H"
 #include "Fl_Button.H"
 
+/**
+  The Fl_Repeat_Button is a subclass of Fl_Button that
+  generates a callback when it is pressed and then repeatedly generates
+  callbacks as long as it is held down.  The speed of the repeat is fixed
+  and depends on the implementation.
+*/
 class FL_EXPORT Fl_Repeat_Button : public Fl_Button {
   static void repeat_callback(void *);
 public:
   int handle(int);
+  /**
+    Creates a new Fl_Repeat_Button widget using the given
+    position, size, and label string. The default boxtype is FL_UP_BOX
+    .
+  */
   Fl_Repeat_Button(int X,int Y,int W,int H,const char *l=0)
     : Fl_Button(X,Y,W,H,l) {}
   void deactivate() {
diff --git a/FL/Fl_Return_Button.H b/FL/Fl_Return_Button.H
index bdc02f617..ea39a7262 100644
--- a/FL/Fl_Return_Button.H
+++ b/FL/Fl_Return_Button.H
@@ -29,11 +29,22 @@
 #define Fl_Return_Button_H
 #include "Fl_Button.H"
 
+/**
+  The Fl_Return_Button is a subclass of Fl_Button that
+  generates a callback when it is pressed or when the user presses the
+  Enter key.  A carriage-return symbol is drawn next to the button label.
+  <P ALIGN=CENTER>\image html Fl_Return_Button.gif
+*/
 class FL_EXPORT Fl_Return_Button : public Fl_Button {
 protected:
   void draw();
 public:
   int handle(int);
+  /**
+    Creates a new Fl_Return_Button widget using the given
+    position, size, and label string. The default boxtype is FL_UP_BOX
+    .
+  */
   Fl_Return_Button(int X, int Y, int W, int H,const char *l=0)
     : Fl_Button(X,Y,W,H,l) {}
 };
diff --git a/FL/Fl_Round_Button.H b/FL/Fl_Round_Button.H
index f1bf6ed0b..c0365add1 100644
--- a/FL/Fl_Round_Button.H
+++ b/FL/Fl_Round_Button.H
@@ -30,6 +30,17 @@
 
 #include "Fl_Light_Button.H"
 
+/**
+  Buttons generate callbacks when they are clicked by the user.  You
+  control exactly when and how by changing the values for type()
+  and when().
+  <P ALIGN=CENTER>\image html Fl_Round_Button.gif</P>
+  <P>The Fl_Round_Button subclass display the &quot;on&quot; state by
+  turning on a light, rather than drawing pushed in.  The shape of the
+  &quot;light&quot; is initially set to FL_ROUND_DOWN_BOX.  The color of the light
+  when on is controlled with selection_color(), which defaults to
+  FL_RED.
+*/
 class FL_EXPORT Fl_Round_Button : public Fl_Light_Button {
 public:
   Fl_Round_Button(int x,int y,int w,int h,const char *l = 0);
diff --git a/FL/Fl_Scroll.H b/FL/Fl_Scroll.H
index 0838c54f0..49390e123 100644
--- a/FL/Fl_Scroll.H
+++ b/FL/Fl_Scroll.H
@@ -31,6 +31,63 @@
 #include "Fl_Group.H"
 #include "Fl_Scrollbar.H"
 
+/**
+  This container widget lets you maneuver around a set of widgets much
+  larger than your window.  If the child widgets are larger than the size
+  of this object then scrollbars will appear so that you can scroll over
+  to them:
+  <P ALIGN=CENTER>\image html Fl_Scroll.gif </P>
+  <P>If all of the child widgets are packed together into a solid
+  rectangle then you want to set box() to FL_NO_BOX or
+  one of the _FRAME types. This will result in the best output.
+  However, if the child widgets are a sparse arrangment you must set 
+  box() to a real _BOX type.  This can result in some
+  blinking during redrawing, but that can be solved by using a 
+  Fl_Double_Window. </P>
+
+  By default you can scroll in both directions, and the scrollbars
+  disappear if the data will fit in the area of the scroll. 
+  <P>Use Fl_Scroll::type() to change this as follows :
+  <UL>
+  <LI>0                            - No scrollbars </LI>
+  <LI>Fl_Scroll::HORIZONTAL        - Only a horizontal scrollbar. </LI>
+  <LI>Fl_Scroll::VERTICAL          - Only a vertical scrollbar. </LI>
+  <LI>Fl_Scroll::BOTH              - The default is both scrollbars. </LI>
+  <LI>Fl_Scroll::HORIZONTAL_ALWAYS - Horizontal scrollbar always on, vertical always off. </LI>
+  <LI>Fl_Scroll::VERTICAL_ALWAYS   - Vertical scrollbar always on, horizontal always off. </LI>
+  <LI>Fl_Scroll::BOTH_ALWAYS       - Both always on. </LI>
+  </UL>
+
+  <P> Use <B> scrollbar.align(int) ( see void Fl_Widget::align(Fl_Align) ) :</B>
+  to change what side the scrollbars are drawn on.<BR>If the 
+  FL_ALIGN_LEFT bit is on, the vertical scrollbar is on the left.
+  If the FL_ALIGN_TOP bit is on, the horizontal scrollbar is on
+  the top. Note that only the alignment flags in scrollbar are 
+  considered. The flags in hscrollbar however are ignored.
+
+  <P>This widget can also be used to pan around a single child widget
+  &quot;canvas&quot;.  This child widget should be of your own class, with a 
+  draw() method that draws the contents.  The scrolling is done by
+  changing the x() and y() of the widget, so this child
+  must use the x() and y() to position it's drawing.
+  To speed up drawing it should test fl_push_clip().
+
+  <P>Another very useful child is a single 
+  Fl_Pack, which is itself a group that packs it's children
+  together and changes size to surround them.  Filling the Fl_Pack
+  with Fl_Tabs groups (and then putting
+  normal widgets inside those) gives you a very powerful scrolling list
+  of individually-openable panels. </P>
+
+  <P>Fluid lets you create these, but you can only lay out objects that
+  fit inside the Fl_Scroll without scrolling.  Be sure to leave
+  space for the scrollbars, as Fluid won't show these either. </P>
+  <P><I>You cannot use Fl_Window as a child of this since the
+  clipping is not conveyed to it when drawn, and it will draw over the
+  scrollbars and neighboring objects.</I>
+*/
+
+*/
 class FL_EXPORT Fl_Scroll : public Fl_Group {
 
   int xposition_, yposition_;
@@ -66,7 +123,9 @@ public:
     BOTH_ALWAYS = 7
   };
 
+  /**    Gets the current horizontal scrolling position.  */
   int xposition() const {return xposition_;}
+  /**    Gets the current vertical scrolling position.  */
   int yposition() const {return yposition_;}
   void scroll_to(int, int);
   void clear();
diff --git a/FL/Fl_Scrollbar.H b/FL/Fl_Scrollbar.H
index 0d474ea0b..43fd7a752 100644
--- a/FL/Fl_Scrollbar.H
+++ b/FL/Fl_Scrollbar.H
@@ -30,6 +30,19 @@
 
 #include "Fl_Slider.H"
 
+/**
+  The Fl_Scrollbar widget displays a slider with arrow buttons
+  at the ends of the scrollbar. Clicking on the arrows move up/left and
+  down/right by linesize().  Scrollbars also accept 
+  FL_SHORTCUT events: the arrows move by linesize(), and
+  vertical scrollbars take Page Up/Down (they move by the page size minus 
+  linesize()) and Home/End (they jump to the top or bottom).
+  <P>Scrollbars have step(1) preset (they always return
+  integers). If desired you can set the step() to non-integer
+  values.  You will then have to use casts to get at the floating-point
+  versions of value() from Fl_Slider. </P>
+  <P ALIGN=CENTER>\image html scrollbar.gif
+*/
 class FL_EXPORT Fl_Scrollbar : public Fl_Slider {
 
   int linesize_;
@@ -45,11 +58,31 @@ public:
   ~Fl_Scrollbar();
   int handle(int);
 
+  /**
+    The first form returns the integer value of the scrollbar. You can get
+    the floating point value with Fl_Slider::value().  The second
+    form sets value(), range(), and slider_size()
+    to make a variable-sized scrollbar. You should call this every time
+    your window changes size, your data changes size, or your scroll
+    position changes (even if in response to a callback from this
+    scrollbar).  All necessary calls to redraw() are done.
+  */
   int value() {return int(Fl_Slider::value());}
+  /**    See int Fl_Scrollbar::value()   */
   int value(int p, int s, int top, int total) {
     return scrollvalue(p, s, top, total);
   }
+  /**
+    This number controls how big the steps are that the arrow keys do.  In
+    addition page up/down move by the size last sent to value()
+    minus one linesize().  The default is 16.
+  */
   int linesize() const {return linesize_;}
+  /**
+    This number controls how big the steps are that the arrow keys do.  In
+    addition page up/down move by the size last sent to value()
+    minus one linesize().  The default is 16.
+  */
   void linesize(int i) {linesize_ = i;}
 
 };
diff --git a/FL/Fl_Valuator.H b/FL/Fl_Valuator.H
index 0959c2dba..7b0446c95 100644
--- a/FL/Fl_Valuator.H
+++ b/FL/Fl_Valuator.H
@@ -36,6 +36,19 @@
 #define FL_VERTICAL		0
 #define FL_HORIZONTAL		1
 
+/**
+  The Fl_Valuator class controls a single floating-point value
+  and provides a consistent interface to set the value, range, and step,
+  and insures that callbacks are done the same for every object.
+  <P>There are probably more of these classes in FLTK than any others: </P>
+  <P ALIGN=CENTER>\image html  src=</P>
+  <P>In the above diagram each box surrounds an actual subclass.  These
+  are further differentiated by setting the 
+  type() of the widget to the symbolic value labeling the
+  widget.  The ones labelled &quot;0&quot; are the default versions with a 
+  type(0).  For consistency the symbol FL_VERTICAL is
+  defined as zero.
+*/
 class FL_EXPORT Fl_Valuator : public Fl_Widget {
 
   double value_;
@@ -58,18 +71,66 @@ protected:
 
 public:
 
-  void bounds(double a, double b) {min=a; max=b;}
-  double minimum() const {return min;}
-  void minimum(double a) {min = a;}
+  /**
+    Sets the minimum (a) and maximum (b) values for
+    the valuator widget.
+  */
+    void bounds(double a, double b) {min=a; max=b;}
+  /**    Gets or sets the minimum value for the valuator.  */
+    double minimum() const {return min;}
+  /**    Gets or sets the minimum value for the valuator.  */
+    void minimum(double a) {min = a;}
+  /**    Gets or sets the maximum value for the valuator.  */
   double maximum() const {return max;}
+  /**    Gets or sets the maximum value for the valuator.  */
   void maximum(double a) {max = a;}
+  /**
+    Sets the minimum and maximum values for the valuator. When
+    the user manipulates the widget, the value is limited to this
+    range. This clamping is done <I>after</I> rounding to the step
+    value (this makes a difference if the range is not a multiple of
+    the step).
+    
+    <P>The minimum may be greater than the maximum. This has the
+    effect of &quot;reversing&quot; the object so the larger values
+    are in the opposite direction. This also switches which end of
+    the filled sliders is filled.</P>
+    
+    <P>Some widgets consider this a &quot;soft&quot; range.  This
+    means they will stop at the range, but if the user releases and
+    grabs the control again and tries to move it further, it is
+    allowed.</P>
+    
+    <P>The range may affect the display. You must redraw()
+    the widget after changing the range.
+  */
   void range(double a, double b) {min = a; max = b;}
+  /**    See double Fl_Valuator::step() const   */
   void step(int a) {A = a; B = 1;}
+  /**    See double Fl_Valuator::step() const   */
   void step(double a, int b) {A = a; B = b;}
   void step(double s);
+  /**
+    Gets or sets the step value. As the user moves the mouse the
+    value is rounded to the nearest multiple of the step value. This
+    is done <I>before</I> clamping it to the range. For most widgets
+    the default step is zero.
+    
+    <P>For precision the step is stored as the ratio of two
+    integers, A/B. You can set these integers directly. Currently
+    setting a floating point value sets the nearest A/1 or 1/B value
+    possible.
+  */
   double step() const {return A/B;}
   void precision(int);
 
+  /**
+    Gets or sets the current value. The new value is <I>not</I>
+    clamped or otherwise changed before storing it. Use
+    clamp() or round() to modify the value before
+    calling value(). The widget is redrawn if the new value
+    is different than the current one. The initial value is zero.
+  */
   double value() const {return value_;}
   int value(double);