Rename Fl_Image::pixel_w() and pixel_h() to Fl_Image::data_w() and data_h().

The docs of class Fl_Image and of Fl_Image::scale() are beefed up.

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

1 files changed, 18 insertions, 11 deletions

diff --git a/FL/Fl_Image.H b/FL/Fl_Image.H
index 75e5820b9..7b6024b65 100644
--- a/FL/Fl_Image.H
+++ b/FL/Fl_Image.H
@@ -49,6 +49,13 @@ enum Fl_RGB_Scaling {
  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.
+ 
+ Each image possesses two (width, height) pairs. 1) The width and height of the
+ image raw data are returned by data_w() and data_h(). These values are set
+ when the image is created and remain unchanged. 2) The width and height
+ of the area filled by the image when it gets drawn are returned by w() and h().
+ The values are equal to data_w() and data_h() when the image is created,
+ and can be changed by the scale() member function.
   
  Since the Fl_Image class does not support image
  drawing by itself, calling the draw() method results in
@@ -63,7 +70,7 @@ public:
     
 private:
   int w_, h_, d_, ld_, count_;
-  int pixel_w_, pixel_h_;
+  int data_w_, data_h_;
   const char * const *data_;
   static Fl_RGB_Scaling RGB_scaling_; // method used when copying RGB images
   static Fl_RGB_Scaling scaling_algorithm_; // method used to rescale RGB source images before drawing
@@ -74,13 +81,13 @@ private:
 protected:
 
   /**
-   Sets the current image width in pixels.
+   Sets the width of the image data.
    */
-  void w(int W) {w_ = W; pixel_w_ = W;}
+  void w(int W) {w_ = W; data_w_ = W;}
   /**
-   Sets the current image height in pixels.
+   Sets the height of the image data.
    */
-  void h(int H) {h_ = H; pixel_h_ = H;}
+  void h(int H) {h_ = H; data_h_ = H;}
   /**
    Sets the current image depth.
    */
@@ -111,24 +118,24 @@ public:
 
   /** 
    Returns the current image width in FLTK units.
-   The values of w() and pixel_w() are identical unless scale() has been called
+   The values of w() and data_w() are identical unless scale() has been called
    after which they may differ.
    */
   int w() const {return w_;}
   /**
    Returns the current image height in FLTK units.
-   The values of h() and pixel_h() are identical unless scale() has been called
+   The values of h() and data_h() are identical unless scale() has been called
    after which they may differ.
    */
   int h() const {return h_;}
   /**
-   Returns the image width in pixels.
+   Returns the width of the image data.
    */
-  int pixel_w() {return pixel_w_;}
+  int data_w() const {return data_w_;}
   /**
-   Returns the image height in pixels.
+   Returns the height of the image data.
    */
-  int pixel_h() {return pixel_h_;}
+  int data_h() const {return data_h_;}
   /**
    Returns the current image depth.
    The return value will be 0 for bitmaps, 1 for