From 42b4db08016753de4045ebea99c78d8ff942c4c2 Mon Sep 17 00:00:00 2001
From: Greg Ercolano <erco@seriss.com>
Date: Sun, 24 May 2015 18:19:24 +0000
Subject: Moved docs for fail() from prototype in Fl_Image.H -> implementation
 in Fl_Image.cxx. Also added coded example to assist app programmers in usage.
 (Matt: feel free to modify the example code as needed)

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@10734 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
---
 src/Fl_Image.cxx | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

(limited to 'src')

diff --git a/src/Fl_Image.cxx b/src/Fl_Image.cxx
index 8afd232dc..a5d1bc750 100644
--- a/src/Fl_Image.cxx
+++ b/src/Fl_Image.cxx
@@ -140,6 +140,32 @@ void Fl_Image::label(Fl_Menu_Item* m) {
   m->label(_FL_IMAGE_LABEL, (const char*)this);
 }
 
+/**
+ Returns a value that is not 0 if there is currently no image
+ available.
+
+ Example use:
+ \code
+    [..]
+    Fl_Box box(X,Y,W,H);
+    Fl_JPEG_Image jpg("/tmp/foo.jpg");
+    switch ( jpg.fail() ) {
+        case Fl_Image::ERR_NO_IMAGE:
+        case Fl_Image::ERR_FILE_ACCESS:
+            fl_alert("/tmp/foo.jpg: %s", strerror(errno));    // shows actual os error to user
+            exit(1);
+        case Fl_Image::ERR_FORMAT:
+            fl_alert("/tmp/foo.jpg: couldn't decode image");
+            exit(1);
+    }
+    box.image(jpg);
+    [..]
+ \endcode
+
+ \return ERR_NO_IMAGE if no image was found
+ \return ERR_FILE_ACCESS if there was a file access related error (errno should be set)
+ \return ERR_FORMAT if image decoding failed.
+ */
 int Fl_Image::fail()
 {
     // if no image exists, ld_ may contain a simple error code
-- 
cgit v1.2.3