Doxygen documentation. Completed Fl class, added a todo related to recent Fl API to document. Matt?. More cosmetics have been done, replaced *all* <pre> </pre> tags by \code \endcode sequences.

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

8 files changed, 39 insertions, 96 deletions

diff --git a/src/Fl.cxx b/src/Fl.cxx
index 92183b54b..e403ab3af 100644
--- a/src/Fl.cxx
+++ b/src/Fl.cxx
@@ -186,57 +186,11 @@ static void elapse_timeouts() {
 // time interval:
 static double missed_timeout_by;
 
-/**
-  Add a one-shot timeout callback.  The function will be called by
-  Fl::wait() at <i>t</i> seconds after this function is called.
-  The optional void* argument is passed to the callback.
-  
-  <P>You can have multiple timeout callbacks. To remove an timeout
-  callback use Fl::remove_timeout().
-  
-  <p>If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to
-  reschedule the subsequent timeouts.</p>
-  
-  <p>The following code will print &quot;TICK&quot; each second on
-  stdout with a fair degree of accuracy:</p>
-  
-  <PRE>
-     void callback(void*) {
-       puts("TICK");
-       Fl::repeat_timeout(1.0, callback);
-     }
-  
-     int main() {
-       Fl::add_timeout(1.0, callback);
-       return Fl::run();
-     }
-  </PRE>
-*/
 void Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *argp) {
   elapse_timeouts();
   repeat_timeout(time, cb, argp);
 }
 
