From 804c48515d63393d12f61f8a783dc9f0586fcdba Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Wed, 20 Apr 2022 17:25:32 +0200 Subject: Improve docs of Fl_Image and related classes (#431) Clarifications as discussed since April 15, 2022 07:00 UTC (see GitHub issue #431). --- src/Fl_Image.cxx | 48 +++++++++++++++++++++++++++--------------------- 1 file changed, 27 insertions(+), 21 deletions(-) (limited to 'src/Fl_Image.cxx') diff --git a/src/Fl_Image.cxx b/src/Fl_Image.cxx index 051e7fc6f..a4dd6d921 100644 --- a/src/Fl_Image.cxx +++ b/src/Fl_Image.cxx @@ -78,20 +78,27 @@ void Fl_Image::draw_empty(int X, int Y) { /** Creates a resized copy of the image. - The copied image should be released when you are done with it. + The new image should be released when you are done with it. Note: since FLTK 1.4.0 you can use Fl_Image::release() for all types of images (i.e. all subclasses of Fl_Image) instead of operator \em delete for Fl_Image's and Fl_Image::release() for Fl_Shared_Image's. - The copied image data will be converted to the requested size. RGB images + The new image data will be converted to the requested size. RGB images are resized using the algorithm set by Fl_Image::RGB_scaling(). - For the copied image the following equations are true: + For the new image the following equations are true: - w() == data_w() == \p W - h() == data_h() == \p H - \param[in] W,H Requested width and height of the copied image + Note: the returned image can be safely cast to the same image type as that + of the source image provided this type is one of Fl_RGB_Image, Fl_SVG_Image, + Fl_Pixmap, Fl_Bitmap, Fl_Tiled_Image, and Fl_Shared_Image. + Returned objects copied from images of other, derived, image classes belong + to the parent class appearing in this list. For example, the copy of an + Fl_GIF_Image is an object of class Fl_Pixmap. + + \param[in] W,H Requested width and height of the new image \note Since FLTK 1.4.0 this method is 'const'. If you derive your own class from Fl_Image or any subclass your overridden methods of 'Fl_Image::copy() const' @@ -104,15 +111,17 @@ Fl_Image *Fl_Image::copy(int W, int H) const { } /** - 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. - - An internal copy is made of the original image before - changes are applied, to avoid modifying the original image. + The color_average() method averages the colors in the image with + the provided FLTK color value. + + The first argument specifies the FLTK color to be used. + + The second 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. + + An internal copy is made of the original image data before changes are + applied, to avoid modifying the original image data in memory. */ void Fl_Image::color_average(Fl_Color, float) { } @@ -123,8 +132,8 @@ void Fl_Image::color_average(Fl_Color, float) { If the image contains an alpha channel (depth = 4), the alpha channel is preserved. - An internal copy is made of the original image data before - changes are applied, to avoid modifying the original image data. + An internal copy is made of the original image data before changes are + applied, to avoid modifying the original image data in memory. */ void Fl_Image::desaturate() { } @@ -143,19 +152,16 @@ Fl_Labeltype Fl_Image::define_FL_IMAGE_LABEL() { This method is 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. + \deprecated Please use Fl_Widget::image() or Fl_Widget::deimage() instead. */ void Fl_Image::label(Fl_Widget* widget) { widget->image(this); } /** - This method is an obsolete way to set the image attribute of a widget - or menu item. + This method is an obsolete way to set the image attribute of a menu item. - Use the image() or deimage() methods of the Fl_Widget and Fl_Menu_Item - classes instead. + \deprecated Please use Fl_Menu_Item::image() instead. */ void Fl_Image::label(Fl_Menu_Item* m) { m->label(FL_IMAGE_LABEL, (const char*)this); -- cgit v1.2.3