document that CanRead() and GetImageCount() functions of wxImageHandlers do NOT modify the current stream position and that they require seekable streams; rename current GetImageCount() functions to DoGetImageCount() and put save-and-restore stream position logic in GetImageCount(); add comments in the various DoCanRead() and in DoGetImageCount() where the stream position is modified; remove unneeded SeekI(0) calls from DoCanRead() and DoGetImageCount() functions: they didn't allow to load images from non-seekable streams; implement forward-seeking in wxInputStream::SeekI() also for non-seekable streams

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@60852 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/image.h

@@ -83,6 +83,26 @@ public:
     */
     virtual ~wxImageHandler();
 
+    /**
+        Returns @true if this handler supports the image format contained in the
+        given stream.
+        
+        This function doesn't modify the current stream position (because it
+        restores the original position before returning; this however requires the
+        stream to be seekable; see wxStreamBase::IsSeekable).
+    */
+    bool CanRead( wxInputStream& stream );    
+
+    /**
+        Returns @true if this handler supports the image format contained in the
+        file with the given name.
+        
+        This function doesn't modify the current stream position (because it
+        restores the original position before returning; this however requires the
+        stream to be seekable; see wxStreamBase::IsSeekable).
+    */
+    bool CanRead( const wxString& filename );
+    
     /**
         Gets the preferred file extension associated with this handler.
 
@@ -106,7 +126,9 @@ public:
 
         @param stream
             Opened input stream for reading image data.
-            Currently, the stream must support seeking.
+            This function doesn't modify the current stream position (because it
+            restores the original position before returning; this however requires the
+            stream to be seekable; see wxStreamBase::IsSeekable).
 
         @return Number of available images. For most image handlers, this is 1
                 (exceptions are TIFF and ICO formats as well as animated GIFs
@@ -1574,9 +1596,20 @@ public:
     
     
     /**
-        Returns @true if the current image handlers can read this file
+        Returns @true if at least one of the available image handlers can read 
+        the file with the given name.
+        
+        See wxImageHandler::CanRead for more info.
     */
     static bool CanRead(const wxString& filename);
+    
+    /**
+        Returns @true if at least one of the available image handlers can read 
+        the data in the given stream.
+        
+        See wxImageHandler::CanRead for more info.
+    */
+    static bool CanRead(wxInputStream& stream);
 
     //@{
     /**
@@ -1586,8 +1619,10 @@ public:
 
         For the overload taking the parameter @a filename, that's the name
         of the file to query.
-        For the overload taking the parameter @a stream, that's the ppened input
-        stream with image data. Currently, the stream must support seeking.
+        For the overload taking the parameter @a stream, that's the opened input
+        stream with image data.
+        
+        See wxImageHandler::GetImageCount() for more info.
 
         The parameter @a type may be one of the following values:
         @li wxBITMAP_TYPE_BMP: Load a Windows bitmap file.

interface/wx/stream.h

@@ -76,7 +76,7 @@ public:
     virtual bool IsOk() const;
 
     /**
-        Returns @true if the streams supports seeking to arbitrary offsets.
+        Returns @true if the stream supports seeking to arbitrary offsets.
     */
     virtual bool IsSeekable() const;
 
@@ -613,6 +613,11 @@ public:
     /**
         Changes the stream current position.
 
+        This operation in general is possible only for seekable streams 
+        (see wxStreamBase::IsSeekable()); non-seekable streams support only
+        seeking positive amounts in mode @c wxFromCurrent (this is implemented
+        by reading data and simply discarding it).
+
         @param pos
             Offset to seek to.
         @param mode
@@ -623,7 +628,9 @@ public:
     virtual wxFileOffset SeekI(wxFileOffset pos, wxSeekMode mode = wxFromStart);
 
     /**
-        Returns the current stream position.
+        Returns the current stream position or ::wxInvalidOffset if it's not
+        available (e.g. socket streams do not have a size nor a current stream
+        position).
     */
     virtual wxFileOffset TellI() const;