Doxygen documentation WP10 Done. Reserved WP11.

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

9 files changed, 203 insertions, 15 deletions

diff --git a/FL/Fl_Adjuster.H b/FL/Fl_Adjuster.H
index 8328e1bda..48a7cc1f4 100644
--- a/FL/Fl_Adjuster.H
+++ b/FL/Fl_Adjuster.H
@@ -34,6 +34,17 @@
 #include "Fl_Valuator.H"
 #endif
 
+/**
+  The Fl_Adjuster widget was stolen from Prisms, and has proven
+  to be very useful for values that need a large dynamic range.
+  <P ALIGN=CENTER>\image html adjuster1.gif</P>
+  <P>When you  press a button and drag to the right the value increases.
+  When you drag  to the left it decreases.  The largest button adjusts by
+  100 *  step(), the next by 10 * step() and that
+  smallest button  by step().  Clicking on the buttons
+  increments by 10 times the  amount dragging by a pixel does. Shift +
+  click decrements by 10 times  the amount.
+*/
 class FL_EXPORT Fl_Adjuster : public Fl_Valuator {
   int drag;
   int ix;
@@ -44,7 +55,19 @@ protected:
   void value_damage();
 public:
   Fl_Adjuster(int X,int Y,int W,int H,const char *l=0);
+  /**
+    If &quot;soft&quot; is turned on, the user is allowed to drag the value outside
+    the range.  If they drag the value to one of the ends, let go, then
+    grab again and continue to drag, they can get to any value.  Default is
+    one.
+  */
   void soft(int s) {soft_ = s;}
+  /**
+    If &quot;soft&quot; is turned on, the user is allowed to drag the value outside
+    the range.  If they drag the value to one of the ends, let go, then
+    grab again and continue to drag, they can get to any value.  Default is
+    one.
+  */
   int soft() const {return soft_;}
 };
 
diff --git a/FL/Fl_Multiline_Output.H b/FL/Fl_Multiline_Output.H
index 7aac4b9a4..c9566e252 100644
--- a/FL/Fl_Multiline_Output.H
+++ b/FL/Fl_Multiline_Output.H
@@ -25,15 +25,26 @@
 //     http://www.fltk.org/str.php
 //
 
+
 #ifndef Fl_Multiline_Output_H
 #define Fl_Multiline_Output_H
 
 #include "Fl_Output.H"
 
+/**
+  This widget is a subclass of Fl_Output that displays multiple
+  lines of text. It also displays tab characters as whitespace to the
+  next column.
+*/
 class Fl_Multiline_Output : public Fl_Output {
 public:
-    Fl_Multiline_Output(int X,int Y,int W,int H,const char *l = 0)
-	: Fl_Output(X,Y,W,H,l) {type(FL_MULTILINE_OUTPUT);}
+  /**
+    Creates a new Fl_Multiline_Output widget using the given
+    position, size, and label string. The default boxtype is FL_DOWN_BOX
+    <P> Inherited destructor destroys the widget and any value associated with it.
+  */
+  Fl_Multiline_Output(int X,int Y,int W,int H,const char *l = 0)
+    : Fl_Output(X,Y,W,H,l) {type(FL_MULTILINE_OUTPUT);}
 };
 
 #endif
diff --git a/FL/Fl_Output.H b/FL/Fl_Output.H
index 93d3e6870..59938a87f 100644
--- a/FL/Fl_Output.H
+++ b/FL/Fl_Output.H
@@ -29,10 +29,30 @@
 #define Fl_Output_H
 
 #include "Fl_Input.H"
