From 7ddd3b8c50d365d860235e4e50b0db06c6acb2d1 Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Sun, 14 Sep 2008 18:19:41 +0000 Subject: 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 --- FL/Fl_BMP_Image.H | 4 ++ FL/Fl_Bitmap.H | 7 ++- FL/Fl_GIF_Image.H | 5 ++ FL/Fl_Image.H | 113 +++++++++++++++++++++++++++++++++++- FL/Fl_JPEG_Image.H | 6 ++ FL/Fl_PNG_Image.H | 6 ++ FL/Fl_PNM_Image.H | 6 ++ FL/Fl_Pixmap.H | 8 +++ FL/Fl_Shared_Image.H | 10 +++- FL/Fl_XBM_Image.H | 4 ++ FL/Fl_XPM_Image.H | 4 ++ documentation/todo_filelist_doc.txt | 2 +- src/Fl_BMP_Image.cxx | 11 ++-- src/Fl_Bitmap.cxx | 10 ++++ src/Fl_GIF_Image.cxx | 5 ++ src/Fl_Image.cxx | 52 ++++++++++++++++- src/Fl_JPEG_Image.cxx | 8 +-- src/Fl_PNG_Image.cxx | 10 ++-- src/Fl_PNM_Image.cxx | 6 ++ src/Fl_Pixmap.cxx | 13 +++++ src/Fl_Shared_Image.cxx | 93 ++++++++++++++--------------- src/Fl_XBM_Image.cxx | 5 ++ src/Fl_XPM_Image.cxx | 6 +- 23 files changed, 325 insertions(+), 69 deletions(-) diff --git a/FL/Fl_BMP_Image.H b/FL/Fl_BMP_Image.H index 20aba3d05..0692aa669 100644 --- a/FL/Fl_BMP_Image.H +++ b/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: diff --git a/FL/Fl_Bitmap.H b/FL/Fl_Bitmap.H index 187fdf8ad..2429d246a 100644 --- a/FL/Fl_Bitmap.H +++ b/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(); diff --git a/FL/Fl_GIF_Image.H b/FL/Fl_GIF_Image.H index 94bf067b4..b231d5037 100644 --- a/FL/Fl_GIF_Image.H +++ b/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 GIFSM images. The class + loads the first image and supports transparency. +*/ class FL_EXPORT Fl_GIF_Image : public Fl_Pixmap { public: diff --git a/FL/Fl_Image.H b/FL/Fl_Image.H index e38b3b17c..1a85f07f8 100644 --- a/FL/Fl_Image.H +++ b/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.

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +

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. This method does not + alter the original image data. + */ 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.

+ +

Fl_RGB_Image is defined in + <FL/Fl_Image.H>, however for compatibility reasons + <FL/Fl_RGB_Image.H> 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(); diff --git a/FL/Fl_JPEG_Image.H b/FL/Fl_JPEG_Image.H index 4cf1b20d0..3501f6491 100644 --- a/FL/Fl_JPEG_Image.H +++ b/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: diff --git a/FL/Fl_PNG_Image.H b/FL/Fl_PNG_Image.H index 86c01fdb1..1b30e7f35 100644 --- a/FL/Fl_PNG_Image.H +++ b/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: diff --git a/FL/Fl_PNM_Image.H b/FL/Fl_PNM_Image.H index a8ce4d2ec..bc4ecc279 100644 --- a/FL/Fl_PNM_Image.H +++ b/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: diff --git a/FL/Fl_Pixmap.H b/FL/Fl_Pixmap.H index 2804ff7f9..be65a3288 100644 --- a/FL/Fl_Pixmap.H +++ b/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); diff --git a/FL/Fl_Shared_Image.H b/FL/Fl_Shared_Image.H index 0dd6f3cd8..6f766ece8 100644 --- a/FL/Fl_Shared_Image.H +++ b/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(); diff --git a/FL/Fl_XBM_Image.H b/FL/Fl_XBM_Image.H index 955210198..e0470b1d7 100644 --- a/FL/Fl_XBM_Image.H +++ b/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: diff --git a/FL/Fl_XPM_Image.H b/FL/Fl_XPM_Image.H index 9d0e7bab0..554abfcc9 100644 --- a/FL/Fl_XPM_Image.H +++ b/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: diff --git a/documentation/todo_filelist_doc.txt b/documentation/todo_filelist_doc.txt index df38628ab..aac1ac06f 100644 --- a/documentation/todo_filelist_doc.txt +++ b/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 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. +

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 #include #include @@ -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. +

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. The original image data is not altered by this + method. +*/ 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. This method does not alter + the original image data. +*/ 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. +

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. +

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. +

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. + +

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. + +

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. +

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. +

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; -- cgit v1.2.3