Doxygen Documentation WP6 Done, Also completed the documentation of Help_View, Help_Dialog and cleaned up Preferences from ugly stars in comments and also removed redundant get/set text from methods doc. In this increment, we don't bother with the old dox format (comments in header). We have better things to do with our time (like about 40 mores files to doxyfy :-).

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

FL/Fl_Help_View.H

@@ -90,10 +90,11 @@ struct Fl_Help_Target
   int		y;		// Y offset of target
 };
 
-//
-// Fl_Help_View class...
-//
-
+/**
+  The Fl_Help_View widget displays HTML text. Most HTML 2.0
+  elements are supported, as well as a primitive implementation of tables.
+  GIF, JPEG, and PNG images are displayed inline.
+*/
 class FL_EXPORT Fl_Help_View : public Fl_Group	//// Help viewer widget
 {
   enum { RIGHT = -1, CENTER, LEFT };	// Alignments
@@ -187,29 +188,64 @@ public:
 
   Fl_Help_View(int xx, int yy, int ww, int hh, const char *l = 0);
   ~Fl_Help_View();
+  /**    This method returns the current directory for the text in the buffer.  */
   const char	*directory() const { if (directory_[0]) return (directory_);
   					else return ((const char *)0); }
+  /**    This method returns the current filename for the text in the buffer.  */
   const char	*filename() const { if (filename_[0]) return (filename_);
   					else return ((const char *)0); }
   int		find(const char *s, int p = 0);
+  /**
+    This method assigns a callback function to use when a link is
+    followed or a file is loaded (via
+    Fl_Help_View::load()) that requires a different
+    file or path. The callback function receives a pointer to the
+    Fl_Help_View widget and the URI or full pathname
+    for the file in question. It must return a pathname that can be
+    opened as a local file or NULL:</P>
+    
+    <UL><PRE>
+    const char *fn(Fl_Widget *w, const char *uri);
+    </PRE></UL>
+    
+    <P>The link function can be used to retrieve remote or virtual
+    documents, returning a temporary file that contains the actual
+    data. If the link function returns NULL, the value of
+    the Fl_Help_View widget will remain unchanged.</P>
+    
+    <P>If the link callback cannot handle the URI scheme, it should
+    return the uri value unchanged or set the value() of the widget
+    before returning NULL.
+  */
   void		link(Fl_Help_Func *fn) { link_ = fn; }
   int		load(const char *f);
   void		resize(int,int,int,int);
+  /** Gets the size of the Help view */
   int		size() const { return (size_); }
   void		size(int W, int H) { Fl_Widget::size(W, H); }
+  /** Sets the default text color. */
   void		textcolor(Fl_Color c) { if (textcolor_ == defcolor_) textcolor_ = c; defcolor_ = c; }
+  /** Returns    the current default text color. */
   Fl_Color	textcolor() const { return (defcolor_); }
+  /** Sets the default text font. */
   void		textfont(Fl_Font f) { textfont_ = f; format(); }
+  /** Returns the current default text font. */
   Fl_Font       textfont() const { return (textfont_); }
+  /** Sets the default text size. */
   void		textsize(Fl_Fontsize s) { textsize_ = s; format(); }
+  /** Gets the default text size. */
   Fl_Fontsize  textsize() const { return (textsize_); }
+  /** Returns the current document title, or NULL if there is no title. */
   const char	*title() { return (title_); }
   void		topline(const char *n);
   void		topline(int);
+  /** Returns the current top line in pixels.  */
   int		topline() const { return (topline_); }
   void		leftline(int);
+  /** Gets the left position. */
   int		leftline() const { return (leftline_); }
   void		value(const char *v);
+  /** Returns the current buffer contents. */
   const char	*value() const { return (value_); }
   void          clear_selection();
   void          select_all();

FL/Fl_Light_Button.H

@@ -30,6 +30,16 @@
 
 #include "Fl_Button.H"
 
+/**
+  <P>This subclass displays 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_DOWN_BOX.  The color of the light when
+  on is controlled with selection_color(), which defaults to FL_YELLOW.
+
+  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_Light_Button.gif</P>
+*/
 class FL_EXPORT Fl_Light_Button : public Fl_Button {
 protected:
     virtual void draw();

documentation/todo_filelist_doc.txt

@@ -14,7 +14,7 @@ In Progress Work List (add your WP and name here):
   - WP3  (engelsman)
   - WP4  (Fabien) DONE
   - WP5  (Fabien) DONE
-  - WP6  (Fabien)
+  - WP6  (Fabien) DONE
   - WP7
   - WP8
   - WP9
@@ -156,10 +156,6 @@ widgets.html
 Enumerations.H		(Albrecht) work in progress !
 Fl_Adjuster.H
 Fl_Adjuster.cxx
-Fl_BMP_Image.H
-Fl_BMP_Image.cxx
-Fl_Bitmap.H
-Fl_Bitmap.cxx
 Fl_Box.H
 Fl_Box.cxx
 Fl_Button.H
@@ -185,31 +181,18 @@ Fl_Float_Input.H
 Fl_Font.H
 Fl_FormsBitmap.H
 Fl_FormsPixmap.H
-Fl_GIF_Image.H
-Fl_GIF_Image.cxx
 Fl_Gl_Choice.H
 Fl_Gl_Choice.cxx
-Fl_Help_Dialog.H
-Fl_Help_Dialog.cxx
-Fl_Help_View.H
-Fl_Help_View.cxx
-Fl_Hold_Browser.H
 Fl_Hor_Fill_Slider.H
 Fl_Hor_Nice_Slider.H
 Fl_Hor_Slider.H
 Fl_Hor_Value_Slider.H
-Fl_Image.H
-Fl_Image.cxx
 Fl_Input.H
 Fl_Input.cxx
 Fl_Input_.H
 Fl_Input_.cxx
 Fl_Input_Choice.H
 Fl_Int_Input.H
-Fl_JPEG_Image.H
-Fl_JPEG_Image.cxx
-Fl_Light_Button.H
-Fl_Light_Button.cxx
 Fl_Line_Dial.H
 Fl_Menu.H
 Fl_Menu.cxx
@@ -232,17 +215,8 @@ Fl_Multiline_Output.H
 Fl_Nice_Slider.H
 Fl_Object.H
 Fl_Output.H
-Fl_PNG_Image.H
-Fl_PNG_Image.cxx
-Fl_PNM_Image.H
-Fl_PNM_Image.cxx
-Fl_Pixmap.H
-Fl_Pixmap.cxx
-Fl_Preferences.H
-Fl_Preferences.cxx
 Fl_Progress.H
 Fl_Progress.cxx
-Fl_RGB_Image.H
 Fl_Radio_Button.H
 Fl_Radio_Light_Button.H
 Fl_Radio_Round_Button.H
@@ -261,8 +235,6 @@ Fl_Scrollbar.H
 Fl_Scrollbar.cxx
 Fl_Secret_Input.H
 Fl_Select_Browser.H
-Fl_Shared_Image.H
-Fl_Shared_Image.cxx
 Fl_Simple_Counter.H
 Fl_Slider.H
 Fl_Slider.cxx
@@ -298,11 +270,7 @@ Fl_Window_hotspot.cxx
 Fl_Window_iconize.cxx
 Fl_Wizard.H
 Fl_Wizard.cxx
-Fl_XBM_Image.H
-Fl_XBM_Image.cxx
 Fl_XColor.H
-Fl_XPM_Image.H
-Fl_XPM_Image.cxx
 Fl_abort.cxx
 Fl_get_key.cxx
 Fl_get_key_mac.cxx

src/Fl_Help_Dialog_Dox.cxx

@@ -0,0 +1,119 @@
+//
+// "$Id"
+//
+// Fl_Help_Dialog dialog for the Fast Light Tool Kit (FLTK).
+//
+// Copyright 1998-2005 by Bill Spitzak and others.
+//
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Library General Public
+// License as published by the Free Software Foundation; either
+// version 2 of the License, or (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Library General Public License for more details.
+//
+// You should have received a copy of the GNU Library General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
+// USA.
+//
+// Please report all bugs and problems on the following page:
+//
+//     http://www.fltk.org/str.php
+//
+
+// Fl_Help_Dialog (autogenerated class) doxygen documentation placeholder
+
+/** \class Fl_Help_Dialog
+  The Fl_Help_Dialog widget displays a standard help dialog window
+  using the Fl_Help_View widget.
+  
+  <CENTER>\image html Fl_Help_Dialog.gif</CENTER>
+*/
+
+/** \fn Fl_Help_Dialog::Fl_Help_Dialog()
+  The constructor creates the dialog pictured above.*/
+
+/** \fn Fl_Help_Dialog::~Fl_Help_Dialog()
+  The destructor destroys the widget and frees all memory that has been
+  allocated for the current file.
+*/
+
+/** \fn void Fl_Help_Dialog::hide()
+  Hides the Fl_Help_Dialog window.*/
+
+/** \fn void Fl_Help_Dialog::load(const char *f)
+  Loads the specified HTML file into the Fl_Help_View widget.
+  The filename can also contain a target name ("filename.html#target").
+*/
+
+/** \fn void Fl_Help_Dialog::position(int x, int y)
+  Set the screen position of the dialog.*/
+
+/** \fn void Fl_Help_Dialog::resize(int xx, int yy, int ww, int hh)
+  Change the position and size of the dialog.*/
+
+/** \fn void Fl_Help_Dialog::show()
+  Shows the Fl_Help_Dialog window.*/
+
+/** \fn void Fl_Help_Dialog::textsize(uchar s)
+  Sets or gets the default text size for the help view.*/
+
+/** \fn uchar Fl_Help_Dialog::textsize()
+  Sets or gets the default text size for the help view.*/
+
+/** \fn void Fl_Help_Dialog::topline(const char *n)
+  Sets the top line in the Fl_Help_View widget to the named or
+  numbered line.
+*/
+
+/** \fn void Fl_Help_Dialog::topline(int n)
+  Sets the top line in the Fl_Help_View widget to the named or
+  numbered line.
+*/
+
+/** \fn void Fl_Help_Dialog::value(const char *v)
+  The first form sets the current buffer to the string provided and
+  reformats the text. It also clears the history of the "back" and
+  "forward" buttons. The second form returns the current buffer contents.
+*/
+
+/** \fn const char *Fl_Help_Dialog::value() const
+  The first form sets the current buffer to the string provided and
+  reformats the text. It also clears the history of the "back" and
+  "forward" buttons. The second form returns the current buffer contents.
+*/
+
+/** \fn int Fl_Help_Dialog::visible()
+  Returns 1 if the Fl_Help_Dialog window is visible.*/
+
+/** \fn int Fl_Help_Dialog::x()
+  Returns the position and size of the help dialog.*/
+
+/** \fn int Fl_Help_Dialog::y()
+  Returns the position and size of the help dialog.*/
+
+/** \fn int Fl_Help_Dialog::w()
+  Returns the position and size of the help dialog.*/
+
+/** \fn int Fl_Help_Dialog::h()
+  Returns the position and size of the help dialog.*/
+
+/** \fn void Fl_Help_Dialog::show()
+  Shows the main Help Dialog Window
+  Delegates call to encapsulated window_ void Fl_Window::show() method */
+
+/** \fn void Fl_Help_Dialog::show(int argc, char **argv)
+  Shows the main Help Dialog Window
+  Delegates call to encapsulated window_ void Fl_Window::show(int argc, char **argv) instance method */
+
+/** \fn void Fl_Help_Dialog::textsize(Fl_Fontsize s)
+  Sets the internal Fl_Help_View instance text size.
+  Delegates call to encapsulated view_ void Fl_Help_View::textsize(Fl_Fontsize s) instance method */
+
+//
+// End of "$Id".
+//

src/Fl_Help_View.cxx

@@ -1002,10 +1002,8 @@ Fl_Help_View::draw()
 }
 
 
-//
-// 'Fl_Help_View::find()' - Find the specified string...
-//
 
+/** Find the specified string s at starting position p, return the matching pos or -1 if not found */
 int						// O - Matching position or -1 if not found
 Fl_Help_View::find(const char *s,		// I - String to find
                    int        p)		// I - Starting position
@@ -2729,12 +2727,13 @@ void Fl_Help_View::follow_link(Fl_Help_Link *linkp)
   leftline(0);
 }
 
