fltk  1.3.5-source
About: FLTK (Fast Light Tool Kit) is a cross-platform C++ GUI toolkit for UNIX/Linux (X11), Microsoft Windows, and MacOS X.
  Fossies Dox: fltk-1.3.5-source.tar.bz2  ("inofficial" and yet experimental doxygen-generated source code documentation)  

Fl_Shared_Image Class Reference

#include <Fl_Shared_Image.H>

Inheritance diagram for Fl_Shared_Image:
[legend]
Collaboration diagram for Fl_Shared_Image:
[legend]

Public Member Functions

const char * name ()
 
int refcount ()
 
int original ()
 
void release ()
 
void reload ()
 
virtual Fl_Imagecopy (int W, int H)
 
Fl_Imagecopy ()
 
virtual void color_average (Fl_Color c, float i)
 
virtual void desaturate ()
 
virtual void draw (int X, int Y, int W, int H, int cx, int cy)
 
void draw (int X, int Y)
 
void scale (int width, int height, int proportional=1, int can_expand=0)
 
virtual void uncache ()
 
- Public Member Functions inherited from Fl_Image
int w () const
 
int h () const
 
int d () const
 
int ld () const
 
int count () const
 
const char *constdata () const
 
int fail ()
 
 Fl_Image (int W, int H, int D)
 
virtual ~Fl_Image ()
 
Fl_Imagecopy ()
 
void inactive ()
 
virtual void label (Fl_Widget *w)
 
virtual void label (Fl_Menu_Item *m)
 
void draw (int X, int Y)
 

Static Public Member Functions

static Fl_Shared_Imagefind (const char *name, int W=0, int H=0)
 
static Fl_Shared_Imageget (const char *name, int W=0, int H=0)
 
static Fl_Shared_Imageget (Fl_RGB_Image *rgb, int own_it=1)
 
static Fl_Shared_Image ** images ()
 
static int num_images ()
 
static void add_handler (Fl_Shared_Handler f)
 
static void remove_handler (Fl_Shared_Handler f)
 
static void scaling_algorithm (Fl_RGB_Scaling algorithm)
 
- Static Public Member Functions inherited from Fl_Image
static void RGB_scaling (Fl_RGB_Scaling)
 
static Fl_RGB_Scaling RGB_scaling ()
 

Protected Member Functions

 Fl_Shared_Image ()
 
 Fl_Shared_Image (const char *n, Fl_Image *img=0)
 
virtual ~Fl_Shared_Image ()
 
void add ()
 
void update ()
 
- Protected Member Functions inherited from Fl_Image
void w (int W)
 
void h (int H)
 
void d (int D)
 
void ld (int LD)
 
void data (const char *const *p, int c)
 
void draw_empty (int X, int Y)
 

Static Protected Member Functions

static int compare (Fl_Shared_Image **i0, Fl_Shared_Image **i1)
 
- Static Protected Member Functions inherited from Fl_Image
static void labeltype (const Fl_Label *lo, int lx, int ly, int lw, int lh, Fl_Align la)
 
static void measure (const Fl_Label *lo, int &lw, int &lh)
 

Protected Attributes

const char * name_
 
int original_
 
int refcount_
 
Fl_Imageimage_
 
int alloc_image_
 

Static Protected Attributes

static Fl_Shared_Image ** images_ = 0
 
static int num_images_ = 0
 
static int alloc_images_ = 0
 
static Fl_Shared_Handlerhandlers_ = 0
 
static int num_handlers_ = 0
 
static int alloc_handlers_ = 0
 

Static Private Attributes

static Fl_RGB_Scaling scaling_algorithm_ = FL_RGB_SCALING_BILINEAR
 

Friends

class Fl_JPEG_Image
 
class Fl_PNG_Image
 

Additional Inherited Members

- Static Public Attributes inherited from Fl_Image
static const int ERR_NO_IMAGE = -1
 
static const int ERR_FILE_ACCESS = -2
 
static const int ERR_FORMAT = -3
 

Detailed Description

This class supports caching, loading, scaling, 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.

Images can be requested (loaded) with Fl_Shared_Image::get(), find(), and some other methods. All images are cached in an internal list of shared images and should be released when they are no longer needed. A refcount is used to determine if a released image is to be destroyed with delete.

