Make storing non-trivial data in wxThreadSpecificInfo possible.

[wxWidgets.git] / interface / wx / wfstream.h

diff --git a/interface/wx/wfstream.h b/interface/wx/wfstream.h
index 46939778e53f74996e3e9d8267754337ffc075b6..27c1a3f40648d21a9b1208da8927ce99ab195e50 100644 (file)
--- a/interface/wx/wfstream.h
+++ b/interface/wx/wfstream.h
@@ -2,15 +2,14 @@
 // Name:        wfstream.h
 // Purpose:     interface of wxTempFileOutputStream
 // Author:      wxWidgets team
 // Name:        wfstream.h
 // Purpose:     interface of wxTempFileOutputStream
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxTempFileOutputStream
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxTempFileOutputStream
 

-    wxTempFileOutputStream is an output stream based on wxTempFile. It
-    provides a relatively safe way to replace the contents of the
+    wxTempFileOutputStream is an output stream based on wxTempFile.
+    It provides a relatively safe way to replace the contents of the

     existing file.
 
     @library{wxbase}
     existing file.
 
     @library{wxbase}


@@ -23,28 +22,31 @@ class wxTempFileOutputStream : public wxOutputStream
 public:
     /**
         Associates wxTempFileOutputStream with the file to be replaced and opens it.
 public:
     /**
         Associates wxTempFileOutputStream with the file to be replaced and opens it.

-        You should use
-        wxStreamBase::IsOk to verify if the constructor succeeded.
-        Call Commit() or wxOutputStream::Close to
-        replace the old file and close this one. Calling Discard()
-        (or allowing the destructor to do it) will discard the changes.
+
+        @warning
+        You should use wxStreamBase::IsOk() to verify if the constructor succeeded.
+
+        Call Commit() or wxOutputStream::Close() to replace the old file and close
+        this one. Calling Discard() (or allowing the destructor to do it) will
+        discard the changes.

     */
     wxTempFileOutputStream(const wxString& fileName);
 
     /**
         Validate changes: deletes the old file of the given name and renames the new
     */
     wxTempFileOutputStream(const wxString& fileName);
 
     /**
         Validate changes: deletes the old file of the given name and renames the new

-        file to the old name. Returns @true if both actions succeeded. If @false is
-        returned it may unfortunately mean two quite different things: either that
+        file to the old name. Returns @true if both actions succeeded.
+
+        If @false is returned it may unfortunately mean two quite different things: either that

         either the old file couldn't be deleted or that the new file couldn't be renamed
         to the old name.
     */
         either the old file couldn't be deleted or that the new file couldn't be renamed
         to the old name.
     */

-    bool Commit();
+    virtual bool Commit();

 
     /**
         Discard changes: the old file contents are not changed, the temporary file is
         deleted.
     */
 
     /**
         Discard changes: the old file contents are not changed, the temporary file is
         deleted.
     */

-    void Discard();
+    virtual void Discard();

 };
 
 
 };
 
 


@@ -52,42 +54,55 @@ public:
 /**
     @class wxFFileOutputStream
 
 /**
     @class wxFFileOutputStream
 

-    This class represents data written to a file. There are actually
-    two such groups of classes: this one is based on wxFFile
-    whereas wxFileInputStream is based in
-    the wxFile class.
+    This class represents data written to a file.
+    There are actually two such groups of classes: this one is based on wxFFile
+    whereas wxFileOutputStream is based in the wxFile class.

 
 

-    Note that wxOutputStream::SeekO
-    can seek beyond the end of the stream (file) and will thus not return
-    @e wxInvalidOffset for that.
+    Note that wxOutputStream::SeekO() can seek beyond the end of the stream
+    (file) and will thus not return ::wxInvalidOffset for that.

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

-    @see wxBufferedOutputStream, wxFFileInputStream, wxFileInputStream
+    @see wxBufferedOutputStream, wxFFileInputStream, wxFileOutputStream, wxFileInputStream

 */
 class wxFFileOutputStream : public wxOutputStream
 {
 public:
 */
 class wxFFileOutputStream : public wxOutputStream
 {
 public:

-    //@{

     /**
     /**

-        Initializes a file stream in write-only mode using the file descriptor @e fp.
+        Open the given file @a filename with mode @a mode.
+
+        @warning
+        You should use wxStreamBase::IsOk() to verify if the constructor succeeded.

     */
     wxFFileOutputStream(const wxString& filename,
                         const wxString& mode = "wb");
     */
     wxFFileOutputStream(const wxString& filename,
                         const wxString& mode = "wb");

+
+    /**
+        Initializes a file stream in write-only mode using the file I/O object file.
+    */

     wxFFileOutputStream(wxFFile& file);
     wxFFileOutputStream(wxFFile& file);

+
+    /**
+        Initializes a file stream in write-only mode using the file descriptor fp.
+    */

     wxFFileOutputStream(FILE* fp);
     wxFFileOutputStream(FILE* fp);

-    //@}

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

-    ~wxFFileOutputStream();
+    virtual ~wxFFileOutputStream();

 
     /**
         Returns @true if the stream is initialized and ready.
     */
     bool IsOk() const;
 
     /**
         Returns @true if the stream is initialized and ready.
     */
     bool IsOk() const;

+
+    /**
+        Returns the underlying file object.
+        @since 2.9.5
+    */
+    wxFFile* GetFile() const;

 };
 
 
 };
 
 