+/** Removes the current text selection. */
 void Fl_Help_View::clear_selection()
 {
   if (current_view==this)
     clear_global_selection();
 }
-
+/** Selects All the text in the view. */
 void Fl_Help_View::select_all()
 {
   clear_global_selection();
@@ -3007,10 +3006,10 @@ Fl_Help_View::handle(int event)	// I - Event to handle
   return (Fl_Group::handle(event));
 }
 
-//
-// 'Fl_Help_View::Fl_Help_View()' - Build a Fl_Help_View widget.
-//
-
+/** 
+  The constructor creates the Fl_Help_View widget at the specified
+  position and size.
+*/
 Fl_Help_View::Fl_Help_View(int        xx,	// I - Left position
                 	   int        yy,	// I - Top position
 			   int        ww,	// I - Width in pixels
@@ -3078,6 +3077,10 @@ Fl_Help_View::Fl_Help_View(int        xx,	// I - Left position
 //
 
 Fl_Help_View::~Fl_Help_View()
+/**
+  The destructor destroys the widget and frees all memory that has been
+  allocated for the current file.
+*/
 {
   clear_selection();
   free_data();
@@ -3090,6 +3093,7 @@ Fl_Help_View::~Fl_Help_View()
 
 int				// O - 0 on success, -1 on error
 Fl_Help_View::load(const char *f)// I - Filename to load (may also have target)
+/**  This method loads the specified file or URL.*/
 {
   FILE		*fp;		// File to read from
   long		len;		// Length of file
@@ -3211,10 +3215,7 @@ Fl_Help_View::resize(int xx,	// I - New left position
 }
 
 
-//
-// 'Fl_Help_View::topline()' - Set the top line to the named target.
-//
-
+/** Scroll the text to the indicated position,  given a named destination */
 void
 Fl_Help_View::topline(const char *n)	// I - Target name
 {
@@ -3235,10 +3236,8 @@ Fl_Help_View::topline(const char *n)	// I - Target name
 }
 
 
-//
-// 'Fl_Help_View::topline()' - Set the top line by number.
-//
 
+/** Scroll the text to the indicated position,  given a pixel line. */
 void
 Fl_Help_View::topline(int t)	// I - Top line number
 {
@@ -3260,10 +3259,9 @@ Fl_Help_View::topline(int t)	// I - Top line number
 }
 
 
-//
-// 'Fl_Help_View::leftline()' - Set the left position.
-//
 
+
+/** Sets the left position. */
 void
 Fl_Help_View::leftline(int l)	// I - Left position
 {
@@ -3283,10 +3281,7 @@ Fl_Help_View::leftline(int l)	// I - Left position
 }
 
 
-//
-// 'Fl_Help_View::value()' - Set the help text directly.
-//
-
+/** Sets the current help text buffer to the string provided and reformats the text. */
 void
 Fl_Help_View::value(const char *v)	// I - Text to view
 {

src/Fl_Light_Button.cxx

@@ -157,6 +157,11 @@ int Fl_Light_Button::handle(int event) {
   }
 }
 
+/**
+  Creates a new Fl_Light_Button widget using the given
+  position, size, and label string.
+  <P>The destructor deletes the check button.
+*/
 Fl_Light_Button::Fl_Light_Button(int X, int Y, int W, int H, const char* l)
 : Fl_Button(X, Y, W, H, l) {
   type(FL_TOGGLE_BUTTON);

src/Fl_Preferences.cxx

@@ -212,9 +212,7 @@ char Fl_Preferences::deleteEntry( const char *key )
 }
 
 
-/**
- * read an entry from the group
- */
+
 char Fl_Preferences::get( const char *key, int &value, int defaultValue )
 {
   const char *v = node->get( key );
@@ -223,9 +221,7 @@ char Fl_Preferences::get( const char *key, int &value, int defaultValue )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, int value )
 {
   sprintf( nameBuffer, "%d", value );
@@ -234,9 +230,7 @@ char Fl_Preferences::set( const char *key, int value )
 }
 
 
-/**
- * read an entry from the group
- */
+
 char Fl_Preferences::get( const char *key, float &value, float defaultValue )
 {
   const char *v = node->get( key );
@@ -245,9 +239,7 @@ char Fl_Preferences::get( const char *key, float &value, float defaultValue )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, float value )
 {
   sprintf( nameBuffer, "%g", value );
@@ -256,9 +248,7 @@ char Fl_Preferences::set( const char *key, float value )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, float value, int precision )
 {
   sprintf( nameBuffer, "%.*g", precision, value );
@@ -267,9 +257,7 @@ char Fl_Preferences::set( const char *key, float value, int precision )
 }
 
 
-/**
- * read an entry from the group
- */
+
 char Fl_Preferences::get( const char *key, double &value, double defaultValue )
 {
   const char *v = node->get( key );
@@ -278,9 +266,7 @@ char Fl_Preferences::get( const char *key, double &value, double defaultValue )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, double value )
 {
   sprintf( nameBuffer, "%g", value );
@@ -289,9 +275,7 @@ char Fl_Preferences::set( const char *key, double value )
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, double value, int precision )
 {
   sprintf( nameBuffer, "%.*g", precision, value );
@@ -373,9 +357,7 @@ char Fl_Preferences::get( const char *key, char *&text, const char *defaultValue
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, const char *text )
 {
   const char *s = text ? text : "";
@@ -474,9 +456,7 @@ char Fl_Preferences::get( const char *key, void *&data, const void *defaultValue
 }
 
 
-/**
- * set an entry (name/value pair)
- */
+
 char Fl_Preferences::set( const char *key, const void *data, int dsize )
 {
   char *buffer = (char*)malloc( dsize*2+1 ), *d = buffer;;