See also
Fl_Shared_Image::get()
Fl_Shared_Image::find()
Fl_Shared_Image::release()

Definition at line 50 of file Fl_Shared_Image.H.

Constructor & Destructor Documentation

◆ Fl_Shared_Image() [1/2]

Fl_Shared_Image::Fl_Shared_Image ( )
protected

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.

Definition at line 120 of file Fl_Shared_Image.cxx.

References alloc_image_, image_, name_, original_, and refcount_.

Referenced by copy(), find(), and get().

◆ Fl_Shared_Image() [2/2]

Fl_Shared_Image::Fl_Shared_Image ( const char *  n,
Fl_Image img = 0 
)
protected

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.

Definition at line 139 of file Fl_Shared_Image.cxx.

References alloc_image_, image_, name_, original_, refcount_, reload(), and update().

◆ ~Fl_Shared_Image()

Fl_Shared_Image::~Fl_Shared_Image ( )
protectedvirtual

The destructor frees 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.

Definition at line 215 of file Fl_Shared_Image.cxx.

References alloc_image_, image_, and name_.

Member Function Documentation

◆ add()

void Fl_Shared_Image::add ( )
protected

Adds a shared image to the image cache.

This protected method adds an image to the cache, an ordered list of shared images. The cache is searched for a matching image whenever one is requested, for instance with Fl_Shared_Image::get() or Fl_Shared_Image::find().

Definition at line 167 of file Fl_Shared_Image.cxx.

References alloc_images_, compare(), images_, and num_images_.

Referenced by Fl_JPEG_Image::Fl_JPEG_Image(), get(), and Fl_PNG_Image::load_png_().

◆ add_handler()

void Fl_Shared_Image::add_handler ( Fl_Shared_Handler  f)
static

Adds a shared image handler, which is basically a test function for adding new formats.

Definition at line 585 of file Fl_Shared_Image.cxx.

References alloc_handlers_, f, handlers_, and num_handlers_.

Referenced by fl_register_images().

◆ color_average()

void Fl_Shared_Image::color_average ( Fl_Color  c,
float  i 
)
virtual

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.

Reimplemented from Fl_Image.

Definition at line 345 of file Fl_Shared_Image.cxx.

References Fl_Image::color_average(), image_, and update().

◆ compare()

int Fl_Shared_Image::compare ( Fl_Shared_Image **  i0,
Fl_Shared_Image **  i1 
)
staticprotected

Compares two shared images.

The order of comparison is:

  1. Image name, usually the filename used to load it
  2. Image width
  3. Image height

A special case is considered if the width of one of the images is zero and the other image is marked original. In this case the images match, i.e. the comparison returns success (0).

An image is marked original if it was directly loaded from a file or from memory as opposed to copied and resized images.

This comparison is used in Fl_Shared_Image::find() to find an image that matches the requested one or to find the position where a new image should be entered into the sorted list of shared images.

It is usually used in two steps:

  1. search with exact width and height
  2. if not found, search again with width = 0 (and height = 0)

The first step will only return a match if the image exists with the same width and height. The second step will match if there is an image marked original with the same name, regardless of width and height.

Returns
Whether the images match or their relative sort order (see text).
Return values
0the images match
<0Image i0 is less than image i1
>0Image i0 is greater than image i1

Definition at line 101 of file Fl_Shared_Image.cxx.

Referenced by add(), and find().

◆ copy() [1/2]

Fl_Image* Fl_Shared_Image::copy ( )
inline

Definition at line 106 of file Fl_Shared_Image.H.

References copy(), Fl_Image::h(), and Fl_Image::w().

Referenced by copy().

◆ copy() [2/2]

Fl_Image * Fl_Shared_Image::copy ( int  W,
int  H 
)
virtual

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.

Reimplemented from Fl_Image.

Definition at line 316 of file Fl_Shared_Image.cxx.

References alloc_image_, Fl_Image::copy(), Fl_Shared_Image(), H, image_, name_, refcount_, and update().

Referenced by get(), and Fl_File_Chooser::update_preview().

◆ desaturate()

void Fl_Shared_Image::desaturate ( )
virtual

The desaturate() method converts an image to grayscale. If the image contains an alpha channel (depth = 4), the alpha channel is preserved.

An internal copy is made of the original image before changes are applied, to avoid modifying the original image.

Reimplemented from Fl_Image.

