Doxygen Documentation WP4 Done. Has all documentation content but should be completed in increment 2. Registered for WP5.

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

8 files changed, 238 insertions, 5 deletions

diff --git a/FL/Fl_Dial.H b/FL/Fl_Dial.H
index 2449f43dd..076c833dd 100644
--- a/FL/Fl_Dial.H
+++ b/FL/Fl_Dial.H
@@ -37,6 +37,18 @@
 #define FL_LINE_DIAL	1
 #define FL_FILL_DIAL	2
 
+/**
+  The Fl_Dial widget provides a circular dial to control a
+  single floating point value.
+  <P ALIGN=CENTER>\image html dial.gif
+  Use type() to set the type of the dial to:
+  <UL>
+  <LI>FL_NORMAL_DIAL - Draws a normal dial with a knob. </LI>
+  <LI>FL_LINE_DIAL - Draws a dial with a line. </LI>
+  <LI>FL_FILL_DIAL - Draws a dial with a filled arc. </LI>
+  </UL>
+
+*/
 class FL_EXPORT Fl_Dial : public Fl_Valuator {
 
   short a1,a2;
@@ -51,11 +63,25 @@ protected:
 public:
 
   int handle(int);
+  /**
+    Creates a new Fl_Dial widget using the given position, size,
+    and label string. The default type is FL_NORMAL_DIAL.
+  */
   Fl_Dial(int x,int y,int w,int h, const char *l = 0);
+  /** 
+     Sets Or gets the angles used for the minimum and maximum values.  The default
+     values are 45 and 315 (0 degrees is straight down and the angles
+     progress clockwise).  Normally angle1 is less than angle2, but if you
+     reverse them the dial moves counter-clockwise.
+  */
   short angle1() const {return a1;}
+  /** See short angle1() const */
   void angle1(short a) {a1 = a;}
+  /** See short angle1() const */
   short angle2() const {return a2;}
+  /** See short angle1() const */
   void angle2(short a) {a2 = a;}
+  /** See short angle1() const */
   void angles(short a, short b) {a1 = a; a2 = b;}
 
 };
diff --git a/FL/Fl_File_Icon.H b/FL/Fl_File_Icon.H
index 1e2e2d60f..2f848caa5 100644
--- a/FL/Fl_File_Icon.H
+++ b/FL/Fl_File_Icon.H
@@ -46,6 +46,10 @@
 // Fl_File_Icon class...
 //
 
+/** 
+  The Fl_File_Icon class manages icon images that can be used 
+  as labels in other widgets and as icons in the FileBrowser widget.
+*/
 class FL_EXPORT Fl_File_Icon			//// Icon data
 {
   static Fl_File_Icon *first_;	// Pointer to first icon/filetype
@@ -83,27 +87,63 @@ class FL_EXPORT Fl_File_Icon			//// Icon data
   ~Fl_File_Icon();
 
   short		*add(short d);
+  /**  Adds a color value to the icon array, returning a pointer to it.*/
   short		*add_color(Fl_Color c)
 		{ short *d = add((short)COLOR); add((short)(c >> 16)); add((short)c); return (d); }
+  /**
+    Adds a vertex value to the icon array, returning a pointer to it.
+    The integer version accepts coordinates from 0 to 10000, while the
+    floating point version goes from 0.0 to 1.0. The origin (0.0) is in
+    the lower-lefthand corner of the icon.
+  */
   short		*add_vertex(int x, int y)
 		{ short *d = add((short)VERTEX); add((short)x); add((short)y); return (d); }
+  /**
+    Adds a vertex value to the icon array, returning a pointer to it.
+    The integer version accepts coordinates from 0 to 10000, while the
+    floating point version goes from 0.0 to 1.0. The origin (0.0) is in
+    the lower-lefthand corner of the icon.
+  */
   short		*add_vertex(float x, float y)
 		{ short *d = add((short)VERTEX); add((short)(x * 10000.0));
 		  add((short)(y * 10000.0)); return (d); }
+  /** Clears all icon data from the icon.*/
   void		clear() { num_data_ = 0; }
+  /** Draws the icon in the indicated area.*/
   void		draw(int x, int y, int w, int h, Fl_Color ic, int active = 1);
+  /** Set the widgets label to an icon */
   void		label(Fl_Widget *w);
+  /** The labeltype function for icons.*/
   static void	labeltype(const Fl_Label *o, int x, int y, int w, int h, Fl_Align a);
   void		load(const char *f);
   int		load_fti(const char *fti);
   int		load_image(const char *i);
+  /** Returns next file icon object. See Fl_File_Icon::first() */
   Fl_File_Icon	*next() { return (next_); }
+  /** Returns the filename matching pattern for the icon.*/
   const char	*pattern() { return (pattern_); }
+  /**  Returns the number of words of data used by the icon.*/
   int		size() { return (num_data_); }
+  /**
+    Returns the filetype associated with the icon, which can be one of the
+    following:
+  
+    <UL>
+  	<LI>Fl_File_Icon::ANY, any kind of file.
+  	<LI>Fl_File_Icon::PLAIN, plain files.
+  	<LI>Fl_File_Icon::FIFO, named pipes.
+  	<LI>Fl_File_Icon::DEVICE, character and block devices.
+  	<LI>Fl_File_Icon::LINK, symbolic links.
+  	<LI>Fl_File_Icon::DIRECTORY, directories.
+    </UL>
+  */
   int		type() { return (type_); }
+  /**  Returns the data array for the icon.*/
   short		*value() { return (data_); }
 
   static Fl_File_Icon *find(const char *filename, int filetype = ANY);
+
+  /** Returns a pointer to the first icon in the list.*/
   static Fl_File_Icon *first() { return (first_); }
   static void	load_system_icons(void);
 };
