added doxygen comments for undocumented features of Fl_Free

- converted some HTML tags tags to doxygen \commands



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

1 files changed, 31 insertions, 30 deletions

diff --git a/FL/Fl_Free.H b/FL/Fl_Free.H
index 313028096..6ee4192bd 100644
--- a/FL/Fl_Free.H
+++ b/FL/Fl_Free.H
@@ -35,32 +35,33 @@
 #include "Fl_Widget.H"
 #endif
 
-#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
+#define FL_NORMAL_FREE		1 /**< normal event handling */
+#define FL_SLEEPING_FREE	2 /**< deactivate event handling */
+#define FL_INPUT_FREE		3 /**< accepts FL_FOCUS events */
+#define FL_CONTINUOUS_FREE	4 /**< repeated timeout handling */
+#define FL_ALL_FREE		5 /**< FL_INPUT_FREE and FL_CONTINOUS_FREE */
 
+/** appropriate signature for handle function */
 typedef int (*FL_HANDLEPTR)(Fl_Widget *, int , float, float, char);
 
 /**
-  Emulation of the Forms "free" 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>
-  \code
-  #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
-  \endcode
-  <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.
+  Emulation of the Forms "free" 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.
+
+  There are five types of free, which determine when the handle function
+  is called:
+  
+  \li \c FL_NORMAL_FREE      normal event handling.
+  \li \c FL_SLEEPING_FREE    deactivates event handling (widget is inactive).
+  \li \c FL_INPUT_FREE       accepts FL_FOCUS events.
+  \li \c FL_CONTINUOUS_FREE  sets a timeout callback 100 times a second and
+                             provides an FL_STEP event. This has obvious
+			     detrimental effects on machine performance.
+  \li \c FL_ALL_FREE         same as FL_INPUT_FREE and FL_CONTINUOUS_FREE.
+ 
 */
 class FL_EXPORT Fl_Free : public Fl_Widget {
     FL_HANDLEPTR hfunc;
@@ -68,18 +69,18 @@ class FL_EXPORT Fl_Free : public Fl_Widget {
 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);
+    int handle(int e);
+  Fl_Free(uchar t,int X,int Y,int W,int H,const char *L,FL_HANDLEPTR hdl);
   ~Fl_Free();
 };
 
 // old event names for compatibility:
-#define FL_MOUSE		FL_DRAG
-#define FL_DRAW			100		// NOT USED
-#define FL_STEP			101
-#define FL_FREEMEM		102		// NOT USED
-#define FL_FREEZE		103		// NOT USED
-#define FL_THAW			104		// NOT USED
+#define FL_MOUSE	FL_DRAG /**< for backward compatibility */
+#define FL_DRAW		100     /**< for backward compatibility [UNUSED]*/
+#define FL_STEP		101     /**< for backward compatibility */
+#define FL_FREEMEM	102     /**< for backward compatibility [UNUSED]*/
+#define FL_FREEZE	103     /**< for backward compatibility [UNUSED]*/
+#define FL_THAW		104     /**< for backward compatibility [UNUSED]*/
 
 #endif