Fl_Shared_Image documentation enhancements and clarifications.

Minor code changes (e.g. renaming of variables) included, but no functional
changes.


git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3-porting@12003 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 20 insertions, 10 deletions

diff --git a/FL/Fl_Shared_Image.H b/FL/Fl_Shared_Image.H
index bbc5ff5a8..5047fa8b9 100644
--- a/FL/Fl_Shared_Image.H
+++ b/FL/Fl_Shared_Image.H
@@ -3,7 +3,7 @@
 //
 // Shared image header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2015 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -29,16 +29,26 @@
 typedef Fl_Image *(*Fl_Shared_Handler)(const char *name, uchar *header,
                                        int headerlen);
 
-// Shared images class. 
+// Shared images class.
 /**
-  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.
+  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 Fl_Shared_Image::get()
+  \see Fl_Shared_Image::find()
+  \see Fl_Shared_Image::release()
 */
 class FL_EXPORT Fl_Shared_Image : public Fl_Image {
-  
+
   friend class Fl_JPEG_Image;
   friend class Fl_PNG_Image;
   friend class Fl_Graphics_Driver;
@@ -87,8 +97,8 @@ public:
   void scale(int width, int height, int proportional = 1, int can_expand = 0);
   virtual void uncache();
 
-  static Fl_Shared_Image *find(const char *n, int W = 0, int H = 0);
-  static Fl_Shared_Image *get(const char *n, int W = 0, int H = 0);
+  static Fl_Shared_Image *find(const char *name, int W = 0, int H = 0);
+  static Fl_Shared_Image *get(const char *name, int W = 0, int H = 0);
   static Fl_Shared_Image *get(Fl_RGB_Image *rgb, int own_it = 1);
   static Fl_Shared_Image **images();
   static int		num_images();