diff --git a/FL/Fl_Free.H b/FL/Fl_Free.H
index 4ac7af543..5b141cc86 100644
--- a/FL/Fl_Free.H
+++ b/FL/Fl_Free.H
@@ -40,6 +40,27 @@
 
 typedef int (*FL_HANDLEPTR)(Fl_Widget *, int , float, float, char);
 
+/**
+  Emulation of the Forms &quot;free&quot; widget.  This emulation allows the free
+  demo to run, and appears to be useful for porting programs written in
+  Forms which use the free widget or make subclasses of the Forms
+  widgets.
+  <P>There are five types of free, which determine when the handle
+  function is called: </P>
+  <UL>
+  <PRE>
+  #define FL_NORMAL_FREE		1
+  #define FL_SLEEPING_FREE	2
+  #define FL_INPUT_FREE		3
+  #define FL_CONTINUOUS_FREE	4
+  #define FL_ALL_FREE		5
+  </PRE>
+  </UL>
+  <P>An FL_INPUT_FREE accepts FL_FOCUS events.  A FL_CONTINUOUS_FREE sets
+  a timeout callback 100 times a second and provides a FL_STEP event,
+  this has obvious detrimental effects on machine performance.
+  FL_ALL_FREE does both.  FL_SLEEPING_FREE are deactivated.
+*/
 class FL_EXPORT Fl_Free : public Fl_Widget {
     FL_HANDLEPTR hfunc;
     static void step(void *);
@@ -47,8 +68,8 @@ protected:
     void draw();
 public:
     int handle(int);
-    Fl_Free(uchar t,int x,int y,int w,int h,const char *l,FL_HANDLEPTR hdl);
-    ~Fl_Free();
+  Fl_Free(uchar t,int x,int y,int w,int h,const char *l,FL_HANDLEPTR hdl);
+  ~Fl_Free();
 };
 
 // old event names for compatability:
diff --git a/FL/Fl_Group.H b/FL/Fl_Group.H
index 8e8626dce..8356d7a8e 100644
--- a/FL/Fl_Group.H
+++ b/FL/Fl_Group.H
@@ -167,8 +167,28 @@ public:
 
 // dummy class used to end child groups in constructors for complex
 // subclasses of Fl_Group:
+/**
+  This is a dummy class that allows you to end a Fl_Group in a constructor list of a
+  class:
+  <UL>
+  <PRE>class MyClass {
+   Fl_Group group;
+   Fl_Button button_in_group;
+   Fl_End end;
+   Fl_Button button_outside_group;
+   MyClass();
+  };
+  MyClass::MyClass() :
+   group(10,10,100,100),
+   button_in_group(20,20,60,30),
+   end(),
+   button_outside_group(10,120,60,30)
+  {}</PRE>
+  </UL>
+*/
 class FL_EXPORT Fl_End {
 public:
+  /** All it does is calling Fl_Group::current()->end() */
   Fl_End() {Fl_Group::current()->end();}
 };
 
