Doxygen Documentation WP5 Done, WP6 half finished so that all Fl_Imag…

…e 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

FL/Fl_BMP_Image.H

@@ -29,6 +29,10 @@
 #define Fl_BMP_Image_H
 #  include "Fl_Image.H"
 
+/**
+  The Fl_BMP_Image class supports loading, caching,
+  and drawing of Windows Bitmap (BMP) image files.
+*/
 class FL_EXPORT Fl_BMP_Image : public Fl_RGB_Image {
 
   public:

FL/Fl_Bitmap.H

@@ -32,6 +32,10 @@
 class Fl_Widget;
 struct Fl_Menu_Item;
 
+/**
+  The Fl_Bitmap class supports caching and drawing of mono-color
+  (bitmap) images. Images are drawn using the current color.
+*/
 class FL_EXPORT Fl_Bitmap : public Fl_Image {
   public:
 
@@ -42,9 +46,10 @@ class FL_EXPORT Fl_Bitmap : public Fl_Image {
 #else
   unsigned id; // for internal use
 #endif // __APPLE__ || WIN32
-
+  /** The constructors create a new bitmap from the specified bitmap data */
   Fl_Bitmap(const uchar *bits, int W, int H) :
     Fl_Image(W,H,0), array(bits), alloc_array(0), id(0) {data((const char **)&array, 1);}
+  /** The constructors create a new bitmap from the specified bitmap data */
   Fl_Bitmap(const char *bits, int W, int H) :
     Fl_Image(W,H,0), array((const uchar *)bits), alloc_array(0), id(0) {data((const char **)&array, 1);}
   virtual ~Fl_Bitmap();

FL/Fl_GIF_Image.H

@@ -29,6 +29,11 @@
 #define Fl_GIF_Image_H
 #  include "Fl_Pixmap.H"
 
+/**
+  The Fl_GIF_Image class supports loading, caching,
+  and drawing of Compuserve GIF<SUP>SM</SUP> images. The class
+  loads the first image and supports transparency.
+*/
 class FL_EXPORT Fl_GIF_Image : public Fl_Pixmap {
 
   public:

FL/Fl_Image.H

@@ -34,6 +34,17 @@ class Fl_Widget;
 struct Fl_Menu_Item;
 struct Fl_Label;
 
+/**
+  Fl_Image is the base class used for caching and
+  drawing all kinds of images in FLTK. This class keeps track of
+  common image data such as the pixels, colormap, width, height,
+  and depth. Virtual methods are used to provide type-specific
+  image handling.</P>
+  
+  <P>Since the Fl_Image class does not support image
+  drawing by itself, calling the draw() method results in
+  a box with an X in it being drawn instead.
+*/
 class FL_EXPORT Fl_Image {
   int w_, h_, d_, ld_, count_;
   const char * const *data_;
@@ -44,10 +55,34 @@ class FL_EXPORT Fl_Image {
 
   protected:
 
+  /**
+    The first form of the w() method returns the current
+    image width in pixels.</P>
+    
+    <P>The second form is a protected method that sets the current
+    image width.
+  */
   void w(int W) {w_ = W;}
+  /**
+    The first form of the h() method returns the current
+    image height in pixels.</P>
+    
+    <P>The second form is a protected method that sets the current
+    image height.
+  */
   void h(int H) {h_ = H;}
+  /**
+    The first form of the d() method returns the current
+    image depth. The return value will be 0 for bitmaps, 1 for
+    pixmaps, and 1 to 4 for color images.</P>
+    
+    <P>The second form is a protected method that sets the current
+    image depth.
+  */
   void d(int D) {d_ = D;}
+  /**    See int ld()  */
   void ld(int LD) {ld_ = LD;}
+  /**    See const char * const *data()  */
   void data(const char * const *p, int c) {data_ = p; count_ = c;}
   void draw_empty(int X, int Y);
 
@@ -56,27 +91,99 @@ class FL_EXPORT Fl_Image {
 
   public:
 
+  /** See void Fl_Image::w(int) */
   int w() const {return w_;}
+  /** See void Fl_Image::h(int) */
   int h() const {return h_;}
+  /**
+    The first form of the d() method returns the current
+    image depth. The return value will be 0 for bitmaps, 1 for
+    pixmaps, and 1 to 4 for color images.</P>
+    
+    <P>The second form is a protected method that sets the current
+    image depth.
+  */
   int d() const {return d_;}
+  /**
+    The first form of the ld() method returns the current
+    line data size in bytes. Line data is extra data that is included
+    after each line of color image data and is normally not present.</P>
+    
+    <P>The second form is a protected method that sets the current
+    line data size in bytes.
+  */
   int ld() const {return ld_;}
+  /**
+    The count() method returns the number of data values
+    associated with the image. The value will be 0 for images with
+    no associated data, 1 for bitmap and color images, and greater
+    than 2 for pixmap images.
+  */
   int count() const {return count_;}
+  /**
+    The first form of the data() method returns a
+    pointer to the current image data array. Use the
+    count() method to find the size of the data array.</P>
+    
+    <P>The second form is a protected method that sets the current
+    array pointer and count of pointers in the array.
+  */
   const char * const *data() const {return data_;}
 
+  /**
+    The constructor creates an empty image with the specified
+    width, height, and depth. The width and height are in pixels.
+    The depth is 0 for bitmaps, 1 for pixmap (colormap) images, and
+    1 to 4 for color images.
+  */
   Fl_Image(int W, int H, int D) {w_ = W; h_ = H; d_ = D; ld_ = 0; count_ = 0; data_ = 0;}
   virtual ~Fl_Image();
   virtual Fl_Image *copy(int W, int H);
+  /**
+    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 *copy() { return copy(w(), h()); }
   virtual void color_average(Fl_Color c, float i);
+  /**
+    The inactive() method calls
+    color_average(FL_BACKGROUND_COLOR, 0.33f) to produce 
+    an image that appears grayed out. <I>This method does not 
+    alter the original image data.</I>
+  */
   void inactive() { color_average(FL_GRAY, .33f); }
   virtual void desaturate();
   virtual void label(Fl_Widget*w);
   virtual void label(Fl_Menu_Item*m);
-  virtual void draw(int X, int Y, int W, int H, int cx=0, int cy=0);
-  void draw(int X, int Y) {draw(X, Y, w(), h(), 0, 0);}
+  /**
+    The draw() methods draw the image. This form specifies
+    a bounding box for the image, with the origin
+    (upper-lefthand corner) of the image offset by the cx
+    and cy arguments.
+  */
+  virtual void draw(int X, int Y, int W, int H, int cx=0, int cy=0); // platform dependent
+  /**
+    The draw() methods draw the image. This form
+    specifies the upper-lefthand corner of the image
+  */
+  void draw(int X, int Y) {draw(X, Y, w(), h(), 0, 0);} // platform dependent
   virtual void uncache();
 };
 
+/**
+  The Fl_RGB_Image class supports caching and drawing
+  of full-color images with 1 to 4 channels of color information.
+  Images with an even number of channels are assumed to contain
+  alpha information, which is used to blend the image with the
+  contents of the screen.</P>
+  
+  <P>Fl_RGB_Image is defined in
+  &lt;FL/Fl_Image.H&gt;, however for compatibility reasons
+  &lt;FL/Fl_RGB_Image.H&gt; should be included.
+*/
 class FL_EXPORT Fl_RGB_Image : public Fl_Image {
   public:
 
@@ -90,7 +197,7 @@ class FL_EXPORT Fl_RGB_Image : public Fl_Image {
   unsigned id; // for internal use
   unsigned mask; // for internal use (mask bitmap)
 #endif // __APPLE__ || WIN32
-
+/**  The constructor creates a new image from the specified data. */
   Fl_RGB_Image(const uchar *bits, int W, int H, int D=3, int LD=0) :
     Fl_Image(W,H,D), array(bits), alloc_array(0), id(0), mask(0) {data((const char **)&array, 1); ld(LD);}
   virtual ~Fl_RGB_Image();

FL/Fl_JPEG_Image.H

@@ -29,6 +29,12 @@
 #define Fl_JPEG_Image_H
 #  include "Fl_Image.H"
 
+/**
+  The Fl_JPEG_Image class supports loading, caching,
+  and drawing of Joint Photographic Experts Group (JPEG) File
+  Interchange Format (JFIF) images. The class supports grayscale
+  and color (RGB) JPEG image files.
+*/
 class FL_EXPORT Fl_JPEG_Image : public Fl_RGB_Image {
 
   public:

FL/Fl_PNG_Image.H

@@ -29,6 +29,12 @@
 #define Fl_PNG_Image_H
 #  include "Fl_Image.H"
 
+/**
+  The Fl_PNG_Image class supports loading, caching,
+  and drawing of Portable Network Graphics (PNG) image files. The
+  class loads colormapped and full-color images and handles color-
+  and alpha-based transparency.
+*/
 class FL_EXPORT Fl_PNG_Image : public Fl_RGB_Image {
 
   public:

FL/Fl_PNM_Image.H

@@ -29,6 +29,12 @@
 #define Fl_PNM_Image_H
 #  include "Fl_Image.H"
 
+/**
+  The Fl_PNM_Image class supports loading, caching,
+  and drawing of Portable Anymap (PNM, PBM, PGM, PPM) image files. The class
+  loads bitmap, grayscale, and full-color images in both ASCII and
+  binary formats.
+*/
 class FL_EXPORT Fl_PNM_Image : public Fl_RGB_Image {
 
   public:

FL/Fl_Pixmap.H

@@ -37,6 +37,10 @@ struct Fl_Menu_Item;
 #    define explicit
 #  endif // __sgi && !_COMPILER_VERSION
 
+/**
+  The Fl_Pixmap class supports caching and drawing of colormap
+  (pixmap) images, including transparency.
+*/
 class FL_EXPORT Fl_Pixmap : public Fl_Image {
   void copy_data();
   void delete_data();
@@ -57,9 +61,13 @@ class FL_EXPORT Fl_Pixmap : public Fl_Image {
   unsigned mask; // for internal use (mask bitmap)
 #endif // __APPLE__ || WIN32
 
+  /**    The constructors create a new pixmap from the specified XPM data.  */
   explicit Fl_Pixmap(char * const * D) : Fl_Image(-1,0,1), alloc_data(0), id(0), mask(0) {set_data((const char*const*)D); measure();}
+  /**    The constructors create a new pixmap from the specified XPM data.  */
   explicit Fl_Pixmap(uchar* const * D) : Fl_Image(-1,0,1), alloc_data(0), id(0), mask(0) {set_data((const char*const*)D); measure();}
+  /**    The constructors create a new pixmap from the specified XPM data.  */
   explicit Fl_Pixmap(const char * const * D) : Fl_Image(-1,0,1), alloc_data(0), id(0), mask(0) {set_data((const char*const*)D); measure();}
+  /**    The constructors create a new pixmap from the specified XPM data.  */
   explicit Fl_Pixmap(const uchar* const * D) : Fl_Image(-1,0,1), alloc_data(0), id(0), mask(0) {set_data((const char*const*)D); measure();}
   virtual ~Fl_Pixmap();
   virtual Fl_Image *copy(int W, int H);

FL/Fl_Shared_Image.H

@@ -36,6 +36,13 @@ typedef Fl_Image *(*Fl_Shared_Handler)(const char *name, uchar *header,
                                        int headerlen);
 
 // Shared images class. 
+/**
+  This class supports caching, loading,
+  and drawing of image files. Most applications will also want to
+  link against the fltk_images library and call the
+  fl_register_images()
+  function to support standard image formats such as BMP, GIF, JPEG, and PNG.
+*/
 class FL_EXPORT Fl_Shared_Image : public Fl_Image {
   protected:
 
@@ -62,8 +69,9 @@ class FL_EXPORT Fl_Shared_Image : public Fl_Image {
   void update();
 
   public:
-
+  /** Returns the filename of the shared image */
   const char	*name() { return name_; }
+  /** Returns the number of references of this shared image. When reference is below 1, the image is deleted. */
   int		refcount() { return refcount_; }
   void		release();
   void		reload();

FL/Fl_XBM_Image.H

@@ -29,6 +29,10 @@
 #define Fl_XBM_Image_H
 #  include "Fl_Bitmap.H"
 
+/**
+  The Fl_XBM_Image class supports loading, caching,
+  and drawing of X Bitmap (XBM) bitmap files.
+*/
 class FL_EXPORT Fl_XBM_Image : public Fl_Bitmap {
 
   public:

FL/Fl_XPM_Image.H

@@ -29,6 +29,10 @@
 #define Fl_XPM_Image_H
 #  include "Fl_Pixmap.H"
 
+/**
+  The Fl_XPM_Image class supports loading, caching,
+  and drawing of X Pixmap (XPM) images, including transparency.
+*/
 class FL_EXPORT Fl_XPM_Image : public Fl_Pixmap {
 
   public:

documentation/todo_filelist_doc.txt

@@ -13,7 +13,7 @@ In Progress Work List (add your WP and name here):
   - WP2  (Fabien) DONE
   - WP3  (engelsman)
   - WP4  (Fabien) DONE
-  - WP5  (Fabien)
+  - WP5  (Fabien) DONE
   - WP6  (Fabien)
   - WP7
   - WP8

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

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;

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