final w*h interface header reviews

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

diff --git a/interface/wx/filefn.h b/interface/wx/filefn.h
index aa1eea43db5bb9b1207debfb1252d4edc431f3af..04b82d18ac4930db57f335cca38d1c576c72a39c 100644 (file)
--- a/interface/wx/filefn.h
+++ b/interface/wx/filefn.h
@@ -101,6 +101,12 @@ public:
 /** @ingroup group_funcmacro_file */
 //@{
 
 /** @ingroup group_funcmacro_file */
 //@{
 

+/**
+    A special return value of many wxWidgets classes to indicate that
+    an invalid offset was given.
+*/
+const int wxInvalidOffset = -1;
+

 /**
     Under Unix this macro changes the current process umask to the given value,
     unless it is equal to -1 in which case nothing is done, and restores it to
 /**
     Under Unix this macro changes the current process umask to the given value,
     unless it is equal to -1 in which case nothing is done, and restores it to

diff --git a/interface/wx/zipstrm.h b/interface/wx/zipstrm.h
index 5e6561f2e53c019cf429b62d60f1d05e32ce1b89..357b113320c2eb8727331ca84b1d7118de8f5ba8 100644 (file)
--- a/interface/wx/zipstrm.h
+++ b/interface/wx/zipstrm.h
@@ -345,69 +345,73 @@ public:
 };
 
 
 };
 
 

-
----
-
-
-

 /**
     @class wxZipInputStream
 
     Input stream for reading zip files.
 
 /**
     @class wxZipInputStream
 
     Input stream for reading zip files.
 

-    wxZipInputStream::GetNextEntry returns an
-     wxZipEntry object containing the meta-data
-    for the next entry in the zip (and gives away ownership). Reading from
-    the wxZipInputStream then returns the entry's data. Eof() becomes @true
-    after an attempt has been made to read past the end of the entry's data.
+    wxZipInputStream::GetNextEntry() returns a wxZipEntry object containing the
+    meta-data for the next entry in the zip (and gives away ownership).
+    Reading from the wxZipInputStream then returns the entry's data.
+    Eof() becomes @true after an attempt has been made to read past the end of
+    the entry's data.

     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
 
     Note that in general zip entries are not seekable, and
     When there are no more entries, GetNextEntry() returns @NULL and sets Eof().
 
     Note that in general zip entries are not seekable, and

-    wxZipInputStream::SeekI() always returns wxInvalidOffset.
+    wxZipInputStream::SeekI() always returns ::wxInvalidOffset.

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

-    @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry,
-    wxZipOutputStream
+    @see @ref overview_archive, wxZipEntry, wxZipOutputStream

 */
 class wxZipInputStream : public wxArchiveInputStream
 {
 public:
 */
 class wxZipInputStream : public wxArchiveInputStream
 {
 public:

+

     //@{
     /**
     //@{
     /**

-        Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
-        When this constructor is used, an emulation of seeking is
-        switched on for compatibility with previous versions. Note however,
-        that it is deprecated.
+        Constructor. In a Unicode build the second parameter @a conv is used to
+        translate the filename and comment fields into Unicode.
+        It has no effect on the stream's data.
+        If the parent stream is passed as a pointer then the new filter stream
+        takes ownership of it. If it is passed by reference then it does not.

     */
     wxZipInputStream(wxInputStream& stream,
                      wxMBConv& conv = wxConvLocal);
     wxZipInputStream(wxInputStream* stream,
                      wxMBConv& conv = wxConvLocal);
     */
     wxZipInputStream(wxInputStream& stream,
                      wxMBConv& conv = wxConvLocal);
     wxZipInputStream(wxInputStream* stream,
                      wxMBConv& conv = wxConvLocal);

+    //@}
+
+    /**
+        @deprecated
+        Compatibility constructor (requires WXWIN_COMPATIBILITY_2_6).
+        When this constructor is used, an emulation of seeking is
+        switched on for compatibility with previous versions. Note however,
+        that it is deprecated.
+    */

     wxZipInputStream(const wxString& archive,
                      const wxString& file);
     wxZipInputStream(const wxString& archive,
                      const wxString& file);

-    //@}

 
     /**
 
     /**

-        Closes the current entry. On a non-seekable stream reads to the end of
-        the current entry first.
+        Closes the current entry.
+        On a non-seekable stream reads to the end of the current entry first.

     */
     bool CloseEntry();
 
     /**
         Returns the zip comment.
     */
     bool CloseEntry();
 
     /**
         Returns the zip comment.

+

         This is stored at the end of the zip, therefore when reading a zip
         This is stored at the end of the zip, therefore when reading a zip

-        from a non-seekable stream, it returns the empty string until the
-        end of the zip has been reached, i.e. when GetNextEntry() returns
-        @NULL.
+        from a non-seekable stream, it returns the empty string until the end
+        of the zip has been reached, i.e. when GetNextEntry() returns @NULL.

     */
     wxString GetComment();
 
     /**
         Closes the current entry if one is open, then reads the meta-data for
     */
     wxString GetComment();
 
     /**
         Closes the current entry if one is open, then reads the meta-data for

-        the next entry and returns it in a wxZipEntry
-        object, giving away ownership. The stream is then open and can be read.
+        the next entry and returns it in a wxZipEntry object, giving away ownership.
+        The stream is then open and can be read.

     */
     wxZipEntry* GetNextEntry();
 
     */
     wxZipEntry* GetNextEntry();
 


@@ -421,8 +425,11 @@ public:
     /**
         Closes the current entry if one is open, then opens the entry specified
         by the @a entry object.
     /**
         Closes the current entry if one is open, then opens the entry specified
         by the @a entry object.

+

         @a entry should be from the same zip file, and the zip should
         be on a seekable stream.
         @a entry should be from the same zip file, and the zip should
         be on a seekable stream.

+
+        @see overview_archive_byname

     */
     bool OpenEntry(wxZipEntry& entry);
 };
     */
     bool OpenEntry(wxZipEntry& entry);
 };