Definition at line 359 of file Fl_Shared_Image.cxx.

References Fl_Image::desaturate(), image_, and update().

◆ draw() [1/2]

void Fl_Shared_Image::draw ( int  X,
int  Y 
)
inline

Definition at line 110 of file Fl_Shared_Image.H.

References draw(), Fl_Image::h(), Fl_Image::w(), and Y.

Referenced by draw().

◆ draw() [2/2]

void Fl_Shared_Image::draw ( int  X,
int  Y,
int  W,
int  H,
int  cx,
int  cy 
)
virtual

Draws the image with a bounding box. Arguments X,Y,W,H specify a bounding box for the image, with the origin
(upper-left corner) of the image offset by the cx and cy arguments.

In other words: fl_push_clip(X,Y,W,H) is applied, the image is drawn with its upper-left corner at X-cx,Y-cy and its own width and height, fl_pop_clip() is applied.

Reimplemented from Fl_Image.

Definition at line 370 of file Fl_Shared_Image.cxx.

References Fl_Image::copy(), Fl_Image::count(), Fl_Image::d(), Fl_Image::draw(), Fl_Graphics_Driver::draw_scaled(), fl_graphics_driver, fl_pop_clip(), fl_push_clip(), H, Fl_Image::h(), image_, NULL, Fl_Image::RGB_scaling(), scaling_algorithm_, Fl_Image::w(), and Y.

Referenced by Fl_Help_View::draw().

◆ find()

Fl_Shared_Image * Fl_Shared_Image::find ( const char *  name,
int  W = 0,
int  H = 0 
)
static

Finds a shared image from its name and size specifications.

This uses a binary search in the image cache.

If the image name exists with the exact width W and height H, then it is returned.

If W == 0 and the image name exists with another size, then the original image with that name is returned.

In either case the refcount of the returned image is increased. The found image should be released with Fl_Shared_Image::release() when no longer needed.

Definition at line 479 of file Fl_Shared_Image.cxx.

References compare(), Fl_Shared_Image(), H, images_, key, name(), and num_images_.

Referenced by get(), Fl_Help_View::get_image(), and show_help().

◆ get() [1/2]

Fl_Shared_Image * Fl_Shared_Image::get ( const char *  name,
int  W = 0,
int  H = 0 
)
static

Find or load an image that can be shared by multiple widgets.

If the image exists with the requested size, this image will be returned.

If the image exists, but only with another size, then a new copy with the requested size (width W and height H) will be created as a resized copy of the original image. The new image is added to the internal list of shared images.

If the image does not yet exist, then a new image of the proper dimension is created from the filename name. The original image from filename name is always added to the list of shared images in its original size. If the requested size differs, then the resized copy with width W and height H is also added to the list of shared images.

Note
If the sizes differ, then two images are created as mentioned above. This is intentional so the original image is cached and preserved. If you request the same image with another size later, then the original image will be found, copied, resized, and returned.

Shared JPEG and PNG images can also be created from memory by using their named memory access constructor.

You should release() the image when you're done with it.

Parameters
namename of the image
W,Hdesired size
See also
Fl_Shared_Image::find(const char *name, int W, int H)
Fl_Shared_Image::release()
Fl_JPEG_Image::Fl_JPEG_Image(const char *name, const unsigned char *data)
Fl_PNG_Image::Fl_PNG_Image (const char *name_png, const unsigned char *buffer, int maxsize)

Definition at line 541 of file Fl_Shared_Image.cxx.

References add(), copy(), find(), Fl_Shared_Image(), H, Fl_Image::h(), image_, name(), NULL, and Fl_Image::w().

Referenced by cb_template_browser(), fl_handle(), Fluid_Image::Fluid_Image(), Fl_Help_View::get_image(), Fl_Image_Surface::highres_image(), Fl_File_Icon::load_image(), and Fl_File_Chooser::update_preview().

◆ get() [2/2]

Fl_Shared_Image * Fl_Shared_Image::get ( Fl_RGB_Image rgb,
int  own_it = 1 
)
static

Builds a shared image from a pre-existing Fl_RGB_Image.

Parameters
[in]rgban Fl_RGB_Image used to build a new shared image.
[in]own_it1 if the shared image should delete rgb when it is itself deleted, 0 otherwise
Version
1.3.4

