images: Document QImageReader::loopCount behaviour for infinite loops

The gif and mng reader will return -1 as QImageReader::loopCount()
for infinite images. Document that this -1 is clashing with the
error handling of this method.

The documentation was mixing the default and error cases. In some
cases "Otherwise -1" and "Otherwise 0" was used. Change this to
mention the default coming from QImageIOHandler in the "Otherwise"
clause and document the error case with -1.

Add a test case to check that loopCount() returns -1 for infinite
animations.

Reviewed-by: Andreas

3 files changed, 21 insertions, 8 deletions

diff --git a/src/gui/image/qimagereader.cpp b/src/gui/image/qimagereader.cpp
index 4fb07fb..c5aa28b 100644
--- a/src/gui/image/qimagereader.cpp
+++ b/src/gui/image/qimagereader.cpp
@@ -1214,10 +1214,12 @@ bool QImageReader::jumpToImage(int imageNumber)
 
 /*!
     For image formats that support animation, this function returns
-    the number of times the animation should loop. Otherwise, it
-    returns -1.
+    the number of times the animation should loop. In case of an
+    infinite animation or an error -1 is returned. To differentiate
+    an infinite animation from an error, canRead() should be called
+    before this function.
 
-    \sa supportsAnimation(), QImageIOHandler::loopCount()
+    \sa supportsAnimation(), QImageIOHandler::loopCount(), canRead()
 */
 int QImageReader::loopCount() const
 {
@@ -1231,9 +1233,9 @@ int QImageReader::loopCount() const
     the total number of images in the animation.
 
     Certain animation formats do not support this feature, in which
-    case 0 is returned.
+    case 0 is returned. In case of an error -1 is returned.
 
-    \sa supportsAnimation(), QImageIOHandler::imageCount()
+    \sa supportsAnimation(), QImageIOHandler::imageCount(), canRead()
 */
 int QImageReader::imageCount() const
 {
@@ -1247,7 +1249,9 @@ int QImageReader::imageCount() const
     the number of milliseconds to wait until displaying the next frame
     in the animation. Otherwise, 0 is returned.
 
-    \sa supportsAnimation(), QImageIOHandler::nextImageDelay()
+    In case of an error -1 is returned.
+
+    \sa supportsAnimation(), QImageIOHandler::nextImageDelay(), canRead()
 */
 int QImageReader::nextImageDelay() const
 {
@@ -1258,10 +1262,12 @@ int QImageReader::nextImageDelay() const
 
 /*!
     For image formats that support animation, this function returns
-    the sequence number of the current frame. Otherwise, -1 is
+    the sequence number of the current frame. Otherwise, 0 is
     returned.
 
-    \sa supportsAnimation(), QImageIOHandler::currentImageNumber()
+    In case of an error -1 is returned.
+
+    \sa supportsAnimation(), QImageIOHandler::currentImageNumber(), canRead()
 */
 int QImageReader::currentImageNumber() const
 {
diff --git a/tests/auto/qimagereader/images/endless-anim.gif b/tests/auto/qimagereader/images/endless-anim.gif
new file mode 100644
index 0000000..00df8da
--- /dev/null
+++ b/tests/auto/qimagereader/images/endless-anim.gif
diff --git a/tests/auto/qimagereader/tst_qimagereader.cpp b/tests/auto/qimagereader/tst_qimagereader.cpp
index 3f9d005..8cfaac5 100644
--- a/tests/auto/qimagereader/tst_qimagereader.cpp
+++ b/tests/auto/qimagereader/tst_qimagereader.cpp
@@ -726,6 +726,13 @@ void tst_QImageReader::gifHandlerBugs()
         QVERIFY(!im1.isNull());  QVERIFY(!im2.isNull());
         QCOMPARE(im1.convertToFormat(QImage::Format_ARGB32), im2.convertToFormat(QImage::Format_ARGB32));
     }
+
+    // Check the undocumented feature.
+    {
+        QImageReader io(prefix + "endless-anim.gif");
+        QVERIFY(io.canRead());
+        QCOMPARE(io.loopCount(), -1);
+    }
 }
 
 void tst_QImageReader::animatedGif()