diff --git a/FL/Fl_Pack.H b/FL/Fl_Pack.H
index ea59f7bf9..1e6e3007d 100644
--- a/FL/Fl_Pack.H
+++ b/FL/Fl_Pack.H
@@ -30,6 +30,22 @@
 
 #include <FL/Fl_Group.H>
 
+/**
+  This widget was designed to add the functionality of compressing and
+  aligning widgets.
+  <P>If type() is Fl_Pack::HORIZONTAL all the children are
+  resized to the height of the Fl_Pack, and are moved next to
+  each other horizontally. If type() is not Fl_Pack::HORIZONTAL
+  then the children are resized to the width and are stacked below each
+  other.  Then the Fl_Pack resizes itself to surround the child
+  widgets.
+  <P>This widget is needed for the Fl_Tabs.
+  In addition you may want to put the Fl_Pack inside an 
+  Fl_Scroll.
+
+  <P>The resizable for Fl_Pack is set to NULL by default.</p>
+  <P>See also: Fl_Group::resizable()
+*/
 class FL_EXPORT Fl_Pack : public Fl_Group {
   int spacing_;
 public:
@@ -39,8 +55,17 @@ public:
   };
   void draw();
   Fl_Pack(int x,int y,int w ,int h,const char *l = 0);
+  /**
+    Gets the number of extra pixels of blank space that are added
+    between the children.
+  */
   int spacing() const {return spacing_;}
+  /**
+    Sets the number of extra pixels of blank space that are added
+    between the children.
+  */
   void spacing(int i) {spacing_ = i;}
+  /** Same as Fl_Group::type() */
   uchar horizontal() const {return type();}
 };
 
diff --git a/FL/Fl_Positioner.H b/FL/Fl_Positioner.H
index 9573381a6..12ebbf2fa 100644
--- a/FL/Fl_Positioner.H
+++ b/FL/Fl_Positioner.H
@@ -32,6 +32,13 @@
 #include "Fl_Widget.H"
 #endif
 
+/**
+  This class is provided for Forms compatibility.  It provides 2D input.
+  It would be useful if this could be put atop another widget so that the
+  crosshairs are on top, but this is not implemented.  The color of the
+  crosshairs is selection_color().
+  <P ALIGN=CENTER>\image html  src=
+*/
 class FL_EXPORT Fl_Positioner : public Fl_Widget {
 
   double xmin, ymin;
@@ -49,25 +56,40 @@ protected:
 public:
 
   int handle(int);
+  /**
+    Creates a new Fl_Positioner widget using the given position,
+    size, and label string. The default boxtype is FL_NO_BOX.
+  */
   Fl_Positioner(int x,int y,int w,int h, const char *l=0);
+  /** Gets the X axis coordinate.*/
   double xvalue() const {return xvalue_;}
+  /** Gets the Y axis coordinate.*/
   double yvalue() const {return yvalue_;}
   int xvalue(double);
   int yvalue(double);
   int value(double,double);
   void xbounds(double, double);
+  /** Gets the X axis minimum */
   double xminimum() const {return xmin;}
+  /** Same as xbounds(a, xmaximum()) */
   void xminimum(double a) {xbounds(a,xmax);}
+  /** Gets the X axis maximum */
   double xmaximum() const {return xmax;}
+  /** Same as xbounds(xminimum(), a) */
   void xmaximum(double a) {xbounds(xmin,a);}
   void ybounds(double, double);
+  /** Gets the Y axis minimum */
   double yminimum() const {return ymin;}
-  void yminimum(double a) {ybounds(a,ymax);}
+  /** Same as ybounds(a, ymaximum()) */
+  void yminimum(double a) {ybounds(a, ymax);}
+  /** Gets the Y axis maximum */
   double ymaximum() const {return ymax;}
-  void ymaximum(double a) {ybounds(ymin,a);}
+  /** Same as ybounds(ymininimum(), a) */
+  void ymaximum(double a) {ybounds(ymin, a);}
+  /** Sets the stepping value for the X axis.*/
   void xstep(double a) {xstep_ = a;}
+  /** Sets the stepping value for the Y axis.*/
   void ystep(double a) {ystep_ = a;}
-
 };
 
 #endif