Definition at line 573 of file Fl_Shared_Image.cxx.

References add(), alloc_image_, Fl_Shared_Image(), and Fl_Preferences::newUUID().

◆ images()

Fl_Shared_Image ** Fl_Shared_Image::images ( )
static

Returns the Fl_Shared_Image* array

Definition at line 54 of file Fl_Shared_Image.cxx.

References images_.

◆ name()

const char* Fl_Shared_Image::name ( )
inline

Returns the filename of the shared image

Definition at line 86 of file Fl_Shared_Image.H.

Referenced by find(), and get().

◆ num_images()

int Fl_Shared_Image::num_images ( )
static

Returns the total number of shared images in the array.

Definition at line 60 of file Fl_Shared_Image.cxx.

References num_images_.

◆ original()

int Fl_Shared_Image::original ( )
inline

Returns whether this is an original image. Images loaded from a file or from memory are marked original as opposed to images created as a copy of another image with different size (width or height).

Note
This is useful for debugging (rarely used in user code).
Since
FLTK 1.4.0

Definition at line 100 of file Fl_Shared_Image.H.

◆ refcount()

int Fl_Shared_Image::refcount ( )
inline

Returns the number of references of this shared image. When reference is below 1, the image is deleted.

Definition at line 91 of file Fl_Shared_Image.H.

◆ release()

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.

Definition at line 230 of file Fl_Shared_Image.cxx.

References alloc_images_, images_, num_images_, and refcount_.

Referenced by cb_Cancel(), cb_template_browser(), cb_template_panel(), cb_template_submit(), fl_handle(), Fl_Help_View::free_data(), Fl_Help_View::get_image(), Fl_File_Icon::load_image(), Fl_File_Chooser::update_preview(), and Fluid_Image::~Fluid_Image().

◆ reload()

void Fl_Shared_Image::reload ( )

Reloads the shared image from disk.

Definition at line 260 of file Fl_Shared_Image.cxx.

References alloc_image_, Fl_Image::copy(), fl_fopen(), Fl_Image::h(), handlers_, image_, name_, NULL, num_handlers_, update(), and Fl_Image::w().

Referenced by Fl_Shared_Image().

◆ remove_handler()

void Fl_Shared_Image::remove_handler ( Fl_Shared_Handler  f)
static

Removes a shared image handler.

Definition at line 614 of file Fl_Shared_Image.cxx.

References f, handlers_, and num_handlers_.

◆ scale()

void Fl_Shared_Image::scale ( int  width,
int  height,
int  proportional = 1,
int  can_expand = 0 
)

Sets the drawing size of the shared image. This function gives the shared image its own size, independently from the size of the original image that is typically larger. This can be useful to draw a shared image on a drawing surface whose resolution is higher than the drawing unit for this surface: all pixels of the original image become available to fill an area of the drawing surface sized at width,height. Examples of such drawing surfaces: laser printers, PostScript files, PDF printers, retina displays on Apple hardware.

Parameters
width,heightmaximum width and height (in drawing units) to use when drawing the shared image
proportionalif not null, keep the width and height of the shared image proportional to those of its original image
can_expandif null, the width and height of the shared image will not exceed those of the original image
Version
1.3.4 and requires compiling with FLTK_ABI_VERSION = 10304

Example code: scale an image to fit in a box

Fl_Box *b = ... // a box
Fl_Shared_Image *shared = Fl_Shared_Image::get("/path/to/picture.jpeg"); // read a picture file
shared->scale(b->w(), b->h(), 1); // set the drawing size of the shared image to the size of the box
b->image(shared); // use the shared image as the box image
b->align(FL_ALIGN_INSIDE | FL_ALIGN_CENTER | FL_ALIGN_CLIP); // the image is to be drawn centered in the box

Definition at line 429 of file Fl_Shared_Image.cxx.

References Fl_Image::h(), image_, and Fl_Image::w().

Referenced by Fl_Image_Surface::highres_image().

◆ scaling_algorithm()

static void Fl_Shared_Image::scaling_algorithm ( Fl_RGB_Scaling  algorithm)
inlinestatic

Sets what algorithm is used when resizing a source image. The default algorithm is FL_RGB_SCALING_BILINEAR. Drawing an Fl_Shared_Image is sometimes performed by first resizing the source image and then drawing the resized copy. This occurs, e.g., when drawing to screen under Linux or MSWindows after having called Fl_Shared_Image::scale(). This function controls what method is used when the image to be resized is an Fl_RGB_Image.

