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 ++ 11 files changed, 168 insertions(+), 5 deletions(-) (limited to 'FL') 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: -- cgit v1.2.3