@@ -432,14 +439,15 @@ public:
 /**
     @class wxZipClassFactory
 
 /**
     @class wxZipClassFactory
 

-    Class factory for the zip archive format. See the base class
-    for details.
+    Class factory for the zip archive format.
+    See the base class for details.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{archive}

 
 

-    @see @ref overview_wxarc "Archive formats such as zip", @ref
-    overview_wxarcgeneric "Generic archive programming", wxZipEntry, wxZipInputStream, wxZipOutputStream
+    @see @ref overview_archive,
+         @ref overview_archive_generic,
+         wxZipEntry, wxZipInputStream, wxZipOutputStream

 */
 class wxZipClassFactory : public wxArchiveClassFactory
 {
 */
 class wxZipClassFactory : public wxArchiveClassFactory
 {


@@ -454,30 +462,32 @@ public:
 
     Output stream for writing zip files.
 
 
     Output stream for writing zip files.
 

-    wxZipOutputStream::PutNextEntry is used to create
-    a new entry in the output zip, then the entry's data is written to the
-    wxZipOutputStream.  Another call to PutNextEntry() closes the current
+    wxZipOutputStream::PutNextEntry() is used to create a new entry in the
+    output zip, then the entry's data is written to the wxZipOutputStream.
+    Another call to wxZipOutputStream::PutNextEntry() closes the current

     entry and begins the next.
 
     @library{wxbase}
     @category{streams}
 
     entry and begins the next.
 
     @library{wxbase}
     @category{streams}
 

-    @see @ref overview_wxarc "Archive formats such as zip", wxZipEntry,
-    wxZipInputStream
+    @see @ref overview_archive, wxZipEntry, wxZipInputStream

 */
 class wxZipOutputStream : public wxArchiveOutputStream
 {
 public:
     //@{
     /**
 */
 class wxZipOutputStream : public wxArchiveOutputStream
 {
 public:
     //@{
     /**

-        Constructor. @c level is the compression level to use.
+        Constructor.
+
+        @a level is the compression level to use.

         It can be a value between 0 and 9 or -1 to use the default value
         which currently is equivalent to 6.
         It can be a value between 0 and 9 or -1 to use the default value
         which currently is equivalent to 6.

+

         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.

-        In a Unicode build the third parameter @c conv is used to translate
-        the filename and comment fields to an 8-bit encoding. It has no effect on the
-        stream's data.
+        In a Unicode build the third parameter @a conv is used to translate
+        the filename and comment fields to an 8-bit encoding.
+        It has no effect on the stream's data.

     */
     wxZipOutputStream(wxOutputStream& stream, int level = -1,
                       wxMBConv& conv = wxConvLocal);
     */
     wxZipOutputStream(wxOutputStream& stream, int level = -1,
                       wxMBConv& conv = wxConvLocal);


@@ -486,8 +496,8 @@ public:
     //@}
 
     /**
     //@}
 
     /**

-        The destructor calls Close() to finish
-        writing the zip if it has not been called already.
+        The destructor calls Close() to finish writing the zip if it has
+        not been called already.

     */
     ~wxZipOutputStream();
 
     */
     ~wxZipOutputStream();
 


@@ -498,10 +508,9 @@ public:
     bool Close();
 
     /**
     bool Close();
 
     /**

-        Close the current entry. It is called implicitly whenever another new
-        entry is created with CopyEntry()
-        or PutNextEntry(), or
-        when the zip is closed.
+        Close the current entry.
+        It is called implicitly whenever another new entry is created with CopyEntry()
+        or PutNextEntry(), or when the zip is closed.

     */
     bool CloseEntry();
 
     */
     bool CloseEntry();
 


@@ -512,51 +521,59 @@ public:
     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 
     /**
     bool CopyArchiveMetaData(wxZipInputStream& inputStream);
 
     /**

-        Takes ownership of @c entry and uses it to create a new entry
-        in the zip. @c entry is then opened in @c inputStream and its contents
+        Takes ownership of @a entry and uses it to create a new entry
+        in the zip. @a entry is then opened in @a inputStream and its contents

         copied to this stream.
         copied to this stream.

+

         CopyEntry() is much more efficient than transferring the data using
         Read() and Write() since it will copy them without decompressing and
         recompressing them.
         CopyEntry() is much more efficient than transferring the data using
         Read() and Write() since it will copy them without decompressing and
         recompressing them.

-        For zips on seekable streams, @c entry must be from the same zip file
-        as @c stream. For non-seekable streams, @c entry must also be the
-        last thing read from @c inputStream.
+
+        For zips on seekable streams, @a entry must be from the same zip file
+        as @a inputStream. For non-seekable streams, @a entry must also be the
+        last thing read from @a inputStream.

     */
     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 
     //@{
     /**
         Set the compression level that will be used the next time an entry is
     */
     bool CopyEntry(wxZipEntry* entry, wxZipInputStream& inputStream);
 
     //@{
     /**
         Set the compression level that will be used the next time an entry is

-        created. It can be a value between 0 and 9 or -1 to use the default value
+        created.
+
+        It can be a value between 0 and 9 or -1 to use the default value

         which currently is equivalent to 6.
     */
         which currently is equivalent to 6.
     */

-    int GetLevel();
-    const void SetLevel(int level);
+    int GetLevel() const;
+    void SetLevel(int level);

     //@}
 
     /**
     //@}
 
     /**

-        )
-        Create a new directory entry
-        (see wxArchiveEntry::IsDir)
-        with the given name and timestamp.
-        PutNextEntry() can
-        also be used to create directory entries, by supplying a name with
-        a trailing path separator.
+        Create a new directory entry (see wxArchiveEntry::IsDir) with the given
+        name and timestamp.
+
+        PutNextEntry() can also be used to create directory entries, by supplying
+        a name with a trailing path separator.

     */
     */

-    bool PutNextDirEntry(const wxString& name);
+    bool PutNextDirEntry(const wxString& name,
+                         const wxDateTime& dt = wxDateTime::Now());

 
     //@{
     /**
 
     //@{
     /**

-        , @b off_t@e size = wxInvalidOffset)
-        Create a new entry with the given name, timestamp and size.
+        Takes ownership of @a entry and uses it to create a new entry in the zip.

     */
     bool PutNextEntry(wxZipEntry* entry);
     */
     bool PutNextEntry(wxZipEntry* entry);

-    bool PutNextEntry(const wxString& name);
+
+    /**
+        Create a new entry with the given name, timestamp and size.
+    */
+    bool PutNextEntry(const wxString& name,
+                      const wxDateTime& dt = wxDateTime::Now(),
+                      off_t size = wxInvalidOffset);

     //@}
 
     /**
     //@}
 
     /**

-        Sets a comment for the zip as a whole. It is written at the end of the
-        zip.
+        Sets a comment for the zip as a whole.
+        It is written at the end of the zip.

     */
     void SetComment(const wxString& comment);
 };
     */
     void SetComment(const wxString& comment);
 };

diff --git a/interface/wx/zstream.h b/interface/wx/zstream.h
index f3b2cf144d1ba07e66541916d4c7533f9d2f394e..db994b47b6b80343f615a1b182819da5ac906c29 100644 (file)
--- a/interface/wx/zstream.h
+++ b/interface/wx/zstream.h
@@ -6,16 +6,35 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+
+/// Compression level
+enum wxZlibCompressionLevels {
+    wxZ_DEFAULT_COMPRESSION = -1,
+    wxZ_NO_COMPRESSION = 0,
+    wxZ_BEST_SPEED = 1,
+    wxZ_BEST_COMPRESSION = 9
+};
+
+/// Flags
+enum wxZLibFlags {
+    wxZLIB_NO_HEADER = 0,    //!< raw deflate stream, no header or checksum
+    wxZLIB_ZLIB = 1,         //!< zlib header and checksum
+    wxZLIB_GZIP = 2,         //!< gzip header and checksum, requires zlib 1.2.1+
+    wxZLIB_AUTO = 3          //!< autodetect header zlib or gzip
+};
+
+

 /**
     @class wxZlibOutputStream
 
 /**
     @class wxZlibOutputStream
 

-    This stream compresses all data written to it. The compressed output can be
-    in zlib or gzip format.
+    This stream compresses all data written to it.
+
+    The compressed output can be in zlib or gzip format.

     Note that writing the gzip format requires zlib version 1.2.1 or greater
     (the builtin version does support gzip format).
 
     Note that writing the gzip format requires zlib version 1.2.1 or greater
     (the builtin version does support gzip format).
 

-    The stream is not seekable, wxOutputStream::SeekO returns
-     @e wxInvalidOffset.
+    The stream is not seekable, wxOutputStream::SeekO() returns
+    ::wxInvalidOffset.

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


@@ -27,19 +46,25 @@ class wxZlibOutputStream : public wxFilterOutputStream
 public:
     //@{
     /**
 public:
     //@{
     /**

-        Creates a new write-only compressed stream. @a level means level of
-        compression. It is number between 0 and 9 (including these values) where
-        0 means no compression and 9 best but slowest compression. -1 is default
-        value (currently equivalent to 6).
+        Creates a new write-only compressed stream.
+
+        @a level means level of compression. It is number between 0 and 9
+        (including these values) where 0 means no compression and 9 best but
+        slowest compression. -1 is default value (currently equivalent to 6).
+

         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.

+

         The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the output data
         will be in zlib or gzip format. wxZLIB_ZLIB is the default.
         The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the output data
         will be in zlib or gzip format. wxZLIB_ZLIB is the default.

+

         If @a flags is wxZLIB_NO_HEADER, then a raw deflate stream is output
         If @a flags is wxZLIB_NO_HEADER, then a raw deflate stream is output

-        without either zlib or gzip headers. This is a lower level
-        mode, which is not usually used directly. It can be used to embed a raw
-        deflate stream in a higher level protocol.
-        The following symbols can be use for the compression level and flags:
+        without either zlib or gzip headers. This is a lower level mode, which
+        is not usually used directly. It can be used to embed a raw deflate
+        stream in a higher level protocol.
+
+        The values of the ::wxZlibCompressionLevels and ::wxZLibFlags
+        enumerations can be used.

     */
     wxZlibOutputStream(wxOutputStream& stream, int level = -1,
                        int flags = wxZLIB_ZLIB);
     */
     wxZlibOutputStream(wxOutputStream& stream, int level = -1,
                        int flags = wxZLIB_ZLIB);


@@ -62,9 +87,8 @@ public:
     Note that reading the gzip format requires zlib version 1.2.1 or greater,
     (the builtin version does support gzip format).
 
     Note that reading the gzip format requires zlib version 1.2.1 or greater,
     (the builtin version does support gzip format).
 

-    The stream is not seekable, wxInputStream::SeekI returns
-     @e wxInvalidOffset. Also wxStreamBase::GetSize is
-    not supported, it always returns 0.
+    The stream is not seekable, wxInputStream::SeekI returns ::wxInvalidOffset.
+    Also wxStreamBase::GetSize() is not supported, it always returns 0.

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


@@ -78,23 +102,20 @@ public:
     /**
         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.
     /**
         If the parent stream is passed as a pointer then the new filter stream
         takes ownership of it. If it is passed by reference then it does not.

+

         The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the input data
         is in zlib or gzip format. If wxZLIB_AUTO is used, then zlib will
         autodetect the stream type, this is the default.
         The @a flags wxZLIB_ZLIB and wxZLIB_GZIP specify whether the input data
         is in zlib or gzip format. If wxZLIB_AUTO is used, then zlib will
         autodetect the stream type, this is the default.

+

         If @a flags is wxZLIB_NO_HEADER, then the data is assumed to be a raw
         deflate stream without either zlib or gzip headers. This is a lower level
         mode, which is not usually used directly. It can be used to read a raw
         deflate stream embedded in a higher level protocol.
         If @a flags is wxZLIB_NO_HEADER, then the data is assumed to be a raw
         deflate stream without either zlib or gzip headers. This is a lower level
         mode, which is not usually used directly. It can be used to read a raw
         deflate stream embedded in a higher level protocol.

-        This version is not by default compatible with the output produced by
-        the version of @e wxZlibOutputStream in wxWidgets 2.4.x. However,
-        there is a compatibility mode, which is switched on by passing
-        wxZLIB_24COMPATIBLE for flags. Note that in when operating in compatibility
-        mode error checking is very much reduced.
-        The following symbols can be use for the flags:
+
+        The values of the ::wxZLibFlags enumeration can be used.

     */
     wxZlibInputStream(wxInputStream& stream, int flags = wxZLIB_AUTO);
     */
     wxZlibInputStream(wxInputStream& stream, int flags = wxZLIB_AUTO);

-    wxZlibInputStream(wxInputStream* stream,
-                      int flags = wxZLIB_AUTO);
+    wxZlibInputStream(wxInputStream* stream, int flags = wxZLIB_AUTO);

     //@}
 
     /**
     //@}
 
     /**