diff --git a/FL/Fl_Tabs.H b/FL/Fl_Tabs.H
index 3f88c2a63..3548dfef4 100644
--- a/FL/Fl_Tabs.H
+++ b/FL/Fl_Tabs.H
@@ -30,6 +30,32 @@
 
 #include "Fl_Group.H"
 
+/**
+  The Fl_Tabs widget is the &quot;file card tabs&quot;
+  interface that allows you to put lots and lots of buttons and
+  switches in a panel, as popularized by many toolkits.
+  
+  <P ALIGN=CENTER>\image html  src=</P>
+  
+  <P>Clicking the tab makes a child visible() by calling
+  show() on it, and all other children are made invisible
+  by calling hide() on them. Usually the children are Fl_Group widgets
+  containing several widgets themselves.
+  
+  <P>Each child makes a card, and it's label() is printed
+  on the card tab, including the label font and style.  The
+  selection color of that child is used to color the tab, while
+  the color of the child determines the background color of the
+  pane.
+  
+  <P>The size of the tabs is controlled by the bounding box of the
+  children (there should be some space between the children and
+  the edge of the Fl_Tabs), and the tabs may be placed
+  &quot;inverted&quot; on the bottom, this is determined by which
+  gap is larger. It is easiest to lay this out in fluid, using the
+  fluid browser to select each child group and resize them until
+  the tabs look the way you want them to.
+*/
 class FL_EXPORT Fl_Tabs : public Fl_Group {
   Fl_Widget *value_;
   Fl_Widget *push_;
diff --git a/FL/Fl_Tile.H b/FL/Fl_Tile.H
index e07399705..9a8bbc813 100644
--- a/FL/Fl_Tile.H
+++ b/FL/Fl_Tile.H
@@ -30,9 +30,62 @@
 
 #include "Fl_Group.H"
 
+/**
+  The Fl_Tile class lets you resize the children by dragging
+  the border between them:
+  
+  <P ALIGN=CENTER>\image html Fl_Tile.gif </P>
+  
+  <P>For the tiling to work correctly, the children of an 
+  Fl_Tile must cover the entire area of the widget, but not
+  overlap. This means that all children must touch each 
+  other at their edges, and no gaps can't be left inside the 
+  Fl_Tile.
+  
+  <P>Fl_Tile does not normailly draw any graphics of its own.
+  The &quot;borders&quot; which can be seen in the snapshot above
+  are actually part of the children. Their boxtypes have been set
+  to FL_DOWN_BOX creating the impression of 
+  &quot;ridges&quot; where the boxes touch. What you see are 
+  actually two adjacent FL_DOWN_BOX's drawn next to each 
+  other. All neighboring widgets share the same edge - the widget's 
+  thick borders make it appear as though the widgets aren't actually
+  touching, but they are. If the edges of adjacent widgets do not
+  touch, then it will be impossible to drag the corresponding
+  edges.</P>
+  
+  <P>Fl_Tile allows objects to be resized to zero dimensions.
+  To prevent this you can use the resizable() to limit where
+  corners can be dragged to.</P>
+  
+  <P>Even though objects can be resized to zero sizes, they must
+  initially have non-zero sizes so the Fl_Tile can figure out
+  their layout. If desired, call position() after creating the
+  children but before displaying the window to set the borders where you
+  want.
+
+  <P>Note on resizable(Fl_Widget &w) :
+  The &quot;resizable&quot; child widget (which should be invisible) limits where the
+  border can be dragged to.  If you don't set it, it will be possible to
+  drag the borders right to the edge, and thus resize objects on the edge
+  to zero width or height.  The resizable() widget is not
+  resized by dragging any borders. See also void Fl_Group::resizable(Fl_Widget &w)
+
+*/
 class FL_EXPORT Fl_Tile : public Fl_Group {
 public:
   int handle(int);
+  /**
+    Creates a new Fl_Tile widget using the given position, size,
+    and label string. The default boxtype is FL_NO_BOX.
+    
+    <P>The destructor <I>also deletes all the children</I>. This allows a
+    whole tree to be deleted at once, without having to keep a pointer to
+    all the children in the user code. A kludge has been done so the 
+    Fl_Tile and all of it's children can be automatic (local)
+    variables, but you must declare the Fl_Tile <I>first</I>, so
+    that it is destroyed last.
+  */
   Fl_Tile(int X,int Y,int W,int H,const char*l=0) : Fl_Group(X,Y,W,H,l) {}
   void resize(int, int, int, int);
   void position(int, int, int, int);