describe wxMemory* streams

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

diff --git a/interface/wx/mstream.h b/interface/wx/mstream.h
index eec704124a2f14b2f50ef831358851be659a09ff..86dbd3775880d7516c465dea72e759d0dc0d0744 100644 (file)
--- a/interface/wx/mstream.h
+++ b/interface/wx/mstream.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        mstream.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        mstream.h

-// Purpose:     interface of wxMemoryOutputStream
+// Purpose:     interface of wxMemoryOutputStream, wxMemoryInputStream

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -9,7 +9,26 @@
 /**
     @class wxMemoryOutputStream
 
 /**
     @class wxMemoryOutputStream
 

-    @todo describe me.
+    This class allows to use all methods taking a wxOutputStream reference to write
+    to in-memory data.
+
+    Example:
+    @code
+        wxMemoryOutputStream stream;
+        if (!my_wxImage.SaveFile(stream))
+            return;
+
+        // now we can access the saved image bytes:
+        wxStreamBuffer* theBuffer = stream.GetOutputStreamBuffer();
+        unsigned char byte;
+        if (theBuffer->Read(byte, 1) != 1)
+            return;
+
+        // ... do something with 'byte'...
+
+        // remember that ~wxMemoryOutputStream will destroy the internal
+        // buffer since we didn't provide our own when constructing it
+    @endcode

 
     @library{wxbase}
     @category{streams}
 
     @library{wxbase}
     @category{streams}


@@ -24,12 +43,15 @@ public:
         grow if required.
 
         @warning
         grow if required.
 
         @warning

-        If the buffer is created, it will be destroyed at the destruction of the stream.
+        If the buffer is created by wxMemoryOutputStream, it will be destroyed
+        at the destruction of the stream.

     */
     wxMemoryOutputStream(void* data = NULL, size_t length = 0);
 
     /**
         Destructor.
     */
     wxMemoryOutputStream(void* data = NULL, size_t length = 0);
 
     /**
         Destructor.

+
+        If the buffer wasn't provided by the user, it will be deleted here.

     */
     virtual ~wxMemoryOutputStream();
 
     */
     virtual ~wxMemoryOutputStream();
 


@@ -41,7 +63,7 @@ public:
 
     /**
         Returns the pointer to the stream object used as an internal buffer
 
     /**
         Returns the pointer to the stream object used as an internal buffer

-        for that stream.
+        for this stream.

     */
     wxStreamBuffer* GetOutputStreamBuffer() const;
 };
     */
     wxStreamBuffer* GetOutputStreamBuffer() const;
 };


@@ -51,7 +73,23 @@ public:
 /**
     @class wxMemoryInputStream
 
 /**
     @class wxMemoryInputStream
 

-    @todo describe me.
+    This class allows to use all methods taking a wxInputStream reference to read
+    in-memory data.
+
+    Example:
+    @code
+        // we've got a block of memory containing a BMP image and we want
+        // to use wxImage to load it:
+        wxMemoryInputStream stream(my_memory_block, size);
+
+        wxImage theBitmap;
+        if (!theBitmap.LoadFile(stream, wxBITMAP_TYPE_BMP))
+            return;
+
+        // we can now safely delete the original memory buffer as the data
+        // has been decoded by wxImage:
+        delete [] my_memory_block;
+    @endcode

 
     @library{wxbase}
     @category{streams}
 
     @library{wxbase}
     @category{streams}


@@ -86,7 +124,7 @@ public:
                         wxFileOffset len = wxInvalidOffset);
 
     /**
                         wxFileOffset len = wxInvalidOffset);
 
     /**

-        Destructor.
+        Destructor. Does NOT free the buffer provided in the ctor.

     */
     virtual ~wxMemoryInputStream();
 
     */
     virtual ~wxMemoryInputStream();