@@ -95,41 +110,54 @@ public:
 /**
     @class wxFileOutputStream
 
 /**
     @class wxFileOutputStream
 

-    This class represents data written to a file. There are actually
-    two such groups of classes: this one is based on wxFile
-    whereas wxFFileInputStream is based in
-    the wxFFile class.
+    This class represents data written to a file.
+    There are actually two such groups of classes: this one is based on wxFile
+    whereas wxFFileOutputStream is based in the wxFFile class.

 
 

-    Note that wxOutputStream::SeekO
-    can seek beyond the end of the stream (file) and will thus not return
-    @e wxInvalidOffset for that.
+    Note that wxOutputStream::SeekO() can seek beyond the end of the stream
+    (file) and will thus not return ::wxInvalidOffset for that.

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

-    @see wxBufferedOutputStream, wxFileInputStream, wxFFileInputStream
+    @see wxBufferedOutputStream, wxFileInputStream, wxFFileOutputStream, wxFFileInputStream

 */
 class wxFileOutputStream : public wxOutputStream
 {
 public:
 */
 class wxFileOutputStream : public wxOutputStream
 {
 public:

-    //@{

     /**
     /**

-        Initializes a file stream in write-only mode using the file descriptor @e fd.
+        Creates a new file with @a ofileName name and initializes the stream in write-only mode.
+
+        @warning
+        You should use wxStreamBase::IsOk() to verify if the constructor succeeded.

     */
     wxFileOutputStream(const wxString& ofileName);
     */
     wxFileOutputStream(const wxString& ofileName);

+
+    /**
+        Initializes a file stream in write-only mode using the file I/O object file.
+    */

     wxFileOutputStream(wxFile& file);
     wxFileOutputStream(wxFile& file);

+
+    /**
+        Initializes a file stream in write-only mode using the file descriptor @e fd.
+    */

     wxFileOutputStream(int fd);
     wxFileOutputStream(int fd);

-    //@}

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

-    ~wxFileOutputStream();
+    virtual ~wxFileOutputStream();

 
     /**
         Returns @true if the stream is initialized and ready.
     */
     bool IsOk() const;
 
     /**
         Returns @true if the stream is initialized and ready.
     */
     bool IsOk() const;

+
+    /**
+        Returns the underlying file object.
+        @since 2.9.5
+    */
+    wxFile* GetFile() const;

 };
 
 
 };
 
 


@@ -137,14 +165,12 @@ public:
 /**
     @class wxFileInputStream
 
 /**
     @class wxFileInputStream
 

-    This class represents data read in from a file. There are actually
-    two such groups of classes: this one is based on wxFile
-    whereas wxFFileInputStream is based in
-    the wxFFile class.
+    This class represents data read in from a file.
+    There are actually two such groups of classes: this one is based on wxFile
+    whereas wxFFileInputStream is based in the wxFFile class.

 
 

-    Note that wxInputStream::SeekI
-    can seek beyond the end of the stream (file) and will thus not return
-    @e wxInvalidOffset for that.
+    Note that wxInputStream::SeekI() can seek beyond the end of the stream (file)
+    and will thus not return ::wxInvalidOffset for that.

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


@@ -154,24 +180,39 @@ public:
 class wxFileInputStream : public wxInputStream
 {
 public:
 class wxFileInputStream : public wxInputStream
 {
 public:

-    //@{

     /**
     /**

-        Initializes a file stream in read-only mode using the specified file descriptor.
+        Opens the specified file using its @a ifileName name in read-only mode.
+
+        @warning
+        You should use wxStreamBase::IsOk() to verify if the constructor succeeded.

     */
     wxFileInputStream(const wxString& ifileName);
     */
     wxFileInputStream(const wxString& ifileName);

+
+    /**
+        Initializes a file stream in read-only mode using the file I/O object file.
+    */

     wxFileInputStream(wxFile& file);
     wxFileInputStream(wxFile& file);

+
+    /**
+        Initializes a file stream in read-only mode using the specified file descriptor.
+    */

     wxFileInputStream(int fd);
     wxFileInputStream(int fd);

-    //@}

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

-    ~wxFileInputStream();
+    virtual ~wxFileInputStream();

 
     /**
         Returns @true if the stream is initialized and ready.
     */
     bool IsOk() const;
 
     /**
         Returns @true if the stream is initialized and ready.
     */
     bool IsOk() const;