Version
1.3.4 and requires compiling with FLTK_ABI_VERSION = 10304

Definition at line 129 of file Fl_Shared_Image.H.

◆ uncache()

void Fl_Shared_Image::uncache ( )
virtual

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.

Reimplemented from Fl_Image.

Definition at line 458 of file Fl_Shared_Image.cxx.

References image_, and Fl_Image::uncache().

◆ update()

void Fl_Shared_Image::update ( )
protected

Friends And Related Function Documentation

◆ Fl_JPEG_Image

friend class Fl_JPEG_Image
friend

Definition at line 52 of file Fl_Shared_Image.H.

◆ Fl_PNG_Image

friend class Fl_PNG_Image
friend

Definition at line 53 of file Fl_Shared_Image.H.

Member Data Documentation

◆ alloc_handlers_

int Fl_Shared_Image::alloc_handlers_ = 0
staticprotected

Definition at line 67 of file Fl_Shared_Image.H.

Referenced by add_handler().

◆ alloc_image_

int Fl_Shared_Image::alloc_image_
protected

Definition at line 73 of file Fl_Shared_Image.H.

Referenced by copy(), Fl_Shared_Image(), get(), reload(), and ~Fl_Shared_Image().

◆ alloc_images_

int Fl_Shared_Image::alloc_images_ = 0
staticprotected

Definition at line 64 of file Fl_Shared_Image.H.

Referenced by add(), and release().

◆ handlers_

Fl_Shared_Handler * Fl_Shared_Image::handlers_ = 0
staticprotected

Definition at line 65 of file Fl_Shared_Image.H.

Referenced by add_handler(), reload(), and remove_handler().

◆ image_

Fl_Image* Fl_Shared_Image::image_
protected

◆ images_

Fl_Shared_Image ** Fl_Shared_Image::images_ = 0
staticprotected

Definition at line 62 of file Fl_Shared_Image.H.

Referenced by add(), find(), images(), and release().

◆ name_

const char* Fl_Shared_Image::name_
protected

Definition at line 69 of file Fl_Shared_Image.H.

Referenced by copy(), Fl_Shared_Image(), reload(), and ~Fl_Shared_Image().

◆ num_handlers_

int Fl_Shared_Image::num_handlers_ = 0
staticprotected

Definition at line 66 of file Fl_Shared_Image.H.

Referenced by add_handler(), reload(), and remove_handler().

◆ num_images_

int Fl_Shared_Image::num_images_ = 0
staticprotected

Definition at line 63 of file Fl_Shared_Image.H.

Referenced by add(), find(), num_images(), and release().

◆ original_

int Fl_Shared_Image::original_
protected

Definition at line 70 of file Fl_Shared_Image.H.

Referenced by Fl_Shared_Image().

◆ refcount_

int Fl_Shared_Image::refcount_
protected

Definition at line 71 of file Fl_Shared_Image.H.

Referenced by copy(), Fl_Shared_Image(), and release().

◆ scaling_algorithm_

Fl_RGB_Scaling Fl_Shared_Image::scaling_algorithm_ = FL_RGB_SCALING_BILINEAR
staticprivate

Definition at line 56 of file Fl_Shared_Image.H.

Referenced by draw().


The documentation for this class was generated from the following files:
b
long b
Definition: jpegint.h:397
FL_ALIGN_INSIDE
const Fl_Align FL_ALIGN_INSIDE
Definition: Enumerations.H:843
Fl_Shared_Image::scale
void scale(int width, int height, int proportional=1, int can_expand=0)
Definition: Fl_Shared_Image.cxx:429
Fl_Box
Definition: Fl_Box.H:34
Fl_Shared_Image::get
static Fl_Shared_Image * get(const char *name, int W=0, int H=0)
Definition: Fl_Shared_Image.cxx:541
FL_ALIGN_CENTER
const Fl_Align FL_ALIGN_CENTER
Definition: Enumerations.H:830
Fl_Shared_Image
Definition: Fl_Shared_Image.H:50
FL_ALIGN_CLIP
const Fl_Align FL_ALIGN_CLIP
Definition: Enumerations.H:849