-
+/**
+  This widget displays a piece of text.  When you set the value()
+  , Fl_Output does a strcpy() to it's own storage,
+  which is useful for program-generated values.  The user may select
+  portions of the text using the mouse and paste the contents into other
+  fields or programs.
+  <CENTER>\image html text.gif</CENTER>
+  <P>There is a single subclass, 
+  Fl_Multiline_Output, which allows you to display multiple lines of
+  text. </P>
+  <P>The text may contain any characters except \0, and will correctly
+  display anything, using ^X notation for unprintable control characters
+  and \nnn notation for unprintable characters with the high bit set. It
+  assumes the font can draw any characters in the ISO-Latin1 character
+  set.
+*/
 class Fl_Output : public Fl_Input {
 public:
-  Fl_Output(int X,int Y,int W,int H, const char *l = 0)
+  /**
+    Creates a new Fl_Output widget using the given position,
+    size, and label string. The default boxtype is FL_DOWN_BOX.
+    <P>Inherited destrucor destroys the widget and any value associated with it.
+  */
+    Fl_Output(int X,int Y,int W,int H, const char *l = 0)
     : Fl_Input(X, Y, W, H, l) {type(FL_NORMAL_OUTPUT);}
 };
 
diff --git a/FL/Fl_Roller.H b/FL/Fl_Roller.H
index 61ef8a846..80b349930 100644
--- a/FL/Fl_Roller.H
+++ b/FL/Fl_Roller.H
@@ -32,6 +32,11 @@
 #include "Fl_Valuator.H"
 #endif
 
