FLTK: Fl_Shared_Image Class Reference

FLTK

Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | Friends | List of all members
Fl_Shared_Image Class Reference

This class supports caching, loading, scaling, and drawing of image files. More...

`#include <Fl_Shared_Image.H>`

Inheritance diagram for Fl_Shared_Image:

## Public Member Functions
virtual void | color_average (Fl_Color c, float i)
| The color_average() method averages the colors in the image with the FLTK color value c. More...
Fl_Image * | copy ()
virtual Fl_Image * | copy (int W, int H)
| The copy() method creates a copy of the specified image. More...
virtual void | desaturate ()
| The desaturate() method converts an image to grayscale. More...
void | draw (int X, int Y)
virtual void | draw (int X, int Y, int W, int H, int cx, int cy)
| Draws the image with a bounding box. More...
const char * | name ()
| Returns the filename of the shared image.
int | original ()
| Returns whether this is an original image. More...
int | refcount ()
| Returns the number of references of this shared image. More...
void | release ()
| Releases and possibly destroys (if refcount <= 0) a shared image. More...
void | reload ()
| Reloads the shared image from disk.
void | scale (int width, int height, int proportional=1, int can_expand=0)
| Sets the drawing size of the shared image. More...
virtual void | uncache ()
| If the image has been cached for display, delete the cache data. More...
Public Member Functions inherited from Fl_Image
Fl_Image * | copy ()
| The copy() method creates a copy of the specified image. More...
int | count () const
| The count() method returns the number of data values associated with the image. More...
int | d () const
| Returns the current image depth. More...
const char *const * | data () const
| Returns a pointer to the current image data array. More...
void | draw (int X, int Y)
| Draws the image. More...
int | fail ()
| Returns a value that is not 0 if there is currently no image available. More...
| Fl_Image (int W, int H, int D)
| The constructor creates an empty image with the specified width, height, and depth. More...
int | h () const
| Returns the current image height in pixels.
void | inactive ()
| The inactive() method calls color_average(FL_BACKGROUND_COLOR, 0.33f) to produce an image that appears grayed out. More...
virtual void | label (Fl_Menu_Item *m)
| The label() methods are an obsolete way to set the image attribute of a widget or menu item. More...
virtual void | label (Fl_Widget *w)
| The label() methods are an obsolete way to set the image attribute of a widget or menu item. More...
int | ld () const
| Returns the current line data size in bytes. More...
int | w () const
| Returns the current image width in pixels.
virtual | ~Fl_Image ()
| The destructor is a virtual method that frees all memory used by the image.

## Static Public Member Functions
static void | add_handler (Fl_Shared_Handler f)
| Adds a shared image handler, which is basically a test function for adding new formats.
static Fl_Shared_Image * | find (const char *name, int W=0, int H=0)
| Finds a shared image from its name and size specifications. More...
static Fl_Shared_Image * | get (const char *name, int W=0, int H=0)
| Find or load an image that can be shared by multiple widgets. More...
static Fl_Shared_Image * | get (Fl_RGB_Image *rgb, int own_it=1)
| Builds a shared image from a pre-existing Fl_RGB_Image. More...
static Fl_Shared_Image ** | images ()
| Returns the Fl_Shared_Image* array.
static int | num_images ()
| Returns the total number of shared images in the array.
static void | remove_handler (Fl_Shared_Handler f)
| Removes a shared image handler.
static void | scaling_algorithm (Fl_RGB_Scaling algorithm)
| Sets what algorithm is used when resizing a source image. More...
Static Public Member Functions inherited from Fl_Image
static Fl_RGB_Scaling | RGB_scaling ()
| Returns the currently used RGB image scaling method.
static void | RGB_scaling (Fl_RGB_Scaling)
| Sets the RGB image scaling method used for copy(int, int). More...