-/**
-  This method repeats a timeout callback from the expiration of the
-  previous timeout, allowing for more accurate timing. You may only call
-  this method inside a timeout callback.
-  
-  <p>The following code will print &quot;TICK&quot; each second on
-  stdout with a fair degree of accuracy:</p>
-  
-  <PRE>
-     void callback(void*) {
-       puts("TICK");
-       Fl::repeat_timeout(1.0, callback);
-     }
-  
-     int main() {
-       Fl::add_timeout(1.0, callback);
-       return Fl::run();
-     }
-  </PRE>
-*/
 void Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *argp) {
   time += missed_timeout_by; if (time < -.05) time = 0;
   Timeout* t = free_timeout;
@@ -316,7 +270,7 @@ static Check *first_check, *next_check, *free_check;
   
   <p>Sample code:
   
-  <UL><PRE>
+  \code
   bool state_changed; // anything that changes the display turns this on
   
   void callback(void*) {
@@ -330,7 +284,7 @@ static Check *first_check, *next_check, *free_check;
    Fl::add_check(callback);
    return Fl::run();
   }
-  </PRE></UL>
+  \endcode
 */
 void Fl::add_check(Fl_Timeout_Handler cb, void *argp) {
   Check* t = free_check;
@@ -543,13 +497,13 @@ int Fl::wait() {
   Same as Fl::wait(0).  Calling this during a big calculation
   will keep the screen up to date and the interface responsive:
   
-  <UL><PRE>
+  \code
   while (!calculation_done()) {
   calculate();
   Fl::check();
   if (user_hit_abort_button()) break;
   }
-  </PRE></UL>
+  \endcode
   
   <P>The returns non-zero if any windows are displayed, and 0 if no
   windows are displayed (this is likely to change in future versions of
@@ -567,7 +521,7 @@ int Fl::check() {
   true if Fl::check() would do anything (it will continue to
   return true until you call Fl::check() or Fl::wait()).
   
-  <UL><PRE>
+  \code
   while (!calculation_done()) {
   calculate();
   if (Fl::ready()) {
@@ -576,7 +530,7 @@ int Fl::check() {
     if (user_hit_abort_button()) break;
   }
   }
-  </PRE></UL>
+  \endcode
 */
 int Fl::ready() {
 #if ! defined( WIN32 )  &&  ! defined(__APPLE__)
@@ -1537,9 +1491,11 @@ void Fl::delete_widget(Fl_Widget *wi) {
   num_dwidgets ++;
 }
 
-
-void
-Fl::do_widget_deletion() {
+/** 
+    Deletes widgets previously scheduled for deletion.
+    See void Fl::delete_widget(Fl_Widget *wi) 
+*/
+void Fl::do_widget_deletion() {
   if (!num_dwidgets) return;
 
   for (int i = 0; i < num_dwidgets; i ++)
@@ -1551,7 +1507,9 @@ Fl::do_widget_deletion() {
 static Fl_Widget ***widget_watch = 0;
 static int num_widget_watch = 0;
 static int max_widget_watch = 0;
-
+/** Adds a widget pointer to the watch list. 
+   \todo explain the role of the watch list, 
+   it may be related to invalid widget deletion crash fixes... */
 void Fl::watch_widget_pointer(Fl_Widget *&w) 
 {
   Fl_Widget **wp = &w;
@@ -1572,6 +1530,7 @@ void Fl::watch_widget_pointer(Fl_Widget *&w)
   widget_watch[num_widget_watch++] = wp;
 }
 
+/** Releases a widget pointer to the watch list */
 void Fl::release_widget_pointer(Fl_Widget *&w)
 {
   Fl_Widget **wp = &w;
@@ -1583,7 +1542,7 @@ void Fl::release_widget_pointer(Fl_Widget *&w)
     }
   }
 }
-
+/** Clears a widget pointer in the watch list */
 void Fl::clear_widget_pointer(Fl_Widget const *w) 
 {
   if (w==0L) return;
diff --git a/src/Fl_File_Chooser2.cxx b/src/Fl_File_Chooser2.cxx
index 8447ab080..be0c8ebd4 100644
--- a/src/Fl_File_Chooser2.cxx
+++ b/src/Fl_File_Chooser2.cxx
@@ -118,9 +118,9 @@
   "Description text (patterns)" or just "patterns". A file chooser
   that provides filters for HTML and image files might look like:
   
-  <UL><PRE>
+  \code
   "HTML Files (*.html)\tImage Files (*.{bmp,gif,jpg,png})"
-  </PRE></UL>
+  \endcode
   
   <P>The file chooser will automatically add the "All Files (*)"
   pattern to the end of the string you pass if you do not provide
@@ -253,13 +253,13 @@
   Fl_File_Chooser::count().
   
   <P>This sample code loops through all selected files:
-  <PRE>
+  \code
   // Get list of filenames user selected from a MULTI chooser
   for ( int t=1; t&lt;=chooser-&gt;count(); t++ ) {
      const char *filename = chooser-&gt;value(t);
      ..
   }
-  </PRE>
+  \endcode
 */
 
 /** \fn const char *Fl_File_Chooser::value(int file)
diff --git a/src/Fl_File_Icon2.cxx b/src/Fl_File_Icon2.cxx
index 303c0e1f5..119954949 100644
--- a/src/Fl_File_Icon2.cxx
+++ b/src/Fl_File_Icon2.cxx
@@ -581,9 +581,9 @@ int Fl_File_Icon::load_image(const char *ifile)	// I - File to read from
   FileChooser widget and should be used when the application
   starts:
   
-  <UL><PRE>
+  \code
   Fl_File_Icon::load_system_icons();
-  </PRE></UL>
+  \endcode
 */
 void
 Fl_File_Icon::load_system_icons(void) {
diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx
index 1edb61394..9265fe7b5 100644
--- a/src/Fl_Menu_add.cxx
+++ b/src/Fl_Menu_add.cxx
@@ -207,19 +207,19 @@ int Fl_Menu_Item::add(
   <P>Shortcut can be 0L, or either a modifier/key combination (for example
   FL_CTRL+'A') or a string describing the shortcut in one of two ways:</p>
   
-  <pre>
+  \code
    [#+^]&lt;ascii_value&gt;    eg. "97", "^97", "+97", "#97"
    [#+^]&lt;ascii_char&gt;     eg. "a", "^a", "+a", "#a"
-  </pre>
+  \endcode
   ..where &lt;ascii_value&gt; is a decimal value representing an
   ascii character (eg. 97 is the ascii for 'a'), and the optional
   prefixes enhance the value  that follows. Multiple prefixes must
   appear in the above order.
-  <pre>
+  \code
    # - Alt
    + - Shift
    ^ - Control
-  </pre>
+  \endcode
   Text shortcuts are converted to integer shortcut by calling 
   int fl_old_shortcut(const char*).
   
diff --git a/src/fl_boxtype.cxx b/src/fl_boxtype.cxx
index ec7490e30..e98a203ec 100644
--- a/src/fl_boxtype.cxx
+++ b/src/fl_boxtype.cxx
@@ -51,7 +51,8 @@ static uchar inactive_ramp[24] = {
   49, 49, 50, 50,
   51, 51, 52, 52};
 static int draw_it_active = 1;
-
+/** Determines if the current draw box is active or inactive. 
+    If inactive, the box color is changed by the inactive color. */
 int Fl::draw_box_active() { return draw_it_active; }
 
 uchar *fl_gray_ramp() {return (draw_it_active?active_ramp:inactive_ramp)-'A';}
@@ -275,12 +276,12 @@ int Fl::box_dx(Fl_Boxtype t) {return fl_box_table[t].dx;}
     respectively.
     
     <P>An example to compute the area inside a widget's box():
-    <pre>
+    \code
          int X = yourwidget-&gt;x() + Fl::box_dx(yourwidget-&gt;box());
          int Y = yourwidget-&gt;y() + Fl::box_dy(yourwidget-&gt;box());
          int W = yourwidget-&gt;w() - Fl::box_dw(yourwidget-&gt;box());
          int H = yourwidget-&gt;h() - Fl::box_dh(yourwidget-&gt;box());
-    </pre>
+    \endcode
     <P>These functions are mainly useful in the draw() code 
     for deriving custom widgets, where one wants to avoid drawing 
     over the widget's own border box().
diff --git a/src/fl_utf.c b/src/fl_utf.c
index c3e80f7f2..95b4e37c6 100644
--- a/src/fl_utf.c
+++ b/src/fl_utf.c
@@ -81,7 +81,7 @@ static unsigned short cp1252[32] = {
     standards recommend), adding a test to see if the length is
     unexpectedly 1 will work:
 
-\code
+    \code
     if (*p & 0x80) { // what should be a multibyte encoding
       code = fl_utf8decode(p,end,&len);
       if (len<2) code = 0xFFFD; // Turn errors into REPLACEMENT CHARACTER
@@ -89,7 +89,7 @@ static unsigned short cp1252[32] = {
       code = *p;
       len = 1;
     }
-\endcode
+    \endcode
 
     Direct testing for the 1-byte case (as shown above) will also
     speed up the scanning of strings where the majority of characters
diff --git a/src/forms_free.cxx b/src/forms_free.cxx
index ec5346299..950fe4730 100644
--- a/src/forms_free.cxx
+++ b/src/forms_free.cxx
@@ -44,30 +44,26 @@ void Fl_Free::step(void *v) {
 /**
     The constructor takes both the type and the handle
     function. The handle function should be declared as follows:
-    <UL>
-    <PRE>
+    \code
     int
     handle_function(Fl_Widget *w,
                    int       event,
     	        float     event_x,
     		float     event_y,
     		char      key)
-    </PRE>
-    </UL>
+    \endcode
     This function is called from the the handle() method in
     response to most events, and is called by the draw() method.
     The event argument contains the event type:
-    <UL>
-    <PRE>
+    \code
     // old event names for compatibility:
     #define FL_MOUSE		FL_DRAG
-    #define FL_DRAW			0
-    #define FL_STEP			9
+    #define FL_DRAW		0
+    #define FL_STEP		9
     #define FL_FREEMEM		12
     #define FL_FREEZE		FL_UNMAP
-    #define FL_THAW			FL_MAP
-    </PRE>
-    </UL>
+    #define FL_THAW		FL_MAP
+    \endcode
 */
 Fl_Free::Fl_Free(uchar t,int X, int Y, int W, int H,const char *l,
 		 FL_HANDLEPTR hdl) :
diff --git a/src/gl_start.cxx b/src/gl_start.cxx
index 868a0d894..8275399a1 100644
--- a/src/gl_start.cxx
+++ b/src/gl_start.cxx
@@ -109,19 +109,6 @@ void gl_finish() {
   glXWaitGL();
 #endif
 }
-/**
-    This does the same thing as
-    Fl::visual(int) but also
-    requires OpenGL drawing to work.  This <I>must</I> be done if
-    you want to draw in normal windows with OpenGL with  gl_start() and
-    gl_end().  It may be useful to call this so your X
-    windows use the same visual as an
-    Fl_Gl_Window, which on
-    some servers will reduce colormap flashing.
-    
-    <P>See Fl_Gl_Window
-    for a list of additional values for the argument.
-*/
 int Fl::gl_visual(int mode, int *alist) {
   Fl_Gl_Choice *c = Fl_Gl_Choice::find(mode,alist);
   if (!c) return 0;