+/**
+  The Fl_Roller widget is a &quot;dolly&quot; control commonly used to
+  move 3D objects.
+  <P ALIGN=CENTER>\image html Fl_Roller.gif
+*/
 class FL_EXPORT Fl_Roller : public Fl_Valuator {
 protected:
   void draw();
diff --git a/FL/Fl_Slider.H b/FL/Fl_Slider.H
index 0277bc25a..9adb48296 100644
--- a/FL/Fl_Slider.H
+++ b/FL/Fl_Slider.H
@@ -40,6 +40,30 @@
 #define FL_VERT_NICE_SLIDER	4
 #define FL_HOR_NICE_SLIDER	5
 
+/**
+  The Fl_Slider widget contains a sliding knob inside a box. It
+  if often used as a scrollbar.  Moving the box all the way to the
+  top/left sets it to the minimum(), and to the bottom/right to
+  the maximum().  The minimum() may be greater than the 
+  maximum() to reverse the slider direction.
+
+  <P>Use void Fl_Widget::type(int) to set how the slider is drawn, 
+  which can be one of the following:
+  <UL>
+  <LI>FL_VERTICAL - Draws a vertical slider (this is the
+  default). </LI>
+  <LI>FL_HORIZONTAL - Draws a horizontal slider. </LI>
+  <LI>FL_VERT_FILL_SLIDER - Draws a filled vertical  slider,
+  useful as a progress or value meter. </LI>
+  <LI>FL_HOR_FILL_SLIDER - Draws a filled horizontal  slider,
+  useful as a progress or value meter. </LI>
+  <LI>FL_VERT_NICE_SLIDER - Draws a vertical slider with  a nice
+  looking control knob. </LI>
+  <LI>FL_HOR_NICE_SLIDER - Draws a horizontal slider with  a
+  nice looking control knob. </LI>
+  </UL>
+  <P ALIGN=CENTER>\image html slider.gif
+*/
 class FL_EXPORT Fl_Slider : public Fl_Valuator {
 
   float slider_size_;
@@ -62,9 +86,20 @@ public:
 
   int scrollvalue(int windowtop,int windowsize,int first,int totalsize);
   void bounds(double a, double b);
+  /**
+    Get or set the dimensions of the moving piece of slider.  This is the
+    fraction of the size of the entire widget.  If you set this to 1 then
+    the slider cannot move.  The default value is .08.
+    <P>For the &quot;fill&quot; sliders this is the size of the area around the end
+    that causes a drag effect rather than causing the slider to jump to the
+    mouse.
+  */
   float slider_size() const {return slider_size_;}
+  /** See float slider_size() const  */
   void slider_size(double v);
+  /** Gets the slider box type. */
   Fl_Boxtype slider() const {return (Fl_Boxtype)slider_;}
+  /** Sets the slider box type. */
   void slider(Fl_Boxtype c) {slider_ = c;}
 };
 
diff --git a/FL/Fl_Valuator.H b/FL/Fl_Valuator.H
index 7b0446c95..5df930c72 100644
--- a/FL/Fl_Valuator.H
+++ b/FL/Fl_Valuator.H
@@ -71,19 +71,16 @@ protected:
 
 public:
 
-  /**
-    Sets the minimum (a) and maximum (b) values for
-    the valuator widget.
-  */
+    /**    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.  */
+    /**    Gets the minimum value for the valuator.  */
     double minimum() const {return min;}
-  /**    Gets or sets the minimum value for the valuator.  */
+    /**    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;}
+    /**    Gets the maximum value for the valuator.  */
+    double maximum() const {return max;}
+    /**    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
diff --git a/FL/Fl_Value_Input.H b/FL/Fl_Value_Input.H
index e3c476597..0ede3cf39 100644
--- a/FL/Fl_Value_Input.H
+++ b/FL/Fl_Value_Input.H
@@ -31,6 +31,33 @@
 #include "Fl_Valuator.H"
 #include "Fl_Input.H"
 
+/**
+  The Fl_Value_Input widget displays a numeric value.
+  The user can click in the text field and edit it - there is in
+  fact a hidden Fl_Input widget with
+  type(FL_FLOAT_INPUT) or type(FL_INT_INPUT) in
+  there - and when they hit return or tab the value updates to
+  what they typed and the callback is done.
+  
+  <P>If step() is non-zero and integral, then the range of numbers
+  is limited to integers instead of floating point numbers. As
+  well as displaying the value as an integer, typed input is also
+  limited to integer values, even if the hidden Fl_Input widget
+  is of type(FL_FLOAT_INPUT).</P>
+  
+  <P>If step() is non-zero, the user can also drag the
+  mouse across the object and thus slide the value. The left
+  button moves one step() per pixel, the middle by 10
+  * step(), and the right button by 100 * step(). It
+  is therefore impossible to select text by dragging across it,
+  although clicking can still move the insertion cursor.</P>
+  
+  <P>If step() is non-zero and integral, then the range
+  of numbers are limited to integers instead of floating point
+  values.
+  
+  <P ALIGN="CENTER">\image html Fl_Value_Input.gif
+*/
 class FL_EXPORT Fl_Value_Input : public Fl_Valuator {
 public:
   Fl_Input input;
@@ -44,19 +71,50 @@ public:
   void resize(int,int,int,int);
   Fl_Value_Input(int x,int y,int w,int h,const char *l=0);
 
+  /** See void Fl_Value_Input::soft(char s) */
   void soft(char s) {soft_ = s;}
+  /**
+    If &quot;soft&quot; is turned on, the user is allowed to drag
+    the value outside the range. If they drag the value to one of
+    the ends, let go, then grab again and continue to drag, they can
+    get to any value. The default is true.
+  */
   char soft() const {return soft_;}
-
+  /**
+    The first form returns the current shortcut key for the Input.
+    <P>The second form sets the shortcut key to key. 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 FL_ALT | 'a'
+    , FL_ALT | (FL_F + 10), or just 'a'.  A value
+    of 0 disables the shortcut. </P>
+    <P>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. </P>
+    <P>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 &quot;don't care&quot;
+    setting).
+  */
   int shortcut() const {return input.shortcut();}
+  /** See int Fl_Value_Input::shortcut() const */
   void shortcut(int s) {input.shortcut(s);}
 
+  /** Gets the typeface of the text in the value box.  */
   Fl_Font textfont() const {return input.textfont();}
+  /** Sets the typeface of the text in the value box.  */
   void textfont(Fl_Font s) {input.textfont(s);}
+  /** Gets the size of the text in the value box.  */
   Fl_Fontsize textsize() const {return input.textsize();}
+  /** Sets the size of the text in the value box.  */
   void textsize(Fl_Fontsize s) {input.textsize(s);}
+  /** Gets the color of the text in the value box.  */
   Fl_Color textcolor() const {return input.textcolor();}
+  /** Sets the color of the text in the value box.*/
   void textcolor(unsigned n) {input.textcolor(n);}
+  /** Gets the color of the text cursor. The text cursor is black by default. */
   Fl_Color cursor_color() const {return input.cursor_color();}
+  /** Sets the color of the text cursor. The text cursor is black by default. */
   void cursor_color(unsigned n) {input.cursor_color(n);}
 
 };
diff --git a/FL/Fl_Value_Output.H b/FL/Fl_Value_Output.H
index cc61cdd6c..b8dc1f98e 100644
--- a/FL/Fl_Value_Output.H
+++ b/FL/Fl_Value_Output.H
@@ -32,6 +32,17 @@
 #include "Fl_Valuator.H"
 #endif
 
+/**
+  The Fl_Value_Output widget displays a floating point value.
+  If step() is not zero, the user can adjust the value by
+  dragging the mouse left and right.  The left button moves one step()
+  per pixel, the middle by 10 * step(), and the right button by 
+  100 * step().
+  <P>This is much lighter-weight than 
+  Fl_Value_Input because it contains no text editing code or
+  character buffer. </P>
+  <P ALIGN=CENTER>\image html Fl_Value_Output.gif
+*/
 class FL_EXPORT Fl_Value_Output : public Fl_Valuator {
   Fl_Font textfont_;
   Fl_Fontsize textsize_;
@@ -42,14 +53,31 @@ public:
   void draw();
   Fl_Value_Output(int x,int y,int w,int h,const char *l=0);
 
+  /**
+    If &quot;soft&quot; is turned on, the user is allowed to drag the value outside
+    the range.  If they drag the value to one of the ends, let go, then
+    grab again and continue to drag, they can get to any value.  Default is
+    one.
+  */
   void soft(uchar s) {soft_ = s;}
+  /**
+    If &quot;soft&quot; is turned on, the user is allowed to drag the value outside
+    the range.  If they drag the value to one of the ends, let go, then
+    grab again and continue to drag, they can get to any value.  Default is
+    one.
+  */
   uchar soft() const {return soft_;}
 
+  /**    Gets the typeface of the text in the value box.  */
   Fl_Font textfont() const {return textfont_;}
+  /**    Sets the typeface of the text in the value box.  */
   void textfont(Fl_Font s) {textfont_ = s;}
+  /**    Gets the size of the text in the value box.  */
   Fl_Fontsize textsize() const {return textsize_;}
   void textsize(Fl_Fontsize s) {textsize_ = s;}
+  /**    Sets the color of the text in the value box.  */
   Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+  /**    Gets the color of the text in the value box.  */
   void textcolor(unsigned s) {textcolor_ = s;}
 };
 
diff --git a/FL/Fl_Value_Slider.H b/FL/Fl_Value_Slider.H
index c9ea2c9fe..8290281dd 100644
--- a/FL/Fl_Value_Slider.H
+++ b/FL/Fl_Value_Slider.H
@@ -30,6 +30,11 @@
 
 #include "Fl_Slider.H"
 
+/**
+  The Fl_Value_Slider widget is a Fl_Slider widget
+  with a box displaying the current value.
+  <P ALIGN=CENTER>\image html value_slider.gif
+*/
 class FL_EXPORT Fl_Value_Slider : public Fl_Slider {
     Fl_Font textfont_;
     Fl_Fontsize textsize_;
@@ -38,11 +43,17 @@ public:
     void draw();
     int handle(int);
     Fl_Value_Slider(int x,int y,int w,int h, const char *l = 0);
+    /**    Gets the typeface of the text in the value box.  */
     Fl_Font textfont() const {return textfont_;}
+    /**    Sets the typeface of the text in the value box.  */
     void textfont(Fl_Font s) {textfont_ = s;}
+    /**    Gets the size of the text in the value box.  */
     Fl_Fontsize textsize() const {return textsize_;}
+    /**    Sets the size of the text in the value box.  */
     void textsize(Fl_Fontsize s) {textsize_ = s;}
+    /**    Gets the color of the text in the value box.  */
     Fl_Color textcolor() const {return (Fl_Color)textcolor_;}
+    /**    Sets the color of the text in the value box.  */
     void textcolor(unsigned s) {textcolor_ = s;}
 };