## Protected Member Functions
void | add ()
| Adds a shared image to the image cache. More...
| Fl_Shared_Image ()
| Creates an empty shared image. More...
| Fl_Shared_Image (const char *n, Fl_Image *img=0)
| Creates a shared image from its filename and its corresponding Fl_Image* img. More...
void | update ()
virtual | ~Fl_Shared_Image ()
| The destructor frees all memory and server resources that are used by the image. More...
Protected Member Functions inherited from Fl_Image
void | d (int D)
| Sets the current image depth.
void | data (const char *const *p, int c)
| Sets the current array pointer and count of pointers in the array.
void | draw_empty (int X, int Y)
| The protected method draw_empty() draws a box with an X in it. More...
void | h (int H)
| Sets the current image height in pixels.
void | ld (int LD)
| Sets the current line data size in bytes. More...
void | w (int W)
| Sets the current image width in pixels.

## Static Protected Member Functions
static int | compare (Fl_Shared_Image **i0, Fl_Shared_Image **i1)
| Compares two shared images. More...
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
int | alloc_image_
Fl_Image * | image_
const char * | name_
int | original_
int | refcount_

## Static Protected Attributes
static int | alloc_handlers_ = 0
static int | alloc_images_ = 0
static Fl_Shared_Handler * | handlers_ = 0
static Fl_Shared_Image ** | images_ = 0
static int | num_handlers_ = 0
static int | num_images_ = 0

## Friends
class | Fl_JPEG_Image
class | Fl_PNG_Image

## Additional Inherited Members
Static Public Attributes inherited from Fl_Image
static const int | ERR_FILE_ACCESS = -2
static const int | ERR_FORMAT = -3
static const int | ERR_NO_IMAGE = -1

## 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()

## 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.

## ◆ 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.

## ◆ ~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.

## 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().

## ◆ 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.

## ◆ 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

  0 | the images match
  <0 | Image `i0` is less than image `i1`
  >0 | Image `i0` is greater than image `i1`

## ◆ copy()

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.

## ◆ 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.

## ◆ draw()

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.

## ◆ 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.

## ◆ 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

  name | name of the image
  W,H | desired 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)

## ◆ 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] | rgb | an Fl_RGB_Image used to build a new shared image.
  [in] | own_it | 1 if the shared image should delete `rgb` when it is itself deleted, 0 otherwise

Version
  1.3.4

## ◆ 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

## ◆ 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.

## ◆ 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.

## ◆ 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,height | maximum width and height (in drawing units) to use when drawing the shared image
  proportional | if not null, keep the width and height of the shared image proportional to those of its original image
  can_expand | if 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

## ◆ 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

## ◆ 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.

The documentation for this class was generated from the following files:

- Fl_Shared_Image.H
- Fl_Shared_Image.cxx

FL_ALIGN_INSIDE
const Fl_Align FL_ALIGN_INSIDE
Draw the label inside of the widget.
Definition: Enumerations.H:843
Fl_Shared_Image::scale
void scale(int width, int height, int proportional=1, int can_expand=0)
Sets the drawing size of the shared image.
Definition: Fl_Shared_Image.cxx:429
Fl_Box
This widget simply draws its box, and possibly its label.
Definition: Fl_Box.H:34
Fl_Shared_Image::get
static Fl_Shared_Image * get(const char *name, int W=0, int H=0)
Find or load an image that can be shared by multiple widgets.
Definition: Fl_Shared_Image.cxx:541
FL_ALIGN_CENTER
const Fl_Align FL_ALIGN_CENTER
Align the label horizontally in the middle.
Definition: Enumerations.H:830
Fl_Shared_Image
This class supports caching, loading, scaling, and drawing of image files.
Definition: Fl_Shared_Image.H:50
FL_ALIGN_CLIP
const Fl_Align FL_ALIGN_CLIP
All parts of the label that are lager than the widget will not be drawn .
Definition: Enumerations.H:849
- © 1998-2016 by Bill Spitzak and others.