mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve docs of Fl_Image and related classes (#431)

Browse Source 
Clarifications as discussed since April 15, 2022 07:00 UTC (see GitHub
issue #431).
This commit is contained in:
Albrecht Schlosser 2022-04-20 17:25:32 +02:00
parent c1d0783df9
commit 804c48515d
4 changed files with 32 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
FL/Fl_Image.H
View File

@ -54,8 +54,8 @@ enum Fl_RGB_Scaling {
returned by w() and h(). These 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 a box with an X in it being drawn instead.
Since the Fl_Image class does not support image drawing by itself, calling the
Fl_Image::draw() method results in a box with an X in it being drawn instead.
*/
class FL_EXPORT Fl_Image {
friend class Fl_Graphics_Driver;
@ -239,7 +239,7 @@ public:
/**
Creates a copy of the image in the same size.
The copied image should be released when you are done with it.
The new image should be released when you are done with it.
This does exactly the same as 'Fl_Image::copy(int W, int H) const' where
\p W and \p H are the width and height of the source image, respectively.

2
FL/Fl_Shared_Image.H
View File

@ -176,7 +176,7 @@ public:
\note The internal image (pointer) is protected for good reasons, e.g.
to prevent access to the image so it can't be modified by user code.
\b DO \b NOT cast away the 'const' to modify the image.
\b DO \b NOT cast away the 'const' attribute to modify the image.
User code should rarely need this method. Use with caution.

4
src/Fl_GIF_Image.cxx
View File

@ -105,7 +105,7 @@ static int gif_error(Fl_Image_Reader &rdr, int line, uchar *Image) {
/**
This constructor loads a GIF image from the given file.
IF a GIF image is animated, Fl_GIF_Image will only read and display the
If a GIF image is animated, Fl_GIF_Image will only read and display the
first frame of the animation.
The destructor frees all memory and server resources that are used by
@ -140,7 +140,7 @@ Fl_GIF_Image::Fl_GIF_Image(const char *filename) :
\p imagename can be NULL. If a name is given, the image is added to the list of
shared images and will be available by that name.
IF a GIF image is animated, Fl_GIF_Image will only read and display the
If a GIF image is animated, Fl_GIF_Image will only read and display the
first frame of the animation.
The destructor frees all memory and server resources that are used by

46
src/Fl_Image.cxx
View File

@ -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.
The color_average() method averages the colors in the image with
the provided FLTK color value.
An internal copy is made of the original image before
changes are applied, to avoid modifying the original image.
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);