+
+    /**
+        Returns the underlying file object.
+        @since 2.9.5
+    */
+    wxFile* GetFile() const;

 };
 
 
 };
 
 


@@ -179,14 +220,12 @@ public:
 /**
     @class wxFFileInputStream
 
 /**
     @class wxFFileInputStream
 

-    This class represents data read in from a file. There are actually
-    two such groups of classes: this one is based on wxFFile
-    whereas wxFileInputStream is based in
-    the wxFile class.
+    This class represents data read in from a file.
+    There are actually two such groups of classes: this one is based on wxFFile
+    whereas wxFileInputStream is based in the wxFile class.

 
 

-    Note that wxInputStream::SeekI
-    can seek beyond the end of the stream (file) and will thus not return
-    @e wxInvalidOffset for that.
+    Note that wxInputStream::SeekI() can seek beyond the end of the stream (file)
+    and will thus not return ::wxInvalidOffset for that.

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


@@ -196,26 +235,40 @@ public:
 class wxFFileInputStream : public wxInputStream
 {
 public:
 class wxFFileInputStream : public wxInputStream
 {
 public:

-    //@{

     /**
     /**

-        Initializes a file stream in read-only mode using the specified file pointer @e
-        fp.
+        Opens the specified file using its @a filename name using the specified @a mode.
+
+        @warning
+        You should use wxStreamBase::IsOk() to verify if the constructor succeeded.

     */
     wxFFileInputStream(const wxString& filename,
                        const wxString& mode = "rb");
     */
     wxFFileInputStream(const wxString& filename,
                        const wxString& mode = "rb");

+
+    /**
+        Initializes a file stream in read-only mode using the file I/O object file.
+    */

     wxFFileInputStream(wxFFile& file);
     wxFFileInputStream(wxFFile& file);

+
+    /**
+        Initializes a file stream in read-only mode using the specified file pointer @a fp.
+    */

     wxFFileInputStream(FILE* fp);
     wxFFileInputStream(FILE* fp);

-    //@}

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

-    ~wxFFileInputStream();
+    virtual ~wxFFileInputStream();

 
     /**
         Returns @true if the stream is initialized and ready.
     */
     bool IsOk() const;
 
     /**
         Returns @true if the stream is initialized and ready.
     */
     bool IsOk() const;

+
+    /**
+        Returns the underlying file object.
+        @since 2.9.5
+    */
+    wxFFile* GetFile() const;

 };
 
 
 };
 
 


@@ -223,20 +276,34 @@ public:
 /**
     @class wxFFileStream
 
 /**
     @class wxFFileStream
 

+    This stream allows to both read from and write to a file using buffered
+    STDIO functions.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{streams}

 
 

-    @see wxStreamBuffer
+    @see wxFFileInputStream, wxFFileOutputStream, wxFileStream

 */
 */

-class wxFFileStream : public wxFFileOutputStream
+class wxFFileStream : public wxFFileInputStream,
+                      public wxFFileOutputStream

 {
 public:
     /**
 {
 public:
     /**

-        Initializes a new file stream in read-write mode using the specified
-        @e iofilename name.
+        Initializes a new file stream in the given @a mode using the specified
+        @a iofileName name.
+
+        @warning
+        You should use wxStreamBase::IsOk() to verify if the constructor succeeded.

     */
     wxFFileStream(const wxString& iofileName, const wxString& mode = "w+b");
     */
     wxFFileStream(const wxString& iofileName, const wxString& mode = "w+b");

+
+    /**
+        Returns @true if the stream is initialized and ready.
+
+        This method returns @true if the stream can be both read from and
+        written to.
+    */
+    bool IsOk() const;

 };
 
 
 };
 
 


@@ -244,19 +311,34 @@ public:
 /**
     @class wxFileStream
 
 /**
     @class wxFileStream
 

+    This class represents data that can be both read from and written to a file.
+    There are actually two such groups of classes: this one is based on wxFile
+    whereas wxFFileStream is based in the wxFFile class.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{streams}

 
 

-    @see wxStreamBuffer
+    @see wxFileInputStream, wxFileOutputStream, wxFFileStream

 */
 */

-class wxFileStream : public wxFileOutputStream
+class wxFileStream : public wxFileOutputStream,
+                     public wxFileInputStream

 {
 public:
     /**
         Initializes a new file stream in read-write mode using the specified
 {
 public:
     /**
         Initializes a new file stream in read-write mode using the specified

-        @e iofilename name.
+        @a iofileName name.
+
+        @warning
+        You should use IsOk() to verify if the constructor succeeded.

     */
     wxFileStream(const wxString& iofileName);
     */
     wxFileStream(const wxString& iofileName);

+
+    /**
+        Returns @true if the stream is initialized and ready.
+
+        This method returns @true if the stream can be both read from and
+        written to.
+    */
+    bool IsOk() const;

 };
 
 };