Doxygen Documentation WP5 Done, WP6 half finished so that all Fl_Image class hierarchy is up-to-date. Also completed the documentation of the useful Fl_Shared_Image.

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

11 files changed, 156 insertions, 63 deletions

diff --git a/src/Fl_BMP_Image.cxx b/src/Fl_BMP_Image.cxx
index c59504ba6..4c5e31da6 100644
--- a/src/Fl_BMP_Image.cxx
+++ b/src/Fl_BMP_Image.cxx
@@ -59,12 +59,15 @@
 static int		read_long(FILE *fp);
 static unsigned short	read_word(FILE *fp);
 static unsigned int	read_dword(FILE *fp);
+/** \fn Fl_BMP_Image::~Fl_BMP_Image()
+*/
 
 
-//
-// 'Fl_BMP_Image::Fl_BMP_Image()' - Load a BMP image file.
-//
-
+/** 
+  The constructor loads the named BMP image from the given bmp filename.  
+  <P>The inherited destructor free all memory and server resources that are used by
+  the image.
+*/
 Fl_BMP_Image::Fl_BMP_Image(const char *bmp) // I - File to read
   : Fl_RGB_Image(0,0,0) {
   FILE		*fp;		// File pointer
diff --git a/src/Fl_Bitmap.cxx b/src/Fl_Bitmap.cxx
index ae49d934e..c4b32cd0a 100644
--- a/src/Fl_Bitmap.cxx
+++ b/src/Fl_Bitmap.cxx
@@ -25,6 +25,12 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \fn Fl_Bitmap::Fl_Bitmap(const char *array, int W, int H)
+  The constructors create a new bitmap from the specified bitmap data.*/
+
+/** \fn Fl_Bitmap::Fl_Bitmap(const unsigned char *array, int W, int H)
+  The constructors create a new bitmap from the specified bitmap data.*/
+
 #include <FL/Fl.H>
 #include <FL/x.H>
 #include <FL/fl_draw.H>
@@ -414,6 +420,10 @@ void Fl_Bitmap::draw(int XP, int YP, int WP, int HP, int cx, int cy) {
 #endif
 }
 
+/**
+  The destructor free all memory and server resources that are used by
+  the bitmap.
+*/
 Fl_Bitmap::~Fl_Bitmap() {
   uncache();
   if (alloc_array) delete[] (uchar *)array;
diff --git a/src/Fl_GIF_Image.cxx b/src/Fl_GIF_Image.cxx
index 395ace3cb..ee5e726da 100644
--- a/src/Fl_GIF_Image.cxx
+++ b/src/Fl_GIF_Image.cxx
@@ -79,6 +79,11 @@ typedef unsigned char uchar;
 #define NEXTBYTE (uchar)getc(GifFile)
 #define GETSHORT(var) var = NEXTBYTE; var += NEXTBYTE << 8
 
+/**  
+  The constructor loads the named GIF image.
+  <P>The inherited destructor free all memory and server resources that are used by
+  the image.
+*/
 Fl_GIF_Image::Fl_GIF_Image(const char *infname) : Fl_Pixmap((char *const*)0) {
   FILE *GifFile;	// File to read
   char **new_data;	// Data array
diff --git a/src/Fl_Image.cxx b/src/Fl_Image.cxx
index 553000fa8..6cd9514bd 100644
--- a/src/Fl_Image.cxx
+++ b/src/Fl_Image.cxx
@@ -43,9 +43,18 @@ void fl_restore_clip(); // from fl_rect.cxx
 // Base image class...
 //
 
+/**
+  The destructor is a virtual method that frees all memory used
+  by the image.
+*/
 Fl_Image::~Fl_Image() {
 }
 
+/**
+  If the image has been cached for display, delete the cache
+  data. This allows you to change the data used for the image and
+  then redraw it without recreating an image object.
+*/
 void Fl_Image::uncache() {
 }
 
@@ -53,6 +62,11 @@ void Fl_Image::draw(int XP, int YP, int, int, int, int) {
   draw_empty(XP, YP);
 }
 
+/**
+  The protected method draw_empty() draws a box with
+  an X in it. It can be used to draw any image that lacks image
+  data.
+*/
 void Fl_Image::draw_empty(int X, int Y) {
   if (w() > 0 && h() > 0) {
     fl_color(FL_FOREGROUND_COLOR);
@@ -62,20 +76,56 @@ void Fl_Image::draw_empty(int X, int Y) {
   }
 }
 
+/**
+  The copy() method creates a copy of the specified
+  image. If the width and height are provided, the image is
+  resized to the specified size. The image should be deleted (or in
+  the case of Fl_Shared_Image, released) when you are done
+  with it.
+*/
 Fl_Image *Fl_Image::copy(int W, int H) {
   return new Fl_Image(W, H, d());
 }
 
+/**
+  The color_average() method averages the colors in
+  the image with the FLTK color value c. The i
+  argument specifies the amount of the original image to combine
+  with the color, so a value of 1.0 results in no color blend, and
+  a value of 0.0 results in a constant image of the specified
+  color. <I>The original image data is not altered by this
+  method.</I>
+*/
 void Fl_Image::color_average(Fl_Color, float) {
 }
 
+/**
+  The desaturate() method converts an image to
+  grayscale. If the image contains an alpha channel (depth = 4),
+  the alpha channel is preserved. <I>This method does not alter
+  the original image data.</I>
+*/
 void Fl_Image::desaturate() {
 }
 
+/**
+  The label() methods are an obsolete way to set the
+  image attribute of a widget or menu item. Use the
+  image() or deimage() methods of the
+  Fl_Widget and Fl_Menu_Item classes
+  instead.
+*/
 void Fl_Image::label(Fl_Widget* widget) {
   widget->image(this);
 }
 
+/**
+  The label() methods are an obsolete way to set the
+  image attribute of a widget or menu item. Use the
+  image() or deimage() methods of the
+  Fl_Widget and Fl_Menu_Item classes
+  instead.
+*/
 void Fl_Image::label(Fl_Menu_Item* m) {
   Fl::set_labeltype(_FL_IMAGE_LABEL, labeltype, measure);
   m->label(_FL_IMAGE_LABEL, (const char*)this);
@@ -122,7 +172,7 @@ Fl_Image::measure(const Fl_Label *lo,		// I - Label
 //
 // RGB image class...
 //
-
+/**  The destructor free all memory and server resources that are used by  the image. */
 Fl_RGB_Image::~Fl_RGB_Image() {
   uncache();
   if (alloc_array) delete[] (uchar *)array;
diff --git a/src/Fl_JPEG_Image.cxx b/src/Fl_JPEG_Image.cxx
index 13889000a..63c09261e 100644
--- a/src/Fl_JPEG_Image.cxx
+++ b/src/Fl_JPEG_Image.cxx
@@ -88,10 +88,10 @@ extern "C" {
 #endif // HAVE_LIBJPEG
 
 
-//
-// 'Fl_JPEG_Image::Fl_JPEG_Image()' - Load a JPEG image file.
-//
-
+/**
+  The constructor loads the JPEG image from the given jpeg filename.
+  <P>The inherited destructor free all memory and server resources that are used by  the image.
+*/
 Fl_JPEG_Image::Fl_JPEG_Image(const char *jpeg)	// I - File to load
   : Fl_RGB_Image(0,0,0) {
 #ifdef HAVE_LIBJPEG
diff --git a/src/Fl_PNG_Image.cxx b/src/Fl_PNG_Image.cxx
index 99011d088..547601c7b 100644
--- a/src/Fl_PNG_Image.cxx
+++ b/src/Fl_PNG_Image.cxx
@@ -26,6 +26,7 @@
 //     http://www.fltk.org/str.php
 //
 // Contents:
+
 //
 //   Fl_PNG_Image::Fl_PNG_Image() - Load a PNG image file.
 //
@@ -54,10 +55,11 @@ extern "C"
 }
 
 
-//
-// 'Fl_PNG_Image::Fl_PNG_Image()' - Load a PNG image file.
-//
-
+/**
+  The constructor loads the named PNG image from the given png filename.
+  <P>The destructor free all memory and server resources that are used by
+  the image.
+*/
 Fl_PNG_Image::Fl_PNG_Image(const char *png) // I - File to read
   : Fl_RGB_Image(0,0,0) {
 #if defined(HAVE_LIBPNG) && defined(HAVE_LIBZ)
diff --git a/src/Fl_PNM_Image.cxx b/src/Fl_PNM_Image.cxx
index d7468b2e1..168f570f5 100644
--- a/src/Fl_PNM_Image.cxx
+++ b/src/Fl_PNM_Image.cxx
@@ -25,6 +25,7 @@
 //     http://www.fltk.org/str.php
 //
 // Contents:
+
 //
 //   Fl_PNM_Image::Fl_PNM_Image() - Load a PNM image...
 //
@@ -45,6 +46,11 @@
 // 'Fl_PNM_Image::Fl_PNM_Image()' - Load a PNM image...
 //
 
+/** 
+  The constructor loads the named PNM image. 
+  <P>The inherited destructor free all memory and server resources that are used by the image.
+*/
+
 Fl_PNM_Image::Fl_PNM_Image(const char *name)	// I - File to read
   : Fl_RGB_Image(0,0,0) {
   FILE		*fp;		// File pointer
diff --git a/src/Fl_Pixmap.cxx b/src/Fl_Pixmap.cxx
index a3fad728a..6d24420d0 100644
--- a/src/Fl_Pixmap.cxx
+++ b/src/Fl_Pixmap.cxx
@@ -25,6 +25,15 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \fn Fl_Pixmap::Fl_Pixmap(const char **data)
+  The constructors create a new pixmap from the specified XPM data.*/
+
+/** \fn Fl_Pixmap::Fl_Pixmap(const unsigned char * const *data)
+  The constructors create a new pixmap from the specified XPM data.*/
+
+/** \fn Fl_Pixmap::Fl_Pixmap(const unsigned char **data)
+  The constructors create a new pixmap from the specified XPM data.*/
+
 // Draws X pixmap data, keeping it stashed in a server pixmap so it
 // redraws fast.
 
@@ -169,6 +178,10 @@ void Fl_Pixmap::draw(int XP, int YP, int WP, int HP, int cx, int cy) {
 #endif
 }
 
+/**
+  The destructor free all memory and server resources that are used by
+  the pixmap.
+*/
 Fl_Pixmap::~Fl_Pixmap() {
   uncache();
   delete_data();
diff --git a/src/Fl_Shared_Image.cxx b/src/Fl_Shared_Image.cxx
index 2ed07eb00..083e12715 100644
--- a/src/Fl_Shared_Image.cxx
+++ b/src/Fl_Shared_Image.cxx
@@ -58,12 +58,11 @@ extern "C" {
 }
 
 
-// Static methods that really should be inline, but some WIN32 compilers
-// can't handle it...
+/** Returns the Fl_Shared_Image* array */
 Fl_Shared_Image **Fl_Shared_Image::images() {
   return images_;
 }
-
+/** Returns the total number of shared images in the array. */
 int Fl_Shared_Image::num_images() {
   return num_images_;
 }
@@ -86,10 +85,13 @@ Fl_Shared_Image::compare(Fl_Shared_Image **i0,		// I - First image
 }
 
 
-//
-// 'Fl_Shared_Image::Fl_Shared_Image()' - Basic constructor.
-//
-
+/** 
+  Creates an empty shared image.
+  The constructors create a new shared image record in the image cache.
+  
+  <P>The constructors are protected and cannot be used directly
+  from a program. Use the get() method instead.
+*/
 Fl_Shared_Image::Fl_Shared_Image() : Fl_Image(0,0,0) {
   name_        = 0;
   refcount_    = 1;
@@ -99,10 +101,13 @@ Fl_Shared_Image::Fl_Shared_Image() : Fl_Image(0,0,0) {
 }
 
 
-//
-// 'Fl_Shared_Image::Fl_Shared_Image()' - Add an image to the image cache.
-//
-
+/** 
+  Creates a shared image from its filename and its corresponding Fl_Image* img.
+  The constructors create a new shared image record in the image cache.
+  
+  <P>The constructors are protected and cannot be used directly
+  from a program. Use the get() method instead.
+*/
 Fl_Shared_Image::Fl_Shared_Image(const char *n,		// I - Filename
                                  Fl_Image   *img)	// I - Image
   : Fl_Image(0,0,0) {
@@ -165,11 +170,12 @@ Fl_Shared_Image::update() {
   }
 }
 
-
-//
-// 'Fl_Shared_Image::~Fl_Shared_Image()' - Destroy a shared image...
-//
-
+/**
+  The destructor free all memory and server resources that are
+  used by the image. The destructor is protected and cannot be
+  used directly from a program. Use the Fl_Shared_Image::release() method
+  instead.
+*/
 Fl_Shared_Image::~Fl_Shared_Image() {
   if (name_) delete[] (char *)name_;
   if (alloc_image_) delete image_;
@@ -177,11 +183,11 @@ Fl_Shared_Image::~Fl_Shared_Image() {
 
 
 //
-// 'Fl_Shared_Image::release()' - Release and possibly destroy a shared image.
-//
-
-void
-Fl_Shared_Image::release() {
+/** 
+  Releases and possibly destroys (if refcount <=0) a shared image. 
+  In the latter case, it will reorganize the shared image array so that no hole will occur.
+*/
+void Fl_Shared_Image::release() {
   int	i;	// Looping var...
 
   refcount_ --;
@@ -211,11 +217,8 @@ Fl_Shared_Image::release() {
 
 
 //
-// 'Fl_Shared_Image::reload()' - Reload the shared image...
-//
-
-void
-Fl_Shared_Image::reload() {
+/** Reloads the shared image from disk */
+void Fl_Shared_Image::reload() {
   // Load image from disk...
   int		i;		// Looping var
   FILE		*fp;		// File pointer
@@ -335,19 +338,15 @@ Fl_Shared_Image::draw(int X, int Y, int W, int H, int cx, int cy) {
 // 'Fl_Shared_Image::uncache()' - Uncache the shared image...
 //
 
-void
-Fl_Shared_Image::uncache()
+void Fl_Shared_Image::uncache()
 {
   if (image_) image_->uncache();
 }
 
 
-//
-// 'Fl_Shared_Image::find()' - Find a shared image...
-//
 
-Fl_Shared_Image *
-Fl_Shared_Image::find(const char *n, int W, int H) {
+/** Finds a shared image from its named and size specifications */
+Fl_Shared_Image* Fl_Shared_Image::find(const char *n, int W, int H) {
   Fl_Shared_Image	*key,		// Image key
 			**match;	// Matching image
 
@@ -374,12 +373,14 @@ Fl_Shared_Image::find(const char *n, int W, int H) {
 }
 
 
-//
-// 'Fl_Shared_Image::get()' - Get a shared image...
-//
-
-Fl_Shared_Image *
-Fl_Shared_Image::get(const char *n, int W, int H) {
+/** 
+  Gets a shared image, if it exists already ; it will return it.
+  If it does not exist or if it exist but with other size, 
+  then the existing image is deleted and replaced
+  by a new image from the n filename of the proper dimension.
+  If n is not a valid image filename, then get() will return NULL.
+*/
+Fl_Shared_Image* Fl_Shared_Image::get(const char *n, int W, int H) {
   Fl_Shared_Image	*temp;		// Image
 
   if ((temp = find(n, W, H)) != NULL) return temp;
@@ -404,12 +405,9 @@ Fl_Shared_Image::get(const char *n, int W, int H) {
 }
 
 
-//
-// 'Fl_Shared_Image::add_handler()' - Add a shared image handler.
-//
 
-void
-Fl_Shared_Image::add_handler(Fl_Shared_Handler f) {
+/** Adds a shared image handler, which is basically a test function for adding new formats */
+void Fl_Shared_Image::add_handler(Fl_Shared_Handler f) {
   int			i;		// Looping var...
   Fl_Shared_Handler	*temp;		// New image handler array...
 
@@ -437,12 +435,9 @@ Fl_Shared_Image::add_handler(Fl_Shared_Handler f) {
 }
 
 
-//
-// 'Fl_Shared_Image::remove_handler()' - Remove a shared image handler.
-//
 
-void
-Fl_Shared_Image::remove_handler(Fl_Shared_Handler f) {
+/** Removes a shared image handler */
+void Fl_Shared_Image::remove_handler(Fl_Shared_Handler f) {
   int	i;				// Looping var...
 
   // First see if the handler has been added...
diff --git a/src/Fl_XBM_Image.cxx b/src/Fl_XBM_Image.cxx
index d4d02d270..4406f7cef 100644
--- a/src/Fl_XBM_Image.cxx
+++ b/src/Fl_XBM_Image.cxx
@@ -44,6 +44,11 @@
 // 'Fl_XBM_Image::Fl_XBM_Image()' - Load an XBM file.
 //
 
+/**  
+  The constructor loads the named XBM file from the given name filename.
+  <P>The destructor free all memory and server resources that are used by 
+  the image.
+*/
 Fl_XBM_Image::Fl_XBM_Image(const char *name) : Fl_Bitmap((const char *)0,0,0) {
   FILE	*f;
   uchar	*ptr;
diff --git a/src/Fl_XPM_Image.cxx b/src/Fl_XPM_Image.cxx
index 09d5c0fbc..603e58b35 100644
--- a/src/Fl_XPM_Image.cxx
+++ b/src/Fl_XPM_Image.cxx
@@ -53,7 +53,11 @@ static int hexdigit(int x) {	// I - Hex digit...
 
 #define MAXSIZE 2048
 #define INITIALLINES 256
-
+/**
+  The constructor loads the XPM image from the name filename.
+  <P>The destructor free all memory and server resources that are used by
+  the image.
+*/
 Fl_XPM_Image::Fl_XPM_Image(const char *name) : Fl_Pixmap((char *const*)0) {
   FILE *f;